viber-channel 0.5.3 → 0.7.0

package/lib/supervisor.ts

@@ -0,0 +1,303 @@
+/**
+ * Agent supervisor (#280 step-12, slice 2).
+ *
+ * Hosts MANY agents by spawning one OS process per agent and managing each one's
+ * lifecycle independently. This is the client-side multiplexer the control plane
+ * drives; agents still never talk directly (hub-and-spoke — the Viber server
+ * relays), so one-process-per-agent buys crash isolation for free.
+ *
+ * Design (per .claude/rules/architecture.md):
+ *   - explicit state machine per agent (no boolean soup),
+ *   - a per-agent state object in a registry (no scattered dicts),
+ *   - spawn + restart scheduling injected so the lifecycle is unit-testable
+ *     without real child processes.
+ *
+ * This module owns ONLY lifecycle (spawn / crash / restart / stop). Wiring it to a
+ * real bridge launch and to the control-plane UI is a later slice.
+ *
+ * Follow-up (real-spawn slice): harden against a synchronous spawn() throw — today
+ * spawn is injected and trusted; the real node-spawn SpawnFn should be wrapped so a
+ * launch failure transitions STARTING -> CRASHED and re-enters the backoff path
+ * instead of leaving the agent stuck in STARTING.
+ */
+
+/** Lifecycle states for a single supervised agent. */
+export enum AgentState {
+	/** Spawn requested; child not yet confirmed running. */
+	STARTING = "starting",
+	/** Child process is live. */
+	RUNNING = "running",
+	/** Child exited unexpectedly; awaiting a restart decision. */
+	CRASHED = "crashed",
+	/** Backoff window before the next spawn attempt. */
+	RESTARTING = "restarting",
+	/** Stopped on request, or crashed past the restart budget. Terminal. */
+	STOPPED = "stopped",
+}
+
+/** Legal transitions. Any attempt outside this map throws. */
+const TRANSITIONS: Record<AgentState, readonly AgentState[]> = {
+	[AgentState.STARTING]: [AgentState.RUNNING, AgentState.CRASHED, AgentState.STOPPED],
+	[AgentState.RUNNING]: [AgentState.CRASHED, AgentState.STOPPED],
+	[AgentState.CRASHED]: [AgentState.RESTARTING, AgentState.STOPPED],
+	[AgentState.RESTARTING]: [AgentState.STARTING, AgentState.STOPPED],
+	[AgentState.STOPPED]: [],
+};
+
+/** What to launch for one agent. `args`/`env` are passed to the spawned bridge. */
+export interface AgentSpec {
+	agentId: string;
+	/** Permission tier (step-11): "chat" | "read" | "write". Carried to the child env. */
+	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). */
+export interface ChildHandle {
+	readonly pid?: number;
+	kill(signal?: NodeJS.Signals): boolean;
+	/** Fires once when the process exits. */
+	onExit(cb: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+}
+
+export type SpawnFn = (spec: AgentSpec) => ChildHandle;
+
+/** Schedules `fn` after `ms`; returns a canceller. Injected so tests run instantly. */
+export type RestartScheduler = (fn: () => void, ms: number) => () => void;
+
+export interface SupervisorOptions {
+	spawn: SpawnFn;
+	/**
+	 * Max consecutive crash-restarts before giving up (then the agent goes STOPPED).
+	 * This counts RESTARTS, not spawn attempts: maxRestarts=N allows N restarts, i.e.
+	 * N+1 total spawns, before stopping. Default 5.
+	 */
+	maxRestarts?: number;
+	/** Base backoff (ms) for the first restart; doubles each consecutive crash. Default 1000. */
+	baseBackoffMs?: number;
+	/** Backoff ceiling (ms). Default 30000. */
+	maxBackoffMs?: number;
+	/**
+	 * How long an agent must stay RUNNING before its crash counter resets to 0
+	 * (default 10000). Without this, a fast crash-loop would reset the counter on
+	 * every optimistic RUNNING and never escalate backoff or hit maxRestarts.
+	 */
+	stabilityMs?: number;
+	/** Restart scheduler (default setTimeout/clearTimeout). */
+	schedule?: RestartScheduler;
+	/** Optional log sink (default: stderr). */
+	log?: (line: string) => void;
+}
+
+/** Per-agent state object held in the registry. */
+class AgentProcess {
+	state: AgentState = AgentState.STARTING;
+	child: ChildHandle | null = null;
+	/** Consecutive crash-restarts; reset to 0 once the agent stays up `stabilityMs`. */
+	restarts = 0;
+	cancelBackoff: (() => void) | null = null;
+	cancelStability: (() => void) | null = null;
+	/** Set when stop() was called — suppresses crash-restart. */
+	stopping = false;
+
+	constructor(readonly spec: AgentSpec) {}
+}
+
+/** Snapshot of one agent's status (for the control plane / `list()`). */
+export interface AgentStatus {
+	agentId: string;
+	tier: string;
+	state: AgentState;
+	pid?: number;
+	restarts: number;
+}
+
+const defaultSchedule: RestartScheduler = (fn, ms) => {
+	const t = setTimeout(fn, ms);
+	return () => clearTimeout(t);
+};
+
+export class Supervisor {
+	private readonly registry = new Map<string, AgentProcess>();
+	private readonly spawn: SpawnFn;
+	private readonly maxRestarts: number;
+	private readonly baseBackoffMs: number;
+	private readonly maxBackoffMs: number;
+	private readonly stabilityMs: number;
+	private readonly schedule: RestartScheduler;
+	private readonly log: (line: string) => void;
+
+	constructor(opts: SupervisorOptions) {
+		this.spawn = opts.spawn;
+		this.maxRestarts = opts.maxRestarts ?? 5;
+		this.baseBackoffMs = opts.baseBackoffMs ?? 1000;
+		this.maxBackoffMs = opts.maxBackoffMs ?? 30_000;
+		this.stabilityMs = opts.stabilityMs ?? 10_000;
+		this.schedule = opts.schedule ?? defaultSchedule;
+		this.log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
+	}
+
+	/** Start a new agent. Throws if an agent with this id already exists (not STOPPED). */
+	start(spec: AgentSpec): void {
+		const existing = this.registry.get(spec.agentId);
+		if (existing && existing.state !== AgentState.STOPPED) {
+			throw new Error(`agent ${spec.agentId} already supervised (${existing.state})`);
+		}
+		const agent = new AgentProcess(spec);
+		this.registry.set(spec.agentId, agent);
+		this.spawnAgent(agent);
+	}
+
+	/** Stop an agent: kill the child, mark STOPPED, suppress restart. No-op if unknown. */
+	stop(agentId: string): void {
+		const agent = this.registry.get(agentId);
+		if (!agent || agent.state === AgentState.STOPPED) return;
+		agent.stopping = true;
+		agent.cancelBackoff?.();
+		agent.cancelBackoff = null;
+		agent.cancelStability?.();
+		agent.cancelStability = null;
+		agent.child?.kill("SIGTERM");
+		this.transition(agent, AgentState.STOPPED);
+	}
+
+	/**
+	 * Restart an agent now (manual): stop, then start fresh with the same spec.
+	 * Resets the crash counter to 0 (a deliberate restart is a clean slate). Works
+	 * even on a STOPPED agent (relaunches it); no-op only for an unknown id.
+	 */
+	restart(agentId: string): void {
+		const agent = this.registry.get(agentId);
+		if (!agent) return;
+		const spec = agent.spec;
+		this.stop(agentId);
+		this.registry.delete(agentId);
+		this.start(spec);
+	}
+
+	/** Status snapshot of every supervised agent. */
+	list(): AgentStatus[] {
+		return [...this.registry.values()].map((a) => ({
+			agentId: a.spec.agentId,
+			tier: a.spec.tier,
+			state: a.state,
+			pid: a.child?.pid,
+			restarts: a.restarts,
+		}));
+	}
+
+	/** Stop every agent (e.g. supervisor shutdown). */
+	stopAll(): void {
+		for (const id of this.registry.keys()) this.stop(id);
+	}
+
+	// ── internals ────────────────────────────────────────────────────────────
+
+	private spawnAgent(agent: AgentProcess): void {
+		if (agent.state === AgentState.RESTARTING) {
+			this.transition(agent, AgentState.STARTING);
+		}
+		agent.stopping = false;
+		let child: ChildHandle;
+		try {
+			child = this.spawn(agent.spec);
+		} catch (err) {
+			// A synchronous launch failure is treated like an immediate crash, so the
+			// agent enters the same backoff/give-up path instead of getting stuck in
+			// STARTING with no child.
+			const msg = err instanceof Error ? err.message : String(err);
+			this.scheduleRestartOrStop(agent, `spawn failed: ${msg}`);
+			return;
+		}
+		agent.child = child;
+		this.transition(agent, AgentState.RUNNING);
+		this.log(`[supervisor] agent ${agent.spec.agentId} running (pid ${child.pid ?? "?"})`);
+		// Reset the crash counter only after the agent proves stable, so a fast
+		// crash-loop keeps escalating backoff and eventually hits maxRestarts.
+		agent.cancelStability?.();
+		agent.cancelStability = this.schedule(() => {
+			agent.cancelStability = null;
+			if (agent.state === AgentState.RUNNING) agent.restarts = 0;
+		}, this.stabilityMs);
+		// Guard the exit callback: ignore a double-delivery (one-shot) and a stale
+		// exit from a child we've already replaced (a late exit must not crash the
+		// freshly respawned agent or throw an illegal RESTARTING->CRASHED).
+		let exited = false;
+		child.onExit((code, signal) => {
+			if (exited) return;
+			exited = true;
+			if (agent.child !== child) return;
+			this.onExit(agent, code, signal);
+		});
+	}
+
+	private onExit(
+		agent: AgentProcess,
+		code: number | null,
+		signal: NodeJS.Signals | null,
+	): void {
+		agent.cancelStability?.();
+		agent.cancelStability = null;
+		if (agent.stopping || agent.state === AgentState.STOPPED) {
+			// Expected exit from stop()/restart(); nothing to do.
+			return;
+		}
+		this.scheduleRestartOrStop(agent, signal ? `signal ${signal}` : `code ${code}`);
+	}
+
+	/**
+	 * Crash recovery, shared by an unexpected child exit and a synchronous spawn
+	 * failure: mark CRASHED, then either schedule a backed-off restart or, past the
+	 * budget, give up (STOPPED).
+	 */
+	private scheduleRestartOrStop(agent: AgentProcess, reason: string): void {
+		this.transition(agent, AgentState.CRASHED);
+		this.log(`[supervisor] agent ${agent.spec.agentId} crashed (${reason})`);
+
+		if (agent.restarts >= this.maxRestarts) {
+			this.log(
+				`[supervisor] agent ${agent.spec.agentId} exceeded ${this.maxRestarts} restarts — giving up`,
+			);
+			this.transition(agent, AgentState.STOPPED);
+			return;
+		}
+
+		const delay = Math.min(
+			this.baseBackoffMs * 2 ** agent.restarts,
+			this.maxBackoffMs,
+		);
+		agent.restarts += 1;
+		this.transition(agent, AgentState.RESTARTING);
+		this.log(
+			`[supervisor] agent ${agent.spec.agentId} restart ${agent.restarts}/${this.maxRestarts} in ${delay}ms`,
+		);
+		agent.cancelBackoff = this.schedule(() => {
+			agent.cancelBackoff = null;
+			// A stop() during the backoff window wins.
+			if (agent.stopping || agent.state === AgentState.STOPPED) return;
+			this.spawnAgent(agent);
+		}, delay);
+	}
+
+	private transition(agent: AgentProcess, next: AgentState): void {
+		const allowed = TRANSITIONS[agent.state];
+		if (!allowed.includes(next)) {
+			throw new Error(
+				`illegal agent transition ${agent.state} -> ${next} (agent ${agent.spec.agentId})`,
+			);
+		}
+		agent.state = next;
+	}
+}

package/lib/supervisor_config.ts

@@ -0,0 +1,140 @@
+/**
+ * Supervisor config parsing (#280 step-12, slice 4).
+ *
+ * Turns a JSON config (or the parsed object) into validated `AgentSpec`s for the
+ * Supervisor. Kept pure + separate from the entry point so it is unit-testable.
+ *
+ * Config shape:
+ *   {
+ *     "agents": [
+ *       { "id": "reviewer", "tier": "read", "args": ["--await-invite"] },
+ *       { "tier": "chat", "count": 2 }            // count → N agents of this tier
+ *     ]
+ *   }
+ *
+ * Defaults: `args` → ["--await-invite"] (the control plane pushes the conversation,
+ * #280 step-03); a missing `id` is generated as `agent-<n>`; `count` (default 1)
+ * expands to that many specs with suffixed ids.
+ */
+
+import type { AgentSpec } from "./supervisor.ts";
+
+const VALID_TIERS = ["chat", "read", "write"] as const;
+type Tier = (typeof VALID_TIERS)[number];
+
+function isTier(v: unknown): v is Tier {
+	return typeof v === "string" && VALID_TIERS.some((t) => t === v);
+}
+
+interface RawAgent {
+	id?: unknown;
+	tier?: unknown;
+	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[] {
+	if (raw === undefined) return ["--await-invite"];
+	if (!Array.isArray(raw) || raw.some((a) => typeof a !== "string")) {
+		throw new Error("agent.args must be an array of strings");
+	}
+	return raw as string[];
+}
+
+function parseEnvField(raw: unknown): Record<string, string> | undefined {
+	if (raw === undefined || raw === null) return undefined;
+	if (typeof raw !== "object" || Array.isArray(raw)) {
+		throw new Error("agent.env must be an object");
+	}
+	const out: Record<string, string> = {};
+	for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+		if (typeof v !== "string") throw new Error(`agent.env.${k} must be a string`);
+		out[k] = v;
+	}
+	return out;
+}
+
+function parseCount(raw: unknown): number {
+	if (raw === undefined) return 1;
+	if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1 || raw > 64) {
+		throw new Error("agent.count must be an integer between 1 and 64");
+	}
+	return raw;
+}
+
+/**
+ * Parse a supervisor config object into a flat list of AgentSpecs.
+ * Throws on any malformed entry (fail fast at launch). Agent ids are unique:
+ * a duplicate explicit id throws; generated ids never collide.
+ */
+export function parseSupervisorConfig(raw: unknown): AgentSpec[] {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+		throw new Error("supervisor config must be an object");
+	}
+	const agents = (raw as { agents?: unknown }).agents;
+	if (!Array.isArray(agents) || agents.length === 0) {
+		throw new Error("supervisor config must have a non-empty `agents` array");
+	}
+
+	const specs: AgentSpec[] = [];
+	const seen = new Set<string>();
+	let generated = 0;
+
+	for (const entry of agents as RawAgent[]) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+			throw new Error("each agent must be an object");
+		}
+		if (!isTier(entry.tier)) {
+			throw new Error(`agent.tier must be one of: ${VALID_TIERS.join(", ")}`);
+		}
+		let explicitId: string | undefined;
+		if (entry.id !== undefined) {
+			if (typeof entry.id !== "string" || entry.id.trim() === "") {
+				throw new Error("agent.id must be a non-empty string");
+			}
+			explicitId = entry.id;
+		}
+		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
+			// the bare id. NOTE: bumping count 1→2 thus renames `rev`→`rev-1`.
+			let id: string;
+			if (explicitId !== undefined) {
+				id = count > 1 ? `${explicitId}-${i + 1}` : explicitId;
+			} else {
+				generated += 1;
+				id = `agent-${generated}`;
+			}
+			if (seen.has(id)) throw new Error(`duplicate agent id: ${id}`);
+			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 } : {}),
+				...(role !== undefined ? { role } : {}),
+				...(nameExplicit ? { nameExplicit: true } : {}),
+			});
+		}
+	}
+
+	return specs;
+}

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "viber-channel",
-  "version": "0.5.3",
+  "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-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"
   ],
@@ -31,6 +37,7 @@
   "license": "MIT",
   "scripts": {
     "start": "bun run viber-channel.ts",
+    "start:codex-bridge": "bun run viber-codex-bridge.ts",
     "test": "bun test"
   },
   "dependencies": {