@cairnvibe/sdk 0.2.13 → 0.3.0

package/dist/skill-store.d.ts

@@ -0,0 +1,17 @@
+import Database from "better-sqlite3";
+import type { Skill, SkillSummary } from "@cairnvibe/core";
+export interface SkillStore {
+    /** Upserts by (scopeId, id) — a re-learned Skill for the same real capability replaces the old one, never accumulates duplicates. */
+    saveSkill(scopeId: string, skill: Skill): void;
+    /** Cheap: id/name/description/pattern only, never the full instructions — see this file's own doc comment. */
+    listSkillSummaries(scopeId: string): SkillSummary[];
+    /** The one Skill a caller actually matched — full instructions included. Null if this scope has no Skill with that id. */
+    getSkill(scopeId: string, id: string): Skill | null;
+}
+/**
+ * @param target Either a file path (opened/created, parent dir made if
+ * needed) or an already-open better-sqlite3 `Database` — pass an open
+ * connection to share it with your own tables (or memory-sqlite.ts's own
+ * store) instead of opening a second file.
+ */
+export declare function createSqliteSkillStore(target: string | Database.Database): SkillStore;

package/dist/skill-store.js

@@ -0,0 +1,78 @@
+"use strict";
+// Architecture Pillar 3 (Skill half) — real, persistent storage for
+// self-authored Skills (packages/core/src/skills.ts), scoped by whatever
+// opaque `scopeId` string the caller passes — same discipline as
+// memory-sqlite.ts's own MemoryStore, but for a DIFFERENT axis of scope on
+// purpose: a MemoryStore scopeId is per-user/session (today's usage,
+// unchanged), while a SkillStore scopeId is meant to be per-DEPLOYMENT
+// (the whole app, shared across every user who talks to it — the same
+// scope ui-manifest.json itself already has). Nothing in this file
+// enforces that distinction; it's the caller's own choice of scopeId that
+// makes it true, exactly as MemoryStore's own doc comment already
+// establishes for its scope.
+//
+// A dedicated table (not reusing memory-sqlite's facts table with a
+// JSON-blob value) specifically so `listSkillSummaries` can select just
+// id/name/description/pattern at the SQL level — the real mechanism
+// behind "progressive disclosure stays cheap": a deployment with many
+// learned Skills never pays to load every Skill's full instructions just
+// to list what's available, only the one a caller actually requests via
+// getSkill.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSqliteSkillStore = createSqliteSkillStore;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const SKILLS_TABLE = "cairn_skills";
+/**
+ * @param target Either a file path (opened/created, parent dir made if
+ * needed) or an already-open better-sqlite3 `Database` — pass an open
+ * connection to share it with your own tables (or memory-sqlite.ts's own
+ * store) instead of opening a second file.
+ */
+function createSqliteSkillStore(target) {
+    const db = typeof target === "string" ? openFile(target) : target;
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS ${SKILLS_TABLE} (
+      scope_id TEXT NOT NULL,
+      id TEXT NOT NULL,
+      name TEXT NOT NULL,
+      description TEXT NOT NULL,
+      instructions TEXT NOT NULL,
+      pattern TEXT,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY (scope_id, id)
+    )
+  `);
+    const upsertSkill = db.prepare(`
+    INSERT INTO ${SKILLS_TABLE} (scope_id, id, name, description, instructions, pattern, created_at)
+    VALUES (@scopeId, @id, @name, @description, @instructions, @pattern, @createdAt)
+    ON CONFLICT(scope_id, id) DO UPDATE SET
+      name = excluded.name, description = excluded.description, instructions = excluded.instructions,
+      pattern = excluded.pattern, created_at = excluded.created_at
+  `);
+    const selectSummaries = db.prepare(`SELECT id, name, description, pattern FROM ${SKILLS_TABLE} WHERE scope_id = ?`);
+    const selectSkill = db.prepare(`SELECT id, name, description, instructions, pattern, created_at FROM ${SKILLS_TABLE} WHERE scope_id = ? AND id = ?`);
+    return {
+        saveSkill(scopeId, skill) {
+            upsertSkill.run({ scopeId, id: skill.id, name: skill.name, description: skill.description, instructions: skill.instructions, pattern: skill.pattern ?? null, createdAt: skill.createdAt });
+        },
+        listSkillSummaries(scopeId) {
+            const rows = selectSummaries.all(scopeId);
+            return rows.map((r) => ({ id: r.id, name: r.name, description: r.description, pattern: r.pattern ?? undefined }));
+        },
+        getSkill(scopeId, id) {
+            const row = selectSkill.get(scopeId, id);
+            if (!row)
+                return null;
+            return { id: row.id, name: row.name, description: row.description, instructions: row.instructions, pattern: row.pattern ?? undefined, createdAt: row.created_at };
+        },
+    };
+}
+function openFile(filePath) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+    return new better_sqlite3_1.default(filePath);
+}

package/dist/tts-stream.d.ts

@@ -1,3 +1,28 @@
+/**
+ * Phase 2 step 1 — the sentence-boundary detector behind true "LLM tokens
+ * streamed straight into TTS." `sendText`/`flush` below already support
+ * being called many times per turn (queue more, render what's queued so
+ * far) — the missing piece was WHEN to flush a growing buffer of
+ * streamed LLM text so audio starts before the whole answer finishes
+ * generating, without cutting off mid-word or (the real trap) mid-number
+ * ("3." from "3.5 dollars").
+ *
+ * Deliberately simple: a period/!/? followed by REAL whitespace that has
+ * already arrived — never a boundary at the current end of the buffer,
+ * even if it looks sentence-final ("...3." with nothing after it yet),
+ * because more streamed text (".5 dollars") could still be on the way.
+ * The caller flushes whatever's left in the buffer once the LLM stream
+ * itself ends, regardless of trailing punctuation — real content is
+ * never silently dropped, just possibly not maximally chunked. This is
+ * a real, accepted simplification, not NLP-grade sentence detection: an
+ * abbreviation like "Mr. Smith" flushes one beat early. That costs a
+ * little TTS naturalness, never correctness — nothing in the text is
+ * lost or reordered.
+ */
+export declare function splitFlushableSentences(buffer: string): {
+    toFlush: string;
+    remainder: string;
+};
 export type SpeakChunkCallback = (audio: Buffer) => void;
 export interface DeepgramSpeakStreamOptions {
     apiKey: string;

package/dist/tts-stream.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeepgramSpeakStream = void 0;
+exports.splitFlushableSentences = splitFlushableSentences;
 // Streaming Deepgram Aura TTS client — a persistent WebSocket against
 // `wss://api.deepgram.com/v1/speak`, kept open for a whole realtime session
 // instead of one REST POST per turn (that REST round trip is what made the
@@ -22,6 +23,37 @@ exports.DeepgramSpeakStream = void 0;
 //   <- {"type":"Warning"/"Metadata"}    informational, non-fatal
 const ws_1 = require("ws");
 const DEEPGRAM_SPEAK_WS_URL = "wss://api.deepgram.com/v1/speak";
+/**
+ * Phase 2 step 1 — the sentence-boundary detector behind true "LLM tokens
+ * streamed straight into TTS." `sendText`/`flush` below already support
+ * being called many times per turn (queue more, render what's queued so
+ * far) — the missing piece was WHEN to flush a growing buffer of
+ * streamed LLM text so audio starts before the whole answer finishes
+ * generating, without cutting off mid-word or (the real trap) mid-number
+ * ("3." from "3.5 dollars").
+ *
+ * Deliberately simple: a period/!/? followed by REAL whitespace that has
+ * already arrived — never a boundary at the current end of the buffer,
+ * even if it looks sentence-final ("...3." with nothing after it yet),
+ * because more streamed text (".5 dollars") could still be on the way.
+ * The caller flushes whatever's left in the buffer once the LLM stream
+ * itself ends, regardless of trailing punctuation — real content is
+ * never silently dropped, just possibly not maximally chunked. This is
+ * a real, accepted simplification, not NLP-grade sentence detection: an
+ * abbreviation like "Mr. Smith" flushes one beat early. That costs a
+ * little TTS naturalness, never correctness — nothing in the text is
+ * lost or reordered.
+ */
+function splitFlushableSentences(buffer) {
+    const re = /[.!?]\s+/g;
+    let lastEnd = -1;
+    let m;
+    while ((m = re.exec(buffer)) !== null)
+        lastEnd = re.lastIndex;
+    if (lastEnd === -1)
+        return { toFlush: "", remainder: buffer };
+    return { toFlush: buffer.slice(0, lastEnd).trimEnd(), remainder: buffer.slice(lastEnd) };
+}
 class DeepgramSpeakStream {
     ws = null;
     opts;

package/dist/vad.d.ts

@@ -0,0 +1,27 @@
+export interface VadFrameResult {
+    isSpeech: boolean;
+    rms: number;
+    zcr: number;
+    noiseFloor: number;
+}
+export interface VadDetector {
+    process(samples: Float32Array): VadFrameResult;
+    reset(): void;
+}
+export declare function computeRms(samples: Float32Array): number;
+export declare function computeZcr(samples: Float32Array): number;
+export declare function createVadDetector(): VadDetector;
+export interface BargeInGate {
+    /** Feed one frame's VAD classification plus that frame's real duration
+     * (samples.length / sampleRate * 1000 — NOT assumed, since sample rate
+     * varies by device/browser). Returns true the instant accumulated
+     * consecutive speech crosses the minimum-duration threshold — fires
+     * exactly once per sustained speech onset. Any non-speech frame resets
+     * the accumulator immediately, so a genuine interruption still cuts in
+     * well under half a second, while an isolated noise burst (which
+     * essentially never sustains across consecutive frames) never fires at
+     * all. */
+    update(frame: VadFrameResult, frameDurationMs: number): boolean;
+    reset(): void;
+}
+export declare function createBargeInGate(minSpeechMs?: number): BargeInGate;

package/dist/vad.js

@@ -0,0 +1,128 @@
+"use strict";
+// A lightweight, dependency-free voice-activity heuristic for client-side
+// barge-in detection — replaces a bare RMS-amplitude threshold with a
+// two-feature (energy + zero-crossing rate) gate plus an adaptive ambient
+// noise floor, entirely in plain JS math over the same Float32Array PCM
+// samples the ScriptProcessorNode already delivers. No model, no WASM, no
+// added bundle weight — the real alternative to a neural VAD (e.g. Silero)
+// this session's own research flagged as carrying a genuine ~1-2MB/
+// 20-30x bundle-size cost for a widget meant to drop into a third-party
+// page (see DEVELOPMENT.md, Phase 2 step 2's Pending section) — this
+// avoids that tradeoff entirely rather than deciding it.
+//
+// Energy alone (the prior BARGE_IN_RMS_THRESHOLD design) fires on ANY
+// loud sound — a cough, a door slam, background music, a raised-volume
+// TV. Zero-crossing rate distinguishes broadly speech-plausible content
+// (voiced pitch + its harmonics, unvoiced fricatives) from the two
+// extremes most likely to false-trigger a bare energy gate: a low-
+// frequency hum/rumble (near-zero ZCR) and broadband hiss/static-like
+// noise (ZCR near its ceiling). The ZCR band below is deliberately wide
+// — it only rejects those two extremes, not a precise speech classifier
+// — and, like the original RMS threshold, is not calibrated against real
+// hardware in this environment (no live mic here); a reasonable starting
+// point, not a tuned production value.
+//
+// The adaptive noise floor is the other real improvement over a flat
+// threshold: instead of one fixed absolute RMS cutoff, the energy gate
+// tracks a slow-moving estimate of the room's own ambient level (updated
+// only on frames NOT classified as speech) and requires real speech to
+// clear a multiple of it — a noisy room raises the bar automatically
+// instead of the old constant threshold false-triggering on ambient
+// noise all the time.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRms = computeRms;
+exports.computeZcr = computeZcr;
+exports.createVadDetector = createVadDetector;
+exports.createBargeInGate = createBargeInGate;
+const ABSOLUTE_MIN_RMS = 0.02; // same floor as the original flat threshold — never MORE sensitive than before in a quiet room
+const NOISE_FLOOR_MULTIPLIER = 3; // real speech must clear 3x the ambient floor, not just the absolute minimum
+const NOISE_FLOOR_EMA_ALPHA = 0.05; // slow-moving — ~1.7s time constant at a 4096-sample/48kHz frame, so a rising voice isn't mistaken for a rising ambient floor
+const MIN_ZCR = 0.003; // rejects near-DC hum/rumble; well below any real voiced-speech fundamental's crossing rate
+const MAX_ZCR = 0.4; // rejects hiss/static-like broadband noise (pure white noise sits near 0.5)
+function computeRms(samples) {
+    if (samples.length === 0)
+        return 0;
+    let sumSquares = 0;
+    for (let i = 0; i < samples.length; i++)
+        sumSquares += samples[i] * samples[i];
+    return Math.sqrt(sumSquares / samples.length);
+}
+// Fraction of adjacent-sample sign changes, in [0, 1] — a coarse
+// frequency-content proxy that needs no FFT: near 0 for a slow/DC-ish
+// signal, near 1 for a signal that changes sign every sample (Nyquist-
+// rate content, the discrete analogue of white noise/hiss).
+function computeZcr(samples) {
+    if (samples.length < 2)
+        return 0;
+    let crossings = 0;
+    for (let i = 1; i < samples.length; i++) {
+        if (samples[i] >= 0 !== samples[i - 1] >= 0)
+            crossings++;
+    }
+    return crossings / (samples.length - 1);
+}
+function createVadDetector() {
+    let noiseFloor = 0;
+    return {
+        process(samples) {
+            const rms = computeRms(samples);
+            const zcr = computeZcr(samples);
+            const energyThreshold = Math.max(ABSOLUTE_MIN_RMS, noiseFloor * NOISE_FLOOR_MULTIPLIER);
+            const isSpeech = rms > energyThreshold && zcr >= MIN_ZCR && zcr <= MAX_ZCR;
+            if (!isSpeech)
+                noiseFloor = noiseFloor * (1 - NOISE_FLOOR_EMA_ALPHA) + rms * NOISE_FLOOR_EMA_ALPHA;
+            return { isSpeech, rms, zcr, noiseFloor };
+        },
+        reset() {
+            noiseFloor = 0;
+        },
+    };
+}
+// A live-reported bug traced this session (see DEVELOPMENT.md) to a
+// server-side "confirm-or-reverse" barge-in design that raced Deepgram's
+// own transcript against a fixed grace window — real, deliberate
+// interruptions routinely lost that race and got treated as false
+// positives. Removing that system fixed the false "resumes from the
+// top," but left barge-in firing on a SINGLE ~85-100ms VAD frame
+// (createVadDetector's own frame-classification granularity at the
+// 4096-sample ScriptProcessorNode buffer size in use) — a single cough
+// or door-slam frame that happens to pass the energy+ZCR gate still cuts
+// the agent off, permanently now, with no recovery at all.
+//
+// Real research into how production voice-agent platforms actually solve
+// this (Pipecat, LiveKit Agents, Vapi, Deepgram's own Voice Agent API —
+// see DEVELOPMENT.md for the full comparison) converges on the same
+// answer, independent of any STT-transcript race: gate the LOCAL VAD
+// trigger on SUSTAINED speech across a minimum duration, not a single
+// frame. Pipecat's own documented production spec cites a 250ms minimum
+// duration; Vapi's stopSpeakingPlan defaults its VAD-duration threshold
+// (voiceSeconds) to 0.2s specifically to "balance responsiveness and
+// avoid false triggers." This is the same idea, entirely client-side —
+// unlike the removed server-side design, it never waits on a network
+// round trip or Deepgram's own transcript timing, so it can't reintroduce
+// that exact race. A brief, real noise burst (a cough, a single loud
+// clack) essentially never sustains cleanly across multiple consecutive
+// frames at these energy/ZCR bands; genuine speech does.
+const BARGE_IN_MIN_SPEECH_MS = 200;
+function createBargeInGate(minSpeechMs = BARGE_IN_MIN_SPEECH_MS) {
+    let accumulatedMs = 0;
+    let fired = false;
+    return {
+        update(frame, frameDurationMs) {
+            if (!frame.isSpeech) {
+                accumulatedMs = 0;
+                fired = false;
+                return false;
+            }
+            accumulatedMs += frameDurationMs;
+            if (fired || accumulatedMs < minSpeechMs)
+                return false;
+            fired = true;
+            return true;
+        },
+        reset() {
+            accumulatedMs = 0;
+            fired = false;
+        },
+    };
+}

package/dist/verb-executor.d.ts

@@ -1,27 +1,36 @@
 import { type TourStep } from "@cairnvibe/core";
 import { type MissContext } from "./element-ladder";
-/** The real result of one agent-loop step (click/fill/read/call_tool, or a
- * batch of several) — fed back to the model as its next turn's
- * "observation" so it can decide what to do next instead of acting blind.
- * The loop that drives this lives on the caller's side, not here:
+/** The real result of one agent-loop step (click/fill/read/call_tool/
+ * navigate, or a batch of several) — fed back to the model as its next
+ * turn's "observation" so it can decide what to do next instead of acting
+ * blind. The loop that drives this lives on the caller's side, not here:
  * index.tsx's runTypedAgentLoop for the HTTP path, realtime-server.ts's
  * finalizeTurn for the realtime one — this module only ever executes one
  * step (or one batch of steps) at a time. */
 export interface ToolStepResult {
-    verb: "click" | "fill" | "read" | "call_tool" | "batch";
+    verb: "click" | "fill" | "read" | "call_tool" | "batch" | "navigate" | "drag" | "select" | "key" | "scroll" | "wait_for";
     target?: string;
     ok: boolean;
     observation: string;
 }
 /**
  * Promise wrapper around executeVerbResponse for a continuing verb
- * (click/fill/read/call_tool) — resolves once the real action has actually
- * finished (synchronously for click/fill/read, after a real await for
- * call_tool) with its real observation, instead of the fire-and-forget
- * callback shape every other verb uses. This is what a loop driver awaits
- * before deciding whether to call the model again.
+ * (click/fill/read/call_tool, or now a navigate marked `continueAfter` —
+ * see isTerminalVerb in @cairnvibe/core) — resolves once the real action
+ * has actually finished (synchronously for click/fill/read, after a real
+ * await for call_tool/navigate) with its real observation, instead of the
+ * fire-and-forget callback shape every other verb uses. This is what a
+ * loop driver awaits before deciding whether to call the model again.
+ * `onNavigate` is only needed for that new navigate-as-continuing-step
+ * case — every existing caller that never passes it keeps working
+ * unchanged (a continueAfter navigate with no onNavigate here would just
+ * never actually move the page; real callers always pass one, same as
+ * handleVerb's own options already do for the terminal case).
  */
-export declare function executeToolStep(raw: unknown, route: string, liveElements?: Map<string, HTMLElement>): Promise<ToolStepResult | null>;
+export declare function executeToolStep(raw: unknown, route: string, liveElements?: Map<string, HTMLElement>, onNavigate?: (route: string) => void, onConfirmTool?: (tool: {
+    name: string;
+    description: string;
+}) => Promise<boolean>): Promise<ToolStepResult | null>;
 export interface VerbExecutorOptions {
     onExplain: (text: string) => void;
     onNavigate?: (route: string) => void;
@@ -45,5 +54,17 @@ export interface VerbExecutorOptions {
      * saw. Absent entirely for a caller that hasn't wired up live scanning.
      */
     liveElements?: Map<string, HTMLElement>;
+    /**
+     * Architecture Pillar 6 (the safety layer) — real confirmation for a
+     * WebMCP tool whose own registration declared `riskTier: "confirm"`
+     * (webmcp-client.ts's own doc comment covers the enforcement point).
+     * Absent means every "confirm"-tier tool call is declined by default —
+     * the safe fallback for a host app that hasn't wired up a real
+     * confirmation UI, never an implicit yes.
+     */
+    onConfirmTool?: (tool: {
+        name: string;
+        description: string;
+    }) => Promise<boolean>;
 }
 export declare function executeVerbResponse(raw: unknown, route: string, options: VerbExecutorOptions): void;