viber-channel 0.6.0 → 0.7.0

package/lib/instance.ts

@@ -63,6 +63,19 @@ export async function registerInstance(
   return (await resp.json()) as RegisterInstanceResponse;
 }
 
+/**
+ * The control-plane `kind` for instances this process registers, from
+ * `VIBER_INSTANCE_KIND` (set by the spawn path — vibe-master's agent_spec, #318
+ * step-01). undefined when unset → the worker defaults to "claude-code", the
+ * historical behavior for a plain channel session. A bridge runtime (codex,
+ * gemma, hermes) sets it so its instance is tagged correctly in the control
+ * plane instead of mislabelled claude-code.
+ */
+export function instanceKindFromEnv(): string | undefined {
+  const raw = process.env.VIBER_INSTANCE_KIND;
+  return raw !== undefined && raw.trim() !== "" ? raw.trim() : undefined;
+}
+
 export interface AcquiredInstance {
   instance_token: string;
   /**
@@ -117,7 +130,14 @@ export async function acquireInstance(
   if (envLabel !== undefined && envLabel.trim() !== "") {
     const label = envLabel.trim();
     log(`[viber-channel] instance: registering fresh labelled instance "${label}"\n`);
-    const reg = await registerInstance(baseUrl, auth.project_id, auth.project_token, fingerprint, label);
+    const reg = await registerInstance(
+      baseUrl,
+      auth.project_id,
+      auth.project_token,
+      fingerprint,
+      label,
+      instanceKindFromEnv(),
+    );
     return { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };
   }
 
@@ -130,7 +150,14 @@ export async function acquireInstance(
   }
 
   log(`[viber-channel] instance: none found — registering a new one via the project_token\n`);
-  const reg = await registerInstance(baseUrl, auth.project_id, auth.project_token, fingerprint);
+  const reg = await registerInstance(
+    baseUrl,
+    auth.project_id,
+    auth.project_token,
+    fingerprint,
+    undefined,
+    instanceKindFromEnv(),
+  );
   persistInstanceCredentials(authFilePath(cwd), reg.instance_id, reg.instance_token, log);
   log(`[viber-channel] instance: registered + persisted (id=${reg.instance_id})\n`);
   return { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };

package/lib/lockfile.ts

@@ -48,3 +48,39 @@ export function lockFilePath(
     .slice(0, 8);
   return join(lockDir, `channel-${suffix}.lock`);
 }
+
+/**
+ * Resolve the lock's session-id axis from the environment (#259/#269/#293).
+ *
+ * Priority (first non-empty wins):
+ *   1. `VIBER_CHANNEL_SESSION_ID` — explicit per-launch id (launchers, #259).
+ *   2. `VIBER_INSTANCE_TOKEN` → `inst-<hash>` — env-injected fleet agents (#269).
+ *   3. `VIBER_CHANNEL_LABEL` → `label-<hash>` — a deliberate 2nd agent in the SAME
+ *      folder (#293): the label already gives it a fresh instance identity, so
+ *      derive a distinct lock from it too. Without this it would share the 1st
+ *      agent's lock and be rejected as a duplicate.
+ *   4. `""` — plain bunx client / accidental respawn: shares the per-folder lock
+ *      so accidental duplicates stay blocked (#166).
+ *
+ * Tokens/labels are HASHED (never raw) because the result is logged as a prefix.
+ */
+export function lockSessionId(env: NodeJS.ProcessEnv): string {
+  // A non-blank explicit id wins verbatim. A BLANK one (set to "" / whitespace)
+  // is treated as ABSENT so it falls through to the token/label tiers — otherwise
+  // `VIBER_CHANNEL_SESSION_ID="" + VIBER_CHANNEL_LABEL=x` would yield "" and the
+  // labelled 2nd agent would still collide (review: Opus #1 / Codex).
+  const explicit = env.VIBER_CHANNEL_SESSION_ID;
+  if (explicit !== undefined && explicit.trim() !== "") return explicit;
+  const token = env.VIBER_INSTANCE_TOKEN?.trim();
+  if (token !== undefined && token !== "") {
+    // Trim before hashing (consistent with acquireInstance, which uses the
+    // trimmed token as the identity) so the lock and the identity derive from
+    // the same effective value.
+    return `inst-${createHash("sha256").update(token).digest("hex").slice(0, 16)}`;
+  }
+  const label = env.VIBER_CHANNEL_LABEL;
+  if (label !== undefined && label.trim() !== "") {
+    return `label-${createHash("sha256").update(label.trim()).digest("hex").slice(0, 16)}`;
+  }
+  return "";
+}

package/lib/messages.ts

@@ -121,6 +121,13 @@ export async function postMessage(
   conversationToken: string,
   text: string,
   artifact?: Artifact,
+  /**
+   * Optional abort signal (#303 step-12.03): the codex bridge passes its stream's
+   * signal so a reply in flight is cancelled atomically if the stream is aborted
+   * (re-join / revoke / shutdown) — closing the check-then-post window that a bare
+   * `signal.aborted` guard before the call cannot.
+   */
+  signal?: AbortSignal,
 ): Promise<MessagePostResult> {
   if (!text || text.trim().length === 0) {
     return {
@@ -142,6 +149,7 @@ export async function postMessage(
         ...cfAccessHeaders(),
       },
       body: JSON.stringify(artifact ? { content: text, artifact } : { content: text }),
+      signal,
     });
   } catch (err) {
     return {

package/lib/ollama_chat.ts

@@ -0,0 +1,106 @@
+/**
+ * ollama_chat.ts — minimal ollama /api/chat client for the Gemma runtime (#318
+ * step-02).
+ *
+ * Gemma is a "bare LLM" runtime: unlike Codex it does not host MCP tools or run
+ * an app-server — the bridge simply feeds the conversation to ollama and posts
+ * the assistant's reply back into Viber. This module is that single call,
+ * isolated and pure (HTTP in → text out) so it is unit-testable without a live
+ * ollama.
+ *
+ * Ported from the existing in-process Python integration (`viber/llm.py` +
+ * `viber/standalone_ai.py`, #188): same model id `gemma4:e4b`, same chat-message
+ * shape, same "ollama not running" error semantics — reimplemented in TS for the
+ * control-plane bridge (D1: a TS bridge, not promoting the Python path).
+ */
+
+/** A chat turn, matching ollama's /api/chat message shape. */
+export interface ChatMessage {
+	role: "system" | "user" | "assistant";
+	content: string;
+}
+
+/** Raised when the ollama daemon is unreachable (not running / wrong host). */
+export class OllamaUnavailableError extends Error {
+	constructor(baseUrl: string, cause?: unknown) {
+		super(
+			`ollama is not reachable at ${baseUrl} — start it with \`ollama serve\` (cause: ${cause instanceof Error ? cause.message : String(cause)})`,
+		);
+		this.name = "OllamaUnavailableError";
+	}
+}
+
+/** Raised when ollama responds but with a non-2xx status (e.g. model missing). */
+export class OllamaResponseError extends Error {
+	status: number;
+	constructor(status: number, detail: string) {
+		super(`ollama /api/chat failed (HTTP ${status}): ${detail}`);
+		this.name = "OllamaResponseError";
+		this.status = status;
+	}
+}
+
+/** Default local ollama endpoint (same default as the ollama CLI/SDK). */
+export const DEFAULT_OLLAMA_URL = "http://127.0.0.1:11434";
+/** Default model — matches `viber/llm.py` DEFAULT_MODEL. */
+export const DEFAULT_GEMMA_MODEL = "gemma4:e4b";
+
+export interface OllamaChatOptions {
+	baseUrl?: string;
+	model?: string;
+	/** Sampling temperature (parity with standalone_ai.py: 0.7). */
+	temperature?: number;
+	/** Abort the request if the stream is torn down mid-generation. */
+	signal?: AbortSignal;
+	/** Injectable fetch for tests (defaults to global fetch). */
+	fetchImpl?: typeof fetch;
+}
+
+/** Shape of the (non-streaming) ollama /api/chat response we consume. */
+interface OllamaChatResponse {
+	message?: { role?: string; content?: string };
+}
+
+/**
+ * Send a chat completion to ollama and return the assistant's text.
+ *
+ * `stream: false` so we get one JSON object (no SSE parsing). A network failure
+ * (ECONNREFUSED when the daemon is down) maps to OllamaUnavailableError; a
+ * non-2xx maps to OllamaResponseError — the bridge turns both into a clean Viber
+ * reply rather than crashing.
+ */
+export async function ollamaChat(
+	messages: ChatMessage[],
+	opts: OllamaChatOptions = {},
+): Promise<string> {
+	const baseUrl = opts.baseUrl ?? DEFAULT_OLLAMA_URL;
+	const model = opts.model ?? DEFAULT_GEMMA_MODEL;
+	const doFetch = opts.fetchImpl ?? fetch;
+
+	let resp: Response;
+	try {
+		resp = await doFetch(`${baseUrl}/api/chat`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				model,
+				messages,
+				stream: false,
+				options: { temperature: opts.temperature ?? 0.7 },
+			}),
+			signal: opts.signal,
+		});
+	} catch (err) {
+		// AbortError must propagate (deliberate teardown), not be masked as "down".
+		if (err instanceof Error && err.name === "AbortError") throw err;
+		throw new OllamaUnavailableError(baseUrl, err);
+	}
+
+	if (!resp.ok) {
+		const detail = await resp.text().catch(() => "");
+		throw new OllamaResponseError(resp.status, detail);
+	}
+
+	const data = (await resp.json()) as OllamaChatResponse;
+	return (data.message?.content ?? "").trim();
+}

package/lib/parent_watchdog.ts

@@ -0,0 +1,276 @@
+/**
+ * Parent-liveness watchdog (#298) — exit when the agent that spawned us dies.
+ *
+ * WHY: a viber-channel is an MCP server spawned over stdio by Claude Code. When
+ * Claude Code dies, the channel SHOULD exit so it stops holding its SSE streams
+ * open and stops sending presence heartbeats — otherwise it becomes a zombie
+ * that still shows "online" while no agent answers (observed live: a 4-day-old
+ * orphaned channel process).
+ *
+ * The existing `process.stdin.on("end")` handler is the intended detector, but it
+ * is unreliable on Windows: when the parent is killed via TerminateProcess (crash
+ * / Task Manager) through a `cmd.exe → bun` or `bunx` wrapper chain, the stdin
+ * pipe EOF is not always propagated to the child. The MCP SDK is no help either —
+ * `StdioServerTransport` only listens to stdin `data`/`error`, never `end`/`close`,
+ * so `server.onclose` never fires on parent death.
+ *
+ * This watchdog is the reliable backstop: poll the parent PID; the instant it is
+ * gone, exit. It does NOT guess from inactivity (no false positives while an
+ * agent merely thinks for a long time) — it keys on the OS truth "is my parent
+ * still alive". `signal 0` probes existence without delivering a signal.
+ */
+
+import { execSync } from "node:child_process";
+
+/**
+ * Shim processes that sit BETWEEN the real agent (e.g. claude.exe) and us in the
+ * spawn tree. Claude Code spawns `cmd.exe /c bun …` (or `… bunx …`), so our
+ * immediate parent is usually a shell/runtime shim — watching it is useless
+ * because killing Claude leaves the shim orphaned but alive. We walk up past
+ * these to find the real agent PID.
+ */
+export const SHIM_PROCESS_NAMES = new Set([
+  "cmd.exe",
+  "conhost.exe",
+  "bun.exe",
+  "bunx.exe",
+  "powershell.exe",
+  "pwsh.exe",
+  "sh.exe",
+  "bash.exe",
+]);
+
+export interface ProcInfo {
+  ppid: number;
+  name: string;
+  /** CIM CreationDate string — part of the (pid, creationDate) identity that
+   * survives PID reuse (#298 P2b). Empty when unknown (e.g. injected in tests). */
+  creationDate?: string;
+}
+
+/** Identity of the watched agent — pid + the fields that defeat PID reuse. */
+export interface AgentIdentity {
+  pid: number;
+  name: string;
+  creationDate: string;
+}
+
+/**
+ * Walk up the ancestry from `startPid`, skipping shim processes, and return the
+ * first "real" (non-shim) ancestor PID — the agent that owns this channel.
+ *
+ * Returns null when no non-shim ancestor is reachable (the walk hits a pid that
+ * is absent from the table, i.e. the agent is already gone). #298 P2a: we do NOT
+ * fall back to the immediate shim parent — a shim (cmd.exe/bun) outlives a killed
+ * agent, so watching it would never fire and the zombie would survive. Better to
+ * return null (no watch) than to watch the wrong, longer-lived process. Pure: the
+ * process table is injected for testability.
+ */
+export function resolveAgentPid(
+  startPid: number,
+  table: Map<number, ProcInfo>,
+): number | null {
+  const start = table.get(startPid);
+  if (!start) return null;
+  let cur = start.ppid;
+  const seen = new Set<number>([startPid]);
+  while (cur && cur > 1 && !seen.has(cur)) {
+    seen.add(cur);
+    const info = table.get(cur);
+    if (!info) break; // chain breaks → agent not present → caller no-ops
+    if (!SHIM_PROCESS_NAMES.has(info.name.toLowerCase())) {
+      return cur; // first non-shim ancestor = the agent
+    }
+    cur = info.ppid;
+  }
+  return null;
+}
+
+/**
+ * Read the Windows process table (pid → {ppid, name, creationDate}) via one CIM
+ * query, or null on any failure / non-Windows. Time-bounded so a slow WMI never
+ * stalls startup.
+ */
+export function readWindowsProcessTable(): Map<number, ProcInfo> | null {
+  if (process.platform !== "win32") return null;
+  try {
+    const out = execSync(
+      'powershell -NoProfile -Command "Get-CimInstance Win32_Process | ' +
+        'Select-Object ProcessId,ParentProcessId,Name,CreationDate | ConvertTo-Csv -NoTypeInformation"',
+      { encoding: "utf8", timeout: 4000, stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const table = new Map<number, ProcInfo>();
+    for (const line of out.split(/\r?\n/)) {
+      // CSV: "ProcessId","ParentProcessId","Name","CreationDate"
+      const m = line.match(/^"?(\d+)"?,"?(\d+)"?,"?(.*?)"?,"?(.*?)"?$/);
+      if (!m) continue;
+      table.set(Number(m[1]), { ppid: Number(m[2]), name: m[3], creationDate: m[4] });
+    }
+    return table.size > 0 ? table : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read one process's identity (name + creationDate) by PID via a filtered CIM
+ * query, or null if it doesn't exist. Used per-poll to defeat PID reuse (#298
+ * P2b): a recycled PID will have a different name/creationDate than the agent we
+ * resolved at startup, so we treat it as gone. Fast (single object) + bounded.
+ */
+export function readProcessIdentity(
+  pid: number,
+): { name: string; creationDate: string } | null {
+  if (process.platform !== "win32") return null;
+  try {
+    const out = execSync(
+      `powershell -NoProfile -Command "Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}' | ` +
+        'Select-Object Name,CreationDate | ConvertTo-Csv -NoTypeInformation"',
+      { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] },
+    );
+    for (const line of out.split(/\r?\n/)) {
+      const m = line.match(/^"(.*?)","(.*?)"$/);
+      if (!m || m[1] === "Name") continue; // skip header
+      return { name: m[1], creationDate: m[2] };
+    }
+    return null; // no row → pid not found
+  } catch {
+    return null;
+  }
+}
+
+export interface ParentWatchdogOptions {
+  /**
+   * Explicit PID to watch (skips the ancestor walk). Mainly for tests; production
+   * resolves the agent ancestor from the process table.
+   */
+  ppid?: number;
+  /** Expected identity for PID-reuse defense; paired with an explicit `ppid`. */
+  identity?: AgentIdentity;
+  /** Poll cadence (ms). Default 5000. */
+  intervalMs?: number;
+  /**
+   * Liveness+identity probe: true iff the resolved agent is STILL the same live
+   * process. Default validates name+creationDate via a filtered CIM query (falls
+   * back to bare PID existence if identity is unknown). Injectable for tests.
+   */
+  isAlive?: (id: AgentIdentity) => boolean;
+  /** Called when the parent is gone (before exit). Defaults to process.exit(0). */
+  onParentGone?: () => void;
+  log?: (line: string) => void;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}
+
+export interface ParentWatchdogHandle {
+  stop: () => void;
+}
+
+const DEFAULT_INTERVAL_MS = 5000;
+
+/** True iff `pid` currently exists. `kill(pid, 0)` throws ESRCH when it doesn't. */
+export function pidIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM = exists but not ours to signal → still alive. ESRCH = gone.
+    return (err as NodeJS.ErrnoException)?.code === "EPERM";
+  }
+}
+
+/**
+ * Default probe: the agent is alive iff a process with its PID exists AND matches
+ * the captured identity (name + creationDate). The identity check is what defeats
+ * PID reuse (#298 P2b) — a recycled PID has a different creationDate/name. If we
+ * never captured a creationDate (non-win32 / unknown), fall back to bare PID
+ * existence so we don't false-positive a still-running agent.
+ */
+function defaultIsAlive(id: AgentIdentity): boolean {
+  if (!id.creationDate) return pidIsAlive(id.pid);
+  const cur = readProcessIdentity(id.pid);
+  if (cur === null) {
+    // CIM said "no such pid". Trust it only if the pid is genuinely gone; if the
+    // query itself failed transiently, pidIsAlive still reports existence and we
+    // keep watching (fail-safe: never exit on a flaky query).
+    return pidIsAlive(id.pid);
+  }
+  return cur.creationDate === id.creationDate && cur.name === id.name;
+}
+
+/**
+ * Start watching the agent process. Returns a handle whose `stop()` cancels it.
+ *
+ * No-op (returns an inert handle) when no agent ancestor can be resolved — e.g.
+ * the agent is already gone at startup (resolveAgentPid returns null rather than
+ * a surviving shim, #298 P2a) or on non-Windows. We must never exit spuriously,
+ * so an unresolvable agent means "don't watch" (the stdin-EOF handler still
+ * covers the clean-exit path).
+ */
+export function startParentWatchdog(
+  opts: ParentWatchdogOptions = {},
+): ParentWatchdogHandle {
+  const log = opts.log ?? ((line: string) => process.stderr.write(line));
+
+  // Resolve the agent to watch + its identity. Explicit ppid (tests) wins;
+  // otherwise walk the process table past shims to the real agent (claude.exe).
+  let identity: AgentIdentity | null = null;
+  if (opts.ppid !== undefined && opts.ppid > 1) {
+    identity = opts.identity ?? { pid: opts.ppid, name: "", creationDate: "" };
+  } else if (opts.ppid === undefined) {
+    const table = readWindowsProcessTable();
+    const resolved = table ? resolveAgentPid(process.pid, table) : null;
+    if (resolved && table) {
+      const info = table.get(resolved);
+      identity = {
+        pid: resolved,
+        name: info?.name ?? "",
+        creationDate: info?.creationDate ?? "",
+      };
+      log(`[viber-channel] parent watchdog watching agent pid ${resolved} (${identity.name})\n`);
+    }
+  }
+
+  if (!identity) {
+    log("[viber-channel] parent watchdog disabled (no resolvable agent ancestor)\n");
+    return { stop: () => {} };
+  }
+
+  const watched = identity;
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const isAlive = opts.isAlive ?? defaultIsAlive;
+  const onParentGone =
+    opts.onParentGone ??
+    (() => {
+      process.exit(0);
+    });
+  const setTimer =
+    opts.setTimer ?? ((fn: () => void, ms: number) => setInterval(fn, ms) as unknown);
+  const clearTimer =
+    opts.clearTimer ??
+    ((h: unknown) => clearInterval(h as ReturnType<typeof setInterval>));
+
+  let stopped = false;
+  const handle = setTimer(() => {
+    if (stopped) return;
+    if (!isAlive(watched)) {
+      log(`[viber-channel] agent process ${watched.pid} is gone — exiting to avoid a zombie channel\n`);
+      stopped = true;
+      clearTimer(handle);
+      onParentGone();
+    }
+  }, intervalMs);
+
+  // The watchdog itself must not keep the process alive.
+  if (handle && typeof (handle as { unref?: () => void }).unref === "function") {
+    (handle as { unref: () => void }).unref();
+  }
+
+  return {
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      clearTimer(handle);
+    },
+  };
+}

package/lib/peers.ts

@@ -0,0 +1,113 @@
+/**
+ * peers.ts — HTTP client for the agent-facing endpoints (#288):
+ *   GET  /api/instances/peers  — discover the other agents of this project
+ *   POST /api/instances/dms    — open-or-create a 1:1 DM with a peer
+ *
+ * Pure functions: no state, no MCP. The CallTool handlers in viber-channel.ts
+ * call these and map the result to MCP tool results. Auth is the caller's
+ * durable instance_token (Bearer) — the server scopes everything to that
+ * instance's project + owner.
+ */
+
+import { cfAccessHeaders } from "./cfAccess.js";
+
+/** A peer agent as returned by GET /api/instances/peers. */
+export interface PeerView {
+  id: string;
+  label: string | null;
+  kind: string;
+  online: boolean;
+  last_seen: number | null;
+  active_conversation_id: string | null;
+}
+
+/**
+ * List the OTHER active instances of this agent's project (self excluded).
+ * Throws on a non-2xx response so the caller can surface a clear tool error.
+ */
+export async function listPeers(
+  baseUrl: string,
+  instanceToken: string,
+): Promise<PeerView[]> {
+  const resp = await fetch(`${baseUrl}/api/instances/peers`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${instanceToken}`, ...cfAccessHeaders() },
+  });
+  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 {
+      /* non-JSON body */
+    }
+    throw new Error(`listPeers failed: ${detail}`);
+  }
+  const body = (await resp.json()) as { instances?: PeerView[] };
+  return Array.isArray(body.instances) ? body.instances : [];
+}
+
+/** Result of opening (or reusing) a DM with a peer — carries the caller's own
+ *  membership conversation_token so it can post into the DM. */
+export interface OpenDmResult {
+  conversation_id: string;
+  conversation_token: string;
+  expires_at: number;
+  invited: boolean;
+}
+
+export type OpenDmOutcome =
+  | { ok: true; dm: OpenDmResult }
+  | { ok: false; detail: string; status: number };
+
+/**
+ * Open-or-create a 1:1 DM with `peerInstanceId` (POST /api/instances/dms).
+ * Returns a structured outcome rather than throwing on the expected 4xx cases
+ * (peer offline / not found) so the tool can surface a clear message to the
+ * model; network/parse failures throw.
+ */
+export async function openDm(
+  baseUrl: string,
+  instanceToken: string,
+  peerInstanceId: string,
+): Promise<OpenDmOutcome> {
+  const resp = await fetch(`${baseUrl}/api/instances/dms`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${instanceToken}`,
+      "Content-Type": "application/json",
+      ...cfAccessHeaders(),
+    },
+    body: JSON.stringify({ peer_instance_id: peerInstanceId }),
+  });
+
+  if (!resp.ok) {
+    let detail = `HTTP ${resp.status}`;
+    try {
+      const json = (await resp.json()) as { detail?: string };
+      if (typeof json.detail === "string") detail = json.detail;
+    } catch {
+      /* non-JSON body */
+    }
+    return { ok: false, detail, status: resp.status };
+  }
+
+  const body = (await resp.json()) as {
+    conversation?: { id?: string };
+    conversation_token?: string;
+    expires_at?: number;
+    invited?: boolean;
+  };
+  if (!body.conversation?.id || typeof body.conversation_token !== "string") {
+    throw new Error("openDm: malformed response (missing conversation id or token)");
+  }
+  return {
+    ok: true,
+    dm: {
+      conversation_id: body.conversation.id,
+      conversation_token: body.conversation_token,
+      expires_at: typeof body.expires_at === "number" ? body.expires_at : 0,
+      invited: body.invited === true,
+    },
+  };
+}

package/lib/supervisor.ts

@@ -51,6 +51,17 @@ export interface AgentSpec {
 	tier: string;
 	args: string[];
 	env?: Record<string, string>;
+	/**
+	 * Optional operator-assigned role (#309 step-17). Untrusted free text; the
+	 * bridge sanitizes it before injecting it into the runtime instructions.
+	 */
+	role?: string;
+	/**
+	 * Whether `agentId` was set EXPLICITLY (vs an auto-generated id like
+	 * `agent-1`). Only an explicit id is injected as the agent's name — auto ids
+	 * look like names but aren't, so the bridge must not claim them (#309).
+	 */
+	nameExplicit?: boolean;
 }
 
 /** Minimal child-process surface the supervisor depends on (injectable for tests). */

package/lib/supervisor_config.ts

@@ -32,6 +32,13 @@ interface RawAgent {
 	args?: unknown;
 	count?: unknown;
 	env?: unknown;
+	role?: unknown;
+}
+
+function parseRoleField(raw: unknown): string | undefined {
+	if (raw === undefined || raw === null) return undefined;
+	if (typeof raw !== "string") throw new Error("agent.role must be a string");
+	return raw;
 }
 
 function parseArgsField(raw: unknown): string[] {
@@ -98,6 +105,11 @@ export function parseSupervisorConfig(raw: unknown): AgentSpec[] {
 		const args = parseArgsField(entry.args);
 		const env = parseEnvField(entry.env);
 		const count = parseCount(entry.count);
+		const role = parseRoleField(entry.role);
+		// #309: a config `id` is operator-chosen → an explicit name (the
+		// count-suffix below keeps it explicit, e.g. `rev-1`). Auto `agent-N`
+		// ids are NOT explicit and must not be injected as the agent's name.
+		const nameExplicit = explicitId !== undefined;
 
 		for (let i = 0; i < count; i++) {
 			// count > 1 suffixes the explicit id (rev-1, rev-2…); a single agent keeps
@@ -113,7 +125,14 @@ export function parseSupervisorConfig(raw: unknown): AgentSpec[] {
 			seen.add(id);
 			// Independent args array per spec so a later mutation can't bleed across
 			// count-expanded siblings.
-			specs.push({ agentId: id, tier: entry.tier, args: [...args], ...(env ? { env } : {}) });
+			specs.push({
+				agentId: id,
+				tier: entry.tier,
+				args: [...args],
+				...(env ? { env } : {}),
+				...(role !== undefined ? { role } : {}),
+				...(nameExplicit ? { nameExplicit: true } : {}),
+			});
 		}
 	}
 

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "viber-channel",
-  "version": "0.6.0",
+  "version": "0.7.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",
     "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"