viber-channel 0.5.0 → 0.5.1

package/lib/connect.ts

@@ -19,6 +19,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { clientFingerprint } from "./fingerprint.js";
+import { cfAccessHeaders } from "./cfAccess.js";
 
 interface InitResponse {
   confirm_url: string;
@@ -141,7 +142,7 @@ export async function runConnect(
 
   const initResp = await fetch(`${baseUrl}/api/connect/${claimId}`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...cfAccessHeaders() },
     body: JSON.stringify({ client_fingerprint: fingerprint }),
   });
   if (!initResp.ok) {
@@ -158,7 +159,7 @@ export async function runConnect(
   const deadline = Date.now() + MAX_POLL_DURATION_MS;
   while (Date.now() < deadline) {
     await sleep(POLL_INTERVAL_MS);
-    const pollResp = await fetch(pollUrl);
+    const pollResp = await fetch(pollUrl, { headers: cfAccessHeaders() });
     if (!pollResp.ok) {
       const body = await pollResp.text().catch(() => "");
       throw new Error(`Poll failed (HTTP ${pollResp.status}): ${body}`);

package/lib/lockfile.ts

@@ -0,0 +1,25 @@
+/**
+ * lockfile.ts — derive the channel's lock file path from VIBER_BASE_URL.
+ *
+ * The lock prevents two instances of the channel from racing on stdin when
+ * Claude Code accidentally spawns duplicates. But two channels targeting
+ * *different* backends (e.g. staging + dev) are legitimately different
+ * processes — they shouldn't share a lock.
+ *
+ * Namespacing the lock by base URL lets them coexist.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+
+/**
+ * Return the lock file path for a given base URL, under `lockDir`.
+ *
+ * The filename is `channel-{8-hex}.lock` where the hex is a stable SHA-256
+ * prefix of the base URL. Two callers with the same base URL get the same
+ * path (same process collision still detected); different base URLs get
+ * different paths (no false collision).
+ */
+export function lockFilePath(baseUrl: string, lockDir: string): string {
+  const suffix = createHash("sha256").update(baseUrl).digest("hex").slice(0, 8);
+  return join(lockDir, `channel-${suffix}.lock`);
+}

package/lib/messages.ts

@@ -15,6 +15,62 @@ export class ConversationTokenExpiredError extends Error {
   }
 }
 
+export type ArtifactFormat = "markdown" | "code" | "json" | "html";
+
+export interface Artifact {
+  content: string;
+  format?: ArtifactFormat;
+}
+
+const ALLOWED_ARTIFACT_FORMATS: readonly ArtifactFormat[] = [
+  "markdown",
+  "code",
+  "json",
+  "html",
+];
+
+export type ParseArtifactResult =
+  | { ok: true; artifact: Artifact | undefined }
+  | { ok: false; error: string };
+
+/**
+ * Validate and normalize a raw `artifact` value coming from MCP tool input.
+ *
+ * - `undefined` / `null` → `{ ok: true, artifact: undefined }` (no artifact attached).
+ * - Anything else must be a plain object with a non-empty trimmed `content` string and,
+ *   optionally, a `format` from the whitelist (`markdown` | `code` | `json` | `html`).
+ *   An omitted `format` is normalized to `"markdown"`.
+ *
+ * Kept as a pure function so the CallTool handler in viber-channel.ts stays small
+ * and the validation rules are unit-testable on their own.
+ */
+export function parseArtifact(raw: unknown): ParseArtifactResult {
+  if (raw === undefined || raw === null) {
+    return { ok: true, artifact: undefined };
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, error: "artifact must be an object" };
+  }
+  const rawArtifact = raw as Record<string, unknown>;
+  const content = rawArtifact.content;
+  if (typeof content !== "string" || content.trim().length === 0) {
+    return { ok: false, error: "artifact.content must be a non-empty string" };
+  }
+  if (rawArtifact.format === undefined) {
+    return { ok: true, artifact: { content, format: "markdown" } };
+  }
+  if (
+    typeof rawArtifact.format !== "string" ||
+    !ALLOWED_ARTIFACT_FORMATS.includes(rawArtifact.format as ArtifactFormat)
+  ) {
+    return {
+      ok: false,
+      error: `artifact.format must be one of ${ALLOWED_ARTIFACT_FORMATS.join(", ")}`,
+    };
+  }
+  return { ok: true, artifact: { content, format: rawArtifact.format as ArtifactFormat } };
+}
+
 export interface MessagePostSuccess {
   ok: true;
   message_id: string;
@@ -40,6 +96,7 @@ export async function postMessage(
   conversationId: string,
   conversationToken: string,
   text: string,
+  artifact?: Artifact,
 ): Promise<MessagePostResult> {
   if (!text || text.trim().length === 0) {
     return {
@@ -60,7 +117,7 @@ export async function postMessage(
         "Content-Type": "application/json",
         ...cfAccessHeaders(),
       },
-      body: JSON.stringify({ content: text }),
+      body: JSON.stringify(artifact ? { content: text, artifact } : { content: text }),
     });
   } catch (err) {
     return {

package/package.json

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

package/viber-channel.ts

@@ -1,13 +1,28 @@
 #!/usr/bin/env bun
 /**
- * viber-channel MCP channel server (#217)
+ * viber-channel MCP channel server (#217, #232)
  *
  * 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
+ * Launch via Claude Code — two MCP server names are in use:
+ *   - server:viber-channel       — npm-published build (bunx viber-channel@latest),
+ *                                  staging backend (viber.dgypx.dev), wired by
+ *                                  external consumers via `claude mcp add`.
+ *   - server:viber-dev-channel   — local-source build, dev backend
+ *                                  (viber-dev.dgypx.dev). Defined in this repo's
+ *                                  committed .mcp.json (or override locally).
+ *
+ *   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)
+ *
+ * CLI subcommand: `bunx viber-channel connect <claim_url>` runs the one-shot
+ * claim flow that writes .viber/auth.json without requiring any Claude Code
+ * recipe in CLAUDE.md.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -15,6 +30,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprot
 import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { runConnect } from "./lib/connect.ts";
+import { lockFilePath } from "./lib/lockfile.ts";
 
 // ---- CLI subcommand dispatch (must happen before lock acquire + loadAuth) ----
 //
@@ -53,13 +69,16 @@ import { runConnect } from "./lib/connect.ts";
   }
 }
 
-// Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac)
+// Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac).
+// Namespaced by VIBER_BASE_URL so channels targeting different backends
+// (staging + dev) coexist on the same machine — only same-backend duplicates
+// still collide, which is the intended guard.
 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");
+const LOCK_BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
+const LOCK_FILE = lockFilePath(LOCK_BASE_URL, LOCK_DIR);
 
 function isProcessAlive(pid: number): boolean {
   try {
@@ -130,16 +149,18 @@ process.on("SIGTERM", () => { releaseLock(); process.exit(0); });
 // 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.
+//
+// NOTE: we deliberately listen to `end` only, not `close`. On Windows/Bun,
+// registering an MCP `StdioServerTransport` reader appears to trigger a
+// spurious `close` event ~2 ms after the transport's read loop starts,
+// which would kill the channel mid-mint before MCP traffic even begins.
+// `end` fires on real EOF (parent closes write end) and is sufficient for
+// orphan detection. See plan #236 step-09 for the diagnosis.
 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 ----
 
@@ -165,7 +186,7 @@ if (computedFp !== auth.client_fingerprint) {
 // ---- Imports for mint ----
 
 import { defaultLabel, mintConversation, ReverifyRequiredError } from "./lib/conversation.ts";
-import { postMessage, ConversationTokenExpiredError } from "./lib/messages.ts";
+import { postMessage, ConversationTokenExpiredError, parseArtifact } from "./lib/messages.ts";
 import { cfAccessHeaders } from "./lib/cfAccess.ts";
 
 const BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
@@ -181,10 +202,13 @@ const mcp = new Server(
       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.",
+      'Voice transcripts arrive as <channel source="viber-channel"> events carrying the user\'s microphone speech.',
+      "Reply with send_message. The `text` field is read aloud to the user, so keep it a short, natural spoken sentence — no markdown symbols, no bullet lists, no tables, no code blocks.",
+      "Put technical content (code, lists, JSON, tables, command output, long file paths) in the optional `artifact` field with the matching `format`; it renders in a side viewer the user can read.",
+      "Available 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 try to send executable JS.",
+      "Rule of thumb: if it would sound bad read aloud, it belongs in the artifact, not the text.",
+      "On exit intent (bye, au revoir, stop) call stop_conversation(), speak a brief farewell, and stop.",
     ].join(" "),
   }
 );
@@ -196,14 +220,37 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       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.",
+        "Send a message into the Viber conversation this channel is bound to. " +
+        "`text` is the spoken/conversational reply (read aloud — keep it short and natural, no markdown). " +
+        "`artifact` is optional and carries technical content (markdown, code, JSON, or sanitized HTML) rendered in a side viewer. " +
+        "Use `html` only when structural HTML markdown can't express is required; scripts and event handlers are stripped before display.",
       inputSchema: {
         type: "object" as const,
         properties: {
           text: {
             type: "string",
             minLength: 1,
-            description: "Message text to send to the user's conversation",
+            description: "Spoken/conversational reply. Plain sentences, no markdown symbols or lists.",
+          },
+          artifact: {
+            type: "object",
+            description: "Optional technical content rendered in the artifact viewer alongside the spoken text.",
+            properties: {
+              content: {
+                type: "string",
+                minLength: 1,
+                description: "Artifact body — markdown, code, JSON, or HTML.",
+              },
+              format: {
+                type: "string",
+                enum: ["markdown", "code", "json", "html"],
+                description:
+                  "Render format for the artifact body. Defaults to markdown if omitted. " +
+                  "Use `html` only when structural HTML is required (styled cards, badges, mixed layouts); " +
+                  "scripts, event handlers, iframes, and inline styles are stripped server-side before rendering.",
+              },
+            },
+            required: ["content"],
           },
         },
         required: ["text"],
@@ -232,9 +279,18 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     };
   }
 
+  const parsed = parseArtifact(args.artifact);
+  if (!parsed.ok) {
+    return {
+      isError: true,
+      content: [{ type: "text" as const, text: `Invalid input: ${parsed.error}` }],
+    };
+  }
+  const artifact = parsed.artifact;
+
   let result;
   try {
-    result = await postMessage(BASE_URL, CONVERSATION_ID, CONVERSATION_TOKEN, text);
+    result = await postMessage(BASE_URL, CONVERSATION_ID, CONVERSATION_TOKEN, text, artifact);
   } catch (err) {
     if (err instanceof ConversationTokenExpiredError) {
       // Notify Claude (and the user) that the channel token has expired
@@ -379,19 +435,36 @@ async function pushTranscript(text: string, lang: string): Promise<void> {
   });
 }
 
-/** 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`);
+/**
+ * Forward a saved conversation message from the event bus to Claude.
+ *
+ * Wire field name is `content` — the SSE payload mirrors the Worker's
+ * `MessageResponse` shape (viber-api/src/db/types.ts), republished verbatim by
+ * Python (`ws_server.internal_notify_message` → `publish_to_conversation`).
+ * The optional `artifact` field is accepted here and threaded through the meta
+ * so downstream consumers (step-03 React viewer) can opt-in without a second
+ * round-trip; the channel itself does no special rendering of it yet.
+ */
+async function pushMessage(msg: {
+  content: string;
+  id?: string | null;
+  source?: string;
+  artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+}): Promise<void> {
+  process.stderr.write(`[viber-channel] pushMessage ENTER: "${msg.content.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" };
+  const meta: Record<string, unknown> = { source: msg.source ?? "conversation" };
   if (typeof msg.id === "string" && msg.id.length > 0) {
     meta.message_id = msg.id;
   }
+  if (msg.artifact && typeof msg.artifact === "object" && typeof msg.artifact.content === "string") {
+    meta.artifact = msg.artifact;
+  }
   try {
     await mcp.notification({
       method: "notifications/claude/channel",
-      params: { content: msg.text, meta },
+      params: { content: msg.content, meta },
     });
     process.stderr.write(`[viber-channel] pushMessage OK\n`);
   } catch (err) {
@@ -477,11 +550,21 @@ async function sseLoop(): Promise<void> {
           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) {
+              // Wire shape mirrors viber-api `MessageResponse` (db/types.ts):
+              // primary text is `content`, not `text`. `artifact` is threaded
+              // through opaquely so step-03 (React viewer) can consume it.
+              const msg = JSON.parse(data) as {
+                content: string;
+                id?: string;
+                source?: string;
+                role?: string;
+                timestamp?: string;
+                artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+              };
+              if (msg.content) {
                 await pushMessage(msg);
               } else {
-                process.stderr.write(`[viber-channel] 'message' event has empty text\n`);
+                process.stderr.write(`[viber-channel] 'message' event has empty content\n`);
               }
             } catch (err) {
               process.stderr.write(`[viber-channel] Failed to parse message data: ${String(err)}\n`);