viber-channel 0.8.2 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.8.2",
+  "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": {

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. " +