viber-channel 0.5.2 → 0.6.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/auth.ts

@@ -1,5 +1,5 @@
-import { readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 
 export interface AuthJson {
   schema_version: number;
@@ -9,7 +9,6 @@ export interface AuthJson {
   project_token: string;
   client_fingerprint: string;
   issued_at: string;
-  rotates_after?: string;
   /**
    * Optional — when present, the CLI must pass this id to the conversation
    * mint endpoint so the worker UPDATES the existing standalone conversation
@@ -21,33 +20,44 @@ 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;
 }
 
 /**
- * Atomically update the project_token in .viber/auth.json.
- * Writes to a tmp file first, then renames (atomic on POSIX; also atomic on Windows for same-volume).
+ * Resolve the auth file path.
+ *
+ * Defaults to `<cwd>/.viber/auth.json`. The optional `VIBER_AUTH_FILE` env var
+ * overrides it — absolute paths are used verbatim, relative paths are resolved
+ * against `cwd`. This lets a local launcher point the channel at an alternate
+ * credential file (e.g. `.viber/dev.auth.json`) WITHOUT swapping `auth.json`,
+ * so the default consumer flow (env var unset) is completely unaffected.
  */
-export function updateAuthToken(folderPath: string, currentAuth: AuthJson, newToken: string): AuthJson {
-  const path = join(folderPath, ".viber", "auth.json");
-  const tmp = `${path}.tmp`;
-  const updated: AuthJson = {
-    ...currentAuth,
-    project_token: newToken,
-    issued_at: new Date().toISOString(),
-  };
-  writeFileSync(tmp, JSON.stringify(updated, null, 2), "utf-8");
-  renameSync(tmp, path);
-  return updated;
+export function authFilePath(cwd: string = process.cwd()): string {
+  const override = process.env.VIBER_AUTH_FILE;
+  if (override !== undefined && override.trim() !== "") {
+    return isAbsolute(override) ? override : join(cwd, override);
+  }
+  return join(cwd, ".viber", "auth.json");
 }
 
 export function loadAuth(cwd: string = process.cwd()): AuthJson {
-  const path = join(cwd, ".viber", "auth.json");
+  const path = authFilePath(cwd);
   let raw: string;
   try {
     raw = readFileSync(path, "utf-8");
   } catch {
     process.stderr.write(
-      `[viber-channel] No \`.viber/auth.json\` found in this folder.\n` +
+      `[viber-channel] No auth file found at \`${path}\`.\n` +
       `Run the connect flow first: visit https://viber.dgypx.dev/projects → Create connection.\n`
     );
     process.exit(1);
@@ -56,16 +66,54 @@ export function loadAuth(cwd: string = process.cwd()): AuthJson {
   try {
     auth = JSON.parse(raw) as AuthJson;
   } catch (err) {
-    process.stderr.write(`[viber-channel] Malformed .viber/auth.json: ${String(err)}\n`);
+    process.stderr.write(`[viber-channel] Malformed auth file \`${path}\`: ${String(err)}\n`);
     process.exit(1);
   }
   if (auth.schema_version !== 1) {
-    process.stderr.write(`[viber-channel] Unsupported auth schema version: ${auth.schema_version}\n`);
+    process.stderr.write(`[viber-channel] Unsupported auth schema version ${auth.schema_version} in \`${path}\`\n`);
     process.exit(1);
   }
   if (!auth.project_token) {
-    process.stderr.write(`[viber-channel] Empty project_token in .viber/auth.json\n`);
+    process.stderr.write(`[viber-channel] Empty project_token in \`${path}\`\n`);
     process.exit(1);
   }
   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`,
+    );
+  }
+}

package/lib/bridge_spawn.ts

@@ -0,0 +1,105 @@
+/**
+ * Bridge spawn adapter (#280 step-12, slice 3).
+ *
+ * Turns an `AgentSpec` into a real launched `viber-codex-bridge` child process and
+ * adapts it to the Supervisor's `ChildHandle`. The node `spawn` primitive is
+ * injected so the mapping (command, args, env, lifecycle wiring) is unit-testable
+ * without launching anything.
+ *
+ * Per-agent identity (critical): each child must register its OWN Viber instance.
+ * The supervisor process may itself have been launched with VIBER_INSTANCE_TOKEN /
+ * VIBER_INSTANCE_ID in its environment; if those leaked into every child, all
+ * agents would share one instance identity and evict each other's membership (the
+ * known shared-auth gotcha). So the adapter strips them from the child env, forcing
+ * the bridge's default "register a fresh instance" path.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+import type { AgentSpec, ChildHandle, SpawnFn } from "./supervisor.ts";
+
+/** Minimal child surface the adapter consumes (matches node's ChildProcess). */
+export interface SpawnedProcess {
+	readonly pid?: number;
+	kill(signal?: NodeJS.Signals): boolean;
+	once(
+		event: "exit",
+		listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+	): unknown;
+	/**
+	 * Launch failures (ENOENT for a missing command, EACCES, …) arrive here as an
+	 * async event — NOT a synchronous throw — so the adapter must listen for it or
+	 * a failed launch would leave the agent "running" with a dead child.
+	 */
+	once(event: "error", listener: (err: Error) => void): unknown;
+}
+
+/** The spawn primitive (injected; defaults to node's child_process.spawn). */
+export type NodeSpawnLike = (
+	command: string,
+	args: string[],
+	options: {
+		env: NodeJS.ProcessEnv;
+		stdio: ("ignore" | "inherit" | "pipe")[];
+	},
+) => SpawnedProcess;
+
+export interface BridgeSpawnOptions {
+	/** Launcher command. Default: the `viber-codex-bridge` bin on PATH. */
+	command?: string;
+	/** Args prepended before each agent's own args (e.g. a script path for `bun`). */
+	baseArgs?: string[];
+	/** Spawn primitive (injected for tests). Default: node child_process.spawn. */
+	spawnImpl?: NodeSpawnLike;
+}
+
+/**
+ * Build a `SpawnFn` for the Supervisor that launches the Codex bridge per agent.
+ *
+ * `AgentSpec.tier` → `VIBER_AGENT_TIER`; `AgentSpec.args` → bridge CLI flags;
+ * `AgentSpec.env` is merged last (so a spec can override). `VIBER_INSTANCE_TOKEN`
+ * / `VIBER_INSTANCE_ID` are stripped unless the spec explicitly re-supplies them.
+ */
+export function createBridgeSpawn(opts: BridgeSpawnOptions = {}): SpawnFn {
+	const command = opts.command ?? "viber-codex-bridge";
+	const baseArgs = opts.baseArgs ?? [];
+	const spawnImpl = opts.spawnImpl ?? (nodeSpawn as unknown as NodeSpawnLike);
+
+	return (spec: AgentSpec): ChildHandle => {
+		const env: NodeJS.ProcessEnv = { ...process.env };
+		// Force a fresh per-agent instance (see file header).
+		delete env.VIBER_INSTANCE_TOKEN;
+		delete env.VIBER_INSTANCE_ID;
+		env.VIBER_AGENT_TIER = spec.tier;
+		// Surface the agent id as the bridge's Viber instance label so distinct
+		// agents are identifiable in the control plane (participants strip / recipient
+		// picker) instead of all showing the same generic "Codex bridge" label.
+		env.VIBER_CODEX_BRIDGE_LABEL = spec.agentId;
+		if (spec.env) Object.assign(env, spec.env);
+
+		const child = spawnImpl(command, [...baseArgs, ...spec.args], {
+			env,
+			// stdin + stdout ignored, stderr inherited. stdout must NOT be inherited:
+			// if viber-channel runs over stdio MCP transport, the parent's stdout is
+			// the protocol wire and a child's stray stdout line would corrupt it.
+			stdio: ["ignore", "ignore", "inherit"],
+		});
+
+		return {
+			pid: child.pid,
+			kill: (signal?: NodeJS.Signals) => child.kill(signal),
+			onExit: (cb) => {
+				// Deliver exactly one terminal callback whether the child exits or
+				// fails to launch ("error"). A launch failure maps to a crash
+				// (null code/signal) so the supervisor runs its backoff path.
+				let fired = false;
+				const fire = (code: number | null, signal: NodeJS.Signals | null): void => {
+					if (fired) return;
+					fired = true;
+					cb(code, signal);
+				};
+				child.once("exit", (code, signal) => fire(code, signal));
+				child.once("error", () => fire(null, null));
+			},
+		};
+	};
+}

package/lib/channel_errors.ts

@@ -5,8 +5,8 @@ import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
  *
  * The CONVERSATION_TOKEN minted at startup has a 1h TTL. After expiry, the
  * server starts responding with 401. We notify the user and exit with code 3
- * (distinct from reverify exit code 2) so the process manager / user can
- * distinguish the cause.
+ * (distinct from the startup/mint failure exit code 1) so the process manager /
+ * user can distinguish the cause.
  *
  * We do NOT attempt to re-mint inline — the project_token is tied to the
  * original auth flow. The user must restart the channel to get a fresh token.

package/lib/channel_session.ts

@@ -0,0 +1,107 @@
+/**
+ * channel_session.ts — persist the channel's active conversation handle to disk.
+ *
+ * When a channel process mints or reattaches to a conversation, it writes the
+ * conversation_id here. A respawned channel process reads this file to find the
+ * existing conversation instead of minting a new one — avoiding duplicates (#257).
+ *
+ * Namespaced by `(VIBER_BASE_URL, instance_key)` since #269, where `instance_key`
+ * is the server-issued `instance_id` (or the `instance_token` when the id is
+ * unknown, e.g. an env-injected agent). This replaces the old
+ * `(client_fingerprint, VIBER_CHANNEL_SESSION_ID)` namespacing so:
+ * - dev and staging channels coexist on the same machine without colliding;
+ * - two *different* instances (different projects, OR two parallel agents of the
+ *   same project) each have their own handle and never reattach to each other's
+ *   conversation — the instance is the isolation axis now, no fingerprint or
+ *   session id required (#259);
+ * - channel respawns reusing the same persisted instance_token inherit the same
+ *   instance_id and find the same handle — reattach still works (#257).
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, unlinkSync } from "node:fs";
+
+export interface ChannelHandle {
+  conversation_id: string;
+  saved_at: number; // unix seconds
+}
+
+/**
+ * Return the session file path for a given base URL and instance key, under `dir`.
+ *
+ * The filename is `channel-session-{8-hex}.json` where the hex is a stable
+ * SHA-256 prefix of `${baseUrl}\n${instanceKey}`. Since #269 the handle is
+ * namespaced by the **server-issued instance** (its `instance_id`, or the
+ * `instance_token` when the id is unknown) instead of the local
+ * `(fingerprint, sessionId)` pair: one durable instance ⇒ one handle. Two
+ * parallel agents of the same project hold distinct instances, so they get
+ * distinct handles and never reattach to each other's conversation — without
+ * relying on `VIBER_CHANNEL_SESSION_ID`.
+ */
+export function sessionFilePath(
+  baseUrl: string,
+  instanceKey: string,
+  dir: string,
+): string {
+  const suffix = createHash("sha256")
+    .update(`${baseUrl}\n${instanceKey}`)
+    .digest("hex")
+    .slice(0, 8);
+  return join(dir, `channel-session-${suffix}.json`);
+}
+
+/**
+ * Read a persisted handle from `path`.
+ *
+ * Returns `null` — NEVER throws — when the file is absent, unreadable,
+ * contains invalid JSON, or the parsed object does not match the expected
+ * shape.
+ */
+export function readHandle(path: string): ChannelHandle | null {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      parsed === null ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed)
+    ) {
+      return null;
+    }
+    const obj = parsed as Record<string, unknown>;
+    if (typeof obj.conversation_id !== "string" || obj.conversation_id.length === 0) return null;
+    if (!Number.isFinite(obj.saved_at)) return null;
+    return { conversation_id: obj.conversation_id, saved_at: obj.saved_at as number };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the conversation handle to `path`.
+ *
+ * Overwrites any existing file. Propagates write errors (matches how
+ * `acquireLock` in viber-channel.ts propagates `writeFileSync` failures —
+ * the caller decides whether to handle them).
+ */
+export function writeHandle(path: string, conversationId: string): void {
+  const handle: ChannelHandle = {
+    conversation_id: conversationId,
+    saved_at: Math.floor(Date.now() / 1000),
+  };
+  writeFileSync(path, JSON.stringify(handle), "utf-8");
+}
+
+/**
+ * Remove the handle file at `path`.
+ *
+ * Best-effort — swallows errors if the file is absent, mirroring
+ * `releaseLock()` in viber-channel.ts.
+ */
+export function clearHandle(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Best-effort — file may already be gone
+  }
+}

package/lib/connect.ts

@@ -12,12 +12,14 @@
 
 import {
   appendFileSync,
+  chmodSync,
   existsSync,
   mkdirSync,
   readFileSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { authFilePath } from "./auth.js";
 import { clientFingerprint } from "./fingerprint.js";
 import { cfAccessHeaders } from "./cfAccess.js";
 
@@ -33,7 +35,6 @@ interface ConsumedResponse {
   user_email: string;
   project_token: string;
   issued_at: string;
-  rotates_after?: string;
   target_conversation_id?: string | null;
   readme_md: string;
 }
@@ -80,6 +81,13 @@ function writeAuthJson(
   const viberDir = join(cwd, ".viber");
   mkdirSync(viberDir, { recursive: true });
 
+  // Honor VIBER_AUTH_FILE so connecting with the override set writes the
+  // credentials to the same file the channel will read (e.g. dev.auth.json),
+  // instead of silently writing auth.json while the channel reads elsewhere.
+  // readme.md + .gitignore stay in <cwd>/.viber regardless.
+  const authPath = authFilePath(cwd);
+  mkdirSync(dirname(authPath), { recursive: true });
+
   const auth: Record<string, unknown> = {
     schema_version: 1,
     project_id: data.project_id,
@@ -88,7 +96,6 @@ function writeAuthJson(
     project_token: data.project_token,
     client_fingerprint: fingerprint,
     issued_at: data.issued_at,
-    rotates_after: data.rotates_after,
   };
   // Only emit target_conversation_id when the server explicitly returned a
   // non-null value (attach-to-project flow). Absent / null → omit to keep
@@ -100,11 +107,15 @@ function writeAuthJson(
     auth.target_conversation_id = data.target_conversation_id;
   }
 
-  writeFileSync(
-    join(viberDir, "auth.json"),
-    JSON.stringify(auth, null, 2),
-    "utf-8",
-  );
+  // mode 0o600: auth.json holds the project_token (and later the instance_token)
+  // — owner-read-only on POSIX (no-op on Windows). chmod afterwards too, since
+  // `mode` only applies on file creation (tightens an older loose auth.json).
+  writeFileSync(authPath, JSON.stringify(auth, null, 2), { encoding: "utf-8", mode: 0o600 });
+  try {
+    chmodSync(authPath, 0o600);
+  } catch {
+    /* best-effort — some filesystems (or Windows) reject chmod */
+  }
   writeFileSync(join(viberDir, "readme.md"), data.readme_md, "utf-8");
 
   // Append `.viber/` to .gitignore if not already present.
@@ -123,6 +134,20 @@ function writeAuthJson(
     const prefix = current === "" || current.endsWith("\n") ? "" : "\n";
     appendFileSync(gitignorePath, `${prefix}.viber/\n`);
   }
+
+  // The `.viber/` entry only covers credentials inside `.viber/`. If
+  // VIBER_AUTH_FILE points the auth file elsewhere, it is NOT auto-ignored —
+  // warn loudly so a project_token doesn't get committed by a later `git add`.
+  const relFromViber = relative(viberDir, authPath);
+  const insideViber =
+    relFromViber !== "" && !relFromViber.startsWith("..") && !isAbsolute(relFromViber);
+  if (!insideViber) {
+    process.stderr.write(
+      `[viber-channel] Warning: VIBER_AUTH_FILE points outside .viber/ (${authPath}).\n` +
+        `  This file holds your project token and is NOT covered by the .viber/ .gitignore entry.\n` +
+        `  Make sure it is git-ignored so the token is not committed.\n`,
+    );
+  }
 }
 
 /**
@@ -169,7 +194,7 @@ export async function runConnect(
       writeAuthJson(cwd, data, fingerprint);
       process.stdout.write(
         `\n✓ Connected as ${data.user_email} to project '${data.project_name}'.\n` +
-          `  Wrote ${join(cwd, ".viber", "auth.json")}\n\n` +
+          `  Wrote ${authFilePath(cwd)}\n\n` +
           `Next steps:\n` +
           `  1. Register the channel MCP server (one-time per machine):\n` +
           `       claude mcp add viber-channel --scope user -- bunx viber-channel@latest\n` +