@snowyroad/arp 0.1.0

package/dist/cli.js

@@ -0,0 +1,1878 @@
+#!/usr/bin/env node
+
+// src/invite.ts
+var REQUIRED_FIELDS = ["relayUrl", "code"];
+function decodeInvite(code) {
+  const trimmed = (code ?? "").trim();
+  if (trimmed === "") throw new Error("Invalid invite: empty");
+  const json = Buffer.from(trimmed, "base64url").toString("utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw new Error("Invalid invite: payload is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("Invalid invite: payload is not an object");
+  }
+  const p = parsed;
+  for (const field of REQUIRED_FIELDS) {
+    const v = p[field];
+    if (typeof v !== "string" || v.trim() === "") {
+      throw new Error(`Invalid invite: missing or empty field "${field}"`);
+    }
+  }
+  const relayUrl = p.relayUrl.trim();
+  if (!/^wss?:\/\//.test(relayUrl)) {
+    throw new Error("Invalid invite: relayUrl must start with ws:// or wss://");
+  }
+  return {
+    relayUrl,
+    code: p.code.trim()
+  };
+}
+
+// src/redeem.ts
+async function redeemInvite(relayHttpUrl, code) {
+  const res = await fetch(`${relayHttpUrl.replace(/\/$/, "")}/invites/redeem`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ code })
+  });
+  if (res.status === 410) {
+    throw new Error("This invite has expired or been revoked. Ask an admin to mint a new one.");
+  }
+  if (!res.ok) {
+    throw new Error(`Invite redemption failed (HTTP ${res.status}).`);
+  }
+  const data = await res.json();
+  if (!data.ok || !data.token || !data.agentId || !data.agentUuid || !data.channelId) {
+    throw new Error("Invite redemption returned an incomplete response.");
+  }
+  return {
+    token: data.token,
+    agentId: data.agentId,
+    agentName: data.agentName ?? data.agentId,
+    agentUuid: data.agentUuid,
+    channelId: data.channelId
+  };
+}
+
+// src/config.ts
+var DEFAULT_MODEL = "claude-opus-4-8";
+var DEFAULT_AGENT_MODE = "acp";
+var DEFAULT_AGENT = "claude-code";
+var VALID_AGENT_MODES = ["acp", "generic"];
+var VALID_AGENTS = ["claude-code", "codex", "gemini", "grok", "cursor"];
+function positiveIntEnv(v, dflt) {
+  const n = v == null ? NaN : Number(v);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : dflt;
+}
+function required(env, key) {
+  const v = env[key];
+  if (!v || v.trim() === "") throw new Error(`Missing required env var: ${key}`);
+  return v.trim();
+}
+function resolveAgentSelection(env) {
+  const agentMode = env.ARP_AGENT_MODE?.trim() || DEFAULT_AGENT_MODE;
+  if (!VALID_AGENT_MODES.includes(agentMode)) {
+    throw new Error(
+      `Invalid ARP_AGENT_MODE: ${agentMode}. Expected one of: ${VALID_AGENT_MODES.join(", ")}`
+    );
+  }
+  const agent = env.ARP_AGENT?.trim() || DEFAULT_AGENT;
+  if (!VALID_AGENTS.includes(agent)) {
+    throw new Error(
+      `Invalid ARP_AGENT: ${agent}. Expected one of: ${VALID_AGENTS.join(", ")}`
+    );
+  }
+  if (agentMode === "generic") required(env, "ANTHROPIC_API_KEY");
+  return { agentMode, agent };
+}
+function loadConfig(env) {
+  const { agentMode, agent } = resolveAgentSelection(env);
+  const relayWsUrl = required(env, "ARP_RELAY_URL");
+  if (!/^wss?:\/\//.test(relayWsUrl)) {
+    throw new Error(`ARP_RELAY_URL must start with ws:// or wss://, got: ${relayWsUrl}`);
+  }
+  const relayHttpUrl = relayWsUrl.replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://");
+  const agentName = required(env, "ARP_AGENT_NAME");
+  return {
+    relayWsUrl,
+    relayHttpUrl,
+    token: required(env, "ARP_TOKEN"),
+    agentId: required(env, "ARP_AGENT_ID"),
+    agentName,
+    agentUuid: required(env, "ARP_AGENT_UUID"),
+    agentMode,
+    agent,
+    model: env.ARP_MODEL?.trim() || DEFAULT_MODEL,
+    catchUpTtlMs: positiveIntEnv(env.ARP_CATCHUP_TTL_MS, 72e5),
+    catchUpMaxMentions: positiveIntEnv(env.ARP_CATCHUP_MAX_MENTIONS, 3)
+  };
+}
+async function loadConfigFromInvite(code, env) {
+  const { agentMode, agent } = resolveAgentSelection(env);
+  const inv = decodeInvite(code);
+  const relayWsUrl = inv.relayUrl;
+  const relayHttpUrl = relayWsUrl.replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://");
+  const bundle = await redeemInvite(relayHttpUrl, inv.code);
+  return {
+    relayWsUrl,
+    relayHttpUrl,
+    token: bundle.token,
+    agentId: bundle.agentId,
+    agentName: bundle.agentName,
+    agentUuid: bundle.agentUuid,
+    agentMode,
+    agent,
+    model: env.ARP_MODEL?.trim() || DEFAULT_MODEL,
+    catchUpTtlMs: positiveIntEnv(env.ARP_CATCHUP_TTL_MS, 72e5),
+    catchUpMaxMentions: positiveIntEnv(env.ARP_CATCHUP_MAX_MENTIONS, 3)
+  };
+}
+function getFlag(argv, name) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === name) return argv[i + 1] ?? "";
+    if (a.startsWith(`${name}=`)) return a.slice(name.length + 1);
+  }
+  return void 0;
+}
+async function resolveConfig(argv, env) {
+  if (argv[0] === "join") {
+    const code = argv[1];
+    if (!code || code.trim() === "") throw new Error("Missing value for join");
+    return loadConfigFromInvite(code.trim(), env);
+  }
+  const argInvite = getFlag(argv, "--invite");
+  if (argInvite !== void 0 && argInvite.trim() === "") {
+    throw new Error("Missing value for --invite");
+  }
+  const invite = (argInvite ?? env.ARP_INVITE)?.trim();
+  if (invite) return loadConfigFromInvite(invite, env);
+  return loadConfig(env);
+}
+function redactConfig(cfg) {
+  const model = cfg.agentMode === "acp" ? `(provider default; ARP_MODEL ignored in acp mode)` : cfg.model;
+  return { ...cfg, token: "<redacted>", model };
+}
+
+// src/relayClient.ts
+import { randomUUID } from "crypto";
+
+// src/card.ts
+function parseCardReply(raw) {
+  const candidate = extractJsonObject(raw);
+  if (!candidate) return null;
+  let obj;
+  try {
+    obj = JSON.parse(candidate);
+  } catch {
+    return null;
+  }
+  if (typeof obj !== "object" || obj === null) return null;
+  if (typeof obj.description !== "string") return null;
+  const rawSkills = Array.isArray(obj.skills) ? obj.skills : [];
+  const skills = [];
+  for (const s of rawSkills) {
+    if (!s || typeof s.name !== "string") continue;
+    skills.push({
+      id: typeof s.id === "string" ? s.id : s.name,
+      name: s.name,
+      description: typeof s.description === "string" ? s.description : "",
+      tags: Array.isArray(s.tags) ? s.tags.filter((t) => typeof t === "string") : [],
+      ...Array.isArray(s.examples) ? { examples: s.examples.filter((e) => typeof e === "string") } : {}
+    });
+  }
+  return { description: obj.description, skills };
+}
+function extractJsonObject(raw) {
+  const start = raw.indexOf("{");
+  if (start < 0) return null;
+  let depth = 0;
+  for (let i = start; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch === '"') {
+      i++;
+      while (i < raw.length && raw[i] !== '"') {
+        if (raw[i] === "\\") i++;
+        i++;
+      }
+      continue;
+    }
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return raw.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+function buildPartialCard(agentName, self) {
+  return {
+    protocolVersion: "0.3.0",
+    name: agentName,
+    description: self.description,
+    capabilities: { streaming: false, pushNotifications: false, stateTransitionHistory: false },
+    defaultInputModes: ["text/plain"],
+    defaultOutputModes: ["text/plain"],
+    skills: self.skills,
+    preferredTransport: "JSONRPC",
+    additionalInterfaces: [],
+    iconUrl: "",
+    documentationUrl: "",
+    securitySchemes: {},
+    security: [],
+    supportsAuthenticatedExtendedCard: false,
+    signatures: []
+  };
+}
+function normalizeRosterEntry(name, memberDescription, card) {
+  let description = memberDescription ?? "";
+  let skills = [];
+  if (card && typeof card === "object") {
+    if (typeof card.description === "string" && card.description) description = card.description;
+    if (Array.isArray(card.skills)) skills = card.skills.map((s) => s && typeof s.name === "string" ? s.name : "").filter(Boolean);
+  }
+  return { name, description, skills };
+}
+function assembleRosterFacts(entries, selfName) {
+  const peers = entries.filter((e) => e.name !== selfName);
+  if (peers.length === 0) return "";
+  const lines = peers.map((p) => {
+    const desc = p.description ? `: ${p.description}` : "";
+    const skills = p.skills.length ? ` [skills: ${p.skills.join(", ")}]` : "";
+    return `- ${p.name}${desc}${skills}`;
+  });
+  return `Also in this channel:
+${lines.join("\n")}`;
+}
+
+// src/channelContext.ts
+function buildChannelContext(input) {
+  let out = "";
+  if (input.memory.trim()) {
+    out += `## Channel Memory (shared context for this channel)
+${input.memory}
+---
+
+`;
+  }
+  if (input.pins.length > 0) {
+    const sections = input.pins.map((p) => `### \u{1F4CC} ${p.label}
+${p.content}`);
+    out += `## Pinned Files (from GitHub)
+${sections.join("\n\n")}
+---
+
+`;
+  }
+  if (input.topics.length > 0) {
+    const lines = input.topics.map((t) => {
+      const count = t.count != null ? ` (${t.count} messages)` : "";
+      return `- ${t.title}${count}`;
+    });
+    out += `## Channel Topics
+${lines.join("\n")}
+---
+
+`;
+  }
+  return out;
+}
+
+// src/catchup.ts
+function isAddressed(content, agentName) {
+  const name = agentName.trim();
+  if (!name) return false;
+  const c = content.toLowerCase();
+  const forms = /* @__PURE__ */ new Set([name.toLowerCase(), name.toLowerCase().replace(/\s+/g, "_")]);
+  for (const f of forms) if (c.includes("@" + f)) return true;
+  return false;
+}
+function classifyCatchUp(messages, agentName, nowMs, opts) {
+  const inWindow = messages.filter((m) => {
+    const t = Date.parse(m.createdAt);
+    return Number.isFinite(t) ? t >= nowMs - opts.ttlMs : true;
+  });
+  const mentions = inWindow.filter(
+    (m) => m.senderName !== agentName && isAddressed(m.content, agentName)
+  );
+  const capped = mentions.slice(-opts.maxMentions);
+  return { context: inWindow, mentions: capped };
+}
+
+// src/relayClient.ts
+var HEARTBEAT_MS = 25e3;
+var WATCHDOG_MS = 4e4;
+var STABLE_RESET_MS = 45e3;
+var MAX_BACKOFF_MS = 3e4;
+var AUTH_GRACE_MS = 1500;
+var CATCHUP_WINDOW_MS = 8e3;
+var SEEN_CAP = 5e3;
+var RESUME_MAX_PAGES = 200;
+var FATAL_CLOSE_CODES = /* @__PURE__ */ new Set([
+  4001,
+  // auth failed (bad/expired/tampered token)
+  4002,
+  // agent not found
+  4003
+  // duplicate connection
+]);
+var RelayClient = class {
+  constructor(cfg, deps) {
+    this.cfg = cfg;
+    this.deps = deps;
+  }
+  cfg;
+  deps;
+  ws = null;
+  inboundCbs = [];
+  rosterCbs = [];
+  flowCbs = [];
+  heartbeatTimer = null;
+  watchdog = null;
+  stableTimer = null;
+  reconnectTimer = null;
+  reconnectAttempts = 0;
+  stopped = false;
+  seenByChannel = /* @__PURE__ */ new Map();
+  cursors = /* @__PURE__ */ new Map();
+  connectedAt = 0;
+  // ms timestamp of the latest WS open; drives the catch-up window
+  graceTimer = null;
+  confirmed = false;
+  // single-shot: onReady has fired (relay accepted the agent)
+  catchUpCbs = [];
+  caughtUp = /* @__PURE__ */ new Set();
+  // channels caught up this connection
+  readyCb = null;
+  fatalCb = null;
+  removedCb = null;
+  addedCb = null;
+  onInbound(cb) {
+    this.inboundCbs.push(cb);
+  }
+  /** Subscribe to roster updates; returns an unsubscribe so a per-channel session can drop
+   *  its subscription on teardown (otherwise handlers accumulate across channel churn). */
+  onRoster(cb) {
+    this.rosterCbs.push(cb);
+    return () => {
+      const i = this.rosterCbs.indexOf(cb);
+      if (i >= 0) this.rosterCbs.splice(i, 1);
+    };
+  }
+  onFlowSignal(cb) {
+    this.flowCbs.push(cb);
+  }
+  onCatchUp(cb) {
+    this.catchUpCbs.push(cb);
+  }
+  onReady(cb) {
+    this.readyCb = cb;
+  }
+  onFatal(cb) {
+    this.fatalCb = cb;
+  }
+  onRemoved(cb) {
+    this.removedCb = cb;
+  }
+  onAdded(cb) {
+    this.addedCb = cb;
+  }
+  start() {
+    this.connect();
+  }
+  connect() {
+    const url = `${this.cfg.relayWsUrl}/ws/agent/${this.cfg.agentId}?token=${this.cfg.token}`;
+    const ws = this.deps.wsFactory(url);
+    this.ws = ws;
+    ws.on("open", () => this.onOpen());
+    ws.on("message", (data) => this.onMessage(data.toString()));
+    ws.on("close", (code, reason) => this.onClose(code, reason.toString()));
+    ws.on("error", () => {
+    });
+  }
+  onOpen() {
+    this.caughtUp.clear();
+    this.connectedAt = Date.now();
+    this.heartbeatTimer = setInterval(() => this.send({ type: "ping" }), HEARTBEAT_MS);
+    this.armWatchdog();
+    this.stableTimer = setTimeout(() => {
+      this.reconnectAttempts = 0;
+    }, STABLE_RESET_MS);
+    if (this.graceTimer) clearTimeout(this.graceTimer);
+    this.graceTimer = setTimeout(() => this.confirmReady(), AUTH_GRACE_MS);
+    this.onConnected();
+  }
+  /** Single-shot: fires onReady at most once, on the FIRST successful connect. */
+  confirmReady() {
+    if (this.graceTimer) {
+      clearTimeout(this.graceTimer);
+      this.graceTimer = null;
+    }
+    if (this.confirmed) return;
+    this.confirmed = true;
+    this.readyCb?.();
+  }
+  armWatchdog() {
+    if (this.watchdog) clearTimeout(this.watchdog);
+    this.watchdog = setTimeout(() => {
+      try {
+        this.ws?.close();
+      } catch {
+      }
+    }, WATCHDOG_MS);
+  }
+  onConnected() {
+  }
+  /** Pull every message after a sequence, paginating on hasMore. Returns them in order.
+   *  The relay paginates and reports `hasMore` (a full page == limit). Follow the
+   *  cursor page by page until the server says there is nothing left, advancing
+   *  afterSeq to the max seq received so far. A defensive page cap prevents an
+   *  infinite loop if a misbehaving server keeps claiming hasMore. */
+  async fetchAfterSeq(channelId, afterSeq) {
+    const out = [];
+    let cursor = afterSeq;
+    for (let page = 0; page < RESUME_MAX_PAGES; page++) {
+      const url = `${this.cfg.relayHttpUrl}/channels/${channelId}/messages?afterSeq=${cursor}`;
+      let res;
+      try {
+        res = await this.deps.fetchFn(url, { headers: { Authorization: `Bearer ${this.cfg.token}` } });
+      } catch (err) {
+        console.warn("[arp-bridge] backfill fetch failed:", String(err));
+        return out;
+      }
+      if (!res.ok) {
+        console.warn("[arp-bridge] backfill HTTP", res.status);
+        return out;
+      }
+      const body = await res.json();
+      const list = Array.isArray(body) ? body : body.messages ?? [];
+      if (list.length === 0) return out;
+      let maxSeq = cursor;
+      for (const m of list) {
+        const seq = Number(m.seq ?? 0);
+        if (seq > maxSeq) maxSeq = seq;
+        out.push({
+          id: String(m.id ?? ""),
+          seq,
+          channelId,
+          content: String(m.content ?? ""),
+          senderId: String(m.agentId ?? ""),
+          senderName: String(m.agentName ?? ""),
+          senderType: String(m.messageType ?? m.type ?? ""),
+          // relay live/resume key is messageType; history path uses type
+          createdAt: String(m.createdAt ?? ""),
+          isHistory: false
+          // shape parity with live messages; the caller decides how to handle them
+        });
+      }
+      if (!body.hasMore) return out;
+      cursor = maxSeq;
+    }
+    console.warn("[arp-bridge] backfill hit page cap", RESUME_MAX_PAGES);
+    return out;
+  }
+  /** Mid-session gap-fill: replay missed messages live (each dedupes via emitInbound). */
+  async resumeAfterSeq(channelId, afterSeq) {
+    for (const m of await this.fetchAfterSeq(channelId, afterSeq)) this.emitInbound(m);
+  }
+  /** Offline-rejoin catch-up: classify the missed window and hand it to onCatchUp once.
+   *  Does NOT route through emitInbound/onInbound to avoid per-message passive submits. */
+  async catchUp(channelId, afterSeq) {
+    const missed = await this.fetchAfterSeq(channelId, afterSeq);
+    if (missed.length === 0) return;
+    for (const m of missed) if (m.id) this.markSeen(channelId, m.id);
+    this.bumpCursor(channelId, missed[missed.length - 1].seq);
+    const result = classifyCatchUp(missed, this.cfg.agentName, Date.now(), {
+      ttlMs: this.cfg.catchUpTtlMs,
+      maxMentions: this.cfg.catchUpMaxMentions
+    });
+    this.catchUpCbs.forEach((cb) => cb(channelId, result));
+  }
+  onClose(code, reason) {
+    this.clearTimers();
+    if (this.stopped) return;
+    if (FATAL_CLOSE_CODES.has(code)) {
+      this.stopped = true;
+      this.fatalCb?.(code, reason);
+      return;
+    }
+    const delay3 = Math.min(1e3 * 2 ** this.reconnectAttempts, MAX_BACKOFF_MS);
+    this.reconnectAttempts++;
+    this.reconnectTimer = setTimeout(() => {
+      if (!this.stopped) this.connect();
+    }, delay3);
+  }
+  clearTimers() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (this.watchdog) {
+      clearTimeout(this.watchdog);
+      this.watchdog = null;
+    }
+    if (this.stableTimer) {
+      clearTimeout(this.stableTimer);
+      this.stableTimer = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.graceTimer) {
+      clearTimeout(this.graceTimer);
+      this.graceTimer = null;
+    }
+  }
+  stop() {
+    this.stopped = true;
+    this.clearTimers();
+    try {
+      this.ws?.removeAllListeners?.();
+    } catch {
+    }
+    try {
+      this.ws?.close();
+    } catch {
+    }
+  }
+  onMessage(raw) {
+    this.armWatchdog();
+    if (!this.confirmed) this.confirmReady();
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    switch (msg?.type) {
+      case "heartbeat":
+        this.send({ type: "heartbeat_ack", clientType: "arp-bridge" });
+        break;
+      case "channel_message":
+        this.handleChannelMessage(msg);
+        break;
+      case "token_refresh":
+        if (typeof msg.token === "string" && msg.token.length > 0) {
+          this.cfg.token = msg.token;
+          console.log("[arp-bridge] token refreshed");
+        }
+        break;
+      case "removed": {
+        const ch = String(msg.channelId ?? "");
+        if (!ch) break;
+        this.cursors.delete(ch);
+        this.seenByChannel.delete(ch);
+        this.caughtUp.delete(ch);
+        this.removedCb?.(ch);
+        break;
+      }
+      case "added": {
+        const ch = String(msg.channelId ?? "");
+        if (!ch) break;
+        this.addedCb?.(ch);
+        break;
+      }
+      case "roster_update": {
+        const m = msg.member ?? {};
+        if (typeof m.name === "string" && m.name.length > 0) {
+          const entry = normalizeRosterEntry(m.name, m.description, m.card);
+          this.rosterCbs.forEach((cb) => cb(entry));
+        }
+        break;
+      }
+      case "turn_notification":
+        this.handleFlowSignal("turn", msg);
+        break;
+      case "synthesis_request":
+        this.handleFlowSignal("synthesis", msg);
+        break;
+      case "direction_request":
+        this.handleFlowSignal("direction", msg);
+        break;
+      case "hello": {
+        const resume = msg?.resume;
+        if (resume && typeof resume === "object") {
+          for (const [ch, seqRaw] of Object.entries(resume)) {
+            const seq = Number(seqRaw);
+            if (Number.isFinite(seq) && seq > this.cursorOf(ch)) this.cursors.set(ch, seq);
+            const floor = this.cursorOf(ch);
+            if (!this.caughtUp.has(ch) && floor > 0) {
+              this.caughtUp.add(ch);
+              void this.catchUp(ch, floor);
+            }
+          }
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  handleChannelMessage(msg) {
+    const channelId = String(msg.channelId ?? "");
+    if (!channelId) {
+      console.warn("[arp-bridge] channel_message with no channelId; dropped");
+      return;
+    }
+    const m = msg.message ?? {};
+    const inbound = {
+      id: String(m.id ?? ""),
+      seq: Number(m.seq ?? 0),
+      channelId,
+      content: String(m.content ?? ""),
+      senderId: String(m.agentId ?? ""),
+      senderName: String(m.agentName ?? ""),
+      senderType: String(m.messageType ?? m.type ?? ""),
+      // relay live/resume key is messageType; history path uses type
+      createdAt: String(m.createdAt ?? ""),
+      isHistory: Boolean(msg.isHistory)
+    };
+    const gapDetected = !inbound.isHistory && this.cursorOf(channelId) > 0 && inbound.seq > this.cursorOf(channelId) + 1;
+    const gapFrom = this.cursorOf(channelId);
+    this.emitInbound(inbound);
+    if (gapDetected) void this.resumeAfterSeq(channelId, gapFrom);
+  }
+  /** Normalize a turn_notification / synthesis_request / direction_request into a FlowSignal and emit it. */
+  handleFlowSignal(kind, msg) {
+    const flowId = String(msg.flowId ?? "");
+    if (!flowId) return;
+    const rawHistory = kind === "synthesis" || kind === "direction" ? msg.flowHistory ?? msg.messages ?? [] : msg.recentMessages ?? [];
+    const history = (Array.isArray(rawHistory) ? rawHistory : []).map((e) => ({
+      agentName: String(e.agentName ?? ""),
+      content: String(e.content ?? ""),
+      messageType: e.messageType ?? e.type,
+      turnNumber: e.turnNumber,
+      createdAt: e.createdAt
+    }));
+    const signal = {
+      kind,
+      flowId,
+      channelId: String(msg.channelId ?? ""),
+      topic: String(msg.topic ?? ""),
+      rolePrompt: typeof msg.rolePrompt === "string" ? msg.rolePrompt : void 0,
+      contextPrompt: typeof msg.contextPrompt === "string" ? msg.contextPrompt : void 0,
+      synthesisPrompt: typeof msg.synthesisPrompt === "string" ? msg.synthesisPrompt : void 0,
+      candidates: Array.isArray(msg.candidates) ? msg.candidates : void 0,
+      history
+    };
+    this.flowCbs.forEach((cb) => cb(signal));
+  }
+  cursorOf(ch) {
+    return this.cursors.get(ch) ?? 0;
+  }
+  bumpCursor(ch, seq) {
+    if (seq > this.cursorOf(ch)) this.cursors.set(ch, seq);
+  }
+  seenSet(ch) {
+    let s = this.seenByChannel.get(ch);
+    if (!s) {
+      s = /* @__PURE__ */ new Set();
+      this.seenByChannel.set(ch, s);
+    }
+    return s;
+  }
+  /** Record an id in a channel's dedupe set. Evicts the oldest entry FIFO when it exceeds SEEN_CAP. */
+  markSeen(ch, id) {
+    const s = this.seenSet(ch);
+    s.add(id);
+    if (s.size > SEEN_CAP) {
+      const oldest = s.values().next().value;
+      if (oldest !== void 0) s.delete(oldest);
+    }
+  }
+  emitInbound(m) {
+    const s = this.seenSet(m.channelId);
+    if (m.id && s.has(m.id)) return;
+    if (m.id) this.markSeen(m.channelId, m.id);
+    this.bumpCursor(m.channelId, m.seq);
+    this.inboundCbs.forEach((cb) => cb(m));
+  }
+  send(obj) {
+    if (this.ws && this.ws.readyState === 1) this.ws.send(JSON.stringify(obj));
+  }
+  /** Emit a best-effort activity lease signal over the agent WS. No-op if the socket
+   *  is closed (send() guards readyState). A "start" within CATCHUP_WINDOW_MS of (re)connect
+   *  is labeled "catching_up" — the agent is re-reading messages it missed while offline,
+   *  not freshly thinking. Otherwise "thinking". Relay broadcasts activity_changed to viewers. */
+  sendActivity(channelId, state) {
+    const catchingUp = state === "start" && this.connectedAt > 0 && Date.now() - this.connectedAt < CATCHUP_WINDOW_MS;
+    this.send({
+      type: state === "start" ? "activity_start" : "activity_stop",
+      channelId,
+      activity: catchingUp ? "catching_up" : "thinking"
+    });
+  }
+  /** Publish this agent's partial A2A card; the relay fills url/version/provider. */
+  async putAgentCard(card) {
+    const url = `${this.cfg.relayHttpUrl}/agents/me/agent-card`;
+    try {
+      const res = await this.deps.fetchFn(url, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.cfg.token}` },
+        body: JSON.stringify(card)
+      });
+      if (!res.ok) console.warn("[arp-bridge] put card HTTP", res.status);
+    } catch (err) {
+      console.warn("[arp-bridge] put card failed:", String(err));
+    }
+  }
+  /** Fetch the channel roster and return normalized bot entries (with cards). */
+  async fetchRoster(channelId) {
+    const url = `${this.cfg.relayHttpUrl}/channels/${channelId}`;
+    try {
+      const res = await this.deps.fetchFn(url, { headers: { Authorization: `Bearer ${this.cfg.token}` } });
+      if (!res.ok) {
+        console.warn("[arp-bridge] roster HTTP", res.status);
+        return [];
+      }
+      const body = await res.json();
+      const members = body?.channel?.members ?? [];
+      return members.filter((m) => m?.type === "bot" && typeof m.id === "string").map((m) => normalizeRosterEntry(m.id, m.description, m.card));
+    } catch (err) {
+      console.warn("[arp-bridge] roster fetch failed:", String(err));
+      return [];
+    }
+  }
+  async postMessage(channelId, content) {
+    const url = `${this.cfg.relayHttpUrl}/channels/${channelId}/messages`;
+    const body = JSON.stringify({
+      id: randomUUID(),
+      // client-generated -> server idempotent on retry
+      content,
+      agentId: this.cfg.agentUuid,
+      agentName: this.cfg.agentName,
+      messageType: "agent"
+    });
+    try {
+      const res = await this.deps.fetchFn(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.cfg.token}` },
+        body
+      });
+      if (!res.ok) {
+        console.warn("[arp-bridge] post HTTP", res.status);
+      }
+    } catch (err) {
+      console.warn("[arp-bridge] post failed:", String(err));
+    }
+  }
+  /** Post a bounded-flow reply (turn or synthesis) to the flow-scoped endpoint.
+   *  agentId MUST be the agent NAME — the relay's flow gate resolves turn ownership and
+   *  synthesis role via resolveAgentUUID (a name lookup); a UUID resolves to uuid.Nil -> 403. */
+  async postFlowMessage(channelId, flowId, content) {
+    const url = `${this.cfg.relayHttpUrl}/channels/${channelId}/flows/${flowId}/messages`;
+    const body = JSON.stringify({
+      id: randomUUID(),
+      content,
+      // The relay's flow gate resolves turn ownership + synthesis role by NAME
+      // (resolveAgentUUID is a name lookup), so the flow reply must carry the agent name.
+      agentId: this.cfg.agentName,
+      agentName: this.cfg.agentName
+    });
+    try {
+      const res = await this.deps.fetchFn(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.cfg.token}` },
+        body
+      });
+      if (!res.ok) console.warn("[arp-bridge] flow post HTTP", res.status);
+    } catch (err) {
+      console.warn("[arp-bridge] flow post failed:", String(err));
+    }
+  }
+  /** Channel memory text ("" if none or on error — never throws). */
+  async fetchChannelMemory(channelId) {
+    const url = `${this.cfg.relayHttpUrl}/channels/${channelId}/memory`;
+    try {
+      const res = await this.deps.fetchFn(url, { headers: { Authorization: `Bearer ${this.cfg.token}` } });
+      if (!res.ok) {
+        console.warn("[arp-bridge] memory HTTP", res.status);
+        return "";
+      }
+      const data = await res.json();
+      return typeof data?.content === "string" ? data.content : "";
+    } catch (err) {
+      console.warn("[arp-bridge] memory fetch failed:", String(err));
+      return "";
+    }
+  }
+  /** Channel topics with message counts ([] if none or on error). The relay returns
+   *  topics with a `title` plus a separate `messageCounts` map keyed by topic id. */
+  async fetchChannelTopics(channelId) {
+    const url = `${this.cfg.relayHttpUrl}/channels/${channelId}/topics`;
+    try {
+      const res = await this.deps.fetchFn(url, { headers: { Authorization: `Bearer ${this.cfg.token}` } });
+      if (!res.ok) {
+        console.warn("[arp-bridge] topics HTTP", res.status);
+        return [];
+      }
+      const data = await res.json();
+      const topics = data?.topics ?? [];
+      const counts = data?.messageCounts ?? {};
+      return topics.filter((t) => typeof t?.title === "string").map((t) => ({ title: t.title, count: typeof counts[t.id] === "number" ? counts[t.id] : null }));
+    } catch (err) {
+      console.warn("[arp-bridge] topics fetch failed:", String(err));
+      return [];
+    }
+  }
+  /** Pinned files marked inject_context=true, labeled with cached content ([] otherwise). */
+  async fetchPinnedContext(channelId) {
+    const url = `${this.cfg.relayHttpUrl}/channels/${channelId}/pins`;
+    try {
+      const res = await this.deps.fetchFn(url, { headers: { Authorization: `Bearer ${this.cfg.token}` } });
+      if (!res.ok) {
+        console.warn("[arp-bridge] pins HTTP", res.status);
+        return [];
+      }
+      const data = await res.json();
+      const pins = data?.pins ?? [];
+      return pins.filter((p) => p?.injectContext && typeof p.cachedContent === "string" && p.cachedContent.trim()).map((p) => ({ label: p.displayName || `${p.repoUrl ?? ""}/${p.filePath ?? ""}`, content: p.cachedContent }));
+    } catch (err) {
+      console.warn("[arp-bridge] pins fetch failed:", String(err));
+      return [];
+    }
+  }
+  /** Assemble the situational channel-context block (memory + pinned files + topics) for a
+   *  passive message. Parallel fetch with per-source graceful degradation (each fetcher
+   *  swallows its own errors). Returns "" when there is nothing to inject. */
+  async fetchChannelContext(channelId) {
+    const [memory, topics, pins] = await Promise.all([
+      this.fetchChannelMemory(channelId),
+      this.fetchChannelTopics(channelId),
+      this.fetchPinnedContext(channelId)
+    ]);
+    return buildChannelContext({ memory, topics, pins });
+  }
+  /** Fetch a flow's transcript (used to backfill a minimal turn_notification). [] on error. */
+  async fetchFlowMessages(channelId, flowId) {
+    const url = `${this.cfg.relayHttpUrl}/channels/${channelId}/flows/${flowId}/messages`;
+    try {
+      const res = await this.deps.fetchFn(url, { headers: { Authorization: `Bearer ${this.cfg.token}` } });
+      if (!res.ok) {
+        console.warn("[arp-bridge] flow messages HTTP", res.status);
+        return [];
+      }
+      const data = await res.json();
+      const list = Array.isArray(data) ? data : data.messages ?? [];
+      return list.map((e) => ({
+        agentName: String(e.agentName ?? ""),
+        content: String(e.content ?? ""),
+        messageType: e.messageType ?? e.type,
+        turnNumber: e.turnNumber,
+        createdAt: e.createdAt
+      }));
+    } catch (err) {
+      console.warn("[arp-bridge] flow messages failed:", String(err));
+      return [];
+    }
+  }
+};
+
+// src/flow.ts
+function renderFlowHistory(entries) {
+  if (entries.length === 0) return "";
+  const lines = entries.map((e) => `${e.agentName || "someone"}: ${e.content}`);
+  return `DISCUSSION HISTORY:
+${lines.join("\n")}
+
+`;
+}
+function buildFlowPrompt(signal, agentName, channelId) {
+  if (signal.kind === "direction") {
+    const candidates = (signal.candidates ?? []).join(", ");
+    const history2 = renderFlowHistory(signal.history);
+    const hasHistory = history2 !== "";
+    const preamble = hasHistory ? [``, history2.trimEnd(), ``, `Read the conversation above and decide who should speak next.`] : [``, `No turns have been taken yet \u2014 choose who should speak FIRST.`];
+    return [
+      `You are the DIRECTOR of a structured discussion on: ${signal.topic}`,
+      ...preamble,
+      `Available participants: ${candidates || "(none online)"}.`,
+      ``,
+      `Reply with ONLY the name of the single participant who should speak next,`,
+      `or reply with ONLY the word END to conclude the discussion and move to synthesis.`,
+      `Do not add any other text \u2014 just the name, or END.`
+    ].filter((line, i, arr) => !(line === "" && arr[i - 1] === "")).join("\n");
+  }
+  const isSynthesis = signal.kind === "synthesis";
+  const header = isSynthesis ? `You are ${agentName} and the TEAM LEAD for this ARP bounded discussion.` : `You are ${agentName} responding in an ARP bounded discussion.`;
+  const role = signal.rolePrompt ? `YOUR ROLE: ${signal.rolePrompt}
+` : "";
+  const ctx = signal.contextPrompt ? `CONTEXT: ${signal.contextPrompt}
+` : "";
+  const synth = signal.synthesisPrompt ? `SYNTHESIS INSTRUCTIONS: ${signal.synthesisPrompt}
+` : "";
+  const history = renderFlowHistory(signal.history);
+  const closer = isSynthesis ? "Synthesize the discussion above: the key findings, points of agreement, and conclusions. Provide the synthesis now." : "It's your turn. Provide a substantive response to the discussion.";
+  return `${header}
+CHANNEL: ${channelId}
+FLOW: ${signal.flowId}
+TOPIC: ${signal.topic}
+` + role + ctx + synth + "\n" + history + closer;
+}
+
+// src/session.ts
+var SILENCE_SENTINEL = "<<silent>>";
+var ChannelSession = class {
+  constructor(adapter, onReply, agentName, channelId, flow, fetchContext, beacon) {
+    this.adapter = adapter;
+    this.onReply = onReply;
+    this.agentName = agentName;
+    this.channelId = channelId;
+    this.flow = flow;
+    this.fetchContext = fetchContext;
+    this.beacon = beacon;
+  }
+  adapter;
+  onReply;
+  agentName;
+  channelId;
+  flow;
+  fetchContext;
+  beacon;
+  session = null;
+  roster = [];
+  /** Replace the known peer roster (situational facts surfaced per message). */
+  setRoster(entries) {
+    this.roster = entries;
+  }
+  async start(opts) {
+    this.session = await this.adapter.start(opts);
+    this.session.onTurn((full) => {
+      this.beacon?.end();
+      if (full.replace(/<<silent>>/gi, "").trim() === "") return;
+      this.onReply(full.replace(/^\s*(?:<<silent>>\s*)+/i, "").trim());
+    });
+  }
+  /**
+   * Frame one inbound channel message with SITUATIONAL FACTS only (no persona, no tone,
+   * no voice). Mirrors the legacy openclaw-arp/src/inbound.ts channel_message case:
+   * tell the agent where it is, who is talking, that this is a passive multi-party
+   * channel, and how to stay silent. Our relay delivers only channel_message to agents
+   * in this slice, so there is a single message-type shape.
+   */
+  async submit(msg) {
+    if (!this.session) throw new Error("ChannelSession not started");
+    const who = msg.senderName || msg.senderId || "someone";
+    const facts = assembleRosterFacts(this.roster, this.agentName);
+    const rosterBlock = facts ? `${facts}
+
+` : "";
+    const channelContext = this.fetchContext ? await this.fetchContext() : "";
+    const head = channelContext + `You are ${this.agentName} observing a message in ARP channel ${this.channelId}.
+FROM: ${who}
+MESSAGE: ${msg.content}
+
+` + rosterBlock;
+    const instructions = isAddressed(msg.content, this.agentName) ? "You were directly addressed (@mentioned), so respond. Output ONLY your channel message itself, concisely. Do NOT include the silence sentinel and do NOT explain whether or why you are responding." : `You received this as a passive channel message. You do NOT need to respond unless it is directly relevant to you. If you have nothing to add, reply with exactly ${SILENCE_SENTINEL} and nothing else. Otherwise output ONLY your channel message, concisely \u2014 do NOT explain whether or why you are responding.`;
+    this.beacon?.begin();
+    this.session.submit(head + instructions);
+  }
+  /**
+   * Run one bounded-flow turn or synthesis. Frames a MUST-RESPOND prompt (no
+   * `<<silent>>`), runs it through the SAME warm session via converseLocal (so the
+   * reply is NOT posted to the channel by onTurn), and routes the reply to the flow
+   * endpoint. A minimal turn_notification carries no transcript, so we backfill it
+   * from the relay first. An empty reply still posts a fallback so the relay-blocked
+   * flow advances rather than timing out.
+   */
+  async runFlowTurn(signal) {
+    if (!this.session) throw new Error("ChannelSession not started");
+    if (!this.session.converseLocal || !this.flow) {
+      console.warn("[arp-bridge] flow turn skipped: warm aside / flow routing unavailable");
+      return;
+    }
+    this.beacon?.begin();
+    try {
+      let history = signal.history;
+      if (history.length === 0) history = await this.flow.fetchHistory(signal.flowId);
+      const prompt = buildFlowPrompt({ ...signal, history }, this.agentName, this.channelId);
+      const reply = await this.session.converseLocal(prompt);
+      await this.flow.postReply(signal.flowId, reply.trim() || "(no response)");
+    } finally {
+      this.beacon?.end();
+    }
+  }
+  /**
+   * Talk to the SAME warm agent locally as a private aside. Delegates to the
+   * underlying session's converseLocal (shared warm context, reply NOT posted to the
+   * channel). Throws a clear error in modes that do not support it (generic mode).
+   */
+  async converseLocal(text) {
+    if (!this.session) throw new Error("ChannelSession not started");
+    if (!this.session.converseLocal) {
+      throw new Error("local conversation not supported in this mode");
+    }
+    this.beacon?.begin();
+    try {
+      return await this.session.converseLocal(text);
+    } finally {
+      this.beacon?.end();
+    }
+  }
+  /**
+   * Offline-rejoin catch-up. Absorbs the within-TTL missed window as context; if any missed
+   * @mentions are in scope, responds ONCE (consolidated) to them and posts to the channel.
+   * No mentions -> absorb privately via converseLocal (not posted). Empty window -> no-op.
+   *
+   * Like `submit()`, the mention branch is fire-and-forget: the returned Promise resolves
+   * after dispatching the turn to the agent, not after the reply lands — the reply arrives
+   * later via the `onTurn` handler (and is then forwarded through `onReply`).
+   */
+  async submitCatchUp(result) {
+    if (!this.session) throw new Error("ChannelSession not started");
+    if (result.context.length === 0) return;
+    const transcript = result.context.map((m) => `[${m.createdAt}] ${m.senderName || m.senderId || "someone"}: ${m.content}`).join("\n");
+    if (result.mentions.length === 0) {
+      if (!this.session.converseLocal) return;
+      this.beacon?.begin();
+      try {
+        await this.session.converseLocal(
+          `You just reconnected to ARP channel ${this.channelId} after being away. Here is what you missed (context only, do NOT reply to it):
+${transcript}`
+        );
+      } finally {
+        this.beacon?.end();
+      }
+      return;
+    }
+    const channelContext = this.fetchContext ? await this.fetchContext() : "";
+    const addressed = result.mentions.map((m) => `[${m.createdAt}] ${m.senderName || m.senderId || "someone"}: ${m.content}`).join("\n");
+    const head = channelContext + `You are ${this.agentName}. You just reconnected to ARP channel ${this.channelId} after being away. While you were gone, the channel said (context):
+${transcript}
+
+You were directly addressed (@mentioned) in:
+${addressed}
+
+`;
+    const instructions = `Respond ONCE, concisely, to what was directed at you. If something is already resolved by the later messages above, say so briefly. Output ONLY your channel message \u2014 do NOT include the silence sentinel and do NOT explain whether or why you are responding.`;
+    this.beacon?.begin();
+    this.session.submit(head + instructions);
+  }
+  async stop() {
+    this.beacon?.stop?.();
+    await this.session?.stop();
+  }
+};
+
+// src/activityBeacon.ts
+var ActivityBeacon = class {
+  constructor(emit, heartbeatMs = 3e4) {
+    this.emit = emit;
+    this.heartbeatMs = heartbeatMs;
+  }
+  emit;
+  heartbeatMs;
+  inFlight = 0;
+  timer = null;
+  begin() {
+    if (this.inFlight++ === 0) {
+      this.emit("start");
+      this.timer = setInterval(() => this.emit("start"), this.heartbeatMs);
+    }
+  }
+  end() {
+    if (this.inFlight === 0) return;
+    if (--this.inFlight === 0) {
+      this.clearTimer();
+      this.emit("stop");
+    }
+  }
+  /** Unconditional teardown (bridge shutdown). Does not emit. */
+  stop() {
+    this.inFlight = 0;
+    this.clearTimer();
+  }
+  clearTimer() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+};
+
+// src/adapter.ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+// src/acp/client.ts
+import { spawn } from "child_process";
+import { Readable, Writable } from "stream";
+import { ClientSideConnection, ndJsonStream } from "@agentclientprotocol/sdk";
+
+// src/acp/filterStream.ts
+function dropVendorNotifications(input) {
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let buf = "";
+  const emit = (controller, line) => {
+    const trimmed = line.trim();
+    if (trimmed) {
+      try {
+        const msg = JSON.parse(trimmed);
+        const isNotification = msg.id === void 0;
+        const method = typeof msg.method === "string" ? msg.method : "";
+        if (isNotification && method.startsWith("_")) {
+          return;
+        }
+      } catch {
+      }
+    }
+    controller.enqueue(encoder.encode(line + "\n"));
+  };
+  return new ReadableStream({
+    async start(controller) {
+      const reader = input.getReader();
+      try {
+        for (; ; ) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          if (!value) continue;
+          buf += decoder.decode(value, { stream: true });
+          const lines = buf.split("\n");
+          buf = lines.pop() ?? "";
+          for (const line of lines) emit(controller, line);
+        }
+        buf += decoder.decode();
+        if (buf.trim()) emit(controller, buf);
+      } catch (err) {
+        controller.error(err);
+        return;
+      } finally {
+        reader.releaseLock();
+      }
+      controller.close();
+    }
+  });
+}
+
+// src/acp/client.ts
+var MODEL_AUTH_ENV_KEYS = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"];
+function buildAcpEnv(base, extra) {
+  const merged = {};
+  for (const [k, v] of Object.entries({ ...base, ...extra ?? {} })) {
+    if (v === void 0) continue;
+    if (MODEL_AUTH_ENV_KEYS.includes(k)) continue;
+    merged[k] = v;
+  }
+  return merged;
+}
+var STOP_DRAIN_MS = 3e3;
+function killProcessGroup(child, signal) {
+  const pid = child.pid;
+  try {
+    if (pid) process.kill(-pid, signal);
+    else child.kill(signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+    }
+  }
+}
+function pickAllowOption(req) {
+  const opts = req.options ?? [];
+  const always = opts.find((o) => o.kind === "allow_always");
+  if (always) return always.optionId;
+  const once = opts.find((o) => o.kind === "allow_once");
+  if (once) return once.optionId;
+  throw new Error(
+    "ACP request_permission had no allow option (allow_always/allow_once); refusing to auto-select a non-allow option"
+  );
+}
+var AcpClient = class {
+  constructor(launch) {
+    this.launch = launch;
+  }
+  launch;
+  child = null;
+  conn = null;
+  _sessionId = null;
+  /**
+   * The currently-running turn's reply accumulator. Set for the duration of one
+   * turn so agent_message_chunk text lands in THIS turn's buffer only. Because
+   * turns are serialized (see #turnQueue), exactly one turn is active at a time,
+   * so a single active buffer cannot interleave across turns.
+   */
+  activeTurnBuffer = null;
+  /** Promise chain serializing overlapping submits onto the one warm session. */
+  turnQueue = Promise.resolve();
+  /** Set when the subprocess exits unexpectedly; surfaced to the next await. */
+  exitError = null;
+  /** Pending rejecters waiting on an in-flight operation (start/submit). */
+  exitRejecters = /* @__PURE__ */ new Set();
+  get sessionId() {
+    return this._sessionId;
+  }
+  /**
+   * The sticky subprocess-exit error, or null if the client is alive. Set when the
+   * subprocess exits/errs unexpectedly and cleared by the next start(). A supervisor
+   * (the AcpAdapter) reads this to decide whether a failed turn was a crash that
+   * warrants a restart, without coupling to the relay WebSocket.
+   */
+  get exited() {
+    return this.exitError;
+  }
+  /**
+   * Spawn the adapter, build the connection, initialize, and open one session.
+   * Any failure (spawn error, premature exit, protocol error) rejects.
+   */
+  async start() {
+    this.exitError = null;
+    this.stopping = false;
+    this.activeTurnBuffer = null;
+    this.turnQueue = Promise.resolve();
+    this.exitRejecters.clear();
+    try {
+      await this.startInner();
+    } catch (err) {
+      await this.stop().catch(() => {
+      });
+      throw err;
+    }
+  }
+  async startInner() {
+    const child = spawn(this.launch.command, this.launch.args, {
+      cwd: this.launch.cwd,
+      // Inherit the user's env so the agent uses ITS OWN auth, but strip any
+      // model-API-auth keys (e.g. a stale ANTHROPIC_API_KEY in the launching
+      // shell) so the agent falls back to its own login instead of silently
+      // billing an API account. See buildAcpEnv / MODEL_AUTH_ENV_KEYS.
+      env: buildAcpEnv(process.env, this.launch.env),
+      stdio: ["pipe", "pipe", "inherit"],
+      // stderr passes through for debugging
+      // Own process group: Ctrl-C (SIGINT to the bridge's foreground group) does NOT reach
+      // the agent subprocess, so the bridge can drain the in-flight turn and shut it down
+      // cleanly instead of the SDK tearing down mid-query. stop() kills the whole group.
+      detached: true
+    });
+    this.child = child;
+    child.on("error", (err) => {
+      this.failPending(new Error(`ACP agent subprocess error: ${err.message}`));
+    });
+    child.on("exit", (code, signal) => {
+      const reason = signal != null ? `signal ${signal}` : `code ${code ?? "unknown"}`;
+      const err = new Error(`ACP agent subprocess exited (${reason})`);
+      if (code !== 0 && !this.stopping) {
+        this.failPending(err);
+      }
+    });
+    const output = Writable.toWeb(child.stdin);
+    const rawInput = Readable.toWeb(
+      child.stdout
+    );
+    const input = dropVendorNotifications(rawInput);
+    const stream = ndJsonStream(output, input);
+    const client = {
+      sessionUpdate: async (params) => {
+        const u = params.update;
+        if (process.env.ARP_ACP_DEBUG) {
+          const au = u;
+          const c = au.content;
+          const preview = c?.type === "text" ? JSON.stringify(c.text).slice(0, 160) : JSON.stringify(u).slice(0, 220);
+          console.error(`[ACP_DEBUG] update=${u.sessionUpdate} content=${c?.type ?? "-"} :: ${preview}`);
+        }
+        if (u.sessionUpdate === "agent_message_chunk" && u.content?.type === "text" && this.activeTurnBuffer) {
+          this.activeTurnBuffer.text += u.content.text;
+        }
+      },
+      requestPermission: async (req) => {
+        return {
+          outcome: { outcome: "selected", optionId: pickAllowOption(req) }
+        };
+      }
+    };
+    this.conn = new ClientSideConnection(() => client, stream);
+    await this.guard(
+      this.conn.initialize({
+        protocolVersion: 1,
+        clientCapabilities: {
+          fs: { readTextFile: false, writeTextFile: false },
+          terminal: false
+        },
+        clientInfo: { name: "arp-bridge", version: "0.1.0" }
+      })
+    );
+    const session = await this.guard(
+      this.conn.newSession({ cwd: this.launch.cwd, mcpServers: [] })
+    );
+    this._sessionId = session.sessionId;
+  }
+  /**
+   * Send one user turn. Resolves with the full assembled reply text once the
+   * agent signals end-of-turn (the prompt promise resolves with a stopReason).
+   *
+   * One-turn-at-a-time contract: an ACP session processes a single prompt turn
+   * at a time. Overlapping submit() calls are SERIALIZED onto the one warm
+   * session via an internal promise-chain queue and run sequentially in call
+   * order. Each turn captures ONLY its own agent_message_chunk text into its own
+   * per-turn buffer, so concurrent callers each receive their own correct,
+   * uncontaminated reply. A turn that rejects (e.g. subprocess death) does not
+   * break the queue for subsequent turns.
+   */
+  async submit(text) {
+    if (!this.conn || !this._sessionId) {
+      throw new Error("AcpClient.submit called before start()");
+    }
+    const run = this.turnQueue.then(() => this.runTurn(text));
+    this.turnQueue = run.catch(() => {
+    });
+    return run;
+  }
+  /** Execute exactly one prompt turn with its own isolated reply buffer. */
+  async runTurn(text) {
+    if (!this.conn || !this._sessionId) {
+      throw new Error("AcpClient.submit called before start()");
+    }
+    const buffer = { text: "" };
+    this.activeTurnBuffer = buffer;
+    try {
+      await this.guard(
+        this.conn.prompt({
+          sessionId: this._sessionId,
+          prompt: [{ type: "text", text }]
+        })
+      );
+      return buffer.text;
+    } finally {
+      if (this.activeTurnBuffer === buffer) this.activeTurnBuffer = null;
+    }
+  }
+  /** Terminate the subprocess. Tolerant of an already-exited child. */
+  stopping = false;
+  async stop() {
+    this.stopping = true;
+    await Promise.race([
+      this.turnQueue.catch(() => {
+      }),
+      new Promise((resolve) => setTimeout(resolve, STOP_DRAIN_MS))
+    ]);
+    const child = this.child;
+    this.child = null;
+    this.conn = null;
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+    await new Promise((resolve) => {
+      const done = () => resolve();
+      child.once("exit", done);
+      try {
+        child.stdin.end();
+      } catch {
+      }
+      killProcessGroup(child, "SIGTERM");
+      const t = setTimeout(() => killProcessGroup(child, "SIGKILL"), 2e3);
+      child.once("exit", () => clearTimeout(t));
+    });
+  }
+  /**
+   * Race a connection promise against an unexpected subprocess exit so that a
+   * crash propagates as a rejection instead of leaving the await pending.
+   */
+  guard(p) {
+    if (this.exitError) return Promise.reject(this.exitError);
+    return new Promise((resolve, reject) => {
+      const rej = (err) => reject(err);
+      this.exitRejecters.add(rej);
+      p.then(
+        (v) => {
+          this.exitRejecters.delete(rej);
+          resolve(v);
+        },
+        (err) => {
+          this.exitRejecters.delete(rej);
+          reject(err);
+        }
+      );
+    });
+  }
+  /**
+   * Record an exit error and reject anything currently in flight. The SDK's
+   * ClientSideConnection is the primary safety net (it rejects pending JSON-RPC
+   * requests when the stream closes); this is the spawn-error/clarity layer that
+   * also covers spawn-level failures and gives a clear subprocess-exit message.
+   */
+  failPending(err) {
+    this.exitError = err;
+    for (const rej of this.exitRejecters) rej(err);
+    this.exitRejecters.clear();
+  }
+};
+
+// src/adapter.ts
+function launchSpecFor(agent) {
+  const cwd = process.cwd();
+  switch (agent) {
+    case "claude-code":
+      return { command: "npx", args: ["@agentclientprotocol/claude-agent-acp@latest"], cwd };
+    // codex: live-verified 2026-06-05 — clean ACP output, no tweaks needed.
+    case "codex":
+      return { command: "npx", args: ["@zed-industries/codex-acp@latest"], cwd };
+    // gemini: live-verified 2026-06-05. Use the current `--acp` flag (not the deprecated
+    // `--experimental-acp`) and pin a GA model — gemini-cli's default is a capacity-starved
+    // preview ("No capacity available for ... preview"); gemini-2.5-flash is GA + fast.
+    case "gemini":
+      return { command: "npx", args: ["@google/gemini-cli@latest", "--acp", "-m", "gemini-2.5-flash"], cwd };
+    // grok: xAI's Grok Build CLI has native ACP baked into the binary (`grok agent stdio`);
+    // no npx wrapper. Runs under the operator's own `grok` login / XAI_API_KEY. Pin a model
+    // via `-m` only if the default proves wrong (as gemini needed).
+    case "grok":
+      return { command: "grok", args: ["agent", "stdio"], cwd };
+    case "cursor":
+      throw new Error(
+        "cursor ACP adapter is unverified / not yet supported; choose claude-code, codex, or gemini"
+      );
+    default: {
+      const exhaustive = agent;
+      throw new Error(`Unknown ACP agent: ${String(exhaustive)}`);
+    }
+  }
+}
+var defaultAcpClientFactory = (launch) => new AcpClient(launch);
+var MAX_CONSECUTIVE_RESTARTS = 3;
+var RESTART_BACKOFF_MS = 250;
+var AcpAdapter = class {
+  constructor(agent, makeClient = defaultAcpClientFactory, backoffMs = RESTART_BACKOFF_MS) {
+    this.makeClient = makeClient;
+    this.backoffMs = backoffMs;
+    this.launch = launchSpecFor(agent);
+  }
+  makeClient;
+  backoffMs;
+  launch;
+  // --- supervised live state (set in start()) ---
+  client = null;
+  turnCbs = [];
+  /** Set true by stop() so a crash during/after intentional shutdown does NOT restart. */
+  stopped = false;
+  /** In-progress restart, shared by all concurrent failing turns (single-flight). */
+  restartInFlight = null;
+  /** Consecutive restart count; reset to 0 on any successful turn. */
+  consecutiveRestarts = 0;
+  /** Latched once the loop guard trips, so we stop trying (and stop retrying turns). */
+  gaveUp = false;
+  async start(_opts) {
+    this.client = this.makeClient(this.launch);
+    await this.client.start();
+    return {
+      submit: (text) => {
+        void this.handleTurn(text, true).then((delivered) => {
+          if (!delivered) this.turnCbs.forEach((cb) => cb(""));
+        }).catch(() => {
+          this.turnCbs.forEach((cb) => cb(""));
+        });
+      },
+      onTurn: (cb) => {
+        this.turnCbs.push(cb);
+      },
+      converseLocal: (text) => this.converseLocal(text),
+      stop: async () => {
+        this.stopped = true;
+        await this.client?.stop();
+      }
+    };
+  }
+  /**
+   * Submit a PRIVATE local aside on the SAME warm session and return the reply
+   * directly. Calls the underlying AcpClient.submit, which shares the one warm
+   * session/context and the serialized FIFO queue with channel turns, so the agent
+   * "remembers" both surfaces. Crucially it does NOT touch turnCbs, so the reply is
+   * never posted to the channel. A local aside on a dead/gave-up client returns a
+   * clear "agent unavailable" string rather than restarting (restart supervision is
+   * reserved for channel turns; a local REPL caller sees the message inline).
+   */
+  async converseLocal(text) {
+    const client = this.client;
+    if (!client || this.stopped || this.gaveUp) {
+      return "[arp-bridge] agent unavailable for local conversation";
+    }
+    try {
+      return await client.submit(text);
+    } catch (err) {
+      return `[arp-bridge] local turn failed: ${err?.message ?? String(err)}`;
+    }
+  }
+  /**
+   * Run one real channel turn against the warm session. On a turn that fails because
+   * the subprocess crashed, supervise a restart (single-flight, capped) and best-effort
+   * retry the triggering message ONCE. A non-crash failure (or a failure after the loop
+   * guard tripped, or after intentional stop) warns and posts nothing.
+   */
+  /** Returns true if a reply was delivered to onTurn, false on terminal failure. The
+   *  caller (submit) fires a terminal empty onTurn when this returns false, so onTurn
+   *  fires exactly once per submit. */
+  async handleTurn(text, allowRetry) {
+    const client = this.client;
+    if (!client) return false;
+    try {
+      const reply = await client.submit(text);
+      this.consecutiveRestarts = 0;
+      this.turnCbs.forEach((cb) => cb(reply));
+      return true;
+    } catch (err) {
+      if (this.stopped) {
+        console.warn(
+          "[arp-bridge] ACP turn failed during shutdown:",
+          err?.message ?? err
+        );
+        return false;
+      }
+      if (!client.exited || this.gaveUp) {
+        console.warn(
+          "[arp-bridge] ACP turn failed:",
+          err?.message ?? err
+        );
+        return false;
+      }
+      console.warn(
+        "[arp-bridge] ACP subprocess crashed mid-turn; attempting restart:",
+        err?.message ?? err
+      );
+      const recovered = await this.ensureRestarted();
+      if (recovered && allowRetry && !this.stopped) {
+        return await this.handleTurn(text, false);
+      }
+      return false;
+    }
+  }
+  /**
+   * Single-flight restart of the crashed subprocess. Concurrent failing turns all await
+   * the SAME in-flight restart (never spawning parallel restarts).
+   * Bounded by MAX_CONSECUTIVE_RESTARTS with a small linear backoff; on exceeding the
+   * cap it logs a clear error, latches gaveUp, and stops trying. Returns true if the
+   * session is alive again, false if it gave up.
+   */
+  ensureRestarted() {
+    if (this.restartInFlight) return this.restartInFlight;
+    this.restartInFlight = this.doRestart().finally(() => {
+      this.restartInFlight = null;
+    });
+    return this.restartInFlight;
+  }
+  async doRestart() {
+    if (this.stopped || this.gaveUp || !this.client) return false;
+    this.consecutiveRestarts += 1;
+    if (this.consecutiveRestarts > MAX_CONSECUTIVE_RESTARTS) {
+      this.gaveUp = true;
+      console.error(
+        `[arp-bridge] ACP subprocess failed to recover after ${MAX_CONSECUTIVE_RESTARTS} consecutive restarts; giving up (relay WS stays connected, channel messages will be dropped until the bridge is restarted)`
+      );
+      return false;
+    }
+    if (this.backoffMs > 0) await delay(this.backoffMs * this.consecutiveRestarts);
+    if (this.stopped) return false;
+    try {
+      await this.client.start();
+      return true;
+    } catch (e) {
+      console.warn(
+        "[arp-bridge] ACP restart attempt failed:",
+        e?.message ?? e
+      );
+      return false;
+    }
+  }
+};
+function delay(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function makeInputQueue() {
+  const buf = [];
+  let resolve = null;
+  let done = false;
+  const iterable = {
+    async *[Symbol.asyncIterator]() {
+      while (!done) {
+        if (buf.length === 0) await new Promise((r) => resolve = r);
+        while (buf.length) yield buf.shift();
+      }
+    }
+  };
+  return {
+    iterable,
+    push(text) {
+      buf.push({
+        type: "user",
+        message: { role: "user", content: text },
+        parent_tool_use_id: null,
+        session_id: ""
+      });
+      resolve?.();
+      resolve = null;
+    },
+    end() {
+      done = true;
+      resolve?.();
+      resolve = null;
+    }
+  };
+}
+var ClaudeAdapter = class {
+  async start(opts) {
+    const input = makeInputQueue();
+    const turnCbs = [];
+    let buffer = "";
+    const q = query({
+      prompt: input.iterable,
+      options: {
+        model: opts.model,
+        // No systemPrompt: the bridge imposes no persona. The SDK uses its default; the
+        // user's agent is itself. Situational framing is sent per message.
+        permissionMode: "bypassPermissions",
+        // headless: no interactive approval surface
+        allowDangerouslySkipPermissions: true
+        // required by the SDK when bypassing permissions
+        // ANTHROPIC_API_KEY is read by the SDK from the process env; we never pass it explicitly here.
+      }
+    });
+    (async () => {
+      for await (const m of q) {
+        if (m.type === "assistant") {
+          const blocks = m.message?.content ?? [];
+          const text = blocks.filter((b) => b.type === "text").map((b) => b.text ?? "").join("");
+          buffer += text;
+        } else if (m.type === "result") {
+          if (m.subtype === "success") {
+            const full = buffer.trim();
+            buffer = "";
+            if (full.length > 0) turnCbs.forEach((cb) => cb(full));
+          } else {
+            buffer = "";
+            console.warn("[arp-bridge] agent turn ended without success:", m.subtype);
+          }
+        }
+      }
+    })().catch((e) => {
+      console.warn("[arp-bridge] generic adapter stream error:", e && e.message || e);
+    });
+    return {
+      submit(text) {
+        input.push(text);
+      },
+      onTurn(cb) {
+        turnCbs.push(cb);
+      },
+      async stop() {
+        input.end();
+        try {
+          await q.interrupt();
+        } catch {
+        }
+      }
+    };
+  }
+};
+function createAdapter(cfg) {
+  return cfg.agentMode === "acp" ? new AcpAdapter(cfg.agent) : new ClaudeAdapter();
+}
+
+// src/elicit.ts
+var CARD_PROMPT = 'Answer IMMEDIATELY with ONLY a JSON object \u2014 do not deliberate, plan, or explain: { "description": string, "skills": [{ "id": string, "name": string, "description": string, "tags": string[] }] }. description = ONE short sentence on what you do. List ALL your skills (do not omit any), each with a SHORT description. No prose outside the JSON.';
+var CARD_PROMPT_RETRY = 'Reply with ONLY the JSON object, nothing else, immediately: { "description": string, "skills": [{ "id": string, "name": string, "description": string, "tags": string[] }] }';
+function isUsable(self) {
+  return !!self && self.description.trim().length > 0;
+}
+function delay2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function elicitCard(converse, agentName, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 12e4;
+  const maxAttempts = Math.max(1, opts.maxAttempts ?? 4);
+  const retryDelayMs = opts.retryDelayMs ?? 2e3;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const prompt = attempt === 0 ? CARD_PROMPT : CARD_PROMPT_RETRY;
+    try {
+      const reply = await withTimeout(converse(prompt), timeoutMs);
+      const self = parseCardReply(reply);
+      if (isUsable(self)) return buildPartialCard(agentName, self);
+    } catch {
+    }
+    if (attempt < maxAttempts - 1 && retryDelayMs > 0) await delay2(retryDelayMs);
+  }
+  return buildPartialCard(agentName, { description: opts.fallbackDescription ?? "", skills: [] });
+}
+function withTimeout(p, ms) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error("elicit timeout")), ms);
+    p.then((v) => {
+      clearTimeout(t);
+      resolve(v);
+    }, (e) => {
+      clearTimeout(t);
+      reject(e);
+    });
+  });
+}
+
+// src/bridge.ts
+async function startBridge(cfg, relay, deps) {
+  const sessions = /* @__PURE__ */ new Map();
+  const pending = /* @__PURE__ */ new Map();
+  const rosterUnsubs = /* @__PURE__ */ new Map();
+  const tornDownWhilePending = /* @__PURE__ */ new Set();
+  let selfCardPublished = false;
+  async function ensureSession(channelId) {
+    const live = sessions.get(channelId);
+    if (live) return live;
+    const inFlight = pending.get(channelId);
+    if (inFlight) return inFlight;
+    const p = (async () => {
+      const adapter = deps.makeAdapter(cfg);
+      const beacon = new ActivityBeacon((state) => relay.sendActivity(channelId, state));
+      const session = new ChannelSession(
+        adapter,
+        (text) => void relay.postMessage(channelId, text),
+        cfg.agentName,
+        channelId,
+        {
+          postReply: (flowId, content) => relay.postFlowMessage(channelId, flowId, content),
+          fetchHistory: (flowId) => relay.fetchFlowMessages(channelId, flowId)
+        },
+        () => relay.fetchChannelContext(channelId),
+        beacon
+      );
+      await session.start({ model: cfg.model });
+      sessions.set(channelId, session);
+      pending.delete(channelId);
+      if (!selfCardPublished) {
+        selfCardPublished = true;
+        void publishSelfCard(cfg, relay, session).catch(
+          (e) => console.warn("[arp-bridge] self card publish failed:", String(e))
+        );
+      }
+      const unsub = learnRoster(relay, channelId, session);
+      if (tornDownWhilePending.delete(channelId)) unsub();
+      else rosterUnsubs.set(channelId, unsub);
+      return session;
+    })();
+    pending.set(channelId, p);
+    p.catch(() => pending.delete(channelId));
+    return p;
+  }
+  function teardown(channelId) {
+    rosterUnsubs.get(channelId)?.();
+    rosterUnsubs.delete(channelId);
+    const s = sessions.get(channelId);
+    if (!s) {
+      if (pending.has(channelId)) tornDownWhilePending.add(channelId);
+      return;
+    }
+    sessions.delete(channelId);
+    void s.stop();
+  }
+  relay.onInbound((m) => {
+    if (m.isHistory) return;
+    if (m.senderId && m.senderId === cfg.agentUuid || m.senderName && m.senderName === cfg.agentName) return;
+    if (!m.content.trim()) return;
+    ensureSession(m.channelId).then((s) => s.submit(m)).catch((e) => console.warn(`[arp-bridge] inbound routing failed for channel ${m.channelId}:`, String(e)));
+  });
+  relay.onFlowSignal((signal) => {
+    if (!signal.channelId) return;
+    ensureSession(signal.channelId).then((s) => s.runFlowTurn(signal)).catch((e) => console.warn(`[arp-bridge] flow routing failed for channel ${signal.channelId}:`, String(e)));
+  });
+  relay.onCatchUp((channelId, result) => {
+    ensureSession(channelId).then((s) => s.submitCatchUp(result)).catch((e) => console.warn(`[arp-bridge] catch-up routing failed for channel ${channelId}:`, String(e)));
+  });
+  relay.onAdded((channelId) => {
+    ensureSession(channelId).catch((e) => console.warn(`[arp-bridge] pre-warm failed for channel ${channelId}:`, String(e)));
+  });
+  relay.onRemoved((channelId) => teardown(channelId));
+  relay.start();
+  maybeStartLocalRepl(cfg);
+  return { sessions, ensureSession, teardown };
+}
+function maybeStartLocalRepl(cfg) {
+  const optIn = isTruthy(process.env.ARP_LOCAL_REPL);
+  const interactive = process.stdin.isTTY === true;
+  if (!optIn || !interactive) return;
+  process.stdout.write(
+    "[arp-bridge] local chat is not available with the multi-channel router yet (no startup session).\n"
+  );
+}
+function isTruthy(v) {
+  if (!v) return false;
+  const s = v.trim().toLowerCase();
+  return s === "1" || s === "true" || s === "yes" || s === "on";
+}
+async function publishSelfCard(cfg, relay, session) {
+  let card;
+  if (cfg.agentMode === "acp") {
+    card = await elicitCard((t) => session.converseLocal(t), cfg.agentName);
+  } else {
+    card = buildPartialCard(cfg.agentName, { description: "", skills: [] });
+  }
+  await relay.putAgentCard(card);
+}
+function learnRoster(relay, channelId, session) {
+  const byName = /* @__PURE__ */ new Map();
+  const apply = () => session.setRoster([...byName.values()]);
+  const unsub = relay.onRoster((e) => {
+    byName.set(e.name, e);
+    apply();
+  });
+  void relay.fetchRoster(channelId).then((roster) => {
+    for (const e of roster) byName.set(e.name, e);
+    apply();
+  }).catch((err) => console.warn("[arp-bridge] learnRoster fetch failed:", String(err)));
+  return unsub;
+}
+async function createAndStartBridge(cfg, deps = {}) {
+  let wsFactory = deps.wsFactory;
+  if (!wsFactory) {
+    const WebSocketImpl = (await import("ws")).default;
+    wsFactory = (url) => new WebSocketImpl(url);
+  }
+  const relay = new RelayClient(cfg, {
+    wsFactory,
+    fetchFn: deps.fetchFn ?? fetch
+  });
+  if (deps.onFatal) relay.onFatal(deps.onFatal);
+  const makeAdapter = deps.makeAdapter ?? createAdapter;
+  const userOnReady = deps.onReady;
+  relay.onReady(() => {
+    userOnReady?.();
+  });
+  const { sessions, ensureSession } = await startBridge(cfg, relay, { makeAdapter });
+  return { relay, sessions, ensureSession };
+}
+
+// src/shutdown.ts
+function installGracefulShutdown(bridge) {
+  let shuttingDown = false;
+  const shutdown = async (sig) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log(`
+[arp-bridge] ${sig} received; shutting down gracefully...`);
+    const force = setTimeout(() => process.exit(0), 8e3);
+    force.unref?.();
+    try {
+      bridge.relay.stop();
+    } catch {
+    }
+    for (const s of bridge.sessions.values()) {
+      try {
+        await s.stop();
+      } catch {
+      }
+    }
+    clearTimeout(force);
+    process.exit(0);
+  };
+  process.once("SIGINT", () => void shutdown("SIGINT"));
+  process.once("SIGTERM", () => void shutdown("SIGTERM"));
+}
+
+// src/cli.ts
+async function main() {
+  const cfg = await resolveConfig(process.argv.slice(2), process.env);
+  console.log("[arp-bridge] starting", redactConfig(cfg));
+  const bridge = await createAndStartBridge(cfg);
+  installGracefulShutdown(bridge);
+  console.log("[arp-bridge] connected; routing per-channel sessions. Ctrl-C to stop.");
+}
+main().catch((err) => {
+  console.error("[arp-bridge] fatal:", err);
+  process.exit(1);
+});