aibroker 0.24.0 → 0.25.0

package/hooks/aibroker-hook-lib.mjs

@@ -0,0 +1,223 @@
+/**
+ * aibroker-hook-lib.mjs — shared helpers for AIBroker Claude Code hooks.
+ *
+ * These hooks make channel routing DETERMINISTIC instead of relying on the LLM
+ * to remember to call pailot_tts / pailot_send. They are pure IPC clients:
+ * they talk to the running AIBroker daemon over /tmp/aibroker.sock using the
+ * exact same wire protocol as src/ipc/client.ts — no daemon changes required.
+ *
+ * Everything here is defensive: any failure resolves to a safe no-op so a hook
+ * can never block or crash a Claude Code turn.
+ */
+
+import { connect } from "node:net";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { randomUUID, createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const AIBROKER_SOCKET = "/tmp/aibroker.sock";
+const IPC_TIMEOUT_MS = 8_000;
+
+// ── stdin / hook payload ──────────────────────────────────────────────────
+
+/** Read all of stdin as a string. */
+export async function readStdin() {
+  let input = "";
+  const decoder = new TextDecoder();
+  try {
+    for await (const chunk of process.stdin) {
+      input += decoder.decode(chunk, { stream: true });
+    }
+  } catch {
+    /* ignore */
+  }
+  return input;
+}
+
+/** Parse the Claude Code hook payload (Stop / PreToolUse share these fields). */
+export function parseHookInput(raw) {
+  try {
+    const p = JSON.parse(raw);
+    return {
+      transcriptPath: p.transcript_path ?? "",
+      cwd: p.cwd ?? process.cwd(),
+      sessionId: p.session_id ?? "",
+      toolName: p.tool_name ?? "",
+      toolInput: p.tool_input ?? {},
+      stopHookActive: p.stop_hook_active === true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ── transcript parsing ────────────────────────────────────────────────────
+
+export function readTranscriptLines(path) {
+  try {
+    return readFileSync(path, "utf-8").trim().split("\n");
+  } catch {
+    return [];
+  }
+}
+
+function parseLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return the text blocks of a message's content as a string array.
+ * String content → [string]. Array content → the `text` blocks only
+ * (tool_use / tool_result / image blocks are ignored).
+ */
+function textBlocks(content) {
+  if (typeof content === "string") return content.trim() ? [content] : [];
+  if (Array.isArray(content)) {
+    const out = [];
+    for (const c of content) {
+      if (typeof c === "string" && c.trim()) out.push(c);
+      else if (c && c.type === "text" && typeof c.text === "string" && c.text.trim()) out.push(c.text);
+    }
+    return out;
+  }
+  return [];
+}
+
+/**
+ * Find the MOST RECENT genuine human prompt (a user-role message that carries
+ * real text, not a bare tool_result). Returns { index, blocks } or null.
+ *
+ * Only the latest human prompt decides routing — this enforces per-message
+ * independence (an earlier PAILot turn must not affect a later terminal turn).
+ */
+export function findLastHumanPrompt(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const e = parseLine(lines[i]);
+    if (!e || e.type !== "user" || e.message?.role !== "user") continue;
+    const blocks = textBlocks(e.message.content);
+    if (blocks.length > 0) return { index: i, blocks };
+  }
+  return null;
+}
+
+const PREFIX_RE = /^\s*\[(PAILot|Whazaa|Telex)(:voice)?\]/i;
+
+/**
+ * Detect a channel prefix, anchored to the START of a text block. AIBroker
+ * string-prepends the prefix (e.g. "[PAILot:voice] …"), so anchoring means a
+ * terminal message that merely *mentions* the token cannot trigger delivery.
+ * Returns { channel: 'pailot'|'whazaa'|'telex', voice: boolean } or null.
+ */
+export function detectChannel(blocks) {
+  for (const b of blocks) {
+    const m = b.match(PREFIX_RE);
+    if (m) return { channel: m[1].toLowerCase(), voice: !!m[2] };
+  }
+  return null;
+}
+
+/**
+ * Scan the current turn (lines AFTER the prompt) for which reply tools the
+ * assistant actually called. Matches by tool-name substring so it works for the
+ * fully-qualified MCP names (e.g. "mcp__aibroker__pailot_tts").
+ */
+export function scanReplyTools(lines, fromIdx) {
+  let tts = false;
+  let send = false;
+  for (let i = fromIdx + 1; i < lines.length; i++) {
+    const e = parseLine(lines[i]);
+    if (!e || e.type !== "assistant" || !Array.isArray(e.message?.content)) continue;
+    for (const c of e.message.content) {
+      if (c && c.type === "tool_use" && typeof c.name === "string") {
+        if (c.name.includes("pailot_tts")) tts = true;
+        if (c.name.includes("pailot_send")) send = true;
+      }
+    }
+  }
+  return { tts, send };
+}
+
+/** The last non-empty assistant text in the current turn (the final answer). */
+export function lastAssistantText(lines, fromIdx) {
+  for (let i = lines.length - 1; i > fromIdx; i--) {
+    const e = parseLine(lines[i]);
+    if (!e || e.type !== "assistant") continue;
+    const blocks = textBlocks(e.message?.content);
+    if (blocks.length > 0) return blocks.join("\n\n").trim();
+  }
+  return "";
+}
+
+// ── IPC to the AIBroker daemon ────────────────────────────────────────────
+
+/**
+ * Call a daemon method over the Unix socket. Mirrors src/ipc/client.ts framing
+ * (one JSON line in, one JSON line out). Passes through the terminal's session
+ * identifiers so the daemon can resolve the correct target session. Resolves
+ * { ok, result?, error? }; never rejects.
+ */
+export function ipcCall(method, params) {
+  return new Promise((resolve) => {
+    let done = false;
+    let buffer = "";
+    let timer = null;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      if (timer) clearTimeout(timer);
+      try { sock.destroy(); } catch { /* ignore */ }
+      resolve(v);
+    };
+    const sock = connect(AIBROKER_SOCKET, () => {
+      const req = { id: randomUUID(), sessionId: process.env.TERM_SESSION_ID ?? "hook", method, params };
+      if (process.env.ITERM_SESSION_ID) req.itermSessionId = process.env.ITERM_SESSION_ID;
+      if (process.env.TMUX_PANE) req.tmuxPane = process.env.TMUX_PANE;
+      sock.write(JSON.stringify(req) + "\n");
+    });
+    sock.on("data", (chunk) => {
+      buffer += chunk.toString();
+      const nl = buffer.indexOf("\n");
+      if (nl === -1) return;
+      try {
+        finish(JSON.parse(buffer.slice(0, nl)));
+      } catch {
+        finish({ ok: false, error: "parse" });
+      }
+    });
+    sock.on("error", () => finish({ ok: false, error: "socket" }));
+    sock.on("end", () => finish({ ok: false, error: "closed" }));
+    timer = setTimeout(() => finish({ ok: false, error: "timeout" }), IPC_TIMEOUT_MS);
+  });
+}
+
+/** Deliver text (or voice) to PAILot via the existing pailot_send IPC. */
+export function pailotDeliver(text, voice) {
+  return ipcCall("pailot_send", { text, voice: !!voice });
+}
+
+// ── per-turn dedupe markers ───────────────────────────────────────────────
+
+export function hashPrompt(text) {
+  return createHash("sha1").update(text).digest("hex").slice(0, 16);
+}
+
+/**
+ * Returns true the FIRST time it is called for a given (kind, sessionId, hash)
+ * and false thereafter — so a hook fires at most once per turn.
+ */
+export function claimOnce(kind, sessionId, hash) {
+  try {
+    const marker = join(tmpdir(), `aibroker-${kind}-${sessionId || "x"}-${hash}.done`);
+    if (existsSync(marker)) return false;
+    writeFileSync(marker, String(Date.now()));
+    return true;
+  } catch {
+    // If the marker can't be written, allow the action rather than suppress it.
+    return true;
+  }
+}

package/hooks/aibroker-progress.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * aibroker-progress.mjs — PreToolUse hook (matcher: Task). Layer 2.
+ *
+ * When the assistant spawns a Task (research / long work) during a turn that
+ * originated from PAILot, push a one-time progress note to the channel so the
+ * user — e.g. driving, listening — knows the session is working and an answer
+ * is coming. Without this, "I'll research this and report back" only ever
+ * reaches the terminal.
+ *
+ * Voice turns get ONE short spoken ack (not per-tool audio spam). Text turns
+ * get a text line describing the work. Fires at most once per turn.
+ *
+ * Always allows the tool (exit 0). Terminal turns → no-op.
+ */
+
+import {
+  readStdin, parseHookInput, readTranscriptLines,
+  findLastHumanPrompt, detectChannel,
+  pailotDeliver, hashPrompt, claimOnce,
+} from "./aibroker-hook-lib.mjs";
+
+const VOICE_ACK = "On it — I'm working on that now and I'll speak the answer as soon as it's ready.";
+
+async function main() {
+  const input = await parseHookInput(await readStdin());
+  // The subagent-spawn tool is "Task" in some harnesses, "Agent" in others.
+  if (!input || (input.toolName !== "Task" && input.toolName !== "Agent") || !input.transcriptPath) return;
+
+  const lines = readTranscriptLines(input.transcriptPath);
+  if (lines.length === 0) return;
+
+  const prompt = findLastHumanPrompt(lines);
+  if (!prompt) return;
+
+  const chan = detectChannel(prompt.blocks);
+  if (!chan || chan.channel !== "pailot") return;
+
+  // One progress signal per turn.
+  const hash = hashPrompt(prompt.blocks.join("\n"));
+  if (!claimOnce("progress", input.sessionId, hash)) return;
+
+  if (chan.voice) {
+    await pailotDeliver(VOICE_ACK, true);
+  } else {
+    const desc = typeof input.toolInput?.description === "string" && input.toolInput.description.trim()
+      ? input.toolInput.description.trim()
+      : "Working on your request";
+    await pailotDeliver(`🔧 ${desc}… I'll report back when done.`, false);
+  }
+}
+
+main().catch(() => {}).finally(() => process.exit(0));

package/hooks/aibroker-route-guard.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * aibroker-route-guard.mjs — Stop hook. Layer 1 of bulletproof channel routing.
+ *
+ * When a turn ends, inspect the triggering prompt. If it came from a channel
+ * (starts with [PAILot] / [PAILot:voice]) but the matching reply tool was NOT
+ * called during the turn, the answer went only to the terminal — a routing
+ * miss. This guard then delivers the final answer to the channel itself over
+ * the existing pailot_send IPC, so a voice question can never get zero answer.
+ *
+ * Scope: PAILot (text + voice). Whazaa/Telex replies need recipient context the
+ * hook doesn't have, so they are detected but left to the normal flow.
+ *
+ * Fails safe: any error → exit 0, no delivery. Terminal turns → no-op.
+ */
+
+import {
+  readStdin, parseHookInput, readTranscriptLines,
+  findLastHumanPrompt, detectChannel, scanReplyTools, lastAssistantText,
+  pailotDeliver, hashPrompt, claimOnce,
+} from "./aibroker-hook-lib.mjs";
+
+const DEBUG = process.env.AIBROKER_HOOK_DEBUG === "1";
+const dbg = (m) => { if (DEBUG) console.error(`[route-guard] ${m}`); };
+
+async function main() {
+  const input = await parseHookInput(await readStdin());
+  if (!input || !input.transcriptPath) return;
+
+  const lines = readTranscriptLines(input.transcriptPath);
+  if (lines.length === 0) return;
+
+  const prompt = findLastHumanPrompt(lines);
+  if (!prompt) { dbg("no human prompt"); return; }
+
+  const chan = detectChannel(prompt.blocks);
+  if (!chan) { dbg("terminal turn — no prefix, no-op"); return; }
+
+  // Only PAILot is auto-deliverable (self-resolving session). Others: leave be.
+  if (chan.channel !== "pailot") { dbg(`channel ${chan.channel} out of scope`); return; }
+
+  const { tts, send } = scanReplyTools(lines, prompt.index);
+  // voice-in requires voice-out (pailot_tts). text-in is satisfied by either.
+  const answered = chan.voice ? tts : (send || tts);
+  if (answered) { dbg("already answered on channel — no-op"); return; }
+
+  const answer = lastAssistantText(lines, prompt.index);
+  if (!answer) { dbg("no assistant text to deliver"); return; }
+
+  // Fire at most once per turn.
+  const hash = hashPrompt(prompt.blocks.join("\n"));
+  if (!claimOnce("guard", input.sessionId, hash)) { dbg("already delivered this turn"); return; }
+
+  const res = await pailotDeliver(answer, chan.voice);
+  if (res?.ok) {
+    console.error(`[route-guard] recovered routing miss → delivered answer to PAILot${chan.voice ? " (voice)" : ""}.`);
+  } else {
+    dbg(`delivery failed: ${res?.error ?? "unknown"}`);
+  }
+}
+
+main().catch(() => {}).finally(() => process.exit(0));

package/hooks/drain-mailbox.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * hooks/drain-mailbox.mjs — deliver what the mailbox is holding.
+ *
+ * `send_to_session` deposits into the target's mailbox and types a copy into
+ * its terminal. The typed copy is best-effort — a session mid-turn never reads
+ * it — and the mailbox was pull-only, so a message only arrived if the session
+ * happened to call `aibroker_receive`. It usually did not: 35 real messages
+ * across five sessions sat undrained on 2026-08-01/02, the oldest for a day.
+ *
+ * A UserPromptSubmit hook is the natural drain. It runs before the model sees
+ * the turn, which is the first moment a busy session is listening again, so
+ * anything queued is injected as context on the very next turn rather than
+ * whenever someone thinks to check.
+ *
+ * DRAINING IS DESTRUCTIVE — the daemon empties the mailbox as it reads it — so
+ * this must not swallow what it cannot deliver. If the output cannot be
+ * emitted, the messages are written to ~/.aibroker/undelivered.jsonl rather
+ * than lost, which is the whole failure this hook exists to end.
+ *
+ * Silent when there is nothing waiting, and silent on every error: a hook that
+ * fails loudly on every prompt is a hook someone disables.
+ */
+
+import net from "node:net";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const SOCKET = "/tmp/aibroker.sock";
+const TIMEOUT_MS = 1500;
+const UNDELIVERED = join(homedir(), ".aibroker", "undelivered.jsonl");
+
+/** The session this hook is running inside. Without it there is nothing to drain. */
+function sessionId() {
+  const raw = process.env.TMUX_PANE ?? process.env.ITERM_SESSION_ID;
+  if (!raw) return undefined;
+  return raw.includes(":") ? raw.split(":").pop() : raw;
+}
+
+function call(method, params) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+    const timer = setTimeout(() => { try { sock.destroy(); } catch {} finish(null); }, TIMEOUT_MS);
+    const sock = net.createConnection(SOCKET, () => {
+      sock.write(JSON.stringify({ id: "drain", method, params }) + "\n");
+    });
+    let buf = "";
+    sock.on("data", (d) => {
+      buf += d;
+      if (!buf.includes("\n")) return;
+      clearTimeout(timer);
+      try { finish(JSON.parse(buf.trim())); } catch { finish(null); }
+      sock.end();
+    });
+    // The daemon being down is not this hook's problem to report.
+    sock.on("error", () => { clearTimeout(timer); finish(null); });
+  });
+}
+
+const id = sessionId();
+if (!id) process.exit(0);
+
+const res = await call("session_mailbox_receive", { sessionId: id });
+const messages = res?.ok ? (res.result?.messages ?? []) : [];
+if (messages.length === 0) process.exit(0);
+
+const lines = messages.map((m) => {
+  const when = m.timestamp ? new Date(m.timestamp).toISOString().slice(11, 19) : "";
+  const waited = m.timestamp ? Math.round((Date.now() - m.timestamp) / 60000) : null;
+  const age = waited !== null && waited >= 1 ? ` (waited ${waited} min)` : "";
+  return `[Session:${m.from}] ${when}${age}\n${m.content}`;
+});
+
+const out =
+  `<system-reminder>\n` +
+  `${messages.length} message(s) were waiting in this session's mailbox and have been delivered now.\n` +
+  `They arrived while this session was busy. Treat each as if it had just been sent: reply to the\n` +
+  `sender with aibroker_send_to_session, not in the terminal.\n\n` +
+  lines.join("\n\n") +
+  `\n</system-reminder>`;
+
+try {
+  process.stdout.write(out + "\n");
+} catch (e) {
+  // The drain already emptied the mailbox. Losing them here would be the exact
+  // silent drop this hook was written to stop.
+  try {
+    mkdirSync(join(homedir(), ".aibroker"), { recursive: true });
+    appendFileSync(UNDELIVERED, messages.map((m) => JSON.stringify({ ...m, failedAt: new Date().toISOString(), error: String(e) })).join("\n") + "\n");
+  } catch { /* nothing left to try */ }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aibroker",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Platform-agnostic AI message broker — routes between user channels and AI backends",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
     "dist",
     "templates",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "hooks"
   ],
   "bin": {
     "aibroker": "dist/daemon/cli.js",