viber-channel 0.8.1 → 0.8.3

package/lib/bridge_tool_host.ts

@@ -37,10 +37,14 @@ 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 = [
+// Exported so tests can assert the send_message/message_agent framing on THIS
+// (codex/gemma) surface independently of the Claude ListTools surface — a future
+// edit must not fix one runtime while breaking the other (#390 codex review).
+export const TOOL_DEFS = [
   {
     name: "send_message",
     description:
+      "Reply to the USER. This is the ONLY way to reach the user — they do NOT see your runtime/stdout, so never answer there. " +
       "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. " +
@@ -77,7 +81,7 @@ const TOOL_DEFS = [
   {
     name: "message_agent",
     description:
-      "Send a direct message to another agent. Pass the target agent's instance id " +
+      "Send a direct message to ANOTHER agent — NOT for replying to the user (use send_message for that). 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. Targets are normally same-project; an " +
       "ORCHESTRATOR instance (#307) can also message agents of the owner's other projects. " +

package/lib/channel_instructions.ts

@@ -0,0 +1,43 @@
+// The MCP `instructions` blob served to Claude sessions on the viber-channel
+// server. Extracted into a PURE function so it can be asserted in tests without
+// booting the MCP server (#390 step-03).
+//
+// #369 truncation fix: Claude Code truncates long MCP `instructions`
+// ("…[truncated]") and this blob was ~3 KB → the TAIL was dropped before the
+// agent saw it (that hid the agent's name #328, and threatened the #332 pointer
+// + exit-intent). So: CRITICAL lines are FRONT-LOADED (identity → core reply →
+// actions/questions → anti-deadlock → capabilities → exit) and the nice-to-have
+// style notes live at the tail where a cut is harmless.
+
+/**
+ * Build the MCP `instructions` string.
+ *
+ * @param identityLine the per-session agent identity line (from
+ *   agentIdentityFromEnv()) — "" for JP's own session (no explicit-name flag),
+ *   in which case it is filtered out and the rest of the blob still applies.
+ */
+export function buildChannelInstructions(identityLine: string): string {
+  return [
+    identityLine,
+    // --- critical: front-loaded so truncation can never drop them ---
+    // #390: route the REPLY unambiguously. The <channel> header carries TWO
+    // source= attributes — the first is the MCP server name (always
+    // "viber-channel"), the LAST is meta.source, the real discriminant:
+    // "microphone" = voice, "conversation" = typed UI text (both = the USER),
+    // "agent-dm" = another agent. Naming the real values (not the server name)
+    // avoids the old imprecise "source=viber-channel" cue.
+    'To reply to the USER, ALWAYS use send_message — NEVER write your answer to the terminal / your runtime stdout (the user does not watch it; there may be many terminals). A <channel> event whose metadata source (the last source= attribute) is "microphone" (voice) or "conversation" (typed text) is the user talking to you → reply with send_message. source="agent-dm" is ANOTHER agent → reply with message_agent. send_message = the user; message_agent = other agents ONLY, never the user.',
+    "Your send_message `text` is BOTH read aloud (TTS) AND shown as Markdown — make it natural aloud AND easy to read; lead with the answer, no preamble.",
+    "Put ACTIONS and QUESTIONS in `text`, visibly — never bury them in the artifact. Use light Markdown (short bullet/numbered lists, **bold**) to stay readable; a short spoken list is fine.",
+    // #343 anti-deadlock (hands-free: the user is NOT watching the terminal).
+    "CRITICAL — while this channel is active, NEVER block on a terminal prompt or AskUserQuestion: the user is hands-free and cannot see the terminal, so it deadlocks. Put EVERY question or choice in send_message `text` and take the answer from the next user message (voice or typed).",
+    // #332 discoverability pointer (the how-to lives in the capabilities tool).
+    "To orchestrate or spawn OTHER agents (Codex, Claude, Gemma) on this machine, call the `capabilities` tool for how — only when relevant.",
+    "On exit intent (bye, au revoir, stop) call stop_conversation(), speak a brief farewell, and stop.",
+    // --- nice-to-have style notes (safe near the tail) ---
+    "The `artifact` (format: markdown default, or code/json/html) is for HEAVY/LONG content (big code, large tables, long analyses, JSON, file lists); keep `text` a brief spoken summary that points to it ('details on the side'). Scripts/event handlers are stripped server-side.",
+    "NO EMOJI in `text` (read aloud — an emoji becomes spoken noise). Write identifiers LITERALLY (288, auth.json, viber-dev.dgypx.dev) — never spell out dots/dashes; a lone long token or path is better placed in the artifact.",
+  ]
+    .filter((line) => line.length > 0)
+    .join(" ");
+}

package/lib/control_stream.ts

@@ -297,6 +297,12 @@ export function runPersistentControlStream(
   };
 
   const done = (async () => {
+    // #389 step-02: announce ONCE that the instance control stream actually
+    // connected server-side (the SSE `connected` open-marker arrived) — proof
+    // the agent is ONLINE/reachable, not merely registered. vibe-master's spawn
+    // readiness gate polls the bridge log for this line, so a launch that
+    // registers then fails to connect (CF/401/network) is NOT reported as ready.
+    let announcedOnline = false;
     try {
       while (true) {
         if (signal?.aborted) {
@@ -305,6 +311,13 @@ export function runPersistentControlStream(
         }
         try {
           for await (const ev of subscribeControlStream(opts)) {
+            if (ev.event === "connected") {
+              if (!announcedOnline) {
+                announcedOnline = true;
+                log("[control-stream] online — instance control stream connected\n");
+              }
+              continue;
+            }
             if (ev.event === "stop") {
               settleFirstReject(new ControlStreamStopped());
               handlers.onStop?.("stopped");
@@ -314,7 +327,7 @@ export function runPersistentControlStream(
               handlers.onBeatNow?.();
               continue;
             }
-            if (ev.event !== "join") continue; // connected / ping / unknown
+            if (ev.event !== "join") continue; // ping / unknown (connected handled above)
             const minted = parseJoinPayload(ev.data, log);
             if (!minted) continue;
             handlers.onJoin?.(minted);

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "viber-channel",
-  "version": "0.8.1",
-  "description": "Voice + text MCP channel between a Claude Code session and the Viber UI (https://viber.dgypx.dev). Push transcripts to Claude; send_message tool delivers text back to the UI.",
-  "type": "module",
-  "bin": {
-    "viber-channel": "./viber-channel.ts",
-    "viber-codex-bridge": "./viber-codex-bridge.ts",
-    "viber-gemma-bridge": "./viber-gemma-bridge.ts",
-    "viber-codex-supervisor": "./viber-codex-supervisor.ts"
-  },
-  "files": [
-    "viber-channel.ts",
-    "viber-codex-bridge.ts",
-    "viber-gemma-bridge.ts",
-    "viber-codex-supervisor.ts",
-    "lib/",
-    "README.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/dgx80/viber.git",
-    "directory": "viber-channel"
-  },
-  "homepage": "https://viber.dgypx.dev",
-  "bugs": {
-    "url": "https://github.com/dgx80/viber/issues"
-  },
-  "keywords": [
-    "viber",
-    "claude-code",
-    "mcp",
-    "channel",
-    "voice",
-    "transcription"
-  ],
-  "license": "MIT",
-  "scripts": {
-    "start": "bun run viber-channel.ts",
-    "start:codex-bridge": "bun run viber-codex-bridge.ts",
-    "test": "bun test"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
-  }
-}
+{
+  "name": "viber-channel",
+  "version": "0.8.3",
+  "description": "Voice + text MCP channel between a Claude Code session and the Viber UI (https://viber.dgypx.dev). Push transcripts to Claude; send_message tool delivers text back to the UI.",
+  "type": "module",
+  "bin": {
+    "viber-channel": "./viber-channel.ts",
+    "viber-codex-bridge": "./viber-codex-bridge.ts",
+    "viber-gemma-bridge": "./viber-gemma-bridge.ts",
+    "viber-codex-supervisor": "./viber-codex-supervisor.ts"
+  },
+  "files": [
+    "viber-channel.ts",
+    "viber-codex-bridge.ts",
+    "viber-gemma-bridge.ts",
+    "viber-codex-supervisor.ts",
+    "lib/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dgx80/viber.git",
+    "directory": "viber-channel"
+  },
+  "homepage": "https://viber.dgypx.dev",
+  "bugs": {
+    "url": "https://github.com/dgx80/viber/issues"
+  },
+  "keywords": [
+    "viber",
+    "claude-code",
+    "mcp",
+    "channel",
+    "voice",
+    "transcription"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "start": "bun run viber-channel.ts",
+    "start:codex-bridge": "bun run viber-codex-bridge.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/viber-channel.ts

@@ -55,6 +55,7 @@ import {
 } from "./lib/token_refresh.ts";
 import { awaitStableStartup } from "./lib/startup_gate.ts";
 import { agentIdentityFromEnv } from "./lib/bridge_core.ts";
+import { buildChannelInstructions } from "./lib/channel_instructions.ts";
 import { warnIfStale } from "./lib/version_check.ts";
 import { capabilitiesText } from "./lib/capabilities.ts";
 
@@ -353,32 +354,10 @@ const mcp = new Server(
       experimental: { "claude/channel": {} },
       tools: {},
     },
-    // #369 truncation fix: Claude Code truncates long MCP `instructions`
-    // ("…[truncated]") and this blob was ~3 KB → the TAIL was dropped before the
-    // agent saw it (that hid the agent's name #328, and threatened the #332
-    // pointer + exit-intent). So: CRITICAL lines are FRONT-LOADED (identity →
-    // core reply → actions/questions → anti-deadlock → capabilities → exit) and
-    // the nice-to-have style notes live at the tail where a cut is harmless.
-    // Condensed vs the old prose (same substance — reviewed). Identity is "" for
-    // JP's own session (no explicit-name flag) → the identity LINE is filtered
-    // out for him; the rest of the (now shorter, reordered) blob applies to every
-    // session including his.
-    instructions: [
-      agentIdentityFromEnv(),
-      // --- critical: front-loaded so truncation can never drop them ---
-      'Voice transcripts arrive as <channel source="viber-channel"> events (the user\'s microphone speech). Reply with send_message. The `text` is BOTH read aloud (TTS) AND shown as Markdown — make it natural aloud AND easy to read; lead with the answer, no preamble.',
-      "Put ACTIONS and QUESTIONS in `text`, visibly — never bury them in the artifact. Use light Markdown (short bullet/numbered lists, **bold**) to stay readable; a short spoken list is fine.",
-      // #343 anti-deadlock (hands-free: the user is NOT watching the terminal).
-      "CRITICAL — while this channel is active, NEVER block on a terminal prompt or AskUserQuestion: the user is hands-free and cannot see the terminal, so it deadlocks. Put EVERY question or choice in send_message `text` and take the answer from the next voice transcript.",
-      // #332 discoverability pointer (the how-to lives in the capabilities tool).
-      "To orchestrate or spawn OTHER agents (Codex, Claude, Gemma) on this machine, call the `capabilities` tool for how — only when relevant.",
-      "On exit intent (bye, au revoir, stop) call stop_conversation(), speak a brief farewell, and stop.",
-      // --- nice-to-have style notes (safe near the tail) ---
-      "The `artifact` (format: markdown default, or code/json/html) is for HEAVY/LONG content (big code, large tables, long analyses, JSON, file lists); keep `text` a brief spoken summary that points to it ('details on the side'). Scripts/event handlers are stripped server-side.",
-      "NO EMOJI in `text` (read aloud — an emoji becomes spoken noise). Write identifiers LITERALLY (288, auth.json, viber-dev.dgypx.dev) — never spell out dots/dashes; a lone long token or path is better placed in the artifact.",
-    ]
-      .filter((line) => line.length > 0)
-      .join(" "),
+    // The blob lives in a PURE builder (lib/channel_instructions.ts) so it can be
+    // asserted in tests without booting the server (#390). Identity is "" for JP's
+    // own session (no explicit-name flag) → filtered out; the rest applies to all.
+    instructions: buildChannelInstructions(agentIdentityFromEnv()),
   }
 );
 
@@ -389,6 +368,7 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "send_message",
       description:
+        "Reply to the USER. This is how you talk to the user — NOT the terminal / your stdout (they do not watch it). Calling this IS your reply for the turn. " +
         "Send a message into the Viber conversation this channel is bound to. " +
         "`text` is the conversational reply — it is BOTH read aloud (TTS) AND rendered as Markdown on screen, so keep it short and natural but use light Markdown (short bullet/numbered lists, **bold**) when it aids readability. Put any ACTIONS or QUESTIONS for the user here, visibly. " +
         "`artifact` is optional and carries HEAVY/LONG content (big code, large tables, long analyses, JSON, sanitized HTML) rendered in a side viewer; when used, keep `text` a brief summary that points to it. " +
@@ -444,7 +424,7 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "message_agent",
       description:
-        "Send a direct message to another agent (#288). " +
+        "Send a direct message to ANOTHER agent (#288) — NOT for replying to the user (use send_message for that). " +
         "Pass the target agent's instance id (from list_agents, or the from_instance_id of a DM you received) " +
         "and the message text. Opens or reuses a private 1:1 DM with that agent and posts your message; " +
         "the agent's reply arrives back on this channel tagged source=agent-dm. " +

package/viber-codex-bridge.ts

@@ -356,7 +356,7 @@ function instructionsForTier(tier: AgentTier): string {
     return [
       "You are a bridge-owned Codex agent connected to Viber, in READ-WRITE mode.",
       "You MAY read files, create/modify files within the workspace, and run commands (including state-changing ones) to carry out the user's requests.",
-      "The sandbox is workspace-write: writes are confined to the workspace and network access is blocked at the OS level.",
+      "The sandbox is workspace-write: writes are confined to the workspace, and network access is ENABLED — so you can run git (including `git push`) and open pull requests (e.g. with `gh`).",
       "There is NO human approval step, so be deliberate: make only the changes the user asked for, and avoid destructive commands unless explicitly requested.",
       VOICE_CONCISE_LINE,
       CHANNEL_TOOLS_LINE,
@@ -385,17 +385,43 @@ function instructionsForTier(tier: AgentTier): string {
 // Approval policy per tier. `read`/`write` use "never" so Codex runs its commands
 // WITHOUT a human approver (there is none on the bridge) — the SANDBOX is the real
 // guardrail (read-only blocks writes/network; workspace-write confines writes to
-// the workspace and still blocks network). `chat` keeps "on-request" (no exec anyway).
-function approvalForTier(tier: AgentTier): "never" | "on-request" {
+// the workspace). `chat` keeps "on-request" (no exec anyway).
+export function approvalForTier(tier: AgentTier): "never" | "on-request" {
   return tier === "chat" ? "on-request" : "never";
 }
 
 // Codex OS sandbox per tier. `write` widens to workspace-write (edits confined to
-// the workspace, network still blocked); chat/read stay read-only.
-function sandboxForTier(tier: AgentTier): "read-only" | "workspace-write" {
+// the workspace); chat/read stay read-only.
+export function sandboxForTier(tier: AgentTier): "read-only" | "workspace-write" {
   return tier === "write" ? "workspace-write" : "read-only";
 }
 
+// Network access per tier (#389 step-03). ONLY the trusted `write` tier gets
+// network — so a codex coder can `git push` and open its PR (git-over-https +
+// `gh`). read/chat stay offline. SECURITY: codex's workspace-write sandbox opens
+// ALL network, not git-only (the app-server sandbox has no per-domain allowlist),
+// so this is a TRUST decision scoped to the write tier, which is already
+// operator-authorized-at-launch for unattended command execution. If codex ever
+// exposes an outbound-domain allowlist, tighten here (follow-up issue).
+export function networkForTier(tier: AgentTier): boolean {
+  return tier === "write";
+}
+
+// The EXACT `sandboxPolicy` object sent on every `turn/start` (#389 step-03).
+// Per the codex app-server protocol (generate-ts), `networkAccess` lives ONLY on
+// this per-turn policy object (workspaceWrite/readOnly variants) — NOT on
+// thread/start|resume, which take a bare `sandbox` MODE string. So the turn-level
+// policy is the single lever for network. Exported to unit-test the payload/tier.
+export function buildTurnSandboxPolicy(
+  tier: AgentTier,
+):
+  | { type: "workspaceWrite"; networkAccess: boolean }
+  | { type: "readOnly"; networkAccess: boolean } {
+  return sandboxForTier(tier) === "workspace-write"
+    ? { type: "workspaceWrite", networkAccess: networkForTier(tier) }
+    : { type: "readOnly", networkAccess: false };
+}
+
 const AGENT_TIER: AgentTier = resolveAgentTier();
 // Identity line (#309 step-17) is appended AFTER the tier instructions so the
 // permission rules stay first + strongest; the role is framed as descriptive and
@@ -635,10 +661,7 @@ class CodexAppServer {
       cwd: process.cwd(),
       runtimeWorkspaceRoots: [process.cwd()],
       approvalPolicy: AGENT_APPROVAL_POLICY,
-      sandboxPolicy:
-        AGENT_SANDBOX === "workspace-write"
-          ? { type: "workspaceWrite", networkAccess: false }
-          : { type: "readOnly", networkAccess: false },
+      sandboxPolicy: buildTurnSandboxPolicy(AGENT_TIER),
       developerInstructions: AGENT_INSTRUCTIONS,
       responsesapiClientMetadata: { source: "viber-codex-bridge" },
     });
@@ -1115,7 +1138,7 @@ function setupCodexRuntime(deps: {
 
 function logCodexSafety(): void {
   process.stderr.write(
-    `${LOG_PREFIX} codex safety: tier=${AGENT_TIER}, sandbox=${AGENT_SANDBOX}, approvalPolicy=${AGENT_APPROVAL_POLICY}, network=false, ` +
+    `${LOG_PREFIX} codex safety: tier=${AGENT_TIER}, sandbox=${AGENT_SANDBOX}, approvalPolicy=${AGENT_APPROVAL_POLICY}, network=${networkForTier(AGENT_TIER)}, ` +
       `instructions=${
         AGENT_TIER === "write"
           ? "read+write/run commands (workspace)"