viber-channel 0.5.3 → 0.7.0

package/lib/bridge_spawn.ts

@@ -0,0 +1,122 @@
+/**
+ * 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;
+		// #309 step-17: NEVER inherit the identity flag/role from the parent
+		// supervisor — a leaked VIBER_AGENT_NAME_EXPLICIT would make an auto id
+		// (agent-1) claim itself as an explicit name. Strip them here and re-derive
+		// authoritatively below (codex-309-review blocking #1).
+		delete env.VIBER_AGENT_NAME_EXPLICIT;
+		delete env.VIBER_AGENT_ROLE;
+		env.VIBER_AGENT_TIER = spec.tier;
+		if (spec.env) Object.assign(env, spec.env);
+		// Identity is set LAST, AFTER spec.env, so neither the inherited env nor a
+		// config `env` block can spoof the explicit-name flag or the role — the
+		// spec fields are the only source of truth (codex-309-review blocking #1).
+		// 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;
+		// Only an EXPLICIT name is claimed as the agent's name (the label is always
+		// set, even for auto ids); the separate flag is the safe signal. `else delete`
+		// closes the spoof path even if spec.env smuggled the flag in.
+		if (spec.nameExplicit) env.VIBER_AGENT_NAME_EXPLICIT = "1";
+		else delete env.VIBER_AGENT_NAME_EXPLICIT;
+		// The role is untrusted text the bridge sanitizes before injecting it.
+		if (spec.role !== undefined) env.VIBER_AGENT_ROLE = spec.role;
+		else delete env.VIBER_AGENT_ROLE;
+
+		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/bridge_tool_host.ts

@@ -0,0 +1,191 @@
+/**
+ * bridge_tool_host.ts — in-process MCP tool host for the Codex bridge (#317 iii).
+ *
+ * The bridge hosts a streamable-HTTP MCP server on loopback; `codex app-server`
+ * connects to it BY URL (mcp_servers.<name>.url). Because the server runs INSIDE
+ * the bridge process (no child spawn), the tools read the bridge's LIVE context
+ * (rotating token, current-turn conversation) by reference — never a snapshot.
+ * This is the same `agent_tools.ts` the Claude MCP uses: one source, no double
+ * maintenance.
+ *
+ * Security (viber-dev-315): the server binds to 127.0.0.1 only and requires an
+ * ephemeral bearer token, so no other local process can post into the channel
+ * through it.
+ *
+ * Anti-double-post (#317 #D): the bridge auto-posts a turn's final text only when
+ * NO outbound tool succeeded that turn. The host reports a SUCCESSFUL
+ * send_message / message_agent via `onOutboundSuccess` so the caller can suppress
+ * the auto-post. A FAILED outbound does NOT report success → the auto-post
+ * fallback still fires (no silent void). list_agents is read-only and never
+ * reports outbound.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import {
+  listAgents,
+  messageAgent,
+  sendMessage,
+  type AgentToolsContext,
+  type AgentToolResult,
+} from "./agent_tools.js";
+
+/** The three channel tools, named so codex (and the elicitation whitelist) match. */
+export const BRIDGE_TOOL_NAMES = ["send_message", "list_agents", "message_agent"] as const;
+export type BridgeToolName = (typeof BRIDGE_TOOL_NAMES)[number];
+
+/** Outbound tools whose SUCCESS suppresses the bridge's final auto-post. */
+const OUTBOUND_TOOLS: ReadonlySet<string> = new Set(["send_message", "message_agent"]);
+
+const TOOL_DEFS = [
+  {
+    name: "send_message",
+    description:
+      "Post your reply into the current Viber conversation. `text` is the conversational reply — " +
+      "read aloud AND shown as Markdown, so keep it short and natural but use light Markdown (short " +
+      "lists, numbered steps, **bold**) for readability; put actions/questions here, visibly. " +
+      "`artifact` is optional HEAVY/LONG content (big code, large tables, long analyses, json, " +
+      "sanitized html) shown in a side viewer; when used, keep `text` a brief summary pointing to it. " +
+      "Calling this IS your reply for the turn.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Spoken/conversational reply. Plain sentences." },
+        artifact: {
+          type: "object",
+          properties: {
+            content: { type: "string" },
+            format: { type: "string", enum: ["markdown", "code", "json", "html"] },
+          },
+          required: ["content"],
+          additionalProperties: false,
+        },
+      },
+      required: ["text"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_agents",
+    description:
+      "List the OTHER agents (instances) in this project you can DM. Returns each agent's id, " +
+      "label, runtime kind, and whether it is online. Use it to find an id before message_agent.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "message_agent",
+    description:
+      "Send a direct message to another agent in this project. Pass the target agent's instance id " +
+      "(from list_agents) and the text. Opens or reuses a private 1:1 DM and posts your message; " +
+      "the agent's reply arrives back on this channel. Fails if the target agent is offline.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        instance_id: { type: "string", description: "Target agent's instance id (from list_agents)." },
+        text: { type: "string", description: "Message to send to the target agent." },
+      },
+      required: ["instance_id", "text"],
+      additionalProperties: false,
+    },
+  },
+] as const;
+
+export interface BridgeToolHost {
+  /** URL codex connects to: http://127.0.0.1:<port>/mcp */
+  url: string;
+  /** Ephemeral bearer token value the host requires (pass to codex via env). */
+  bearerToken: string;
+  /** Stop the HTTP server. */
+  stop(): void;
+}
+
+export interface BridgeToolHostOptions {
+  /** Live bridge context (per-turn conversation, rotating token, DM streaming). */
+  ctx: AgentToolsContext;
+  /** Called with the tool name when an OUTBOUND tool (send_message/message_agent) SUCCEEDS. */
+  onOutboundSuccess: (tool: BridgeToolName) => void;
+  /** stderr-style logger. */
+  log: (line: string) => void;
+  /** Generate the ephemeral bearer token (injected for testability). */
+  makeToken: () => string;
+}
+
+/**
+ * Dispatch a single tool call to the shared lib and, on a successful outbound,
+ * report it. Exported for unit testing without spinning up the HTTP server.
+ */
+export async function dispatchBridgeTool(
+  name: string,
+  args: Record<string, unknown>,
+  opts: Pick<BridgeToolHostOptions, "ctx" | "onOutboundSuccess">,
+): Promise<AgentToolResult> {
+  let result: AgentToolResult;
+  if (name === "list_agents") {
+    result = await listAgents(opts.ctx);
+  } else if (name === "message_agent") {
+    result = await messageAgent(opts.ctx, args);
+  } else if (name === "send_message") {
+    result = await sendMessage(opts.ctx, args);
+  } else {
+    return { isError: true, content: [{ type: "text", text: `Unknown tool: ${name}` }] };
+  }
+  // Only a SUCCESSFUL outbound suppresses the auto-post (#317 #D: success, not attempt).
+  if (OUTBOUND_TOOLS.has(name) && result.isError !== true) {
+    opts.onOutboundSuccess(name as BridgeToolName);
+  }
+  return result;
+}
+
+function buildServer(opts: BridgeToolHostOptions): Server {
+  const mcp = new Server({ name: "viber-channel-tools", version: "0.1.0" }, { capabilities: { tools: {} } });
+  mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFS as unknown as object[] }));
+  mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const args = (request.params.arguments ?? {}) as Record<string, unknown>;
+    try {
+      return await dispatchBridgeTool(request.params.name, args, opts);
+    } catch (err) {
+      // The shared lib rethrows ConversationTokenExpiredError (host-specific
+      // teardown). In the bridge we surface it as a tool error rather than
+      // killing the turn mid-flight: the stream's own next op hits 401 and the
+      // refresh/abort path handles renewal. NOT reported as outbound success.
+      opts.log(`[bridge-tool-host] tool ${request.params.name} threw: ${String(err)}\n`);
+      return { isError: true, content: [{ type: "text", text: `Tool error: ${String(err)}` }] };
+    }
+  });
+  return mcp;
+}
+
+/**
+ * Start the loopback MCP HTTP host. Returns the URL + bearer for codex config.
+ * Stateless transport → a fresh Server+transport per request (SDK requirement).
+ */
+export function startBridgeToolHost(opts: BridgeToolHostOptions): BridgeToolHost {
+  const bearerToken = opts.makeToken();
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    async fetch(req) {
+      const auth = req.headers.get("authorization") ?? "";
+      if (auth !== `Bearer ${bearerToken}`) {
+        return new Response(JSON.stringify({ error: "unauthorized" }), {
+          status: 401,
+          headers: { "content-type": "application/json" },
+        });
+      }
+      const mcp = buildServer(opts);
+      const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+      });
+      await mcp.connect(transport);
+      return transport.handleRequest(req);
+    },
+  });
+  const url = `http://127.0.0.1:${server.port}/mcp`;
+  opts.log(`[bridge-tool-host] MCP tools on ${url} (loopback, bearer-guarded)\n`);
+  return {
+    url,
+    bearerToken,
+    stop: () => server.stop(true),
+  };
+}

package/lib/channel_session.ts

@@ -5,16 +5,17 @@
  * 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, client_fingerprint, VIBER_CHANNEL_SESSION_ID)` so:
+ * 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* projects on the same backend each have their own handle and
- *   never reattach to each other's conversation — the fingerprint axis is the
- *   only thing that isolates them for a normal bunx client (#267), where the
- *   sessionId is always "";
- * - two concurrent launches of the *same* project (each with its own session id
- *   set by viber-dev.ps1 / viber.ps1) each have their own handle (#259);
- * - channel respawns within one launch inherit the same session id and find
- *   the same handle — reattach still works (#257).
+ * - 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";
@@ -26,22 +27,24 @@ export interface ChannelHandle {
 }
 
 /**
- * Return the session file path for a given base URL, fingerprint, and session
- * id, under `dir`.
+ * 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${fingerprint}\n${sessionId}` — the same input
- * shape as `lockFilePath`, so the lock and session files sit side by side for
- * the same `(baseUrl, fingerprint, sessionId)` triple.
+ * 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,
-  fingerprint: string,
-  sessionId: string,
+  instanceKey: string,
   dir: string,
 ): string {
   const suffix = createHash("sha256")
-    .update(`${baseUrl}\n${fingerprint}\n${sessionId}`)
+    .update(`${baseUrl}\n${instanceKey}`)
     .digest("hex")
     .slice(0, 8);
   return join(dir, `channel-session-${suffix}.json`);

package/lib/connect.ts

@@ -12,6 +12,7 @@
 
 import {
   appendFileSync,
+  chmodSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -106,7 +107,15 @@ function writeAuthJson(
     auth.target_conversation_id = data.target_conversation_id;
   }
 
-  writeFileSync(authPath, 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.