@jademind/pi-bridge

Package scope: use @jademind/pi-bridge (scoped). Older unscoped naming should be considered deprecated.

Minimal secure inbox bridge for Pi sessions.

@jademind/pi-bridge is designed for status bar and mobile clients that must send messages reliably to running Pi agents, including plain terminal sessions where tty injection is unreliable.

It is primarily consumed by the free open-source macOS app pi-statusbar, and complements @jademind/pi-telemetry for runtime observability.

Related projects

• pi-statusbar: macOS menu bar app for Pi (daemon + UI)
• @jademind/pi-telemetry: per-process telemetry heartbeat + snapshot CLI

What it does

• Watches a per-PID inbox directory
• Validates signed/structured message envelopes
• Delivers to Pi using user-message semantics
  • queued mode -> followUp when busy
  • interrupt mode -> steer when busy
• Writes delivery acknowledgements per message
• Publishes lightweight per-session registry heartbeat
• Enforces size limits, TTL, path safety, idempotency, and rate limits

Install

pi install npm:@jademind/pi-bridge

Restart active Pi sessions after install so the extension loads.

If you use pi-statusbar, install/start everything with:

brew install jademind/tap/pi-statusbar
statusbar-setup enable

Filesystem layout

Default base directory:

~/.pi/agent/statusbridge/
  registry/<pid>.json
  inbox/<pid>/<message-id>.json
  processing/<pid>/*.processing
  acks/<pid>/<message-id>.json

Override base with:

• PI_BRIDGE_DIR

Envelope (send-v1)

{
  "v": 1,
  "id": "4a4c5295-d3e4-4f91-b562-8f0f4cc6f413",
  "pid": 12345,
  "text": "Please summarize current progress and blockers.",
  "source": "statusbar",
  "createdAt": "2026-02-24T15:50:00Z",
  "expiresAt": "2026-02-24T15:51:00Z",
  "delivery": {
    "mode": "queued"
  },
  "meta": {
    "requestId": "ios-123"
  }
}

delivery.mode values:

• queued (default): queue politely if busy
• interrupt: steering interrupt if busy

Ack (ack-v1)

{
  "v": 1,
  "id": "4a4c5295-d3e4-4f91-b562-8f0f4cc6f413",
  "pid": 12345,
  "status": "delivered",
  "at": 1771948234000,
  "resolvedMode": "queued"
}

Possible statuses:

• delivered
• failed
• duplicate

Security defaults

• file size cap: 32 KB
• message length cap: 4000 chars
• strict PID matching
• TTL expiry enforcement
• symlink and path traversal rejection
• bounded queue depth
• separate normal/interrupt rate limiters

Runtime config

• PI_BRIDGE_MAX_TEXT (default 4000, minimum 256)
• PI_BRIDGE_MAX_SKEW_MS (default 120000)
• PI_BRIDGE_HEARTBEAT_MS (default 2000)
• PI_BRIDGE_SCAN_MS (default 750)
• PI_BRIDGE_QUEUE_DEPTH (default 64, minimum 8)
• PI_BRIDGE_RATE_PER_MIN (default 20, minimum 20)
• PI_BRIDGE_RATE_BURST (default 6, minimum 4)
• PI_BRIDGE_INTERRUPT_RATE_PER_MIN (default 20, minimum 20)
• PI_BRIDGE_INTERRUPT_RATE_BURST (default 4, minimum 4)

Command

• /pi-bridge-status

Development

npm test
npm pack --dry-run

Suggested release checklist:

1. Update version in package.json
2. Run tests (npm test)
3. Validate package tarball (npm pack --dry-run)
4. Tag and push release commit
5. Publish to npm (npm publish --access public)

OSS best practices

• Keep package references scoped in docs/examples (@jademind/pi-bridge, @jademind/pi-telemetry).
• Keep bridge inbox/ack directories user-local (~/.pi/agent/statusbridge) and avoid world-writable permissions.
• Treat all inbox payloads as untrusted: validate PID, TTL, size, and path constraints before delivery.
• Keep rate limits enabled (normal + interrupt) to protect active sessions from spam and accidental loops.
• When changing envelope/ack schema, bump docs with explicit compatibility notes.
• Keep release notes aligned across npm package, Git tag, and dependent clients (status bar / mobile).

License

MIT