@stimm/protocol 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @stimm/protocol — TypeScript types and supervisor client
+ * for Stimm dual-agent voice orchestration.
+ *
+ * @packageDocumentation
+ */
+export type { TranscriptMessage, StateMessage, BeforeSpeakMessage, MetricsMessage, InstructionMessage, ContextMessage, ActionResultMessage, ModeMessage, OverrideMessage, AgentMode, VoiceAgentMessage, SupervisorMessage, StimmMessage, } from "./messages.js";
+export { STIMM_TOPIC } from "./messages.js";
+export { StimmSupervisorClient, type StimmSupervisorClientOptions, } from "./supervisor-client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,GACb,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @stimm/protocol — TypeScript types and supervisor client
+ * for Stimm dual-agent voice orchestration.
+ *
+ * @packageDocumentation
+ */
+export { STIMM_TOPIC } from "./messages.js";
+// Supervisor client
+export { StimmSupervisorClient, } from "./supervisor-client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmBH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,oBAAoB;AACpB,OAAO,EACL,qBAAqB,GAEtB,MAAM,wBAAwB,CAAC"}

package/dist/messages.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Stimm Protocol — TypeScript message types.
+ *
+ * Mirror of the Python Pydantic models in `stimm.protocol`.
+ * All messages are exchanged as JSON over LiveKit reliable data channels.
+ *
+ * @module
+ */
+/** Real-time speech transcript from the voice agent's STT. */
+export interface TranscriptMessage {
+    type: "transcript";
+    /** Whether this is a partial (streaming) or final transcript. */
+    partial: boolean;
+    text: string;
+    timestamp: number;
+    confidence: number;
+}
+/** Voice agent state transition. */
+export interface StateMessage {
+    type: "state";
+    state: "listening" | "thinking" | "speaking";
+    timestamp: number;
+}
+/** Emitted before the voice agent sends text to TTS. */
+export interface BeforeSpeakMessage {
+    type: "before_speak";
+    text: string;
+    turn_id: string;
+}
+/** Per-turn latency metrics. */
+export interface MetricsMessage {
+    type: "metrics";
+    turn: number;
+    vad_ms: number;
+    stt_ms: number;
+    llm_ttft_ms: number;
+    tts_ttfb_ms: number;
+    total_ms: number;
+}
+/** Voice agent operating mode. */
+export type AgentMode = "autonomous" | "relay" | "hybrid";
+/** Instruction for the voice agent to speak or incorporate. */
+export interface InstructionMessage {
+    type: "instruction";
+    text: string;
+    priority: "normal" | "interrupt";
+    speak: boolean;
+}
+/** Additional context for the voice agent's working memory. */
+export interface ContextMessage {
+    type: "context";
+    text: string;
+    append: boolean;
+}
+/** Notification that a tool/action completed in the supervisor. */
+export interface ActionResultMessage {
+    type: "action_result";
+    action: string;
+    status: string;
+    summary: string;
+}
+/** Switch the voice agent's operating mode. */
+export interface ModeMessage {
+    type: "mode";
+    mode: AgentMode;
+}
+/** Cancel the voice agent's pending response and replace it. */
+export interface OverrideMessage {
+    type: "override";
+    turn_id: string;
+    replacement: string;
+}
+/** Any message sent by the voice agent. */
+export type VoiceAgentMessage = TranscriptMessage | StateMessage | BeforeSpeakMessage | MetricsMessage;
+/** Any message sent by the supervisor. */
+export type SupervisorMessage = InstructionMessage | ContextMessage | ActionResultMessage | ModeMessage | OverrideMessage;
+/** Any stimm protocol message. */
+export type StimmMessage = VoiceAgentMessage | SupervisorMessage;
+/** The LiveKit data channel topic used by stimm. */
+export declare const STIMM_TOPIC = "stimm";
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,CAAC;IACnB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1D,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,YAAY,GACZ,kBAAkB,GAClB,cAAc,CAAC;AAEnB,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,cAAc,GACd,mBAAmB,GACnB,WAAW,GACX,eAAe,CAAC;AAEpB,kCAAkC;AAClC,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEjE,oDAAoD;AACpD,eAAO,MAAM,WAAW,UAAU,CAAC"}

package/dist/messages.js

@@ -0,0 +1,11 @@
+/**
+ * Stimm Protocol — TypeScript message types.
+ *
+ * Mirror of the Python Pydantic models in `stimm.protocol`.
+ * All messages are exchanged as JSON over LiveKit reliable data channels.
+ *
+ * @module
+ */
+/** The LiveKit data channel topic used by stimm. */
+export const STIMM_TOPIC = "stimm";
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0GH,oDAAoD;AACpD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC"}

package/dist/supervisor-client.d.ts

@@ -0,0 +1,75 @@
+/**
+ * StimmSupervisorClient — TypeScript supervisor for Node.js consumers.
+ *
+ * Connects to a LiveKit room as a data-only participant and provides
+ * a typed event-driven interface for receiving voice agent messages
+ * and sending instructions back.
+ *
+ * @example
+ * ```ts
+ * import { StimmSupervisorClient } from "@stimm/protocol";
+ *
+ * const client = new StimmSupervisorClient({
+ *   livekitUrl: "ws://localhost:7880",
+ *   token: supervisorToken,
+ * });
+ *
+ * client.on("transcript", async (msg) => {
+ *   if (!msg.partial) {
+ *     const result = await myAgent.process(msg.text);
+ *     await client.instruct({ text: result, speak: true, priority: "normal" });
+ *   }
+ * });
+ *
+ * await client.connect();
+ * ```
+ *
+ * @module
+ */
+import type { AgentMode, TranscriptMessage, StateMessage, BeforeSpeakMessage, MetricsMessage, InstructionMessage, ContextMessage, ActionResultMessage, OverrideMessage } from "./messages.js";
+type VoiceAgentEventMap = {
+    transcript: TranscriptMessage;
+    state: StateMessage;
+    before_speak: BeforeSpeakMessage;
+    metrics: MetricsMessage;
+};
+type VoiceAgentEvent = keyof VoiceAgentEventMap;
+type EventHandler<T> = (msg: T) => void | Promise<void>;
+export interface StimmSupervisorClientOptions {
+    /** LiveKit server WebSocket URL. */
+    livekitUrl: string;
+    /** Access token with data-channel permissions. */
+    token: string;
+}
+export declare class StimmSupervisorClient {
+    private room;
+    private url;
+    private token;
+    private handlers;
+    private _connected;
+    constructor(options: StimmSupervisorClientOptions);
+    /** Whether the client is currently connected. */
+    get connected(): boolean;
+    /** Connect to the LiveKit room. */
+    connect(): Promise<void>;
+    /** Disconnect from the room. */
+    disconnect(): Promise<void>;
+    /** Register a handler for voice agent events. */
+    on<E extends VoiceAgentEvent>(event: E, handler: EventHandler<VoiceAgentEventMap[E]>): void;
+    /** Remove a handler. */
+    off<E extends VoiceAgentEvent>(event: E, handler: EventHandler<VoiceAgentEventMap[E]>): void;
+    private onData;
+    private send;
+    /** Send an instruction to the voice agent. */
+    instruct(msg: Omit<InstructionMessage, "type">): Promise<void>;
+    /** Add context to the voice agent's working memory. */
+    addContext(msg: Omit<ContextMessage, "type">): Promise<void>;
+    /** Notify the voice agent that a tool/action completed. */
+    sendActionResult(msg: Omit<ActionResultMessage, "type">): Promise<void>;
+    /** Switch the voice agent's operating mode. */
+    setMode(mode: AgentMode): Promise<void>;
+    /** Cancel the voice agent's pending response and replace it. */
+    override(msg: Omit<OverrideMessage, "type">): Promise<void>;
+}
+export {};
+//# sourceMappingURL=supervisor-client.d.ts.map

package/dist/supervisor-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-client.d.ts","sourceRoot":"","sources":["../src/supervisor-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EAEnB,eAAe,EAEhB,MAAM,eAAe,CAAC;AAQvB,KAAK,kBAAkB,GAAG;IACxB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,EAAE,cAAc,CAAC;CACzB,CAAC;AAEF,KAAK,eAAe,GAAG,MAAM,kBAAkB,CAAC;AAEhD,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAMxD,MAAM,WAAW,4BAA4B;IAC3C,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAoD;IACpE,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,4BAA4B;IAMjD,iDAAiD;IACjD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAID,mCAAmC;IAC7B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B,gCAAgC;IAC1B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC,iDAAiD;IACjD,EAAE,CAAC,CAAC,SAAS,eAAe,EAC1B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,YAAY,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,GAC3C,IAAI;IAMP,wBAAwB;IACxB,GAAG,CAAC,CAAC,SAAS,eAAe,EAC3B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,YAAY,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,GAC3C,IAAI;IAOP,OAAO,CAAC,MAAM;YAwBA,IAAI;IAQlB,8CAA8C;IACxC,QAAQ,CACZ,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC;IAIhB,uDAAuD;IACjD,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlE,2DAA2D;IACrD,gBAAgB,CACpB,GAAG,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,GACrC,OAAO,CAAC,IAAI,CAAC;IAIhB,+CAA+C;IACzC,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,gEAAgE;IAC1D,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlE"}

package/dist/supervisor-client.js

@@ -0,0 +1,123 @@
+/**
+ * StimmSupervisorClient — TypeScript supervisor for Node.js consumers.
+ *
+ * Connects to a LiveKit room as a data-only participant and provides
+ * a typed event-driven interface for receiving voice agent messages
+ * and sending instructions back.
+ *
+ * @example
+ * ```ts
+ * import { StimmSupervisorClient } from "@stimm/protocol";
+ *
+ * const client = new StimmSupervisorClient({
+ *   livekitUrl: "ws://localhost:7880",
+ *   token: supervisorToken,
+ * });
+ *
+ * client.on("transcript", async (msg) => {
+ *   if (!msg.partial) {
+ *     const result = await myAgent.process(msg.text);
+ *     await client.instruct({ text: result, speak: true, priority: "normal" });
+ *   }
+ * });
+ *
+ * await client.connect();
+ * ```
+ *
+ * @module
+ */
+import { Room, RoomEvent } from "livekit-client";
+import { STIMM_TOPIC } from "./messages.js";
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+export class StimmSupervisorClient {
+    room;
+    url;
+    token;
+    handlers = new Map();
+    _connected = false;
+    constructor(options) {
+        this.url = options.livekitUrl;
+        this.token = options.token;
+        this.room = new Room();
+    }
+    /** Whether the client is currently connected. */
+    get connected() {
+        return this._connected;
+    }
+    // -- Connection -----------------------------------------------------------
+    /** Connect to the LiveKit room. */
+    async connect() {
+        this.room.on(RoomEvent.DataReceived, this.onData.bind(this));
+        await this.room.connect(this.url, this.token);
+        this._connected = true;
+    }
+    /** Disconnect from the room. */
+    async disconnect() {
+        await this.room.disconnect();
+        this._connected = false;
+    }
+    // -- Receiving messages ---------------------------------------------------
+    /** Register a handler for voice agent events. */
+    on(event, handler) {
+        const list = this.handlers.get(event) ?? [];
+        list.push(handler);
+        this.handlers.set(event, list);
+    }
+    /** Remove a handler. */
+    off(event, handler) {
+        const list = this.handlers.get(event);
+        if (!list)
+            return;
+        const idx = list.indexOf(handler);
+        if (idx >= 0)
+            list.splice(idx, 1);
+    }
+    onData(payload, participant, kind, topic) {
+        if (topic !== STIMM_TOPIC)
+            return;
+        try {
+            const text = new TextDecoder().decode(payload);
+            const msg = JSON.parse(text);
+            const handlers = this.handlers.get(msg.type) ?? [];
+            for (const handler of handlers) {
+                Promise.resolve(handler(msg)).catch((err) => {
+                    console.error(`[stimm] Error in ${msg.type} handler:`, err);
+                });
+            }
+        }
+        catch (err) {
+            console.error("[stimm] Failed to deserialize message:", err);
+        }
+    }
+    // -- Sending messages to voice agent --------------------------------------
+    async send(msg) {
+        const payload = new TextEncoder().encode(JSON.stringify(msg));
+        await this.room.localParticipant.publishData(payload, {
+            topic: STIMM_TOPIC,
+            reliable: true,
+        });
+    }
+    /** Send an instruction to the voice agent. */
+    async instruct(msg) {
+        await this.send({ type: "instruction", ...msg });
+    }
+    /** Add context to the voice agent's working memory. */
+    async addContext(msg) {
+        await this.send({ type: "context", ...msg });
+    }
+    /** Notify the voice agent that a tool/action completed. */
+    async sendActionResult(msg) {
+        await this.send({ type: "action_result", ...msg });
+    }
+    /** Switch the voice agent's operating mode. */
+    async setMode(mode) {
+        await this.send({ type: "mode", mode });
+    }
+    /** Cancel the voice agent's pending response and replace it. */
+    async override(msg) {
+        await this.send({ type: "override", ...msg });
+    }
+}
+//# sourceMappingURL=supervisor-client.js.map

package/dist/supervisor-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-client.js","sourceRoot":"","sources":["../src/supervisor-client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@stimm/protocol",
+  "version": "0.1.0",
+  "description": "TypeScript types and supervisor client for Stimm dual-agent voice orchestration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "livekit-client": "^2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/etienne/stimm",
+    "directory": "packages/protocol-ts"
+  },
+  "keywords": [
+    "stimm",
+    "voice",
+    "livekit",
+    "dual-agent",
+    "protocol"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @stimm/protocol — TypeScript types and supervisor client
+ * for Stimm dual-agent voice orchestration.
+ *
+ * @packageDocumentation
+ */
+
+// Message types
+export type {
+  TranscriptMessage,
+  StateMessage,
+  BeforeSpeakMessage,
+  MetricsMessage,
+  InstructionMessage,
+  ContextMessage,
+  ActionResultMessage,
+  ModeMessage,
+  OverrideMessage,
+  AgentMode,
+  VoiceAgentMessage,
+  SupervisorMessage,
+  StimmMessage,
+} from "./messages.js";
+
+export { STIMM_TOPIC } from "./messages.js";
+
+// Supervisor client
+export {
+  StimmSupervisorClient,
+  type StimmSupervisorClientOptions,
+} from "./supervisor-client.js";

package/src/messages.ts

@@ -0,0 +1,115 @@
+/**
+ * Stimm Protocol — TypeScript message types.
+ *
+ * Mirror of the Python Pydantic models in `stimm.protocol`.
+ * All messages are exchanged as JSON over LiveKit reliable data channels.
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// Voice Agent → Supervisor
+// ---------------------------------------------------------------------------
+
+/** Real-time speech transcript from the voice agent's STT. */
+export interface TranscriptMessage {
+  type: "transcript";
+  /** Whether this is a partial (streaming) or final transcript. */
+  partial: boolean;
+  text: string;
+  timestamp: number;
+  confidence: number;
+}
+
+/** Voice agent state transition. */
+export interface StateMessage {
+  type: "state";
+  state: "listening" | "thinking" | "speaking";
+  timestamp: number;
+}
+
+/** Emitted before the voice agent sends text to TTS. */
+export interface BeforeSpeakMessage {
+  type: "before_speak";
+  text: string;
+  turn_id: string;
+}
+
+/** Per-turn latency metrics. */
+export interface MetricsMessage {
+  type: "metrics";
+  turn: number;
+  vad_ms: number;
+  stt_ms: number;
+  llm_ttft_ms: number;
+  tts_ttfb_ms: number;
+  total_ms: number;
+}
+
+// ---------------------------------------------------------------------------
+// Supervisor → Voice Agent
+// ---------------------------------------------------------------------------
+
+/** Voice agent operating mode. */
+export type AgentMode = "autonomous" | "relay" | "hybrid";
+
+/** Instruction for the voice agent to speak or incorporate. */
+export interface InstructionMessage {
+  type: "instruction";
+  text: string;
+  priority: "normal" | "interrupt";
+  speak: boolean;
+}
+
+/** Additional context for the voice agent's working memory. */
+export interface ContextMessage {
+  type: "context";
+  text: string;
+  append: boolean;
+}
+
+/** Notification that a tool/action completed in the supervisor. */
+export interface ActionResultMessage {
+  type: "action_result";
+  action: string;
+  status: string;
+  summary: string;
+}
+
+/** Switch the voice agent's operating mode. */
+export interface ModeMessage {
+  type: "mode";
+  mode: AgentMode;
+}
+
+/** Cancel the voice agent's pending response and replace it. */
+export interface OverrideMessage {
+  type: "override";
+  turn_id: string;
+  replacement: string;
+}
+
+// ---------------------------------------------------------------------------
+// Union types
+// ---------------------------------------------------------------------------
+
+/** Any message sent by the voice agent. */
+export type VoiceAgentMessage =
+  | TranscriptMessage
+  | StateMessage
+  | BeforeSpeakMessage
+  | MetricsMessage;
+
+/** Any message sent by the supervisor. */
+export type SupervisorMessage =
+  | InstructionMessage
+  | ContextMessage
+  | ActionResultMessage
+  | ModeMessage
+  | OverrideMessage;
+
+/** Any stimm protocol message. */
+export type StimmMessage = VoiceAgentMessage | SupervisorMessage;
+
+/** The LiveKit data channel topic used by stimm. */
+export const STIMM_TOPIC = "stimm";

package/src/supervisor-client.ts

@@ -0,0 +1,193 @@
+/**
+ * StimmSupervisorClient — TypeScript supervisor for Node.js consumers.
+ *
+ * Connects to a LiveKit room as a data-only participant and provides
+ * a typed event-driven interface for receiving voice agent messages
+ * and sending instructions back.
+ *
+ * @example
+ * ```ts
+ * import { StimmSupervisorClient } from "@stimm/protocol";
+ *
+ * const client = new StimmSupervisorClient({
+ *   livekitUrl: "ws://localhost:7880",
+ *   token: supervisorToken,
+ * });
+ *
+ * client.on("transcript", async (msg) => {
+ *   if (!msg.partial) {
+ *     const result = await myAgent.process(msg.text);
+ *     await client.instruct({ text: result, speak: true, priority: "normal" });
+ *   }
+ * });
+ *
+ * await client.connect();
+ * ```
+ *
+ * @module
+ */
+
+import { Room, DataPacket_Kind, RoomEvent } from "livekit-client";
+import type {
+  AgentMode,
+  TranscriptMessage,
+  StateMessage,
+  BeforeSpeakMessage,
+  MetricsMessage,
+  InstructionMessage,
+  ContextMessage,
+  ActionResultMessage,
+  ModeMessage,
+  OverrideMessage,
+  StimmMessage,
+} from "./messages.js";
+
+import { STIMM_TOPIC } from "./messages.js";
+
+// ---------------------------------------------------------------------------
+// Event types
+// ---------------------------------------------------------------------------
+
+type VoiceAgentEventMap = {
+  transcript: TranscriptMessage;
+  state: StateMessage;
+  before_speak: BeforeSpeakMessage;
+  metrics: MetricsMessage;
+};
+
+type VoiceAgentEvent = keyof VoiceAgentEventMap;
+
+type EventHandler<T> = (msg: T) => void | Promise<void>;
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface StimmSupervisorClientOptions {
+  /** LiveKit server WebSocket URL. */
+  livekitUrl: string;
+  /** Access token with data-channel permissions. */
+  token: string;
+}
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+export class StimmSupervisorClient {
+  private room: Room;
+  private url: string;
+  private token: string;
+  private handlers: Map<string, Array<EventHandler<any>>> = new Map();
+  private _connected = false;
+
+  constructor(options: StimmSupervisorClientOptions) {
+    this.url = options.livekitUrl;
+    this.token = options.token;
+    this.room = new Room();
+  }
+
+  /** Whether the client is currently connected. */
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  // -- Connection -----------------------------------------------------------
+
+  /** Connect to the LiveKit room. */
+  async connect(): Promise<void> {
+    this.room.on(RoomEvent.DataReceived, this.onData.bind(this));
+    await this.room.connect(this.url, this.token);
+    this._connected = true;
+  }
+
+  /** Disconnect from the room. */
+  async disconnect(): Promise<void> {
+    await this.room.disconnect();
+    this._connected = false;
+  }
+
+  // -- Receiving messages ---------------------------------------------------
+
+  /** Register a handler for voice agent events. */
+  on<E extends VoiceAgentEvent>(
+    event: E,
+    handler: EventHandler<VoiceAgentEventMap[E]>,
+  ): void {
+    const list = this.handlers.get(event) ?? [];
+    list.push(handler as EventHandler<any>);
+    this.handlers.set(event, list);
+  }
+
+  /** Remove a handler. */
+  off<E extends VoiceAgentEvent>(
+    event: E,
+    handler: EventHandler<VoiceAgentEventMap[E]>,
+  ): void {
+    const list = this.handlers.get(event);
+    if (!list) return;
+    const idx = list.indexOf(handler as EventHandler<any>);
+    if (idx >= 0) list.splice(idx, 1);
+  }
+
+  private onData(
+    payload: Uint8Array,
+    participant?: unknown,
+    kind?: DataPacket_Kind,
+    topic?: string,
+  ): void {
+    if (topic !== STIMM_TOPIC) return;
+
+    try {
+      const text = new TextDecoder().decode(payload);
+      const msg = JSON.parse(text) as StimmMessage;
+      const handlers = this.handlers.get(msg.type) ?? [];
+      for (const handler of handlers) {
+        Promise.resolve(handler(msg)).catch((err) => {
+          console.error(`[stimm] Error in ${msg.type} handler:`, err);
+        });
+      }
+    } catch (err) {
+      console.error("[stimm] Failed to deserialize message:", err);
+    }
+  }
+
+  // -- Sending messages to voice agent --------------------------------------
+
+  private async send(msg: Record<string, unknown>): Promise<void> {
+    const payload = new TextEncoder().encode(JSON.stringify(msg));
+    await this.room.localParticipant.publishData(payload, {
+      topic: STIMM_TOPIC,
+      reliable: true,
+    });
+  }
+
+  /** Send an instruction to the voice agent. */
+  async instruct(
+    msg: Omit<InstructionMessage, "type">,
+  ): Promise<void> {
+    await this.send({ type: "instruction", ...msg });
+  }
+
+  /** Add context to the voice agent's working memory. */
+  async addContext(msg: Omit<ContextMessage, "type">): Promise<void> {
+    await this.send({ type: "context", ...msg });
+  }
+
+  /** Notify the voice agent that a tool/action completed. */
+  async sendActionResult(
+    msg: Omit<ActionResultMessage, "type">,
+  ): Promise<void> {
+    await this.send({ type: "action_result", ...msg });
+  }
+
+  /** Switch the voice agent's operating mode. */
+  async setMode(mode: AgentMode): Promise<void> {
+    await this.send({ type: "mode", mode });
+  }
+
+  /** Cancel the voice agent's pending response and replace it. */
+  async override(msg: Omit<OverrideMessage, "type">): Promise<void> {
+    await this.send({ type: "override", ...msg });
+  }
+}