@acpfx/bridge-acpx 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @acpfx/bridge-acpx
+
+## 0.2.0
+
+### Minor Changes
+
+- d757640: Initial release: type-safe contracts, Rust orchestrator, manifest-driven event filtering
+
+  - Rust schema crate as canonical event type source of truth with codegen to TypeScript + Zod
+  - Node manifests (manifest.yaml) declaring consumes/emits contracts
+  - Orchestrator event filtering: nodes only receive declared events
+  - Rust orchestrator with ratatui TUI (--ui flag)
+  - node-sdk with structured logging helpers
+  - CI/CD with GitHub Actions and changesets
+  - Platform-specific npm packages for Rust binaries (esbuild-style distribution)
+
+### Patch Changes
+
+- Updated dependencies [d757640]
+  - @acpfx/core@0.2.0
+  - @acpfx/node-sdk@0.2.0

package/manifest.yaml

@@ -0,0 +1,17 @@
+name: bridge-acpx
+description: Agent bridge connecting to Claude via ACP
+consumes:
+  - speech.partial
+  - speech.pause
+  - control.interrupt
+emits:
+  - agent.submit
+  - agent.delta
+  - agent.complete
+  - agent.thinking
+  - agent.tool_start
+  - agent.tool_done
+  - control.interrupt
+  - control.error
+  - lifecycle.ready
+  - lifecycle.done

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@acpfx/bridge-acpx",
+  "version": "0.2.0",
+  "type": "module",
+  "bin": {
+    "acpfx-bridge-acpx": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "dependencies": {
+    "@acpfx/core": "0.2.0",
+    "@acpfx/node-sdk": "0.2.0"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external"
+  }
+}

package/src/acpx-ipc.ts

@@ -0,0 +1,533 @@
+/**
+ * acpx Queue IPC client.
+ *
+ * Connects to acpx's queue owner Unix socket, submits prompts,
+ * streams responses (ACP JSON-RPC messages), and cancels.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as net from "node:net";
+import { log } from "@acpfx/node-sdk";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const SOCKET_CONNECT_TIMEOUT_MS = 5_000;
+const CONNECT_RETRY_MS = 50;
+const CONNECT_MAX_ATTEMPTS = 40;
+
+// --- Queue path resolution (mirrors acpx/src/queue-paths.ts) ---
+
+function shortHash(value: string, length: number): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+
+function queueKeyForSession(sessionId: string): string {
+  return shortHash(sessionId, 24);
+}
+
+function queueBaseDir(): string {
+  return path.join(os.homedir(), ".acpx", "queues");
+}
+
+function queueSocketPath(sessionId: string): string {
+  const key = queueKeyForSession(sessionId);
+  if (process.platform === "win32") {
+    return `\\\\.\\pipe\\acpx-${key}`;
+  }
+  const socketBase = path.join("/tmp", `acpx-${shortHash(os.homedir(), 10)}`);
+  return path.join(socketBase, `${key}.sock`);
+}
+
+function queueLockFilePath(sessionId: string): string {
+  return path.join(queueBaseDir(), `${queueKeyForSession(sessionId)}.lock`);
+}
+
+// --- Queue owner record ---
+
+type QueueOwnerRecord = {
+  pid: number;
+  sessionId: string;
+  socketPath: string;
+  ownerGeneration?: number;
+};
+
+async function readQueueOwnerRecord(
+  sessionId: string,
+): Promise<QueueOwnerRecord | undefined> {
+  const lockPath = queueLockFilePath(sessionId);
+  try {
+    const payload = await fs.readFile(lockPath, "utf8");
+    const parsed = JSON.parse(payload);
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      typeof parsed.pid !== "number" ||
+      typeof parsed.sessionId !== "string" ||
+      typeof parsed.socketPath !== "string"
+    ) {
+      return undefined;
+    }
+    return {
+      pid: parsed.pid,
+      sessionId: parsed.sessionId,
+      socketPath: parsed.socketPath,
+      ownerGeneration:
+        typeof parsed.ownerGeneration === "number"
+          ? parsed.ownerGeneration
+          : undefined,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+// --- Socket connection ---
+
+function connectToSocket(
+  socketPath: string,
+  timeoutMs = SOCKET_CONNECT_TIMEOUT_MS,
+): Promise<net.Socket> {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let settled = false;
+
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(
+        new Error(
+          `Connection to ${socketPath} timed out after ${timeoutMs}ms`,
+        ),
+      );
+    }, timeoutMs);
+
+    socket.once("connect", () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve(socket);
+    });
+
+    socket.once("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
+async function connectToQueueOwner(
+  owner: QueueOwnerRecord,
+): Promise<net.Socket | undefined> {
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt < CONNECT_MAX_ATTEMPTS; attempt++) {
+    try {
+      return await connectToSocket(owner.socketPath);
+    } catch (error) {
+      lastError = error;
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ECONNREFUSED") {
+        throw error;
+      }
+      await new Promise((r) => setTimeout(r, CONNECT_RETRY_MS));
+    }
+  }
+
+  return undefined;
+}
+
+// --- ACP message parsing ---
+
+type AcpTextDelta = {
+  type: "text_delta";
+  text: string;
+};
+
+type AcpStopReason = {
+  type: "stop_reason";
+  reason: string;
+};
+
+type AcpEvent = AcpTextDelta | AcpStopReason | { type: "other" };
+
+/**
+ * Extracts meaningful data from an ACP JSON-RPC message streamed from the queue owner.
+ * The queue owner wraps ACP messages in: { type: "event", requestId, message: AcpJsonRpcMessage }
+ * where AcpJsonRpcMessage is a JSON-RPC notification like:
+ * { method: "session/update", params: { update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "..." } } } }
+ */
+export function extractAcpEvent(acpMessage: Record<string, unknown>): AcpEvent {
+  // Check for session/update notifications with agent_message_chunk
+  if (acpMessage.method === "session/update") {
+    const params = acpMessage.params as Record<string, unknown> | undefined;
+    if (!params) return { type: "other" };
+    const update = params.update as Record<string, unknown> | undefined;
+    if (!update) return { type: "other" };
+
+    if (update.sessionUpdate === "agent_message_chunk") {
+      const content = update.content as Record<string, unknown> | undefined;
+      if (content && content.type === "text" && typeof content.text === "string") {
+        return { type: "text_delta", text: content.text };
+      }
+    }
+    return { type: "other" };
+  }
+
+  // Check for prompt completion (JSON-RPC response with result)
+  if (Object.hasOwn(acpMessage, "result")) {
+    const result = acpMessage.result as Record<string, unknown> | undefined;
+    if (result && typeof result.stopReason === "string") {
+      return { type: "stop_reason", reason: result.stopReason };
+    }
+  }
+
+  return { type: "other" };
+}
+
+// --- IPC client ---
+
+export type SubmitOptions = {
+  sessionId: string;
+  text: string;
+  onTextDelta: (delta: string, seq: number) => void;
+  onComplete: (fullText: string) => void;
+  onError: (error: Error) => void;
+  signal?: AbortSignal;
+};
+
+export type CancelResult = {
+  cancelled: boolean;
+};
+
+export class AcpxIpcClient {
+  private _sessionId: string;
+  private _verbose: boolean;
+
+  constructor(sessionId: string, opts?: { verbose?: boolean }) {
+    this._sessionId = sessionId;
+    this._verbose = opts?.verbose ?? false;
+  }
+
+  get sessionId(): string {
+    return this._sessionId;
+  }
+
+  /**
+   * Submit a prompt to the acpx queue owner and stream text deltas back.
+   * Returns the requestId. Calls onTextDelta for each chunk, onComplete when done.
+   */
+  async submitPrompt(opts: SubmitOptions): Promise<string> {
+    const owner = await readQueueOwnerRecord(this._sessionId);
+    if (!owner) {
+      throw new Error(
+        `No active acpx session found for "${this._sessionId}". ` +
+        `Start one with: acpx ${this._sessionId} "hello"`,
+      );
+    }
+
+    const socket = await connectToQueueOwner(owner);
+    if (!socket) {
+      throw new Error(
+        `Could not connect to acpx queue owner for session "${this._sessionId}"`,
+      );
+    }
+
+    const requestId = randomUUID();
+    let seq = 0;
+    let fullText = "";
+    let acknowledged = false;
+    let buffer = "";
+
+    const request = {
+      type: "submit_prompt",
+      requestId,
+      ownerGeneration: owner.ownerGeneration,
+      message: opts.text,
+      permissionMode: "approve-all",
+      waitForCompletion: true,
+    };
+
+    socket.setEncoding("utf8");
+
+    return new Promise<string>((resolve, reject) => {
+      let settled = false;
+
+      const cleanup = () => {
+        if (!socket.destroyed) {
+          socket.end();
+        }
+        socket.removeAllListeners();
+      };
+
+      const finish = (error?: Error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        if (error) {
+          opts.onError(error);
+          reject(error);
+        }
+      };
+
+      // Handle abort signal
+      if (opts.signal) {
+        if (opts.signal.aborted) {
+          cleanup();
+          reject(new Error("Aborted"));
+          return;
+        }
+        opts.signal.addEventListener("abort", () => {
+          finish(new Error("Aborted"));
+        }, { once: true });
+      }
+
+      const processLine = (line: string) => {
+        let parsed: Record<string, unknown>;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          return; // Skip malformed lines
+        }
+
+        if (typeof parsed.type !== "string") return;
+
+        // Check requestId matches
+        if (parsed.requestId !== requestId) return;
+
+        if (parsed.type === "accepted") {
+          acknowledged = true;
+          return;
+        }
+
+        if (!acknowledged) {
+          finish(new Error("Queue owner sent data before acknowledging request"));
+          return;
+        }
+
+        if (parsed.type === "error") {
+          const msg = typeof parsed.message === "string"
+            ? parsed.message
+            : "Queue owner error";
+          finish(new Error(msg));
+          return;
+        }
+
+        if (parsed.type === "event") {
+          const acpMessage = parsed.message as Record<string, unknown> | undefined;
+          if (!acpMessage) return;
+
+          const event = extractAcpEvent(acpMessage);
+          if (event.type === "text_delta") {
+            fullText += event.text;
+            opts.onTextDelta(event.text, seq++);
+          }
+          return;
+        }
+
+        if (parsed.type === "result") {
+          opts.onComplete(fullText);
+          if (!settled) {
+            settled = true;
+            cleanup();
+            resolve(requestId);
+          }
+          return;
+        }
+
+        if (parsed.type === "cancel_result") {
+          opts.onComplete(fullText);
+          if (!settled) {
+            settled = true;
+            cleanup();
+            resolve(requestId);
+          }
+          return;
+        }
+      };
+
+      socket.on("data", (chunk: string) => {
+        buffer += chunk;
+        let idx = buffer.indexOf("\n");
+        while (idx >= 0) {
+          const line = buffer.slice(0, idx).trim();
+          buffer = buffer.slice(idx + 1);
+          if (line.length > 0) {
+            processLine(line);
+          }
+          idx = buffer.indexOf("\n");
+        }
+      });
+
+      socket.once("error", (err: Error) => {
+        finish(err);
+      });
+
+      socket.once("close", () => {
+        if (!settled) {
+          if (!acknowledged) {
+            finish(new Error("Queue owner disconnected before acknowledging request"));
+          } else {
+            // Connection closed after acknowledgement, treat as completion
+            opts.onComplete(fullText);
+            settled = true;
+            cleanup();
+            resolve(requestId);
+          }
+        }
+      });
+
+      // Send the request
+      socket.write(JSON.stringify(request) + "\n");
+
+      if (this._verbose) {
+        log.debug(`submitted prompt to session ${this._sessionId} (requestId: ${requestId})`);
+      }
+    });
+  }
+
+  /**
+   * Cancel a running prompt on the acpx queue owner.
+   */
+  async cancelPrompt(): Promise<CancelResult> {
+    const owner = await readQueueOwnerRecord(this._sessionId);
+    if (!owner) {
+      return { cancelled: false };
+    }
+
+    const socket = await connectToQueueOwner(owner);
+    if (!socket) {
+      return { cancelled: false };
+    }
+
+    const requestId = randomUUID();
+    const request = {
+      type: "cancel_prompt",
+      requestId,
+      ownerGeneration: owner.ownerGeneration,
+    };
+
+    socket.setEncoding("utf8");
+
+    return new Promise<CancelResult>((resolve) => {
+      let settled = false;
+      let buffer = "";
+
+      const timeout = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        socket.destroy();
+        resolve({ cancelled: false });
+      }, SOCKET_CONNECT_TIMEOUT_MS);
+
+      socket.on("data", (chunk: string) => {
+        buffer += chunk;
+        let idx = buffer.indexOf("\n");
+        while (idx >= 0) {
+          const line = buffer.slice(0, idx).trim();
+          buffer = buffer.slice(idx + 1);
+          if (line.length > 0) {
+            try {
+              const parsed = JSON.parse(line);
+              if (parsed.requestId === requestId) {
+                if (parsed.type === "accepted") {
+                  // Wait for cancel_result
+                } else if (parsed.type === "cancel_result") {
+                  if (!settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    socket.end();
+                    resolve({ cancelled: parsed.cancelled === true });
+                  }
+                } else if (parsed.type === "error") {
+                  if (!settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    socket.end();
+                    resolve({ cancelled: false });
+                  }
+                }
+              }
+            } catch {
+              // Skip malformed
+            }
+          }
+          idx = buffer.indexOf("\n");
+        }
+      });
+
+      socket.once("error", () => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timeout);
+          resolve({ cancelled: false });
+        }
+      });
+
+      socket.once("close", () => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timeout);
+          resolve({ cancelled: false });
+        }
+      });
+
+      socket.write(JSON.stringify(request) + "\n");
+
+      if (this._verbose) {
+        log.debug(`cancel request sent to session ${this._sessionId}`);
+      }
+    });
+  }
+}
+
+// --- Session resolution ---
+
+/**
+ * Find the session ID for a given agent name.
+ * Looks at ~/.acpx/sessions/ index to find the most recent open session
+ * for the given agent command.
+ */
+export async function resolveSessionId(
+  agentName: string,
+  sessionName?: string,
+): Promise<string | undefined> {
+  const indexPath = path.join(os.homedir(), ".acpx", "sessions", "index.json");
+  try {
+    const data = await fs.readFile(indexPath, "utf8");
+    const raw = JSON.parse(data);
+
+    const entries: unknown[] = Array.isArray(raw) ? raw : Array.isArray(raw?.entries) ? raw.entries : [];
+    if (entries.length === 0) return undefined;
+
+    type IndexEntry = {
+      acpxRecordId?: string;
+      acpSessionId?: string;
+      agentCommand?: string;
+      name?: string;
+      closed?: boolean;
+      lastUsedAt?: string;
+    };
+
+    const matches = (entries as IndexEntry[])
+      .filter(
+        (entry) =>
+          entry.agentCommand &&
+          entry.agentCommand.includes(agentName) &&
+          !entry.closed &&
+          (entry.acpxRecordId || entry.acpSessionId) &&
+          // If sessionName specified, match it; otherwise match unnamed sessions
+          (sessionName ? entry.name === sessionName : !entry.name || entry.name === ""),
+      )
+      .sort((a, b) =>
+        (b.lastUsedAt ?? "").localeCompare(a.lastUsedAt ?? ""),
+      );
+
+    return matches[0]?.acpxRecordId ?? matches[0]?.acpSessionId;
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,317 @@
+/**
+ * bridge-acpx node — reads speech.pause events, submits to acpx CLI,
+ * streams agent.submit/agent.delta/agent.complete events.
+ * Handles control.interrupt by killing the active process + acpx cancel.
+ *
+ * Uses `acpx --format json` for structured ACP output instead of
+ * direct socket IPC. acpx handles session management, queue owner
+ * lifecycle, and agent reconnection.
+ *
+ * Settings:
+ *   agent: string (required)  — agent name (claude, codex, pi, etc.)
+ *   session?: string          — named session (maps to acpx -s <name>)
+ *   args?: Record<string, string | boolean> — extra acpx CLI flags
+ *   verbose?: boolean
+ */
+
+import { randomUUID } from "node:crypto";
+import { spawn, execSync, type ChildProcess } from "node:child_process";
+import { appendFileSync, writeFileSync } from "node:fs";
+import { emit, log, onEvent, handleManifestFlag } from "@acpfx/node-sdk";
+
+handleManifestFlag();
+
+type Settings = {
+  agent: string;
+  session?: string;
+  args?: Record<string, string | boolean>;
+  verbose?: boolean;
+};
+
+const settings: Settings = JSON.parse(process.env.ACPFX_SETTINGS || "{}");
+
+if (!settings.agent) {
+  log.error("settings.agent is required");
+  process.exit(1);
+}
+
+const AGENT = settings.agent;
+const VERBOSE = settings.verbose ?? false;
+const NODE_NAME = process.env.ACPFX_NODE_NAME ?? "bridge";
+
+let activeChild: ChildProcess | null = null;
+let interrupted = false;
+let streaming = false;
+let agentResponding = false;
+
+
+/** Build CLI args from settings.args */
+function buildExtraArgs(): string[] {
+  const args: string[] = [];
+  if (!settings.args) return args;
+  for (const [key, value] of Object.entries(settings.args)) {
+    const flag = key.length === 1 ? `-${key}` : `--${key}`;
+    if (value === true) {
+      args.push(flag);
+    } else if (typeof value === "string") {
+      args.push(flag, value);
+    }
+  }
+  return args;
+}
+
+/**
+ * Ensure an acpx session exists.
+ * `sessions ensure` creates the record; the first prompt bootstraps the queue owner.
+ */
+function ensureSession(): void {
+  log.info(`Ensuring session for "${AGENT}"${settings.session ? ` (session: ${settings.session})` : ""}...`);
+
+  const args = ["acpx@latest", AGENT, "sessions", "ensure"];
+  if (settings.session) args.push("--name", settings.session);
+
+  try {
+    const output = execSync(["npx", "-y", ...args].join(" "), {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
+      timeout: 30000,
+      encoding: "utf8",
+    });
+    log.info(`Session: ${output.trim()}`);
+  } catch (err) {
+    log.warn(`sessions ensure failed: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+/**
+ * Submit a prompt via `acpx --format json` and stream deltas.
+ */
+function handleSpeechPause(pendingText: string): void {
+  if (interrupted) return;
+
+  const requestId = randomUUID();
+  streaming = true;
+
+  emit({ type: "agent.submit", requestId, text: pendingText });
+
+  // Build acpx command: npx -y acpx@latest --format json [extra-args] <agent> -s <session> "text"
+  const args = [
+    "-y", "acpx@latest",
+    "--format", "json",
+    ...buildExtraArgs(),
+    AGENT,
+  ];
+  if (settings.session) args.push("-s", settings.session);
+  args.push(pendingText);
+
+  const child = spawn("npx", args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env,
+  });
+  activeChild = child;
+
+  let seq = 0;
+  let fullText = "";
+  let buffer = "";
+
+  let emittedThinking = false;
+
+  const processLine = (line: string) => {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    // Handle session/update events
+    if (msg.method === "session/update") {
+      const params = msg.params as Record<string, unknown> | undefined;
+      const update = params?.update as Record<string, unknown> | undefined;
+      if (!update) return;
+
+      const sessionUpdate = update.sessionUpdate as string;
+      // Log all non-chunk session updates to debug event flow
+      if (sessionUpdate !== "agent_message_chunk" && sessionUpdate !== "usage_update" && sessionUpdate !== "available_commands_update") {
+        log.debug(`ACP: ${sessionUpdate} ${JSON.stringify(update).slice(0, 200)}`);
+      }
+
+      // Thinking chunks
+      if (sessionUpdate === "agent_thought_chunk") {
+        if (!emittedThinking) {
+          emittedThinking = true;
+          emit({ type: "agent.thinking", requestId });
+        }
+        return;
+      }
+
+      // Tool call started — tool_call event means a new tool invocation
+      if (sessionUpdate === "tool_call") {
+        emit({
+          type: "agent.tool_start",
+          requestId,
+          toolCallId: (typeof update.toolCallId === "string" ? update.toolCallId : ""),
+        });
+        return;
+      }
+
+      // Tool call completed/failed
+      if (sessionUpdate === "tool_call_update") {
+        const status = update.status as string | undefined;
+        if (status === "completed" || status === "failed") {
+          emit({
+            type: "agent.tool_done",
+            requestId,
+            toolCallId: (update.toolCallId as string) ?? "",
+            status,
+          });
+        }
+        return;
+      }
+
+      // Text generation
+      if (sessionUpdate === "agent_message_chunk") {
+        const content = update.content as Record<string, unknown> | undefined;
+        if (content?.type === "text" && typeof content.text === "string" && content.text) {
+          fullText += content.text;
+          agentResponding = true;
+          emit({ type: "agent.delta", requestId, delta: content.text, seq: seq++ });
+        }
+        return;
+      }
+
+      return;
+    }
+
+    // Look for completion: JSON-RPC result with stopReason
+    if (Object.hasOwn(msg, "result") && typeof msg.id === "number") {
+      const result = msg.result as Record<string, unknown> | undefined;
+      if (result && typeof result.stopReason === "string") {
+        if (!interrupted) {
+          emit({ type: "agent.complete", requestId, text: fullText });
+        }
+      }
+    }
+  };
+
+  writeFileSync("/tmp/acpfx-bridge-raw.log", "");
+  child.stdout!.setEncoding("utf8");
+  child.stdout!.on("data", (chunk: string) => {
+    appendFileSync("/tmp/acpfx-bridge-raw.log", chunk);
+    buffer += chunk;
+    let idx = buffer.indexOf("\n");
+    while (idx >= 0) {
+      const line = buffer.slice(0, idx).trim();
+      buffer = buffer.slice(idx + 1);
+      if (line.length > 0) processLine(line);
+      idx = buffer.indexOf("\n");
+    }
+  });
+
+  if (VERBOSE) {
+    child.stderr!.setEncoding("utf8");
+    child.stderr!.on("data", (chunk: string) => {
+      log.debug(`acpx stderr: ${chunk.trimEnd()}`);
+    });
+  }
+
+  child.on("close", (code, _signal) => {
+    if (activeChild === child) activeChild = null;
+    streaming = false;
+
+    // null code + signal means we killed it (SIGTERM on cancel) — not an error
+    if (code !== 0 && code !== null && !interrupted) {
+      log.error(`acpx exited with code ${code}`);
+      emit({
+        type: "control.error",
+        component: "bridge-acpx",
+        message: `acpx exited with code ${code}`,
+        fatal: false,
+      });
+    }
+  });
+}
+
+/**
+ * Cancel the active prompt: kill process + acpx cancel command.
+ */
+function cancelCurrentPrompt(): void {
+  if (activeChild) {
+    activeChild.kill("SIGTERM");
+    activeChild = null;
+  }
+
+  // Fire-and-forget cancel to the queue owner
+  const args = ["-y", "acpx@latest", AGENT, "cancel"];
+  if (settings.session) args.push("-s", settings.session);
+
+  const cancel = spawn("npx", args, {
+    stdio: "ignore",
+    detached: true,
+    env: process.env,
+  });
+  cancel.unref();
+
+  streaming = false;
+}
+
+// --- Main ---
+
+function main(): void {
+  ensureSession();
+
+  emit({ type: "lifecycle.ready", component: "bridge-acpx" });
+
+  let active = false;
+  let interruptedForBargein = false;
+  let accumulatedText = "";
+
+  const rl = onEvent((event) => {
+      if (event.type === "speech.partial" && active && !interruptedForBargein) {
+        log.info("Barge-in detected (speech.partial while active) — interrupting");
+        interruptedForBargein = true;
+        emit({ type: "control.interrupt", reason: "user_speech" });
+        if (streaming) cancelCurrentPrompt();
+      } else if (event.type === "speech.pause") {
+        interruptedForBargein = false;
+        active = true;
+        const text = (event.pendingText as string) ?? (event.text as string) ?? "";
+        if (text) {
+          emit({ type: "control.interrupt", reason: "user_speech" });
+
+          if (agentResponding) {
+            // Agent already responded — this is a new turn, clear accumulator
+            accumulatedText = text;
+            agentResponding = false;
+          } else if (streaming) {
+            // Agent hasn't responded yet — append to accumulator and resubmit
+            cancelCurrentPrompt();
+            accumulatedText = accumulatedText ? accumulatedText + " " + text : text;
+          } else {
+            // Fresh submission
+            accumulatedText = accumulatedText ? accumulatedText + " " + text : text;
+          }
+
+          handleSpeechPause(accumulatedText);
+        }
+      } else if (event.type === "control.interrupt" && event._from !== NODE_NAME) {
+        // Ignore our own interrupts that cycled back through the graph
+        interrupted = true;
+        cancelCurrentPrompt();
+        interrupted = false;
+      }
+  });
+
+  rl.on("close", () => {
+    if (streaming) cancelCurrentPrompt();
+    emit({ type: "lifecycle.done", component: "bridge-acpx" });
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", () => {
+    if (streaming) cancelCurrentPrompt();
+    process.exit(0);
+  });
+}
+
+main();