viber-channel 0.5.3 → 0.7.0

package/README.md

@@ -37,12 +37,40 @@ claude mcp add viber-channel --scope user \
 
 Restart Claude Code in the project directory. The channel acquires a single-instance lock under `%APPDATA%/viber/` (or `~/.config/viber/` on Linux/macOS), mints a conversation against the Worker, and subscribes to the conversation-scoped SSE stream.
 
+## Codex bridge experiment
+
+Issue #252 adds a Codex bridge as a sibling process to the Claude Code MCP channel. The bridge joins an existing Viber conversation as its own fresh Viber instance, listens to SSE events, forwards user/user_voice messages into a bridge-owned persistent `codex app-server` thread, and posts Codex's final reply back to Viber.
+
+Launch it against a conversation that already exists:
+
+```bash
+bun run viber-codex-bridge.ts --conversation <conversation_id>
+```
+
+Or via env fallback:
+
+```bash
+VIBER_TARGET_CONVERSATION_ID=<conversation_id> bun run viber-codex-bridge.ts
+```
+
+For one-shot validation, add `--once`; the bridge exits after the first Codex reply.
+
+The bridge persists its Codex thread id in `.viber/codex-bridge-threads.json` by default, keyed by project/fingerprint/conversation. Restarting the bridge resumes that thread, so Codex context carries across Viber turns. To reset/respawn the bridge-owned Codex session, start with `--new-thread`.
+
+Initial validation runs conservatively: `sandbox=read-only`, `approvalPolicy=on-request`, network disabled for turns, and developer instructions tell Codex not to run shell commands or read/write files. This is a validation posture, not a complete security boundary yet; hard permission enforcement must be designed before widening the bridge beyond read-only. Widen permissions only after the voice round-trip and memory test are validated.
+
+By default the bridge registers a fresh instance and does not persist it into the shared auth file. This avoids rotating another live agent's per-membership conversation token. For diagnostics only, `--reuse-auth-instance` restores the shared-auth behavior.
+
+For an agent-to-agent proof, add `--include-agent-messages --echo-content`. The bridge then reacts to non-user messages from other instances and replies with the exact content it received.
+
 ## Configuration
 
 | Env var | Default | Purpose |
 |---|---|---|
 | `VIBER_BASE_URL` | `https://viber.dgypx.dev` | Worker base URL (staging today; switch later if a separate prod hostname appears). |
 | `VIBER_CHANNEL_LABEL` | folder basename | Human-readable name for the conversation in the UI. |
+| `VIBER_CODEX_BIN` | `codex` | Codex executable used by `viber-codex-bridge` to spawn `codex app-server`. |
+| `VIBER_CODEX_BRIDGE_STATE` | `.viber/codex-bridge-threads.json` | Optional path for the bridge-owned Codex thread state file. |
 | `VIBER_CF_CLIENT_ID` / `VIBER_CF_CLIENT_SECRET` | unset | CF Access service-token headers (only needed when targeting a CF Access-protected hostname without a public bypass policy). |
 
 ## Source

package/lib/agent_tools.ts

@@ -0,0 +1,201 @@
+/**
+ * agent_tools.ts — shared logic for the three channel tools (#317).
+ *
+ * The Claude MCP server (viber-channel.ts) and the Codex bridge
+ * (viber-codex-bridge.ts) must expose the SAME tools with the SAME behaviour —
+ * one source, no double maintenance. This module holds that behaviour as pure,
+ * context-injected functions; each host wraps them in a thin adapter (an MCP
+ * CallTool handler for Claude, an in-process MCP server for Codex).
+ *
+ * The context is read through LIVE getters, never a snapshot: the host's
+ * conversation token rotates (token refresh / re-mint) and these functions must
+ * always read the current value at call time. That is why the context exposes
+ * functions, not fields.
+ *
+ * messages.ts (postMessage/parseArtifact) and peers.ts (listPeers/openDm) stay
+ * pure HTTP clients — this module orchestrates them and maps results to the
+ * MCP tool-result shape. It does NOT hold state.
+ */
+import { postMessage, parseArtifact, type Artifact } from "./messages.js";
+import { listPeers, openDm, type OpenDmResult } from "./peers.js";
+import { ConversationTokenExpiredError } from "./messages.js";
+
+/** MCP tool-result shape (text content + optional error flag). */
+export interface AgentToolResult {
+  isError?: boolean;
+  content: { type: "text"; text: string }[];
+}
+
+/**
+ * Live, by-reference access to the host channel's runtime state. Implemented by
+ * both hosts so the shared tool logic never reads a stale snapshot. Every getter
+ * is called at tool-invocation time.
+ */
+export interface AgentToolsContext {
+  /** API base URL (e.g. https://viber-dev.dgypx.dev). */
+  baseUrl(): string;
+  /** This instance's durable instance_token (Bearer) for the agent endpoints. */
+  instanceToken(): string;
+  /** WebSocket base URL used to stream an opened DM (empty until ready). */
+  voiceBaseUrl(): string;
+  /** Conversation id send_message posts into (main conv, or the active DM). */
+  sendConversationId(): string;
+  /** Conversation token paired with sendConversationId(). */
+  sendConversationToken(): string;
+  /**
+   * Start streaming a freshly opened DM so the peer's reply surfaces back on the
+   * host channel. The host supplies its own ws base URL; the lib only forwards
+   * the DM coordinates. Fire-and-forget (parity with the Claude channel).
+   */
+  startDmStream(dm: OpenDmResult): void;
+  /**
+   * Optional: the current stream's AbortSignal, passed to postMessage so a post
+   * in flight is cancelled atomically if the stream is torn down (re-join /
+   * revoke / shutdown). The Claude channel returns undefined (it never passed a
+   * signal); the Codex bridge returns its per-turn stream signal (#303 parity).
+   */
+  abortSignal?(): AbortSignal | undefined;
+}
+
+function text(s: string): AgentToolResult {
+  return { content: [{ type: "text" as const, text: s }] };
+}
+
+function errorText(s: string): AgentToolResult {
+  return { isError: true, content: [{ type: "text" as const, text: s }] };
+}
+
+/**
+ * list_agents — return this project's other agents so the model can pick one to
+ * message. Guards the startup window: an empty instance token means "channel not
+ * ready" rather than hitting the peers endpoint with no credential.
+ */
+export async function listAgents(ctx: AgentToolsContext): Promise<AgentToolResult> {
+  if (!ctx.instanceToken()) {
+    return errorText("Channel not ready: no instance identity yet.");
+  }
+  try {
+    const peers = await listPeers(ctx.baseUrl(), ctx.instanceToken());
+    // Project only what the model needs to pick a peer (drop last_seen /
+    // active_conversation_id — available over the wire if a future tool needs them).
+    const summary = peers.map((p) => ({ id: p.id, label: p.label, kind: p.kind, online: p.online }));
+    const body =
+      summary.length === 0
+        ? "No other agents are currently registered in this project."
+        : JSON.stringify(summary, null, 2);
+    return text(body);
+  } catch (err) {
+    return errorText(`list_agents failed: ${String(err)}`);
+  }
+}
+
+/**
+ * message_agent — open/reuse a DM with a peer and post a message, then start
+ * streaming that DM so the peer's reply arrives back on this channel. Mirrors
+ * the Claude MCP behaviour exactly: structured outcomes for offline / transient
+ * conflict, a clean retry hint on an expired DM token, and the DM stream started
+ * BEFORE the post so we are subscribed before the peer can reply.
+ */
+export async function messageAgent(
+  ctx: AgentToolsContext,
+  args: Record<string, unknown>,
+): Promise<AgentToolResult> {
+  if (!ctx.instanceToken() || !ctx.voiceBaseUrl()) {
+    return errorText("Channel not ready: no instance identity yet.");
+  }
+  const peerId = args.instance_id;
+  const body = args.text;
+  if (typeof peerId !== "string" || peerId.trim().length === 0) {
+    return errorText("Invalid input: instance_id must be a non-empty string");
+  }
+  if (typeof body !== "string" || body.trim().length === 0) {
+    return errorText("Invalid input: text must be a non-empty string");
+  }
+  const trimmedPeerId = peerId.trim();
+
+  let outcome;
+  try {
+    outcome = await openDm(ctx.baseUrl(), ctx.instanceToken(), trimmedPeerId);
+  } catch (err) {
+    return errorText(`message_agent failed: ${String(err)}`);
+  }
+  if (!outcome.ok) {
+    let friendly: string;
+    if (outcome.detail === "target_offline") {
+      friendly = "That agent is offline right now — it must be running to receive a DM.";
+    } else if (outcome.detail === "dm_unavailable_retry") {
+      friendly = "Could not open the DM due to a transient conflict — try message_agent again.";
+    } else {
+      friendly = `Could not open a DM: ${outcome.detail}`;
+    }
+    return errorText(friendly);
+  }
+
+  // Subscribe before posting so the peer's reply (which requires the peer agent
+  // to process the message, i.e. seconds) always loses the race to our subscribe.
+  ctx.startDmStream(outcome.dm);
+
+  let result;
+  try {
+    result = await postMessage(
+      ctx.baseUrl(),
+      outcome.dm.conversation_id,
+      outcome.dm.conversation_token,
+      body,
+      undefined,
+      ctx.abortSignal?.(),
+    );
+  } catch (err) {
+    // A DM membership token expired — unlike send_message we do NOT tear down the
+    // host here (the main conversation is unaffected). Tell the model to retry;
+    // a retry re-opens the DM with a fresh token.
+    if (err instanceof ConversationTokenExpiredError) {
+      return errorText("The DM session token expired — call message_agent again to re-open and resend.");
+    }
+    return errorText(`message_agent post failed: ${String(err)}`);
+  }
+  if (!result.ok) {
+    return errorText(result.detail);
+  }
+  return text(`Message sent to agent (DM ${outcome.dm.conversation_id}).`);
+}
+
+/**
+ * send_message — post text (+ optional artifact) into the conversation this turn
+ * belongs to. Guards the startup window (empty conversation token/id) and
+ * validates input identically to the Claude MCP.
+ *
+ * NB: a ConversationTokenExpiredError from postMessage is NOT caught here — the
+ * host adapter handles it (Claude tears down the channel; the bridge surfaces a
+ * controlled shutdown), because that policy differs per host.
+ */
+export async function sendMessage(
+  ctx: AgentToolsContext,
+  args: Record<string, unknown>,
+): Promise<AgentToolResult> {
+  if (!ctx.sendConversationToken() || !ctx.sendConversationId()) {
+    return errorText("Channel not ready: no conversation yet.");
+  }
+  const body = args.text;
+  if (typeof body !== "string" || body.trim().length === 0) {
+    return errorText("Invalid input: text must be a non-empty string");
+  }
+  const parsed = parseArtifact(args.artifact);
+  if (!parsed.ok) {
+    return errorText(`Invalid input: ${parsed.error}`);
+  }
+  const artifact: Artifact | undefined = parsed.artifact;
+
+  const result = await postMessage(
+    ctx.baseUrl(),
+    ctx.sendConversationId(),
+    ctx.sendConversationToken(),
+    body,
+    artifact,
+    ctx.abortSignal?.(),
+  );
+  if (!result.ok) {
+    return errorText(result.detail);
+  }
+  return text(`Message sent: ${result.message_id}`);
+}

package/lib/auth.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 
 export interface AuthJson {
@@ -20,6 +20,17 @@ export interface AuthJson {
    * the first successful mint, but doing so is not required for correctness.
    */
   target_conversation_id?: string | null;
+  /**
+   * Server-issued per-instance identity (#269). Both optional + additive, so
+   * `schema_version` stays **1**: an existing auth.json with neither field is
+   * valid and self-heals on first run (the channel registers an instance with
+   * its stable project_token and writes these back). `instance_token` is the
+   * durable, opaque per-agent credential (D4); `instance_id` is its server id,
+   * used to namespace the conversation handle (replacing the local fingerprint
+   * + VIBER_CHANNEL_SESSION_ID axes, #259).
+   */
+  instance_token?: string;
+  instance_id?: string;
 }
 
 /**
@@ -68,3 +79,41 @@ export function loadAuth(cwd: string = process.cwd()): AuthJson {
   }
   return auth;
 }
+
+/**
+ * Merge server-issued instance credentials into the auth file in place (#269
+ * self-healing migration). Reads the current JSON, sets `instance_id` +
+ * `instance_token`, and writes it back — preserving every other field and the
+ * `schema_version` (still 1; the fields are additive + optional).
+ *
+ * Best-effort: a write failure is logged, not fatal. The channel keeps the
+ * in-memory token for this run and simply re-registers on the next run (which
+ * yields a new instance — acceptable, the old one is just never reused).
+ */
+export function persistInstanceCredentials(
+  path: string,
+  instanceId: string,
+  instanceToken: string,
+  log: (msg: string) => void = (m) => process.stderr.write(m),
+): void {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const obj = JSON.parse(raw) as AuthJson;
+    obj.instance_id = instanceId;
+    obj.instance_token = instanceToken;
+    // mode 0o600: the file holds long-lived secrets (project_token + now the
+    // instance_token) — owner-read-only on POSIX (no-op on Windows). `mode` only
+    // applies when CREATING the file, so chmod afterwards too, to tighten an
+    // already-loose auth.json from an older version (best-effort).
+    writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+    try {
+      chmodSync(path, 0o600);
+    } catch {
+      /* best-effort — some filesystems (or Windows) reject chmod */
+    }
+  } catch (err) {
+    log(
+      `[viber-channel] Warning: failed to persist instance credentials to \`${path}\`: ${String(err)}\n`,
+    );
+  }
+}