viber-channel 0.4.0

package/README.md

@@ -0,0 +1,50 @@
+# viber-channel
+
+Voice + text MCP channel that connects a Claude Code session to the Viber UI at https://viber.dgypx.dev.
+
+When attached, transcripts spoken in the Viber browser tab are pushed into the Claude Code session as channel notifications, and Claude's `send_message` tool delivers text back to the UI (with edge-tts playback).
+
+## Prerequisites
+
+- A Viber project + token. Open https://viber.dgypx.dev/projects, sign in with Google, create a project, click "Create connection", and paste the resulting `connect to viber: <url>` line into your Claude Code session — Claude writes `.viber/auth.json` for you.
+- [bun](https://bun.sh) on `PATH` (used to run the TypeScript channel).
+
+## Wiring
+
+Add this to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "viber-channel": {
+      "command": "bunx",
+      "args": ["viber-channel@latest"],
+      "env": {
+        "VIBER_BASE_URL": "https://viber.dgypx.dev"
+      }
+    }
+  }
+}
+```
+
+Or register globally for the current user:
+
+```bash
+claude mcp add viber-channel --scope user \
+  --env VIBER_BASE_URL=https://viber.dgypx.dev \
+  -- bunx viber-channel@latest
+```
+
+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.
+
+## 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_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
+
+This package is built from [`viber-channel/`](https://github.com/dgx80/viber/tree/master/viber-channel) in the main Viber repo.

package/lib/auth.ts

@@ -0,0 +1,71 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface AuthJson {
+  schema_version: number;
+  project_id: number;
+  project_name: string;
+  user_email: string;
+  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
+   * in place rather than INSERTING a new one (step-05 / D4 case 3).
+   *
+   * The field is one-shot: once the upgrade succeeds the worker flips the
+   * conversation's mode to 'channel-attached' and subsequent mints would
+   * return `target_not_standalone`. Future writers may strip this field after
+   * the first successful mint, but doing so is not required for correctness.
+   */
+  target_conversation_id?: string | null;
+}
+
+/**
+ * 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).
+ */
+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 loadAuth(cwd: string = process.cwd()): AuthJson {
+  const path = join(cwd, ".viber", "auth.json");
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    process.stderr.write(
+      `[viber-channel] No \`.viber/auth.json\` found in this folder.\n` +
+      `Run the connect flow first: visit https://viber.dgypx.dev/projects → Create connection.\n`
+    );
+    process.exit(1);
+  }
+  let auth: AuthJson;
+  try {
+    auth = JSON.parse(raw) as AuthJson;
+  } catch (err) {
+    process.stderr.write(`[viber-channel] Malformed .viber/auth.json: ${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.exit(1);
+  }
+  if (!auth.project_token) {
+    process.stderr.write(`[viber-channel] Empty project_token in .viber/auth.json\n`);
+    process.exit(1);
+  }
+  return auth;
+}

package/lib/cfAccess.ts

@@ -0,0 +1,21 @@
+/**
+ * cfAccess — optional Cloudflare Access service-token headers.
+ *
+ * Some viber hostnames (notably the dev tunnel `viber-dev.dgypx.dev`) are
+ * behind CF Access. When `VIBER_CF_CLIENT_ID` and `VIBER_CF_CLIENT_SECRET`
+ * env vars are set, every API call from the channel includes them so the
+ * request reaches the Worker instead of being 302'd to a login page.
+ *
+ * Returns an empty object when the env vars aren't set — production setups
+ * that have a CF Access bypass policy on the API paths don't need these.
+ */
+
+export function cfAccessHeaders(): Record<string, string> {
+	const id = process.env.VIBER_CF_CLIENT_ID;
+	const secret = process.env.VIBER_CF_CLIENT_SECRET;
+	if (!id || !secret) return {};
+	return {
+		"CF-Access-Client-Id": id,
+		"CF-Access-Client-Secret": secret,
+	};
+}

package/lib/channel_errors.ts

@@ -0,0 +1,23 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+
+/**
+ * Called when the server returns HTTP 401 during SSE or polling.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export async function handleConversationTokenExpired(mcp: Server): Promise<never> {
+  await mcp.notification({
+    method: "notifications/claude/channel",
+    params: {
+      content: "⚠️ Voice connection expired. Restart this channel to continue.",
+      meta: { source: "system", type: "conversation_token_expired" },
+    },
+  });
+  process.exit(3);
+}

package/lib/conversation.ts

@@ -0,0 +1,86 @@
+import { basename } from "node:path";
+import { cfAccessHeaders } from "./cfAccess.js";
+
+export interface ConversationMintResponse {
+  conversation_id: string;
+  conversation_token: string;
+  ws_url: string;
+  expires_at: number;
+  new_project_token?: string;
+  new_project_token_expires_at?: number | null;
+}
+
+export class ReverifyRequiredError extends Error {
+  url: string;
+  reason: string;
+  constructor(url: string, reason: string) {
+    super(`Re-verification required: ${reason}`);
+    this.name = "ReverifyRequiredError";
+    this.url = url;
+    this.reason = reason;
+  }
+}
+
+export async function mintConversation(
+  baseUrl: string,
+  projectId: number,
+  projectToken: string,
+  fingerprint: string,
+  label: string,
+  /**
+   * Optional — when set, the worker upgrades the existing standalone
+   * conversation with this id rather than minting a new one (step-05).
+   * Originates from `.viber/auth.json` (`target_conversation_id`), which
+   * Claude Code populates from the connect-flow poll response when the claim
+   * was created via attach-to-project.
+   */
+  targetConversationId?: string | null,
+): Promise<ConversationMintResponse> {
+  const requestBody: { conversation_label: string; target_conversation_id?: string } = {
+    conversation_label: label,
+  };
+  // Explicit null check (not truthy) — guards against future widening of the
+  // type accidentally letting empty strings flow through to the worker, which
+  // would be parsed as null on the receiving end and silently fall through to
+  // the new-conv path.
+  if (targetConversationId != null) {
+    requestBody.target_conversation_id = targetConversationId;
+  }
+
+  const resp = await fetch(`${baseUrl}/api/projects/${projectId}/conversations`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${projectToken}`,
+      "X-Client-Fingerprint": fingerprint,
+      "Content-Type": "application/json",
+      ...cfAccessHeaders(),
+    },
+    body: JSON.stringify(requestBody),
+  });
+  if (!resp.ok) {
+    if (resp.status === 403) {
+      let body: { type?: string; reverify_url?: string; reason?: string };
+      try {
+        body = (await resp.json()) as typeof body;
+      } catch {
+        body = {};
+      }
+      if (body.type === "reverify_required" && typeof body.reverify_url === "string") {
+        throw new ReverifyRequiredError(body.reverify_url, body.reason ?? "unknown");
+      }
+      throw new Error(`Failed to mint conversation token (HTTP 403): ${JSON.stringify(body)}`);
+    }
+    const detail = await resp.text();
+    throw new Error(`Failed to mint conversation token (HTTP ${resp.status}): ${detail}`);
+  }
+  return (await resp.json()) as ConversationMintResponse;
+}
+
+export function defaultLabel(folderPath: string): string {
+  const folder = basename(folderPath);
+  // Local time, not UTC — the user sees this label in the UI; UTC was confusing.
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const ts = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+  return `${folder} • ${ts}`;
+}

package/lib/fingerprint.ts

@@ -0,0 +1,47 @@
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+
+// Path normalization: on Windows, Node's realpathSync returns "C:\\Users\\..."
+// while the Claude Code bootstrap shell uses `pwd -P` under Git Bash, which returns
+// "/c/Users/...". These paths must hash identically — otherwise the fingerprint
+// computed at bootstrap time and at channel start time would never match.
+export function normalizePath(absPath: string): string {
+  if (process.platform !== "win32") return absPath;
+  // C:\Users\jeanp\... → /c/Users/jeanp/...
+  let p = absPath.replace(/\\/g, "/");
+  const driveMatch = p.match(/^([A-Za-z]):\/(.*)$/);
+  if (driveMatch) {
+    const drive = driveMatch[1].toLowerCase();
+    const rest = driveMatch[2];
+    p = `/${drive}/${rest}`;
+  }
+  return p;
+}
+
+export function getMachineId(): string {
+  if (process.platform === "linux") {
+    const id = execSync("cat /etc/machine-id 2>/dev/null || cat /var/lib/dbus/machine-id").toString().trim();
+    if (!id) throw new Error("Could not read machine-id on Linux");
+    return id;
+  }
+  if (process.platform === "darwin") {
+    const out = execSync("ioreg -rd1 -c IOPlatformExpertDevice").toString();
+    const id = out.match(/IOPlatformUUID.*=.*"([^"]+)"/)?.[1];
+    if (!id) throw new Error("Could not read IOPlatformUUID on macOS");
+    return id;
+  }
+  if (process.platform === "win32") {
+    const out = execSync('reg query "HKLM\\SOFTWARE\\Microsoft\\Cryptography" /v MachineGuid').toString();
+    const id = out.match(/MachineGuid\s+REG_SZ\s+(\S+)/)?.[1]?.trim();
+    if (!id) throw new Error("Could not read MachineGuid from Windows registry");
+    return id;
+  }
+  throw new Error(`Unsupported platform: ${process.platform}`);
+}
+
+export function clientFingerprint(folderPath: string): string {
+  const machineId = getMachineId();
+  const absPath = normalizePath(realpathSync(folderPath) as string);
+  return createHash("sha256").update(`${machineId}:${absPath}`).digest("hex").slice(0, 32);
+}

package/lib/messages.ts

@@ -0,0 +1,123 @@
+/**
+ * messages.ts — HTTP client for POST /api/conversations/:id/messages
+ *
+ * Pure function: no state, no MCP, no side effects.
+ * The MCP CallTool handler in viber-channel.ts calls postMessage() and maps
+ * the result to MCP tool call results.
+ */
+
+import { cfAccessHeaders } from "./cfAccess.js";
+
+export class ConversationTokenExpiredError extends Error {
+  constructor() {
+    super("conversation token expired (HTTP 401)");
+    this.name = "ConversationTokenExpiredError";
+  }
+}
+
+export interface MessagePostSuccess {
+  ok: true;
+  message_id: string;
+}
+
+export interface MessagePostError {
+  ok: false;
+  status: number;
+  detail: string;
+  retriable: boolean;
+}
+
+export type MessagePostResult = MessagePostSuccess | MessagePostError;
+
+/**
+ * POST /api/conversations/:conversationId/messages
+ *
+ * @throws ConversationTokenExpiredError on HTTP 401
+ * @returns MessagePostResult — success with message_id, or error with detail
+ */
+export async function postMessage(
+  baseUrl: string,
+  conversationId: string,
+  conversationToken: string,
+  text: string,
+): Promise<MessagePostResult> {
+  if (!text || text.trim().length === 0) {
+    return {
+      ok: false,
+      status: 0,
+      detail: "text must be a non-empty string",
+      retriable: false,
+    };
+  }
+
+  const url = `${baseUrl}/api/conversations/${conversationId}/messages`;
+  let resp: Response;
+  try {
+    resp = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${conversationToken}`,
+        "Content-Type": "application/json",
+        ...cfAccessHeaders(),
+      },
+      body: JSON.stringify({ content: text }),
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      status: 0,
+      detail: `Network error: ${String(err)}`,
+      retriable: true,
+    };
+  }
+
+  if (resp.status === 401) {
+    throw new ConversationTokenExpiredError();
+  }
+
+  if (resp.status >= 500) {
+    let body = "";
+    try {
+      body = await resp.text();
+    } catch {
+      // ignore
+    }
+    return {
+      ok: false,
+      status: resp.status,
+      detail: `Server error (HTTP ${resp.status}): ${body || resp.statusText}. Retry the call.`,
+      retriable: true,
+    };
+  }
+
+  if (!resp.ok) {
+    let detail = `HTTP ${resp.status}`;
+    try {
+      const json = (await resp.json()) as { detail?: string };
+      if (typeof json.detail === "string") detail = `HTTP ${resp.status}: ${json.detail}`;
+    } catch {
+      try {
+        const body = await resp.text();
+        if (body) detail = `HTTP ${resp.status}: ${body}`;
+      } catch {
+        // ignore
+      }
+    }
+    return { ok: false, status: resp.status, detail, retriable: false };
+  }
+
+  // 200 or 201 — parse the saved message
+  let message: { id: string };
+  try {
+    message = (await resp.json()) as { id: string };
+  } catch (err) {
+    return {
+      ok: false,
+      status: resp.status,
+      detail: `Failed to parse response JSON: ${String(err)}`,
+      retriable: false,
+    };
+  }
+
+  return { ok: true, message_id: message.id };
+}

package/lib/urls.ts

@@ -0,0 +1,12 @@
+/**
+ * URL construction helpers for viber-channel.
+ * Kept in a side-effect-free module so tests can import them directly.
+ */
+
+/**
+ * Build the conversation-scoped SSE URL.
+ * Introduced in #221 step-05 to replace the legacy /api/voice-events endpoint.
+ */
+export function buildSseUrl(voiceBaseUrl: string, conversationId: string): string {
+  return `${voiceBaseUrl}/api/conversations/${conversationId}/events`;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "viber-channel",
+  "version": "0.4.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": {
+    "viber-channel": "./viber-channel.ts"
+  },
+  "files": [
+    "viber-channel.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",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/viber-channel.ts

@@ -0,0 +1,478 @@
+#!/usr/bin/env bun
+/**
+ * viber-channel MCP channel server (#217)
+ *
+ * Reads .viber/auth.json for authentication, then connects to
+ * /api/conversations/<id>/events SSE stream and pushes transcripts and
+ * messages as channel events.
+ *
+ * Start Claude with:
+ *   claude --dangerously-load-development-channels server:viber-channel
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+// Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac)
+const LOCK_DIR =
+  process.env.APPDATA
+    ? join(process.env.APPDATA, "viber")
+    : join(process.env.HOME ?? "/tmp", ".config", "viber");
+// TODO: rename to channel.lock once all installations have transitioned off the old name
+const LOCK_FILE = join(LOCK_DIR, "watchdog.lock");
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: any) {
+    if (err?.code === "EPERM") return true; // Process exists, no permission to signal
+    return false; // ESRCH or anything Bun-specific — treat as dead
+  }
+}
+
+/** Try to acquire lock. Returns null on success, or the blocking PID on conflict. */
+function acquireLock(): number | null {
+  mkdirSync(LOCK_DIR, { recursive: true });
+  const ourPid = String(process.pid);
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      writeFileSync(LOCK_FILE, ourPid + "\n", { flag: "wx" });
+      return null; // Lock acquired
+    } catch (err: any) {
+      if (err?.code !== "EEXIST") throw err;
+
+      // Lock file exists — check if the holder is still alive
+      let existingPid: number;
+      try {
+        existingPid = parseInt(readFileSync(LOCK_FILE, "utf-8").trim(), 10);
+      } catch {
+        // Corrupt or unreadable — treat as stale
+        releaseLock();
+        continue;
+      }
+
+      if (isNaN(existingPid) || !isProcessAlive(existingPid)) {
+        // Stale lock — remove and retry
+        releaseLock();
+        continue;
+      }
+
+      // Another live channel is running
+      process.stderr.write(
+        `[viber-channel] Another instance already running (PID ${existingPid}), exiting.\n`
+      );
+      return existingPid;
+    }
+  }
+
+  process.stderr.write("[viber-channel] Failed to acquire lock after retries, exiting.\n");
+  return -1; // Failed to acquire
+}
+
+function releaseLock(): void {
+  try {
+    unlinkSync(LOCK_FILE);
+  } catch {
+    // Best-effort — file may already be gone
+  }
+}
+
+// Best-effort cleanup — on Windows, signals may not fire (TerminateProcess)
+process.on("exit", releaseLock);
+process.on("SIGINT", () => { releaseLock(); process.exit(0); });
+process.on("SIGTERM", () => { releaseLock(); process.exit(0); });
+
+// stdin EOF — Claude Code closes its end of the pipe when the session
+// terminates (or the parent process is killed via TerminateProcess on
+// Windows, which the kernel propagates as a pipe close). Without this,
+// the bun subprocess outlives Claude Code and leaks (the orphan that
+// taunts us on every restart). The MCP transport uses stdin too, but
+// it doesn't propagate close as a process exit, so we wire it ourselves.
+process.stdin.on("end", () => {
+  process.stderr.write("[viber-channel] stdin closed (parent exited), shutting down\n");
+  releaseLock();
+  process.exit(0);
+});
+process.stdin.on("close", () => {
+  process.stderr.write("[viber-channel] stdin close event, shutting down\n");
+  releaseLock();
+  process.exit(0);
+});
+
+// ---- Auth from .viber/auth.json ----
+
+import { loadAuth, updateAuthToken } from "./lib/auth.ts";
+import { handleConversationTokenExpired } from "./lib/channel_errors.ts";
+import { buildSseUrl } from "./lib/urls.ts";
+
+let auth = loadAuth();
+
+// ---- Fingerprint verification ----
+
+import { clientFingerprint } from "./lib/fingerprint.ts";
+
+const computedFp = clientFingerprint(process.cwd());
+if (computedFp !== auth.client_fingerprint) {
+  process.stderr.write(
+    `[viber-channel] Folder fingerprint mismatch — \`.viber/auth.json\` was issued for a different machine/folder.\n` +
+    `Re-run the connect flow at https://viber.dgypx.dev/projects.\n`
+  );
+  process.exit(1);
+}
+
+// ---- Imports for mint ----
+
+import { defaultLabel, mintConversation, ReverifyRequiredError } from "./lib/conversation.ts";
+import { postMessage, ConversationTokenExpiredError } from "./lib/messages.ts";
+import { cfAccessHeaders } from "./lib/cfAccess.ts";
+
+const BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
+const label = process.env.VIBER_CONVERSATION_LABEL ?? defaultLabel(process.cwd());
+
+// ---- MCP server ----
+
+const mcp = new Server(
+  { name: "viber-channel", version: "0.3.0" },
+  {
+    capabilities: {
+      experimental: { "claude/channel": {} },
+      tools: {},
+    },
+    instructions: [
+      'Voice transcripts arrive as <channel source="viber-channel">.',
+      "Each event contains transcriptions from the user's microphone.",
+      "Process the transcript and respond with speak(). Do NOT launch any watchdog or call check_voice().",
+      "On exit intent (bye, au revoir, stop) → call stop_conversation(), speak farewell, stop.",
+    ].join(" "),
+  }
+);
+
+// ---- Tool registration (ListTools + CallTool) ----
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "send_message",
+      description:
+        "Send a message into the Viber conversation this channel is bound to. The user sees it in the web UI in real-time. Use this to deliver Claude's responses to the user without typing.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          text: {
+            type: "string",
+            minLength: 1,
+            description: "Message text to send to the user's conversation",
+          },
+        },
+        required: ["text"],
+      },
+    },
+  ],
+}));
+
+// NOTE: CONVERSATION_TOKEN, CONVERSATION_ID, BASE_URL are populated after
+// mintConversation() runs (below). The handler closure captures the variables
+// by reference — by the time Claude Code calls the tool, they are populated.
+mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name !== "send_message") {
+    return {
+      isError: true,
+      content: [{ type: "text" as const, text: `Unknown tool: ${request.params.name}` }],
+    };
+  }
+
+  const args = (request.params.arguments ?? {}) as Record<string, unknown>;
+  const text = args.text;
+  if (typeof text !== "string" || text.trim().length === 0) {
+    return {
+      isError: true,
+      content: [{ type: "text" as const, text: "Invalid input: text must be a non-empty string" }],
+    };
+  }
+
+  let result;
+  try {
+    result = await postMessage(BASE_URL, CONVERSATION_ID, CONVERSATION_TOKEN, text);
+  } catch (err) {
+    if (err instanceof ConversationTokenExpiredError) {
+      // Notify Claude (and the user) that the channel token has expired
+      await handleConversationTokenExpired(mcp);
+      // handleConversationTokenExpired calls process.exit(3) — unreachable, but
+      // TypeScript needs a return to satisfy the type checker.
+      return {
+        isError: true,
+        content: [{ type: "text" as const, text: "conversation token expired" }],
+      };
+    }
+    return {
+      isError: true,
+      content: [{ type: "text" as const, text: `Unexpected error: ${String(err)}` }],
+    };
+  }
+
+  if (!result.ok) {
+    return {
+      isError: true,
+      content: [{ type: "text" as const, text: result.detail }],
+    };
+  }
+
+  return {
+    content: [{ type: "text" as const, text: `Message sent: ${result.message_id}` }],
+  };
+});
+
+// Prevent duplicate instances (#166)
+process.stderr.write(`[viber-channel] startup: pid=${process.pid}, acquiring lock\n`);
+const blockingPid = acquireLock();
+process.stderr.write(`[viber-channel] startup: lock acquired (blockingPid=${blockingPid})\n`);
+
+// Connect to Claude Code over stdio FIRST so notifications can be sent
+process.stderr.write(`[viber-channel] startup: calling mcp.connect()\n`);
+await mcp.connect(new StdioServerTransport());
+process.stderr.write(`[viber-channel] startup: mcp.connect() returned\n`);
+
+// If another instance is running, notify Claude and exit
+if (blockingPid !== null) {
+  const msg = blockingPid > 0
+    ? `⚠️ Another viber-channel is already running (PID ${blockingPid}). This channel is inactive — voice transcriptions are handled by the other instance.`
+    : `⚠️ Failed to acquire channel lock file. This channel is inactive.`;
+  await mcp.notification({
+    method: "notifications/claude/channel",
+    params: {
+      content: msg,
+      meta: { source: "system" },
+    },
+  });
+  process.exit(1);
+}
+
+// ---- Mint conversation token (after mcp.connect so reverify notifications can be sent) ----
+
+let CONVERSATION_TOKEN: string;
+let VOICE_BASE_URL: string;
+let CONVERSATION_ID: string;
+
+process.stderr.write(`[viber-channel] startup: calling mintConversation (project=${auth.project_id}, target=${auth.target_conversation_id ?? "null"})\n`);
+try {
+  const minted = await mintConversation(
+    BASE_URL,
+    auth.project_id,
+    auth.project_token,
+    auth.client_fingerprint,
+    label,
+    auth.target_conversation_id ?? null,
+  );
+  process.stderr.write(`[viber-channel] startup: mint OK, conv_id=${minted.conversation_id}\n`);
+
+  // Apply token rotation if the server issued a new project_token
+  if (minted.new_project_token) {
+    try {
+      auth = updateAuthToken(process.cwd(), auth, minted.new_project_token);
+    } catch (err) {
+      process.stderr.write(`[viber-channel] Warning: failed to update .viber/auth.json: ${String(err)}\n`);
+      // Don't exit — token is valid in memory; auth.json will be stale but channel keeps running
+    }
+  }
+
+  CONVERSATION_TOKEN = minted.conversation_token;
+  VOICE_BASE_URL = minted.ws_url;
+  CONVERSATION_ID = minted.conversation_id;
+} catch (err) {
+  if (err instanceof ReverifyRequiredError) {
+    await mcp.notification({
+      method: "notifications/claude/channel",
+      params: {
+        content: `⚠️ Re-verification required (reason: ${err.reason}). Visit ${err.url} to re-authenticate, then restart this channel.`,
+        meta: { source: "system", type: "reverify_required", url: err.url },
+      },
+    });
+    process.exit(2);
+  }
+  process.stderr.write(`[viber-channel] ${String(err)}\n`);
+  process.stderr.write(
+    `[viber-channel] If your project_token is no longer valid, run the connect flow again at https://viber.dgypx.dev/projects.\n`
+  );
+  process.exit(1);
+}
+
+// ---- Channel ready banner ----
+
+process.stderr.write(
+  `[viber-channel] Channel ready: 1 tool (send_message), SSE on /api/conversations/${CONVERSATION_ID}/events\n`
+);
+
+// ---- URLs and auth headers ----
+
+/** Primary SSE endpoint: conversation-scoped event bus (step-03 / #221). */
+const SSE_URL = buildSseUrl(VOICE_BASE_URL, CONVERSATION_ID);
+
+// Voice endpoints (/api/conversations/<id>/events) authenticate via the
+// per-conversation token minted by the Worker at startup (#220 step 05).
+// Python validates the token through ConversationTokenValidator → Worker,
+// not against a static shared secret. The previous VIBER_CHANNEL_SECRET path
+// has been removed everywhere. The legacy /api/check_voice long-poll fallback
+// was retired in #221 step-09 once the conversation-scoped SSE proved reliable.
+
+function getHeaders(): Record<string, string> {
+  return {
+    Authorization: `Bearer ${CONVERSATION_TOKEN}`,
+    "X-Client-Fingerprint": auth.client_fingerprint,
+    ...cfAccessHeaders(),
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function pushTranscript(text: string, lang: string): Promise<void> {
+  process.stderr.write(`[viber-channel] Speech detected: "${text}"\n`);
+  await mcp.notification({
+    method: "notifications/claude/channel",
+    params: {
+      content: text,
+      meta: { lang, source: "microphone" },
+    },
+  });
+}
+
+/** Forward a saved conversation message from the event bus to Claude. */
+async function pushMessage(msg: { text: string; id?: string | null; source?: string }): Promise<void> {
+  process.stderr.write(`[viber-channel] pushMessage ENTER: "${msg.text.slice(0, 60)}"\n`);
+  // MCP notification handler (Claude Code v2.1.143) validates meta with Zod;
+  // null fields are rejected as invalid type. Omit message_id when missing.
+  const meta: Record<string, string> = { source: msg.source ?? "conversation" };
+  if (typeof msg.id === "string" && msg.id.length > 0) {
+    meta.message_id = msg.id;
+  }
+  try {
+    await mcp.notification({
+      method: "notifications/claude/channel",
+      params: { content: msg.text, meta },
+    });
+    process.stderr.write(`[viber-channel] pushMessage OK\n`);
+  } catch (err) {
+    process.stderr.write(`[viber-channel] pushMessage FAILED: ${String(err)}\n`);
+    throw err;
+  }
+}
+
+/** SSE stream — preferred method (#170) */
+async function sseLoop(): Promise<void> {
+  const headers = getHeaders();
+  headers["Accept"] = "text/event-stream";
+
+  process.stderr.write(`[viber-channel] Connecting to SSE: ${SSE_URL}\n`);
+
+  const resp = await fetch(SSE_URL, { headers });
+
+  if (resp.status === 401) {
+    await handleConversationTokenExpired(mcp);
+  }
+
+  if (!resp.ok || !resp.body) {
+    throw new Error(`SSE connection failed: HTTP ${resp.status}`);
+  }
+
+  process.stderr.write(`[viber-channel] SSE connected\n`);
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+
+    // Parse SSE events from buffer
+    while (true) {
+      const eventEnd = buffer.indexOf("\n\n");
+      if (eventEnd === -1) break;
+
+      const eventBlock = buffer.slice(0, eventEnd);
+      buffer = buffer.slice(eventEnd + 2);
+
+      // Skip comments (keepalive)
+      if (eventBlock.startsWith(":")) continue;
+
+      // Parse event type and data
+      let eventType = "";
+      let data = "";
+      for (const line of eventBlock.split("\n")) {
+        if (line.startsWith("event: ")) eventType = line.slice(7);
+        else if (line.startsWith("data: ")) data = line.slice(6);
+      }
+
+      switch (eventType) {
+        case "connected":
+          // Keepalive marker sent when the stream opens — no action needed.
+          process.stderr.write(`[viber-channel] SSE stream ready (connected event)\n`);
+          break;
+
+        case "stop":
+          process.stderr.write(`[viber-channel] Received stop signal, exiting.\n`);
+          releaseLock();
+          process.exit(0);
+          break;
+
+        case "transcription":
+          if (data) {
+            try {
+              const item = JSON.parse(data) as { text: string; language?: string };
+              if (item.text) {
+                await pushTranscript(item.text, item.language ?? "unknown");
+              }
+            } catch (err) {
+              process.stderr.write(`[viber-channel] Failed to parse transcription data: ${String(err)}\n`);
+            }
+          }
+          break;
+
+        case "message":
+          process.stderr.write(`[viber-channel] SSE event 'message' received, data_len=${data.length}\n`);
+          if (data) {
+            try {
+              const msg = JSON.parse(data) as { text: string; id?: string; source?: string; role?: string; timestamp?: string };
+              if (msg.text) {
+                await pushMessage(msg);
+              } else {
+                process.stderr.write(`[viber-channel] 'message' event has empty text\n`);
+              }
+            } catch (err) {
+              process.stderr.write(`[viber-channel] Failed to parse message data: ${String(err)}\n`);
+            }
+          }
+          break;
+
+        default:
+          if (eventType) {
+            process.stderr.write(`[viber-channel] Unknown SSE event type: "${eventType}", ignoring.\n`);
+          }
+          break;
+      }
+    }
+  }
+}
+
+/** Main loop: keep the SSE stream connected, reconnect on transient errors. */
+async function mainLoop(): Promise<void> {
+  while (true) {
+    try {
+      await sseLoop();
+      // If SSE ends cleanly, reconnect immediately
+      process.stderr.write(`[viber-channel] SSE stream ended, reconnecting...\n`);
+    } catch (err) {
+      process.stderr.write(`[viber-channel] SSE failed: ${String(err)}, retrying in 2s...\n`);
+      await sleep(2000);
+    }
+  }
+}
+
+mainLoop();