@jademind/pi-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jademind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @jademind/pi-bridge
+
+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.
+
+## 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
+
+```bash
+pi install npm:@jademind/pi-bridge
+```
+
+## Filesystem layout
+
+Default base directory:
+
+```text
+~/.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`)
+
+```json
+{
+  "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`)
+
+```json
+{
+  "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`)
+- `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`)
+- `PI_BRIDGE_RATE_PER_MIN` (default `12`)
+- `PI_BRIDGE_RATE_BURST` (default `4`)
+- `PI_BRIDGE_INTERRUPT_RATE_PER_MIN` (default `4`)
+- `PI_BRIDGE_INTERRUPT_RATE_BURST` (default `2`)
+
+## Command
+
+- `/pi-bridge-status`
+
+## Development
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+## License
+
+MIT

package/extensions/pi-bridge.mjs

@@ -0,0 +1,314 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { makeTokenBucket, normalizeDelivery, safeChildPath, validateEnvelope } from "../lib/core.mjs";
+
+const MAX_FILE_BYTES = 32 * 1024;
+const PROCESSED_CACHE_MAX = 1024;
+
+function envNumber(name, fallback, min = 1) {
+  const parsed = Number(process.env[name] ?? "");
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.floor(parsed));
+}
+
+function ensureDirSecure(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+function atomicWriteJson(filePath, data) {
+  ensureDirSecure(path.dirname(filePath));
+  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+}
+
+function safeUnlink(filePath) {
+  try {
+    fs.unlinkSync(filePath);
+  } catch {
+    // ignore
+  }
+}
+
+function randomId() {
+  return crypto.randomUUID ? crypto.randomUUID() : `${Date.now()}-${Math.random()}`;
+}
+
+export default function (pi) {
+  const baseDir = process.env.PI_BRIDGE_DIR?.trim() || path.join(os.homedir(), ".pi", "agent", "statusbridge");
+  const registryDir = path.join(baseDir, "registry");
+  const inboxRoot = path.join(baseDir, "inbox");
+  const ackRoot = path.join(baseDir, "acks");
+  const processingRoot = path.join(baseDir, "processing");
+
+  const pidStr = String(process.pid);
+  const inboxDir = path.join(inboxRoot, pidStr);
+  const ackDir = path.join(ackRoot, pidStr);
+  const processingDir = path.join(processingRoot, pidStr);
+  const registryFile = path.join(registryDir, `${pidStr}.json`);
+
+  const maxTextLength = envNumber("PI_BRIDGE_MAX_TEXT", 4000, 32);
+  const maxSkewMs = envNumber("PI_BRIDGE_MAX_SKEW_MS", 120000, 1000);
+  const heartbeatMs = envNumber("PI_BRIDGE_HEARTBEAT_MS", 2000, 250);
+  const scanMs = envNumber("PI_BRIDGE_SCAN_MS", 750, 100);
+  const refillPerMinute = envNumber("PI_BRIDGE_RATE_PER_MIN", 12, 1);
+  const burst = envNumber("PI_BRIDGE_RATE_BURST", 4, 1);
+  const refillInterruptPerMinute = envNumber("PI_BRIDGE_INTERRUPT_RATE_PER_MIN", 4, 1);
+  const burstInterrupt = envNumber("PI_BRIDGE_INTERRUPT_RATE_BURST", 2, 1);
+  const queueDepthLimit = envNumber("PI_BRIDGE_QUEUE_DEPTH", 64, 1);
+
+  ensureDirSecure(baseDir);
+  ensureDirSecure(registryDir);
+  ensureDirSecure(inboxRoot);
+  ensureDirSecure(ackRoot);
+  ensureDirSecure(processingRoot);
+  ensureDirSecure(inboxDir);
+  ensureDirSecure(ackDir);
+  ensureDirSecure(processingDir);
+
+  const normalLimiter = makeTokenBucket({ refillPerMinute, burst });
+  const interruptLimiter = makeTokenBucket({ refillPerMinute: refillInterruptPerMinute, burst: burstInterrupt });
+  const processed = new Map();
+
+  let heartbeat = undefined;
+  let scanner = undefined;
+  let watcher = undefined;
+  let isDraining = false;
+  let sessionId = "";
+  let lastCtx = undefined;
+
+  function rememberProcessed(id) {
+    processed.set(id, Date.now());
+    if (processed.size <= PROCESSED_CACHE_MAX) return;
+    const first = processed.keys().next().value;
+    if (first) processed.delete(first);
+  }
+
+  function writeAck(status, envelope, extra = {}) {
+    const ack = {
+      v: 1,
+      id: envelope?.id || randomId(),
+      pid: process.pid,
+      status,
+      at: Date.now(),
+      messagePid: envelope?.pid,
+      source: envelope?.source,
+      delivery: envelope?.delivery,
+      ...extra,
+    };
+    const ackFile = path.join(ackDir, `${ack.id}.json`);
+    atomicWriteJson(ackFile, ack);
+  }
+
+  function publishRegistry() {
+    const payload = {
+      v: 1,
+      pid: process.pid,
+      ppid: process.ppid,
+      startedAt: process.uptime ? Math.floor(Date.now() - process.uptime() * 1000) : Date.now(),
+      updatedAt: Date.now(),
+      sessionId,
+      cwd: process.cwd(),
+      capabilities: {
+        queueing: true,
+        steering: true,
+      },
+    };
+    atomicWriteJson(registryFile, payload);
+  }
+
+  function moveToProcessing(fileName) {
+    const src = path.join(inboxDir, fileName);
+    const dst = path.join(processingDir, `${fileName}.${Date.now()}.processing`);
+    if (!safeChildPath(inboxDir, src) || !safeChildPath(processingDir, dst)) return null;
+    try {
+      const st = fs.lstatSync(src);
+      if (!st.isFile() || st.isSymbolicLink() || st.size > MAX_FILE_BYTES) {
+        safeUnlink(src);
+        return null;
+      }
+      fs.renameSync(src, dst);
+      return dst;
+    } catch {
+      return null;
+    }
+  }
+
+  function readEnvelope(filePath) {
+    try {
+      if (!safeChildPath(processingDir, filePath)) return { ok: false, error: "invalid_path" };
+      const text = fs.readFileSync(filePath, "utf8");
+      return { ok: true, raw: JSON.parse(text) };
+    } catch {
+      return { ok: false, error: "invalid_json" };
+    }
+  }
+
+  function sendToAgent(ctx, envelope) {
+    const isIdle = Boolean(ctx?.isIdle?.());
+    const delivery = normalizeDelivery(envelope.delivery, isIdle);
+
+    const limiter = delivery.mode === "interrupt" ? interruptLimiter : normalLimiter;
+    if (!limiter.allow(1)) {
+      return { ok: false, error: "rate_limited", delivery };
+    }
+
+    try {
+      if (delivery.sendUserMessageOptions) {
+        pi.sendUserMessage(envelope.text, delivery.sendUserMessageOptions);
+      } else {
+        pi.sendUserMessage(envelope.text);
+      }
+      return { ok: true, delivery };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : "send_failed", delivery };
+    }
+  }
+
+  function processOneFile(fileName, ctx) {
+    const processingFile = moveToProcessing(fileName);
+    if (!processingFile) return;
+
+    const parsed = readEnvelope(processingFile);
+    if (!parsed.ok) {
+      writeAck("failed", { id: fileName, pid: process.pid, source: "unknown" }, { error: parsed.error });
+      safeUnlink(processingFile);
+      return;
+    }
+
+    const validated = validateEnvelope(parsed.raw, {
+      maxTextLength,
+      maxSkewMs,
+      expectedPid: process.pid,
+    });
+
+    if (!validated.ok) {
+      writeAck("failed", { id: parsed.raw?.id ?? fileName, pid: process.pid, source: parsed.raw?.source }, { error: validated.error });
+      safeUnlink(processingFile);
+      return;
+    }
+
+    const envelope = validated.value;
+    if (processed.has(envelope.id)) {
+      writeAck("duplicate", envelope, { error: "duplicate_id" });
+      safeUnlink(processingFile);
+      return;
+    }
+
+    const result = sendToAgent(ctx, envelope);
+    if (!result.ok) {
+      writeAck("failed", envelope, { error: result.error, resolvedMode: result.delivery?.mode });
+      safeUnlink(processingFile);
+      return;
+    }
+
+    rememberProcessed(envelope.id);
+    writeAck("delivered", envelope, { resolvedMode: result.delivery.mode });
+    safeUnlink(processingFile);
+  }
+
+  function drainInbox(ctx) {
+    if (isDraining) return;
+    isDraining = true;
+    try {
+      if (!ctx) return;
+      const entries = fs.readdirSync(inboxDir, { withFileTypes: true })
+        .filter((d) => d.isFile() && d.name.endsWith(".json"))
+        .map((d) => d.name)
+        .sort();
+
+      if (entries.length > queueDepthLimit) {
+        const dropCount = entries.length - queueDepthLimit;
+        for (const name of entries.slice(0, dropCount)) {
+          const full = path.join(inboxDir, name);
+          safeUnlink(full);
+        }
+      }
+
+      for (const name of entries.slice(-queueDepthLimit)) {
+        processOneFile(name, ctx);
+      }
+    } finally {
+      isDraining = false;
+    }
+  }
+
+  function startBackground() {
+    publishRegistry();
+
+    if (heartbeat) clearInterval(heartbeat);
+    heartbeat = setInterval(() => publishRegistry(), heartbeatMs);
+    heartbeat.unref?.();
+
+    if (scanner) clearInterval(scanner);
+    scanner = setInterval(() => drainInbox(lastCtx), scanMs);
+    scanner.unref?.();
+
+    try {
+      if (watcher) watcher.close();
+      watcher = fs.watch(inboxDir, { persistent: false }, () => drainInbox(lastCtx));
+    } catch {
+      watcher = undefined;
+    }
+  }
+
+  function stopBackground() {
+    if (heartbeat) clearInterval(heartbeat);
+    if (scanner) clearInterval(scanner);
+    heartbeat = undefined;
+    scanner = undefined;
+    if (watcher) {
+      watcher.close();
+      watcher = undefined;
+    }
+  }
+
+  pi.registerCommand("pi-bridge-status", {
+    description: "Show pi-bridge directories and runtime settings",
+    handler: async (_args, ctx) => {
+      lastCtx = ctx;
+      const msg = [
+        `pi-bridge pid=${process.pid}`,
+        `base=${baseDir}`,
+        `inbox=${inboxDir}`,
+        `acks=${ackDir}`,
+        `maxText=${maxTextLength}`,
+        `queueDepthLimit=${queueDepthLimit}`,
+        `rate/min=${refillPerMinute} burst=${burst}`,
+        `interruptRate/min=${refillInterruptPerMinute} burst=${burstInterrupt}`,
+      ].join("\n");
+
+      pi.sendMessage({ customType: "pi-bridge", content: msg, display: true });
+      if (ctx.hasUI) ctx.ui.notify("pi-bridge status emitted", "info");
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    lastCtx = ctx;
+    sessionId = ctx.sessionManager.getSessionId();
+    startBackground();
+    drainInbox(ctx);
+  });
+
+  pi.on("turn_start", async (_event, ctx) => {
+    lastCtx = ctx;
+    drainInbox(ctx);
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    lastCtx = ctx;
+    drainInbox(ctx);
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    lastCtx = ctx;
+    drainInbox(ctx);
+  });
+
+  pi.on("session_shutdown", async () => {
+    stopBackground();
+    safeUnlink(registryFile);
+  });
+}

package/lib/core.mjs

@@ -0,0 +1,107 @@
+import path from "node:path";
+
+export const VALID_MODES = new Set(["queued", "interrupt"]);
+
+export function parseTime(input) {
+  if (typeof input === "number" && Number.isFinite(input)) return input;
+  if (typeof input === "string" && input.trim()) {
+    const n = Number(input);
+    if (Number.isFinite(n)) return n;
+    const d = Date.parse(input);
+    if (Number.isFinite(d)) return d;
+  }
+  return NaN;
+}
+
+export function nowMs() {
+  return Date.now();
+}
+
+export function safeChildPath(root, target) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(target);
+  return resolvedTarget === resolvedRoot || resolvedTarget.startsWith(`${resolvedRoot}${path.sep}`);
+}
+
+export function normalizeDelivery(delivery, isIdle) {
+  const mode = delivery?.mode === "interrupt" ? "interrupt" : "queued";
+
+  if (isIdle) {
+    return { mode, sendUserMessageOptions: undefined };
+  }
+
+  if (mode === "interrupt") {
+    return { mode, sendUserMessageOptions: { deliverAs: "steer" } };
+  }
+
+  return { mode, sendUserMessageOptions: { deliverAs: "followUp" } };
+}
+
+export function validateEnvelope(raw, opts = {}) {
+  const maxTextLength = Number.isFinite(opts.maxTextLength) ? opts.maxTextLength : 4000;
+  const maxSkewMs = Number.isFinite(opts.maxSkewMs) ? opts.maxSkewMs : 60_000;
+  const now = Number.isFinite(opts.now) ? opts.now : nowMs();
+  const expectedPid = Number.isFinite(opts.expectedPid) ? opts.expectedPid : undefined;
+
+  if (!raw || typeof raw !== "object") return { ok: false, error: "invalid_json" };
+
+  const v = raw.v;
+  const id = typeof raw.id === "string" ? raw.id.trim() : "";
+  const pid = Number(raw.pid);
+  const text = typeof raw.text === "string" ? raw.text.replace(/\r\n?/g, "\n").trim() : "";
+  const source = typeof raw.source === "string" ? raw.source.trim() : "unknown";
+  const createdAt = parseTime(raw.createdAt);
+  const expiresAt = raw.expiresAt == null ? createdAt + maxSkewMs : parseTime(raw.expiresAt);
+
+  if (v !== 1) return { ok: false, error: "unsupported_version" };
+  if (!id || id.length > 128) return { ok: false, error: "invalid_id" };
+  if (!Number.isFinite(pid) || pid <= 0) return { ok: false, error: "invalid_pid" };
+  if (expectedPid != null && pid !== expectedPid) return { ok: false, error: "pid_mismatch" };
+  if (!text) return { ok: false, error: "empty_text" };
+  if (text.length > maxTextLength) return { ok: false, error: "text_too_long" };
+  if (!Number.isFinite(createdAt)) return { ok: false, error: "invalid_created_at" };
+  if (!Number.isFinite(expiresAt)) return { ok: false, error: "invalid_expires_at" };
+  if (expiresAt < now) return { ok: false, error: "expired" };
+
+  const rawMode = raw.delivery?.mode;
+  const mode = VALID_MODES.has(rawMode) ? rawMode : "queued";
+
+  return {
+    ok: true,
+    value: {
+      v,
+      id,
+      pid,
+      text,
+      source: source || "unknown",
+      createdAt,
+      expiresAt,
+      delivery: {
+        mode,
+        channel: "steer",
+        triggerTurn: true,
+      },
+      meta: raw.meta && typeof raw.meta === "object" ? raw.meta : undefined,
+    },
+  };
+}
+
+export function makeTokenBucket({ refillPerMinute = 12, burst = 4 } = {}) {
+  const ratePerMs = Math.max(1, refillPerMinute) / 60_000;
+  const capacity = Math.max(1, burst);
+  let tokens = capacity;
+  let last = nowMs();
+
+  return {
+    allow(cost = 1, now = nowMs()) {
+      const delta = Math.max(0, now - last);
+      last = now;
+      tokens = Math.min(capacity, tokens + delta * ratePerMs);
+      if (tokens >= cost) {
+        tokens -= cost;
+        return true;
+      }
+      return false;
+    },
+  };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@jademind/pi-bridge",
+  "version": "0.1.0",
+  "description": "Minimal secure inbox bridge for Pi: reliable queued/steering message delivery to running sessions.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "bridge",
+    "messaging",
+    "statusbar",
+    "ios"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jademind/pi-bridge.git"
+  },
+  "homepage": "https://github.com/jademind/pi-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/jademind/pi-bridge/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "extensions",
+    "lib",
+    "test",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  }
+}

package/test/core.test.mjs

@@ -0,0 +1,67 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { makeTokenBucket, normalizeDelivery, safeChildPath, validateEnvelope } from "../lib/core.mjs";
+
+test("validateEnvelope accepts valid payload", () => {
+  const now = Date.now();
+  const res = validateEnvelope(
+    {
+      v: 1,
+      id: "abc",
+      pid: 123,
+      text: "hello",
+      source: "statusbar",
+      createdAt: now,
+      expiresAt: now + 5000,
+      delivery: { mode: "interrupt" },
+    },
+    { expectedPid: 123, now },
+  );
+
+  assert.equal(res.ok, true);
+  assert.equal(res.value.delivery.mode, "interrupt");
+});
+
+test("validateEnvelope rejects wrong pid", () => {
+  const now = Date.now();
+  const res = validateEnvelope(
+    {
+      v: 1,
+      id: "abc",
+      pid: 999,
+      text: "hello",
+      createdAt: now,
+      expiresAt: now + 5000,
+    },
+    { expectedPid: 123, now },
+  );
+
+  assert.equal(res.ok, false);
+  assert.equal(res.error, "pid_mismatch");
+});
+
+test("normalizeDelivery maps queued to followUp while busy", () => {
+  const d = normalizeDelivery({ mode: "queued" }, false);
+  assert.equal(d.mode, "queued");
+  assert.deepEqual(d.sendUserMessageOptions, { deliverAs: "followUp" });
+});
+
+test("normalizeDelivery maps interrupt to steer while busy", () => {
+  const d = normalizeDelivery({ mode: "interrupt" }, false);
+  assert.equal(d.mode, "interrupt");
+  assert.deepEqual(d.sendUserMessageOptions, { deliverAs: "steer" });
+});
+
+test("safeChildPath rejects traversal", () => {
+  assert.equal(safeChildPath("/tmp/a", "/tmp/a/b/c"), true);
+  assert.equal(safeChildPath("/tmp/a", "/tmp/other"), false);
+});
+
+test("token bucket throttles", () => {
+  const bucket = makeTokenBucket({ refillPerMinute: 60, burst: 2 });
+  const t = 1000;
+  assert.equal(bucket.allow(1, t), true);
+  assert.equal(bucket.allow(1, t), true);
+  assert.equal(bucket.allow(1, t), false);
+  assert.equal(bucket.allow(1, t + 1000), true);
+});