viber-channel 0.7.2 → 0.8.0

package/lib/bridge_core.ts

@@ -841,14 +841,23 @@ export function buildAgentIdentityInstructions(opts: {
 
 /**
  * Read the agent identity from the spawn env and build the identity line.
- * `VIBER_AGENT_NAME_EXPLICIT === "1"` gates whether `VIBER_CODEX_BRIDGE_LABEL`
- * is treated as an explicit name (the label is always set — even for auto ids —
- * so the separate flag is the only safe signal). Shared by every bridge.
+ * `VIBER_AGENT_NAME_EXPLICIT === "1"` gates whether the spawn label is treated as
+ * an explicit name (the label is always set — even for auto ids — so the separate
+ * flag is the only safe signal). Shared by every runtime:
+ *   - the codex/gemma bridges set `VIBER_CODEX_BRIDGE_LABEL`;
+ *   - a Claude terminal session (#328) has no bridge — its label is
+ *     `VIBER_CHANNEL_LABEL` (set by buildClaudeLaunchSpec) — so fall back to it.
  */
 export function agentIdentityFromEnv(): string {
 	const explicit = process.env.VIBER_AGENT_NAME_EXPLICIT === "1";
+	// A BLANK bridge label counts as absent (defense in depth, #328): the terminal
+	// launcher wipes an inherited VIBER_CODEX_BRIDGE_LABEL to "", so a Claude
+	// session falls through to its own VIBER_CHANNEL_LABEL instead of a leaked
+	// parent bridge name.
+	const bridgeLabel = process.env.VIBER_CODEX_BRIDGE_LABEL?.trim();
+	const label = bridgeLabel || process.env.VIBER_CHANNEL_LABEL;
 	return buildAgentIdentityInstructions({
-		explicitName: explicit ? process.env.VIBER_CODEX_BRIDGE_LABEL : undefined,
+		explicitName: explicit ? label : undefined,
 		role: process.env.VIBER_AGENT_ROLE,
 	});
 }

package/lib/capabilities.ts

@@ -0,0 +1,41 @@
+/**
+ * Control-plane capabilities help (#332).
+ *
+ * An agent connected via the channel does not otherwise know that a `vibe-master`
+ * control plane exists on the machine, nor how to spawn other agents with it. Per
+ * the issue + JP: this must be DISCOVERABLE ON DEMAND, never injected into every
+ * conversation. So the channel exposes a `capabilities` MCP tool that returns
+ * this text only when the agent chooses to call it; the channel instructions
+ * carry just a one-line pointer to the tool, not its contents.
+ *
+ * Pure (no I/O) so it is trivially testable and identical across hosts.
+ */
+
+export function capabilitiesText(): string {
+	return [
+		"Viber control plane (vibe-master) — orchestrate other agents from this machine.",
+		"",
+		"vibe-master is a CLI + TUI (installed on the operator machine) that spawns and",
+		"supervises agents which appear in the Viber web UI and answer in their own",
+		"conversations. Use it when you want to delegate to another agent (e.g. a Codex",
+		"reviewer, a second Claude, or a Gemma chat).",
+		"",
+		"Runtimes: codex (background, via vctl) · gemma (background) · claude (terminal).",
+		"(--runtime defaults to codex. Gemma is conversational/read-only only — it",
+		" rejects --permission read-write.)",
+		"",
+		"Spawn one agent (CLI, non-interactive):",
+		"  vibe-master spawn --permission <read-only|read-write> \\",
+		"                    [--runtime codex|claude|gemma] [--name <id>]",
+		"  → only --permission is required; --runtime and --name are optional",
+		"    (--name auto-generated if omitted). Prints the agent id; it registers",
+		"    in Viber and comes online.",
+		"",
+		"Interactive: `vibe-master tui` (menu: + Add agent → runtime → permission → name).",
+		"Inspect / stop: `vibe-master list` · `vibe-master kill <id>`.",
+		"",
+		"Talk to a spawned agent from here with list_agents + message_agent.",
+		"Requires vibe-master installed on the machine (see the Install page on the web).",
+		"Run `vibe-master --help` for the full command reference.",
+	].join("\n");
+}

package/lib/lockfile.ts

@@ -14,8 +14,8 @@
  * axis that isolates them for a normal bunx client, where sessionId is always
  * "" (the #259 sessionId axis below provides no isolation there).
  *
- * #259 adds the per-instance axis: when the launcher (e.g. viber-dev.ps1)
- * supplies a per-launch session id via VIBER_CHANNEL_SESSION_ID, the lock is
+ * #259 adds the per-instance axis: when a launcher supplies a per-launch session
+ * id via VIBER_CHANNEL_SESSION_ID, the lock is
  * additionally namespaced by it, so two concurrent launches of the *same*
  * project each get their own lock. Channel respawns within one launch inherit
  * the same env var and reuse the same lock — accidental duplicates are still

package/lib/version_check.ts

@@ -0,0 +1,124 @@
+/**
+ * viber-channel stale-version guard (#330).
+ *
+ * A globally-installed `viber-channel` that a user placed by hand (old docs) can
+ * fall far behind npm `latest`. When a later refactor removes/renames a lib file,
+ * that stale install crashes with a raw `Cannot find module './lib/…'` instead of
+ * anything actionable. We can't fix an ALREADY-broken old install from here (its
+ * code predates this guard), so the useful move is PREVENTION: on every startup
+ * that still runs, check whether the installed version is behind `latest` and, if
+ * so, print a clear one-line nudge to update — BEFORE the user ever hits a
+ * breaking refactor. Best-effort and non-fatal: any error (offline, timeout, odd
+ * registry response) is swallowed so the channel starts normally.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const NPM_LATEST_URL = "https://registry.npmjs.org/viber-channel/latest";
+const DEFAULT_TIMEOUT_MS = 1500;
+
+/** Parse a `major.minor.patch` string to a numeric tuple; non-numeric → 0. */
+function parseVersion(v: string): [number, number, number] {
+	const parts = v
+		.trim()
+		.replace(/^v/, "")
+		.split(".")
+		.map((p) => Number.parseInt(p, 10));
+	return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+
+/** True iff `local` is strictly older than `latest` (major.minor.patch order). */
+export function isOlder(local: string, latest: string): boolean {
+	const a = parseVersion(local);
+	const b = parseVersion(latest);
+	for (let i = 0; i < 3; i++) {
+		if (a[i] < b[i]) return true;
+		if (a[i] > b[i]) return false;
+	}
+	return false;
+}
+
+/** Read this package's own version from its package.json (best-effort → null). */
+export function readLocalVersion(
+	readFile: (p: string) => string = (p) => readFileSync(p, "utf-8"),
+	dir: string = import.meta.dir,
+): string | null {
+	try {
+		const pkg = JSON.parse(readFile(join(dir, "..", "package.json")));
+		return typeof pkg.version === "string" ? pkg.version : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Fetch npm `latest` version with a short timeout; null on any failure. */
+export async function fetchLatestVersion(
+	timeoutMs: number = DEFAULT_TIMEOUT_MS,
+	fetchImpl: typeof fetch = fetch,
+): Promise<string | null> {
+	const ctrl = new AbortController();
+	const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+	try {
+		const res = await fetchImpl(NPM_LATEST_URL, { signal: ctrl.signal });
+		if (!res.ok) return null;
+		const body = (await res.json()) as { version?: unknown };
+		return typeof body.version === "string" ? body.version : null;
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+export interface StaleCheck {
+	local: string;
+	latest: string;
+	stale: boolean;
+}
+
+/** Compare the installed version against npm latest. Null when either is unknown. */
+export async function checkStaleVersion(opts?: {
+	localVersion?: string | null;
+	fetchLatest?: () => Promise<string | null>;
+}): Promise<StaleCheck | null> {
+	// Honor an EXPLICIT localVersion (incl. null = "unknown"); only read the real
+	// package.json when the caller didn't pass the key at all.
+	const local =
+		opts && "localVersion" in opts ? opts.localVersion : readLocalVersion();
+	if (!local) return null;
+	const latest = opts?.fetchLatest
+		? await opts.fetchLatest()
+		: await fetchLatestVersion();
+	if (!latest) return null;
+	return { local, latest, stale: isOlder(local, latest) };
+}
+
+/** The one-line nudge printed to stderr when the install is behind. */
+export function staleWarning(local: string, latest: string): string {
+	return (
+		`[viber-channel] version ${local} is behind latest ${latest}. ` +
+		`Update to avoid a broken install: bun add -g viber-channel@latest`
+	);
+}
+
+/**
+ * Best-effort: warn on stderr when this install is behind npm latest. Never
+ * throws, never blocks longer than the fetch timeout. Called at startup.
+ */
+export async function warnIfStale(opts?: {
+	localVersion?: string | null;
+	fetchLatest?: () => Promise<string | null>;
+	write?: (msg: string) => void;
+}): Promise<void> {
+	try {
+		const check = await checkStaleVersion(opts);
+		if (check?.stale) {
+			(opts?.write ?? ((m) => process.stderr.write(`${m}\n`)))(
+				staleWarning(check.local, check.latest),
+			);
+		}
+	} catch {
+		/* best-effort — never break startup on a version check */
+	}
+}

package/package.json

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

@@ -16,9 +16,9 @@
  *
  *   claude --dangerously-load-development-channels server:<name>
  *
- * Two PowerShell launchers wrap the right flag:
- *   - viber.ps1       → server:viber-channel (staging)
- *   - viber-dev.ps1   → server:viber-dev-channel (this repo, dev)
+ * For dev in this repo, vibe-master-dev.ps1 (the multi-agent TUI launcher) wraps
+ * the flag: `server:viber-dev-channel` against the dev backend. Staging sessions
+ * use the plain user-scoped `viber-channel` registration with no launcher flag.
  *
  * CLI subcommand: `bunx viber-channel connect <claim_url>` runs the one-shot
  * claim flow that writes .viber/auth.json without requiring any Claude Code
@@ -54,6 +54,9 @@ import {
   type TokenRefreshScheduler,
 } from "./lib/token_refresh.ts";
 import { awaitStableStartup } from "./lib/startup_gate.ts";
+import { agentIdentityFromEnv } from "./lib/bridge_core.ts";
+import { warnIfStale } from "./lib/version_check.ts";
+import { capabilitiesText } from "./lib/capabilities.ts";
 
 // ---- CLI subcommand dispatch (must happen before lock acquire + loadAuth) ----
 //
@@ -98,6 +101,11 @@ import { awaitStableStartup } from "./lib/startup_gate.ts";
       );
       process.exit(1);
     }
+    // #330: this is the exact path that crashed on a stale hand-placed install
+    // (`bunx viber-channel connect` → missing ./lib/peers.ts). Await the check
+    // here so the "you're behind, update" nudge shows BEFORE the connect work
+    // (best-effort — never throws, short timeout).
+    await warnIfStale();
     try {
       await runConnect(claimUrl);
       process.exit(0);
@@ -108,6 +116,11 @@ import { awaitStableStartup } from "./lib/startup_gate.ts";
   }
 }
 
+// Server path (fell through the dispatch block): warn if this install is behind
+// npm latest, but fire-and-forget so it never delays mcp.connect — the nudge
+// lands on stderr shortly after startup (#330).
+void warnIfStale();
+
 // Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac).
 // Namespaced by (VIBER_BASE_URL, client_fingerprint, VIBER_CHANNEL_SESSION_ID) so:
 //   - channels at different backends (staging + dev) coexist (different base_url);
@@ -340,18 +353,32 @@ 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: [
-      'Voice transcripts arrive as <channel source="viber-channel"> events carrying the user\'s microphone speech.',
-      "Reply with send_message. You are talking to a human who both LISTENS (the `text` is read aloud by TTS) AND READS it on screen (the `text` is ALSO rendered as Markdown in the UI). So aim for both: it must sound natural read aloud AND be easy to read. Lead with the answer, no preamble or recap.",
-      "USE light Markdown in `text` when it makes the message easier to read: short bullet lists (`- `), numbered steps (`1.`), checklists, **bold** for key terms. A short list reads aloud just fine — a spoken list is natural. Don't cram several points into one dense paragraph; break them out. Avoid heavy/awkward-to-speak markup (big tables, code blocks, long fenced snippets) in `text` — that belongs in the artifact.",
-      "ACTIONS and QUESTIONS belong in `text`, made visible — never bury them in the artifact. If you need a decision, ask it clearly in `text` (a short bullet list of the options is good); the artifact may hold supporting detail but the question itself must be in `text` where it jumps out.",
-      "The `artifact` is for HEAVY or LONG content only: big code, large tables, long multi-point analyses, review dumps, JSON, file lists. When you use an artifact, keep `text` a brief spoken summary that points to it ('details on the side') — don't read the heavy content aloud.",
-      "Write identifiers LITERALLY with their real characters (288, auth.json, viber-dev.dgypx.dev, CONVERSATION_TOKEN) — never spell them out as 'point'/'dash' and never as awkward digit-by-digit text. A lone long token or path is better placed in the artifact than spoken.",
-      "Artifact formats: `markdown` (default), `code`, `json`, `html`. Use `html` only when the rendering needs structural HTML Markdown can't express (styled cards, badges, mixed layouts). Scripts and event handlers are stripped server-side; don't send executable JS.",
-      "NO EMOJI in `text` — it is read aloud, so an emoji becomes spoken noise (a check mark is read as 'check mark'). Use plain Markdown (bullets, bold) for structure instead. Emoji are tolerable only inside an artifact (not spoken).",
-      "Rule of thumb: short and conversational, but readable — break points into a list rather than a wall of text; reserve the artifact for what is genuinely long or heavy.",
+      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.",
-    ].join(" "),
+      // --- 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(" "),
   }
 );
 
@@ -438,6 +465,20 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         additionalProperties: false,
       },
     },
+    {
+      name: "capabilities",
+      description:
+        "On-demand: learn what the Viber control plane (vibe-master) can do on this " +
+        "machine — how to spawn and supervise OTHER agents (Codex, Claude, Gemma). " +
+        "Call this only when orchestrating other agents is relevant; it is not part " +
+        "of the default context. Returns a short usage reference.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {},
+        required: [],
+        additionalProperties: false,
+      },
+    },
   ],
 }));
 
@@ -478,6 +519,11 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     return libMessageAgent(channelToolsCtx, args);
   }
 
+  // #332: on-demand control-plane discovery — static help, no runtime state.
+  if (request.params.name === "capabilities") {
+    return { content: [{ type: "text" as const, text: capabilitiesText() }] };
+  }
+
   if (request.params.name !== "send_message") {
     return {
       isError: true,
@@ -829,7 +875,7 @@ try {
 // ---- Channel ready banner ----
 
 process.stderr.write(
-  `[viber-channel] Channel ready: 3 tools (send_message, list_agents, message_agent), SSE on /api/conversations/${CONVERSATION_ID}/events\n`
+  `[viber-channel] Channel ready: 4 tools (send_message, list_agents, message_agent, capabilities), SSE on /api/conversations/${CONVERSATION_ID}/events\n`
 );
 
 // Channel liveness is proven by the INSTANCE heartbeat (#311, started above), not