pi-tmux-bridge 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tmux-bridge",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A pi coding-agent extension that feeds this terminal's tmux state (status bar, attention bell, session bus) from a pi session.",
   "type": "module",
   "license": "MIT",

package/src/bell.test.ts

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { ringBell, raiseAttention } from "./bell.ts";
+import { ringBell, raiseAttention, raisePermissionAttention, clearPermissionAttention } from "./bell.ts";
 
 const ctx = { socket: "proj-pi", pane: "%47" };
 const BEL = String.fromCharCode(7);
@@ -36,3 +36,30 @@ test("an unresolvable session raises nothing rather than raising the wrong thing
   raiseAttention(ctx, { session: () => undefined, run: (cmd) => calls.push(cmd) });
   assert.deepEqual(calls, []);
 });
+
+test("permission attention calls claude-attn raise-wait with the session", () => {
+  const calls: Array<{ cmd: string; args: string[] }> = [];
+  raisePermissionAttention(ctx, { session: () => "pi-97", run: (cmd, args) => calls.push({ cmd, args }) });
+  assert.equal(calls.length, 1);
+  assert.match(calls[0].cmd, /claude-attn$/);
+  assert.deepEqual(calls[0].args, ["raise-wait", "pi-97"]);
+});
+
+test("clearing permission attention calls claude-attn clear-wait with the session", () => {
+  const calls: Array<{ cmd: string; args: string[] }> = [];
+  clearPermissionAttention(ctx, { session: () => "pi-97", run: (cmd, args) => calls.push({ cmd, args }) });
+  assert.deepEqual(calls[0].args, ["clear-wait", "pi-97"]);
+});
+
+test("an unresolvable session neither raises nor clears the permission flag", () => {
+  const calls: string[] = [];
+  raisePermissionAttention(ctx, { session: () => undefined, run: (cmd) => calls.push(cmd) });
+  clearPermissionAttention(ctx, { session: () => undefined, run: (cmd) => calls.push(cmd) });
+  assert.deepEqual(calls, []);
+});
+
+test("a failing permission-attention call is swallowed — it must not fail a turn", () => {
+  assert.doesNotThrow(() =>
+    raisePermissionAttention(ctx, { session: () => "pi-97", run: () => { throw new Error("gone"); } }),
+  );
+});

package/src/bell.ts

@@ -38,6 +38,41 @@ export function raiseAttention(
     session?: (socket: string, pane: string) => string | undefined;
     run?: (cmd: string, args: string[]) => void;
   } = {},
+): void {
+  runAttn(ctx, "raise", deps);
+}
+
+// The permission-waiting flag (@claude_attn_perm) is a SECOND, more urgent state
+// than the turn-done flag raiseAttention sets: it lights the 🔐 title prefix
+// (over the 🔔 of a settled turn) while a permission prompt waits on the
+// operator, and is cleared the moment the prompt is answered.
+export function raisePermissionAttention(
+  ctx: TmuxContext,
+  deps: {
+    session?: (socket: string, pane: string) => string | undefined;
+    run?: (cmd: string, args: string[]) => void;
+  } = {},
+): void {
+  runAttn(ctx, "raise-wait", deps);
+}
+
+export function clearPermissionAttention(
+  ctx: TmuxContext,
+  deps: {
+    session?: (socket: string, pane: string) => string | undefined;
+    run?: (cmd: string, args: string[]) => void;
+  } = {},
+): void {
+  runAttn(ctx, "clear-wait", deps);
+}
+
+function runAttn(
+  ctx: TmuxContext,
+  verb: string,
+  deps: {
+    session?: (socket: string, pane: string) => string | undefined;
+    run?: (cmd: string, args: string[]) => void;
+  },
 ): void {
   const readSession = deps.session ?? sessionOfPane;
   const run =
@@ -48,7 +83,7 @@ export function raiseAttention(
   try {
     const session = readSession(ctx.socket, ctx.pane);
     if (!session) return;
-    run(ATTN, ["raise", session]);
+    run(ATTN, [verb, session]);
   } catch {
     // Best-effort: an attention flag must not fail a turn.
   }

package/src/index.test.ts

@@ -6,11 +6,17 @@ type Handler = (event: unknown, ctx: unknown) => unknown;
 
 function fakePi() {
   const handlers = new Map<string, Handler[]>();
+  const busHandlers = new Map<string, Handler[]>();
   const sent: Array<{ message: unknown; options: unknown }> = [];
   const pi = {
     on(event: string, handler: Handler) {
       handlers.set(event, [...(handlers.get(event) ?? []), handler]);
     },
+    events: {
+      on(event: string, handler: Handler) {
+        busHandlers.set(event, [...(busHandlers.get(event) ?? []), handler]);
+      },
+    },
     sendMessage(message: unknown, options?: unknown) {
       sent.push({ message, options });
     },
@@ -28,7 +34,20 @@ function fakePi() {
     for (const h of handlers.get(event) ?? []) out.push(await h(payload, overrideCtx ?? ctx));
     return out;
   }
-  return { pi, ctx, fire, events: () => [...handlers.keys()], sent };
+  async function fireBus(event: string, payload: unknown = {}) {
+    const out: unknown[] = [];
+    for (const h of busHandlers.get(event) ?? []) out.push(await h(payload, undefined as never));
+    return out;
+  }
+  return {
+    pi,
+    ctx,
+    fire,
+    fireBus,
+    events: () => [...handlers.keys()],
+    busEvents: () => [...busHandlers.keys()],
+    sent,
+  };
 }
 
 // A tmux address that cannot collide with a real server or pane on the
@@ -497,3 +516,64 @@ test("session_shutdown tombstones and drops state ONLY on reason quit", async ()
   );
   assert.equal(removed.length, 1, "reason quit must drop the state file");
 });
+
+test("a permission ui_prompt rings the bell and raises the permission flag", async () => {
+  const { pi, fire, fireBus } = fakePi();
+  const bells: unknown[] = [];
+  const perms: string[] = [];
+  createHarness(pi as never, {
+    tmux: () => ctxTmux,
+    raiseAttention: noopBell,
+    ringBell: (c) => bells.push(c),
+    raisePermissionAttention: () => perms.push("raise"),
+    clearPermissionAttention: () => perms.push("clear"),
+  });
+  await fire("session_start", { reason: "startup" });
+  await fireBus("permissions:ui_prompt", { requestId: "req-1", surface: "bash", value: "rm -rf x" });
+  assert.equal(bells.length, 1, "prompt must ring the bell");
+  assert.deepEqual(perms, ["raise"]);
+});
+
+test("the matching decision clears the permission flag; a stray one does not", async () => {
+  const { pi, fire, fireBus } = fakePi();
+  const perms: string[] = [];
+  createHarness(pi as never, {
+    tmux: () => ctxTmux,
+    raiseAttention: noopBell,
+    ringBell: noopBell,
+    raisePermissionAttention: () => perms.push("raise"),
+    clearPermissionAttention: () => perms.push("clear"),
+  });
+  await fire("session_start", { reason: "startup" });
+  await fireBus("permissions:ui_prompt", { requestId: "req-1" });
+  await fireBus("permissions:decision", { requestId: "other", result: "allow" });
+  assert.deepEqual(perms, ["raise"], "an unrelated decision must not clear the flag");
+  await fireBus("permissions:decision", { requestId: "req-1", result: "allow" });
+  assert.deepEqual(perms, ["raise", "clear"], "the resolving decision clears the flag");
+});
+
+test("a subagent node (never owned the pane) ignores permission prompts", async () => {
+  const { pi, fire, fireBus, ctx } = fakePi();
+  const perms: string[] = [];
+  const bells: unknown[] = [];
+  createHarness(pi as never, {
+    tmux: () => ctxTmux,
+    raiseAttention: noopBell,
+    ringBell: (c) => bells.push(c),
+    raisePermissionAttention: () => perms.push("raise"),
+    clearPermissionAttention: () => perms.push("clear"),
+  });
+  await fire("session_start", { reason: "startup" }, { ...ctx, mode: "print" });
+  await fireBus("permissions:ui_prompt", { requestId: "req-1" });
+  assert.deepEqual(perms, [], "a non-owning node must not raise the flag");
+  assert.deepEqual(bells, [], "a non-owning node must not ring");
+});
+
+test("it subscribes to exactly the pi.events channels it needs", async () => {
+  const { pi, busEvents } = fakePi();
+  createHarness(pi as never, { raiseAttention: noopBell, tmux: () => ctxTmux });
+  assert.deepEqual(
+    busEvents().sort(),
+    ["permissions:decision", "permissions:ui_prompt"].sort(),
+  );
+});

package/src/index.ts

@@ -1,7 +1,12 @@
 import { resolveTmux, tmux as runTmuxDefault } from "./tmux.ts";
 import type { TmuxContext } from "./tmux.ts";
 import { writeState as writeStateDefault, removeState as removeStateDefault } from "./state.ts";
-import { ringBell as ringBellDefault, raiseAttention as raiseAttentionDefault } from "./bell.ts";
+import {
+  ringBell as ringBellDefault,
+  raiseAttention as raiseAttentionDefault,
+  raisePermissionAttention as raisePermissionAttentionDefault,
+  clearPermissionAttention as clearPermissionAttentionDefault,
+} from "./bell.ts";
 import { sessionStart, drain, sessionEnd, become } from "./muster.ts";
 import type { Run } from "./muster.ts";
 
@@ -13,6 +18,8 @@ type Deps = {
   removeState?: (ctx: TmuxContext) => void;
   ringBell?: (ctx: TmuxContext) => void;
   raiseAttention?: (ctx: TmuxContext) => void;
+  raisePermissionAttention?: (ctx: TmuxContext) => void;
+  clearPermissionAttention?: (ctx: TmuxContext) => void;
 };
 
 // The session id reaches tmux as a session option value; sanitize before it
@@ -46,6 +53,10 @@ export function createHarness(pi: any, deps: Deps = {}): void {
   const removeState = deps.removeState ?? ((ctx) => removeStateDefault(ctx));
   const ringBell = deps.ringBell ?? ((ctx) => ringBellDefault(ctx));
   const raiseAttention = deps.raiseAttention ?? ((ctx) => raiseAttentionDefault(ctx));
+  const raisePermissionAttention =
+    deps.raisePermissionAttention ?? ((ctx) => raisePermissionAttentionDefault(ctx));
+  const clearPermissionAttention =
+    deps.clearPermissionAttention ?? ((ctx) => clearPermissionAttentionDefault(ctx));
 
   // Loop guard for the drain on agent_settled: injecting a block reason
   // starts a turn, which produces another settle. Without tracking whether
@@ -63,6 +74,18 @@ export function createHarness(pi: any, deps: Deps = {}): void {
   // again would be a pointless round-trip.
   let lastAlias: string | undefined;
 
+  // A permission prompt pauses mid-turn, so neither turn_end nor agent_settled
+  // fires while it waits — the two events that normally light the pane. The
+  // permission system announces that exact moment on pi.events; we ring and
+  // raise the 🔐 flag on the prompt, and drop it on the matching decision.
+  // pi.events handlers get no ctx, so ownership is captured here from the one
+  // session_start that owns the pane (a subagent node's stays false).
+  let ownsThisPane = false;
+  // Clear only on the decision that resolves the prompt we lit: one tool call
+  // runs several gates, and an unrelated auto-allow decision must not drop a
+  // flag a still-pending prompt is holding.
+  let pendingPromptRequestId: string | undefined;
+
   // Only an interactive session owns the pane's identity. Subagent sessions
   // (pi-subagents' createAgentSession) run IN-PROCESS: they load this
   // extension too, inherit $TMUX/$TMUX_PANE, and their extension mode stays
@@ -74,8 +97,27 @@ export function createHarness(pi: any, deps: Deps = {}): void {
   // for the same reason — they are guests, not the pane's owner.
   const ownsPane = (ctx: any): boolean => ctx?.mode === "tui";
 
+  pi.events?.on?.("permissions:ui_prompt", (data: any) => safe(() => {
+    if (!ownsThisPane) return;
+    const t = getTmux();
+    if (!t) return;
+    pendingPromptRequestId = data?.requestId;
+    ringBell(t);
+    raisePermissionAttention(t);
+  }));
+
+  pi.events?.on?.("permissions:decision", (data: any) => safe(() => {
+    if (!ownsThisPane) return;
+    if (!pendingPromptRequestId || data?.requestId !== pendingPromptRequestId) return;
+    pendingPromptRequestId = undefined;
+    const t = getTmux();
+    if (!t) return;
+    clearPermissionAttention(t);
+  }));
+
   pi.on("session_start", (event: any, ctx: any) => safe(() => {
     if (!ownsPane(ctx)) return;
+    ownsThisPane = true;
     const t = getTmux();
     if (!t) return;
     const rawSessionId = String(ctx.sessionManager.getSessionId());