@cairnvibe/sdk 0.1.0

package/dist/key-rotator.d.ts

@@ -0,0 +1,7 @@
+export declare class KeyRotator {
+    private keys;
+    private next;
+    constructor(keys: string[]);
+    static fromEnvList(value: string | undefined): KeyRotator | null;
+    take(): string;
+}

package/dist/key-rotator.js

@@ -0,0 +1,31 @@
+"use strict";
+// Round-robins across a comma-separated list of API keys (e.g. `GROQ_API_KEYS`)
+// so runtime verb calls spread across several free-tier rate limits instead
+// of hammering a single key. Mirrors packages/indexer/src/key-rotator.ts —
+// small enough that duplicating it beats adding a shared package for it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyRotator = void 0;
+class KeyRotator {
+    keys;
+    next = 0;
+    constructor(keys) {
+        if (keys.length === 0)
+            throw new Error("KeyRotator: at least one key is required");
+        this.keys = keys;
+    }
+    static fromEnvList(value) {
+        if (!value)
+            return null;
+        const keys = value
+            .split(",")
+            .map((k) => k.trim())
+            .filter(Boolean);
+        return keys.length > 0 ? new KeyRotator(keys) : null;
+    }
+    take() {
+        const key = this.keys[this.next % this.keys.length];
+        this.next += 1;
+        return key;
+    }
+}
+exports.KeyRotator = KeyRotator;

package/dist/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/realtime-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/realtime-cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// `cairn-realtime` — zero-code way to run the realtime voice relay
+// alongside `next dev`, configured entirely through env vars (matching how
+// `cairn build` already works) plus an optional `--port` flag.
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const core_1 = require("@cairnvibe/core");
+const realtime_server_1 = require("./realtime-server");
+function parseCapability(raw) {
+    if (raw === "explain" || raw === "guide" || raw === "act")
+        return raw;
+    return "act";
+}
+function parsePortFlag(argv) {
+    const idx = argv.indexOf("--port");
+    if (idx === -1)
+        return undefined;
+    const value = Number(argv[idx + 1]);
+    return Number.isFinite(value) ? value : undefined;
+}
+function main() {
+    const manifestPath = node_path_1.default.join(process.cwd(), "ui-manifest.json");
+    if (!node_fs_1.default.existsSync(manifestPath)) {
+        console.error(`cairn-realtime: no ${manifestPath} — run \`cairn build\` first.`);
+        process.exit(1);
+    }
+    const manifest = core_1.ManifestSchema.parse(JSON.parse(node_fs_1.default.readFileSync(manifestPath, "utf8")));
+    const deepgramApiKey = process.env.DEEPGRAM_API_KEY;
+    if (!deepgramApiKey) {
+        console.error("cairn-realtime: DEEPGRAM_API_KEY is not set.");
+        process.exit(1);
+    }
+    const provider = process.env.CAIRN_RUNTIME_PROVIDER === "anthropic" ? "anthropic" : "groq";
+    if (provider === "anthropic" && !process.env.ANTHROPIC_API_KEY) {
+        console.error("cairn-realtime: ANTHROPIC_API_KEY is not set (CAIRN_RUNTIME_PROVIDER=anthropic).");
+        process.exit(1);
+    }
+    if (provider === "groq" && !process.env.GROQ_API_KEYS) {
+        console.error("cairn-realtime: GROQ_API_KEYS is not set (comma-separated).");
+        process.exit(1);
+    }
+    const registeredActions = (process.env.CAIRN_REGISTERED_ACTIONS ?? "")
+        .split(",")
+        .map((a) => a.trim())
+        .filter(Boolean);
+    const port = parsePortFlag(process.argv.slice(2)) ?? Number(process.env.CAIRN_REALTIME_PORT ?? 3010);
+    const capability = parseCapability(process.env.CAIRN_CAPABILITY);
+    const persona = process.env.CAIRN_PERSONA || undefined;
+    const server = (0, realtime_server_1.createRealtimeServer)({ manifest, provider, deepgramApiKey, registeredActions, capability, persona });
+    server.listen(port, () => {
+        console.error(`cairn-realtime: listening on ws://localhost:${port} (provider: ${provider})`);
+    });
+}
+main();

package/dist/realtime-server.d.ts

@@ -0,0 +1,10 @@
+import http from "node:http";
+import type { Manifest } from "@cairnvibe/core";
+import { type CreateCopilotHandlerOptions } from "./server";
+export interface CreateRealtimeServerOptions extends CreateCopilotHandlerOptions {
+    manifest: Manifest;
+    deepgramApiKey: string;
+    sttModel?: string;
+    ttsVoice?: string;
+}
+export declare function createRealtimeServer(options: CreateRealtimeServerOptions): http.Server;

package/dist/realtime-server.js

@@ -0,0 +1,291 @@
+"use strict";
+// A real-time voice relay: browser <-> this server <-> Deepgram live STT,
+// resolving a verb (via the same core the HTTP handler uses) on every
+// finalized utterance, then streaming synthesized speech back as it's
+// rendered — not after it's fully rendered.
+//
+// Runs as its OWN process (via realtime-cli.ts / `cairn-realtime`), separate
+// from the consumer's Next.js server — a plain WebSocket relay, nothing
+// Next-specific about it. The Deepgram API key never leaves this process.
+//
+// Verified live before building this: a Node script opened
+// wss://api.deepgram.com/v1/listen with a plain (non-scoped) API key,
+// streamed real 16kHz PCM audio, and got back interim + final transcripts.
+// True client-to-Deepgram streaming needs a short-lived scoped key this
+// account can't mint (no keys:write scope) — this relay sidesteps that
+// entirely by keeping the real key server-side, which is the more secure
+// shape anyway.
+//
+// TTS is Deepgram's streaming Speak WebSocket (see tts-stream.ts), not the
+// one-shot REST /v1/speak call this used to be — that REST call forced
+// waiting for an entire MP3 to render AND download before playing a single
+// byte, which was the actual cause of "the agent takes 5-10s to speak." One
+// connection is opened per client and reused for every turn in the session
+// (a fresh handshake per turn costs a real, measurable chunk of that latency
+// on its own). Pattern verified against a real, working implementation of
+// exactly this shape (a prior voice-agent project of the author's, VOXERA —
+// its lib/deepgram/tts-stream.ts and server.ts) before building this.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRealtimeServer = createRealtimeServer;
+const node_http_1 = __importDefault(require("node:http"));
+const ws_1 = require("ws");
+const server_1 = require("./server");
+const tts_stream_1 = require("./tts-stream");
+const DEEPGRAM_LIVE_URL = "wss://api.deepgram.com/v1/listen";
+const DEFAULT_STT_MODEL = "nova-2";
+const DEFAULT_TTS_VOICE = "aura-2-thalia-en";
+// Not constrained by any telephony 8kHz requirement — this is just "what
+// quality does Deepgram render at" for browser playback, and the Web Audio
+// API resamples an AudioBuffer at any declared rate transparently.
+const TTS_SAMPLE_RATE = 24000;
+function createRealtimeServer(options) {
+    const registeredActions = options.registeredActions ?? [];
+    const capability = options.capability ?? "act";
+    const llm = (0, server_1.createVerbLLM)(options);
+    // "text" is optional on highlight/open/navigate/do in the base prompt —
+    // fine for the typed/HTTP path, which always has a visible answer area,
+    // but silence reads as broken in a live voice conversation (the client
+    // still recovers correctly either way, via turn_complete below). The
+    // instruction asks for a confirmation grounded in what was actually
+    // done, not filler — generic phrasing here is what made replies feel
+    // "unrelated" to the question that was just asked.
+    const systemPrompt = (0, server_1.buildSystemPrompt)(options.manifest, registeredActions, options.persona) +
+        `\n\nYou are in a live voice conversation right now — the user is speaking out loud and may not be looking at the screen. For highlight/open/navigate/do, include a short spoken "text" that names the specific thing you're pointing at or the specific place you're sending them (e.g. "Highlighting the New Invoice button" or "Taking you to Invoices"), not a generic filler phrase — so they hear a confirmation that's actually about their question.`;
+    const sttModel = options.sttModel ?? process.env.DEEPGRAM_MODEL ?? DEFAULT_STT_MODEL;
+    const ttsVoice = options.ttsVoice ?? process.env.DEEPGRAM_VOICE ?? DEFAULT_TTS_VOICE;
+    const deepgramApiKey = options.deepgramApiKey;
+    const httpServer = node_http_1.default.createServer((_req, res) => {
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end("cairn realtime relay\n");
+    });
+    const wss = new ws_1.WebSocketServer({ server: httpServer });
+    wss.on("connection", (client) => {
+        handleConnection(client, { deepgramApiKey, sttModel, ttsVoice, llm, systemPrompt, registeredActions, capability }).catch((err) => {
+            console.error("[cairn realtime] connection error:", err);
+            safeSend(client, { type: "error", message: "internal error" });
+            client.close();
+        });
+    });
+    return httpServer;
+}
+const MAX_HISTORY_TURNS = 8; // 4 exchanges — enough for "the first one"/"do that instead" without growing the prompt unbounded over a long call
+async function handleConnection(client, deps) {
+    let context = { route: "/", visible: [] };
+    // Unlike the stateless HTTP path (which needs the client to resend
+    // history every request), a realtime connection is already stateful —
+    // one WebSocket per call — so this is accumulated here directly rather
+    // than round-tripped through the client.
+    const history = [];
+    const dgUrl = `${DEEPGRAM_LIVE_URL}?model=${encodeURIComponent(deps.sttModel)}` +
+        `&encoding=linear16&sample_rate=16000&channels=1&interim_results=true&endpointing=300&utterance_end_ms=1000`;
+    const dg = new ws_1.WebSocket(dgUrl, { headers: { Authorization: `Token ${deps.deepgramApiKey}` } });
+    let dgOpen = false;
+    const pendingAudio = [];
+    dg.on("open", () => {
+        dgOpen = true;
+        for (const chunk of pendingAudio.splice(0))
+            dg.send(chunk);
+    });
+    // ONE Speak connection reused for every turn in this session — a fresh
+    // handshake per turn is a real, measurable chunk of the latency this
+    // rewrite exists to remove. Recreated on demand if it ever drops.
+    let speakStream = null;
+    let speakStreamReady = null;
+    // Resolves the in-flight speakStreamed() call for the current turn once
+    // Deepgram confirms (via "Flushed") that every chunk for this turn's
+    // Flush has actually been sent — the real "no more audio coming" signal,
+    // not a fixed timeout. Bound once at stream creation (Deepgram fires one
+    // Flushed per Flush call), rebound per-turn as each new call starts.
+    let onCurrentTurnFlushed = null;
+    // Bumped on barge-in — any audio_chunk/speaking_end belonging to an
+    // earlier generation is dropped instead of sent, so a chunk that was
+    // already in flight over the network when the user interrupted can't
+    // sneak back in and resume playback after the client already moved on.
+    let generation = 0;
+    function ensureSpeakStream() {
+        if (!speakStream) {
+            const stream = new tts_stream_1.DeepgramSpeakStream({ apiKey: deps.deepgramApiKey, model: deps.ttsVoice, encoding: "linear16", sampleRate: TTS_SAMPLE_RATE }, () => { }, // rebound per-turn via setAudioHandler before each use
+            { onFlushed: () => onCurrentTurnFlushed?.() });
+            speakStream = stream;
+            speakStreamReady = stream.connect().catch((err) => {
+                console.error("[cairn realtime] Speak stream connect failed:", err);
+                speakStream = null;
+                speakStreamReady = null;
+            });
+        }
+        return { stream: speakStream, ready: speakStreamReady };
+    }
+    // Discards whatever the current turn is still synthesizing/sending, and
+    // unsticks a pending speakStreamed() call if one is in flight — Deepgram's
+    // "Clear" isn't guaranteed to itself trigger a "Flushed" confirmation, so
+    // without this the interrupted call's promise would hang forever.
+    function triggerServerBargeIn() {
+        generation++;
+        speakStream?.clear();
+        onCurrentTurnFlushed?.();
+    }
+    async function speakStreamed(text) {
+        const myGeneration = generation;
+        const { stream, ready } = ensureSpeakStream();
+        stream.setAudioHandler((chunk) => {
+            if (myGeneration !== generation)
+                return; // stale — dropped by barge-in
+            safeSend(client, { type: "audio_chunk", audio: chunk.toString("base64"), sampleRate: TTS_SAMPLE_RATE });
+        });
+        await ready;
+        if (!speakStream || myGeneration !== generation) {
+            // Reconnect failed, or barge-in happened before the stream connected —
+            // either way, only degrade to turn_complete if this is still current.
+            if (myGeneration === generation)
+                safeSend(client, { type: "turn_complete" });
+            return;
+        }
+        await new Promise((resolve) => {
+            onCurrentTurnFlushed = () => {
+                onCurrentTurnFlushed = null;
+                if (myGeneration === generation)
+                    safeSend(client, { type: "speaking_end" });
+                resolve();
+            };
+            safeSend(client, { type: "speaking_start" });
+            stream.sendText(text);
+            stream.flush();
+        });
+    }
+    dg.on("message", (data) => {
+        void handleDeepgramMessage(data.toString(), client, deps, () => context, speakStreamed, history);
+    });
+    dg.on("error", (err) => {
+        console.error("[cairn realtime] Deepgram STT connection error:", err);
+        safeSend(client, { type: "error", message: "speech recognition unavailable" });
+    });
+    client.on("message", (data, isBinary) => {
+        if (isBinary) {
+            const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+            if (dgOpen)
+                dg.send(buf);
+            else
+                pendingAudio.push(buf);
+            return;
+        }
+        try {
+            const msg = JSON.parse(data.toString());
+            if (msg.type === "context") {
+                context = { route: String(msg.route ?? "/"), visible: Array.isArray(msg.visible) ? msg.visible : [] };
+            }
+            else if (msg.type === "end") {
+                client.close();
+            }
+            else if (msg.type === "barge_in") {
+                triggerServerBargeIn();
+            }
+            else if (msg.type === "speak" && typeof msg.text === "string" && msg.text.trim()) {
+                // A "tour" step being narrated while a realtime session is already
+                // open — reuses the exact same streaming Speak connection and
+                // audio_chunk protocol as a conversational reply, instead of the
+                // client falling back to a separate buffered REST call. No STT/verb
+                // resolution involved; the client already resolved the tour steps
+                // itself and just needs this text spoken.
+                void speakStreamed(msg.text);
+            }
+        }
+        catch {
+            // Ignore malformed control messages — never crash the relay on bad client input.
+        }
+    });
+    client.on("close", () => {
+        try {
+            dg.close();
+        }
+        catch {
+            // already closed
+        }
+        speakStream?.close();
+    });
+}
+async function handleDeepgramMessage(raw, client, deps, getContext, speakStreamed, history) {
+    let msg;
+    try {
+        msg = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    if (msg.type !== "Results")
+        return;
+    const transcript = msg.channel?.alternatives?.[0]?.transcript;
+    if (!transcript)
+        return;
+    if (!msg.is_final) {
+        safeSend(client, { type: "interim", text: transcript });
+        return;
+    }
+    safeSend(client, { type: "final", text: transcript });
+    // Everything from here on (the LLM call, TTS streaming) can fail in ways
+    // that have nothing to do with a malformed message — a flaky provider
+    // call, a rate limit, a dropped upstream connection. This whole function
+    // is invoked fire-and-forget (`void handleDeepgramMessage(...)`), so an
+    // uncaught throw here previously vanished into an unhandled rejection:
+    // the client had already been told "final" (entering its "thinking"
+    // state) and then simply never heard from the server again for this
+    // turn — stuck indefinitely with the mic never resuming. Every path out
+    // of this try block now sends the client something that ends the turn.
+    try {
+        const { route, visible } = getContext();
+        const verb = await (0, server_1.resolveVerb)(deps.llm, deps.systemPrompt, deps.registeredActions, deps.capability, {
+            route,
+            question: transcript,
+            visible,
+            history,
+        });
+        // Sent immediately — before speech synthesis even starts — so
+        // highlight/navigate/do execute in the browser right away instead of
+        // waiting on audio. The agent visibly acts while it's still about to
+        // speak, not after.
+        safeSend(client, { type: "verb", verb });
+        history.push({ role: "user", text: transcript }, { role: "assistant", text: summarizeVerbForHistory(verb) });
+        history.splice(0, Math.max(0, history.length - MAX_HISTORY_TURNS));
+        // A verb with no spoken text (highlight/navigate/do often have none)
+        // still needs to unstick the client's "thinking" state and let the mic
+        // resume — turn_complete covers that with no audio path involved.
+        if ("text" in verb && verb.text) {
+            await speakStreamed(verb.text);
+        }
+        else {
+            safeSend(client, { type: "turn_complete" });
+        }
+    }
+    catch (err) {
+        console.error("[cairn realtime] failed to resolve/speak this turn:", err);
+        safeSend(client, { type: "error", message: "Something went wrong answering that — try again." });
+        safeSend(client, { type: "turn_complete" });
+    }
+}
+function safeSend(client, message) {
+    if (client.readyState !== ws_1.WebSocket.OPEN)
+        return;
+    client.send(JSON.stringify(message));
+}
+/** A short text form of any verb for the history log — not shown to the
+ * user, just fed back to the model on later turns so it knows what it
+ * already did/said. */
+function summarizeVerbForHistory(verb) {
+    if ("text" in verb && verb.text)
+        return verb.text;
+    switch (verb.verb) {
+        case "highlight":
+        case "open":
+            return `(highlighted ${verb.target})`;
+        case "navigate":
+            return `(navigated to ${verb.route})`;
+        case "do":
+            return `(ran ${verb.action}${verb.target ? ` on ${verb.target}` : ""})`;
+        case "tour":
+            return verb.steps.map((s) => s.text).join(" ");
+        default:
+            return "(no response)";
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,95 @@
+import { type HistoryTurn, type Manifest, type VerbResponse } from "@cairnvibe/core";
+import { KeyRotator } from "./key-rotator";
+/**
+ * What the agent is allowed to do, independent of which specific "do"
+ * actions are registered:
+ * - explain: only explain/highlight — can talk and point, never moves the user or clicks anything.
+ * - guide: adds open/navigate — can move the user around the app, still never triggers a real action.
+ * - act: everything, including "do" (still gated per-action by `registeredActions`).
+ * Defaults to "act" so existing deployments that only set `registeredActions` keep working unchanged.
+ */
+export type CapabilityTier = "explain" | "guide" | "act";
+export interface CreateCopilotHandlerOptions {
+    provider?: "anthropic" | "groq";
+    /** Single API key. For groq, prefer `apiKeys` to round-robin; falls back to GROQ_API_KEYS env. */
+    apiKey?: string;
+    apiKeys?: string[];
+    model?: string;
+    /** Action ids this deployment actually supports. "do" is refused for anything else. */
+    registeredActions?: string[];
+    /** What the agent is allowed to do at all. Defaults to "act". See `CapabilityTier`. */
+    capability?: CapabilityTier;
+    /** Display name / identity for the agent, woven into its system prompt and shown in the widget. Defaults to "Cairn". */
+    persona?: string;
+}
+export interface CopilotHandlerResult {
+    status: number;
+    body: VerbResponse | {
+        error: string;
+    };
+}
+export type CopilotHandler = (body: unknown) => Promise<CopilotHandlerResult>;
+/** Minimal shape the handler needs from an Anthropic client — narrow enough to fake in tests. */
+export interface MessagesClient {
+    messages: {
+        create: (params: any) => Promise<{
+            content: unknown[];
+        }>;
+    };
+}
+/**
+ * Provider-neutral boundary the handler talks to. `respond` returns the raw
+ * parsed tool-call payload (or undefined/null if the model didn't produce
+ * one) — the handler is the only place that validates it against
+ * `VerbResponseSchema`, so every provider is held to the exact same contract.
+ */
+export interface VerbLLM {
+    respond(systemPrompt: string, userMessage: string): Promise<unknown>;
+}
+export declare function createCopilotHandler(manifest: Manifest, options?: CreateCopilotHandlerOptions): CopilotHandler;
+/** Same as `createCopilotHandler`, but with the LLM injected — used by tests to fake it. */
+export declare function createCopilotHandlerWithLLM(manifest: Manifest, llm: VerbLLM, options?: {
+    registeredActions?: string[];
+    capability?: CapabilityTier;
+    persona?: string;
+}): CopilotHandler;
+/**
+ * The safety-critical core, shared by the HTTP handler above and the
+ * realtime relay (realtime-server.ts) — one place validates every LLM
+ * response against the fixed verb schema and the registered-actions
+ * allowlist, regardless of which transport the question arrived on.
+ */
+export declare function resolveVerb(llm: VerbLLM, systemPrompt: string, registeredActions: string[], capability: CapabilityTier, input: {
+    route: string;
+    question: string;
+    visible: string[];
+    history?: HistoryTurn[];
+}): Promise<VerbResponse>;
+/** Builds the provider-appropriate VerbLLM from the same options createCopilotHandler accepts — reused by the realtime relay. */
+export declare function createVerbLLM(options?: CreateCopilotHandlerOptions): VerbLLM;
+export declare class AnthropicVerbLLM implements VerbLLM {
+    private client;
+    private model;
+    private toolSchema;
+    constructor(client: MessagesClient, model: string, toolSchema: Record<string, unknown>);
+    respond(systemPrompt: string, userMessage: string): Promise<unknown>;
+}
+/** Minimal shape GroqVerbLLM needs — narrow enough to fake in tests. */
+export interface GroqLikeClient {
+    chat: {
+        completions: {
+            create: (params: any) => Promise<{
+                choices: any[];
+            }>;
+        };
+    };
+}
+export declare class GroqVerbLLM implements VerbLLM {
+    private keys;
+    private model;
+    private toolSchema;
+    private clientFactory;
+    constructor(keys: KeyRotator, model: string, toolSchema: Record<string, unknown>, clientFactory?: (apiKey: string) => GroqLikeClient);
+    respond(systemPrompt: string, userMessage: string): Promise<unknown>;
+}
+export declare function buildSystemPrompt(manifest: Manifest, registeredActions: string[], persona?: string): string;