@cairnvibe/sdk 0.3.0 → 0.4.0

package/dist/cursor-overlay.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Animates the synthetic cursor to `el`'s center and resolves once it has
+ * genuinely arrived (plus a brief real hover pause) — callers await this
+ * BEFORE performing the real action, so the cursor is seen gliding there
+ * first. Deliberately timer-driven (`window.setTimeout`), not
+ * `transitionend`/`Element.animate().finished`-driven — this repo's test
+ * environment is plain Node, not a real browser (see waitForDomSettle's own
+ * doc comment for the same discipline), and a fixed, known duration is what
+ * makes this testable with fake timers instead of needing real animation-
+ * completion events that a headless/no-DOM environment may never fire.
+ *
+ * SSR/no-DOM safe — same defensive guard `waitForDomSettle` already uses —
+ * so a caller never needs its own environment check before calling this.
+ */
+export declare function moveCursorTo(el: HTMLElement): Promise<void>;
+/** Fades the synthetic cursor out — called once the widget itself closes or
+ * unmounts, so it doesn't sit visible on screen after the conversation
+ * ends. Safe to call even if the cursor was never created. */
+export declare function hideCursor(): void;

package/dist/cursor-overlay.js

@@ -0,0 +1,126 @@
+"use strict";
+// A visible, animated synthetic cursor that glides to whatever element the
+// agent is about to act on, and genuinely arrives — before anything actually
+// happens on screen — rather than a click just occurring with no visible
+// lead-up. Real, watchable proof of what the agent resolved, the same way
+// watching a person's own mouse move tells you where they're about to click
+// before it happens; matches this SDK's own "verified, not trusted"
+// discipline in a form a user can literally see, not just read.
+//
+// Purely additive and deliberately decoupled from highlightElement
+// (element-ladder.ts) — that function's own scroll+glow behavior is
+// unchanged and still called by every site that used it before. This module
+// only adds the moving cursor itself; a caller awaits moveCursorTo(el)
+// before firing the real action so the cursor is seen arriving first, never
+// after the fact — see verb-executor.ts's own call sites for the exact
+// sequencing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.moveCursorTo = moveCursorTo;
+exports.hideCursor = hideCursor;
+const CURSOR_ID = "cairn-cursor";
+const MOVE_MS = 550;
+const ARRIVE_PAUSE_MS = 160;
+// The CSS side already disables the cursor's transition/animation under
+// prefers-reduced-motion (see #cairn-cursor in the injected <style> block),
+// which makes it jump instead of glide — but without this, the real delay
+// before the action fires would stay the full ~710ms even though there's
+// nothing left to watch. Mirrors the visual change with a real timing one.
+const REDUCED_MOVE_MS = 60;
+const REDUCED_ARRIVE_PAUSE_MS = 40;
+function prefersReducedMotion() {
+    return (typeof window !== "undefined" &&
+        typeof window.matchMedia === "function" &&
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches);
+}
+// Module-scope, not per-call — the whole point is a SINGLE cursor that
+// glides from wherever it last was, the way a real mouse never teleports
+// between two unrelated screen positions.
+let lastX = null;
+let lastY = null;
+function ensureCursorEl() {
+    if (typeof document === "undefined" || !document.body)
+        return null;
+    let el = document.getElementById(CURSOR_ID);
+    if (el)
+        return el;
+    el = document.createElement("div");
+    el.id = CURSOR_ID;
+    el.setAttribute("aria-hidden", "true");
+    // A simple filled pointer shape — matches the widget's own ember accent,
+    // with a thin dark stroke so it reads clearly on light AND dark pages
+    // (the host app's own background is never something this SDK controls).
+    el.innerHTML =
+        '<svg width="22" height="22" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg">' +
+            '<path d="M2 1.5 L2 18.2 L6.3 14.4 L9.1 20.6 L11.7 19.4 L8.9 13.3 L14.6 13.1 Z" fill="#E07A3F" stroke="#1B1815" stroke-width="1.1" stroke-linejoin="round"/>' +
+            "</svg>";
+    el.style.cssText =
+        "position:fixed;left:0;top:0;z-index:2147483001;pointer-events:none;opacity:0;transition:opacity 180ms ease;will-change:transform;filter:drop-shadow(0 3px 6px rgba(0,0,0,0.35));";
+    document.body.appendChild(el);
+    return el;
+}
+/**
+ * Animates the synthetic cursor to `el`'s center and resolves once it has
+ * genuinely arrived (plus a brief real hover pause) — callers await this
+ * BEFORE performing the real action, so the cursor is seen gliding there
+ * first. Deliberately timer-driven (`window.setTimeout`), not
+ * `transitionend`/`Element.animate().finished`-driven — this repo's test
+ * environment is plain Node, not a real browser (see waitForDomSettle's own
+ * doc comment for the same discipline), and a fixed, known duration is what
+ * makes this testable with fake timers instead of needing real animation-
+ * completion events that a headless/no-DOM environment may never fire.
+ *
+ * SSR/no-DOM safe — same defensive guard `waitForDomSettle` already uses —
+ * so a caller never needs its own environment check before calling this.
+ */
+function moveCursorTo(el) {
+    if (typeof document === "undefined" || typeof window === "undefined" || typeof el.getBoundingClientRect !== "function") {
+        return Promise.resolve();
+    }
+    const cursor = ensureCursorEl();
+    if (!cursor)
+        return Promise.resolve();
+    const rect = el.getBoundingClientRect();
+    const x = rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    if (lastX === null || lastY === null) {
+        // The very first move of the session starts from the widget's own
+        // corner (bottom-right, where the FAB lives) instead of materializing
+        // at (0,0) — reads as "coming from Cairn," not appearing from nowhere.
+        lastX = window.innerWidth - 40;
+        lastY = window.innerHeight - 40;
+        cursor.style.transform = `translate(${lastX}px, ${lastY}px)`;
+    }
+    const reduced = prefersReducedMotion();
+    const moveMs = reduced ? REDUCED_MOVE_MS : MOVE_MS;
+    const arrivePauseMs = reduced ? REDUCED_ARRIVE_PAUSE_MS : ARRIVE_PAUSE_MS;
+    cursor.style.transition = `transform ${moveMs}ms cubic-bezier(.4,0,.2,1), opacity 180ms ease`;
+    cursor.style.opacity = "1";
+    // Forces a style flush so the browser animates FROM the current position
+    // TO the new one instead of jumping straight there — reading a layout
+    // property is the standard, harmless way to force this without a real
+    // animation API (which, per this function's own doc comment, this
+    // deliberately avoids depending on for its completion signal anyway).
+    void cursor.offsetHeight;
+    cursor.style.transform = `translate(${x}px, ${y}px)`;
+    lastX = x;
+    lastY = y;
+    return new Promise((resolve) => {
+        window.setTimeout(() => {
+            cursor.classList.add("cairn-cursor-hover");
+            window.setTimeout(() => {
+                cursor.classList.remove("cairn-cursor-hover");
+                resolve();
+            }, arrivePauseMs);
+        }, moveMs);
+    });
+}
+/** Fades the synthetic cursor out — called once the widget itself closes or
+ * unmounts, so it doesn't sit visible on screen after the conversation
+ * ends. Safe to call even if the cursor was never created. */
+function hideCursor() {
+    if (typeof document === "undefined")
+        return;
+    const el = document.getElementById(CURSOR_ID);
+    if (el)
+        el.style.opacity = "0";
+}

package/dist/index.js

@@ -13,6 +13,7 @@ const lucide_react_1 = require("lucide-react");
 const core_1 = require("@cairnvibe/core");
 const agent_loop_1 = require("./agent-loop");
 const context_collector_1 = require("./context-collector");
+const cursor_overlay_1 = require("./cursor-overlay");
 const element_ladder_1 = require("./element-ladder");
 const runtime_scan_1 = require("./runtime-scan");
 const webmcp_client_1 = require("./webmcp-client");
@@ -40,6 +41,13 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
     // loadPersistedConversation's own doc comment) had showing a moment ago,
     // so a real reload never again looks like the conversation simply ended.
     const [open, setOpen] = (0, react_1.useState)(false);
+    // Fades the synthetic cursor out once the panel closes (or the widget
+    // itself unmounts) instead of leaving it sitting visible on the page.
+    (0, react_1.useEffect)(() => {
+        if (!open)
+            (0, cursor_overlay_1.hideCursor)();
+        return () => (0, cursor_overlay_1.hideCursor)();
+    }, [open]);
     // Collapsed by default so the panel only ever shows the current exchange
     // — the full archived transcript (built up over a long conversation)
     // stays out of the way behind an explicit toggle instead of always being
@@ -1901,9 +1909,13 @@ const COPILOT_STYLES = `
   0%, 100% { box-shadow: 0 0 0 0 rgba(16, 185, 129, 0.4); }
   70% { box-shadow: 0 0 0 10px rgba(16, 185, 129, 0); }
 }
-@keyframes cairn-pulse-indigo {
-  0%, 100% { box-shadow: 0 0 0 0 rgba(99, 102, 241, 0.4); }
-  70% { box-shadow: 0 0 0 10px rgba(99, 102, 241, 0); }
+@keyframes cairn-pulse-ember {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(224, 122, 63, 0.4); }
+  70% { box-shadow: 0 0 0 10px rgba(224, 122, 63, 0); }
+}
+@keyframes cairn-cursor-arrive {
+  0% { box-shadow: 0 0 0 0 rgba(224, 122, 63, 0.55); }
+  100% { box-shadow: 0 0 0 9px rgba(224, 122, 63, 0); }
 }
 @keyframes cairn-spin {
   from { transform: rotate(0deg); }
@@ -1919,7 +1931,7 @@ const COPILOT_STYLES = `
 }
 @keyframes cairn-word-sweep {
   0% { opacity: 0.35; text-shadow: none; }
-  35% { opacity: 1; color: #4f46e5; text-shadow: 0 0 10px rgba(99, 102, 241, 0.45); }
+  35% { opacity: 1; color: #E07A3F; text-shadow: 0 0 10px rgba(224, 122, 63, 0.45); }
   100% { opacity: 1; color: inherit; text-shadow: none; }
 }
 @keyframes cairn-thinking-bounce {
@@ -1927,16 +1939,19 @@ const COPILOT_STYLES = `
   40% { opacity: 0.9; transform: translateY(-3px); }
 }
 .cairn-glow {
-  animation: cairn-pulse-indigo 1.1s ease-out 2;
-  outline: 2px solid #6366f1;
+  animation: cairn-pulse-ember 1.1s ease-out 2;
+  outline: 2px solid #E07A3F;
   outline-offset: 3px;
   border-radius: 8px;
 }
+.cairn-cursor-hover {
+  animation: cairn-cursor-arrive 0.3s ease-out;
+}
 .cairn-spin {
   animation: cairn-spin 0.8s linear infinite;
 }
 @media (prefers-reduced-motion: reduce) {
-  .cairn-fab, .cairn-panel, .cairn-bubble, .cairn-word, .cairn-thinking-dot {
+  .cairn-fab, .cairn-panel, .cairn-bubble, .cairn-word, .cairn-thinking-dot, #cairn-cursor {
     animation: none !important;
     transition: none !important;
   }

package/dist/realtime-server.js

@@ -105,11 +105,22 @@ async function handleRememberFactTool(memory, scopeId, args) {
 function createRealtimeServer(options) {
     const registeredActions = options.registeredActions ?? [];
     const capability = options.capability ?? "act";
-    const llm = (0, server_1.createVerbLLM)(options);
+    // One shared rotator across all three LLM roles — see
+    // CreateCopilotHandlerOptions.keyRotator's own doc comment for the real
+    // gap this closes (a key one role confirmed dead used to stay invisible
+    // to the other two, which kept rediscovering it fresh on every call).
+    // Only built for groq — anthropic's createXLLM calls ignore keyRotator
+    // entirely, so building one for it would be dead work. Respects a
+    // caller-supplied options.keyRotator (e.g. shared with the typed/HTTP
+    // transport in the same process) instead of always building a fresh one.
+    const sharedOptions = options.provider === "groq" && !options.keyRotator
+        ? { ...options, keyRotator: options.apiKeys ? new server_1.KeyRotator(options.apiKeys) : options.apiKey ? new server_1.KeyRotator([options.apiKey]) : server_1.KeyRotator.fromEnvList(process.env.GROQ_API_KEYS) ?? undefined }
+        : options;
+    const llm = (0, server_1.createVerbLLM)(sharedOptions);
     // Phase 3 steps 2-3 — real, separately-configured Planner/Critic LLMs.
     // See finalizeTurn's own doc comment for how they're actually used.
-    const planLLM = (0, server_1.createPlanLLM)(options);
-    const criticLLM = (0, server_1.createCriticLLM)(options);
+    const planLLM = (0, server_1.createPlanLLM)(sharedOptions);
+    const criticLLM = (0, server_1.createCriticLLM)(sharedOptions);
     // "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

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import { type CriticVerdict, type HistoryTurn, type LiveElement, type Manifest, type Plan, type Skill, type SkillSummary, type Task, type UiPatternId, type VerbResponse, type WebMcpTool } from "@cairnvibe/core";
 import { type MemoryStore } from "./memory-sqlite";
+export { KeyRotator } from "./key-rotator";
 import { KeyRotator } from "./key-rotator";
 import type { SkillStore } from "./skill-store";
 /**
@@ -16,6 +17,22 @@ export interface CreateCopilotHandlerOptions {
     /** Single API key. For groq, prefer `apiKeys` to round-robin; falls back to GROQ_API_KEYS env. */
     apiKey?: string;
     apiKeys?: string[];
+    /**
+     * A pre-built rotator to share across multiple LLM roles (verb, plan,
+     * critic) instead of each one building its own from `apiKeys`/`apiKey`/
+     * env. Real, live-found gap this closes: createVerbLLM/createPlanLLM/
+     * createCriticLLM each called createToolLLM independently, and each one
+     * built a BRAND NEW KeyRotator from the same GROQ_API_KEYS list — so a
+     * key one of them confirmed dead via a real 401 (KeyRotator.markDead)
+     * stayed invisible to the other two, which went on rediscovering the
+     * exact same dead key from scratch on every one of their own calls,
+     * wasting real round trips and, worse, stacking up wasted attempts
+     * against the SAME small number of retries each call is bounded to.
+     * Takes precedence over `apiKeys`/`apiKey`/env when provided. See
+     * groq-llm.ts in examples/demo-app for the intended usage: build one
+     * KeyRotator at module scope, pass it to all three createXLLM calls.
+     */
+    keyRotator?: KeyRotator;
     model?: string;
     /** Action ids this deployment actually supports. "do" is refused for anything else. */
     registeredActions?: string[];

package/dist/server.js

@@ -7,7 +7,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GroqStreamingTextLLM = exports.GroqVerbLLM = exports.AnthropicStreamingTextLLM = exports.AnthropicVerbLLM = void 0;
+exports.GroqStreamingTextLLM = exports.GroqVerbLLM = exports.AnthropicStreamingTextLLM = exports.AnthropicVerbLLM = exports.KeyRotator = void 0;
 exports.createCopilotHandler = createCopilotHandler;
 exports.createCopilotHandlerWithLLM = createCopilotHandlerWithLLM;
 exports.resolveVerb = resolveVerb;
@@ -34,7 +34,9 @@ const zod_1 = require("zod");
 const core_1 = require("@cairnvibe/core");
 const agent_loop_1 = require("./agent-loop");
 const memory_sqlite_1 = require("./memory-sqlite");
-const key_rotator_1 = require("./key-rotator");
+var key_rotator_1 = require("./key-rotator");
+Object.defineProperty(exports, "KeyRotator", { enumerable: true, get: function () { return key_rotator_1.KeyRotator; } });
+const key_rotator_2 = require("./key-rotator");
 const VERB_TOOL_NAME = "respond_with_verb";
 const PLAN_TOOL_NAME = "create_plan";
 const PLAN_TOOL_DESCRIPTION = "Submit an ordered task plan for achieving the user's real end goal.";
@@ -372,11 +374,12 @@ function createCriticLLM(options = {}) {
 function createToolLLM(options, toolSchema, toolName, toolDescription) {
     const provider = options.provider ?? "anthropic";
     if (provider === "groq") {
-        const rotator = options.apiKeys
-            ? new key_rotator_1.KeyRotator(options.apiKeys)
-            : options.apiKey
-                ? new key_rotator_1.KeyRotator([options.apiKey])
-                : key_rotator_1.KeyRotator.fromEnvList(process.env.GROQ_API_KEYS);
+        const rotator = options.keyRotator
+            ?? (options.apiKeys
+                ? new key_rotator_2.KeyRotator(options.apiKeys)
+                : options.apiKey
+                    ? new key_rotator_2.KeyRotator([options.apiKey])
+                    : key_rotator_2.KeyRotator.fromEnvList(process.env.GROQ_API_KEYS));
         if (!rotator) {
             throw new Error("createToolLLM: provider 'groq' needs apiKey(s), or GROQ_API_KEYS in env");
         }
@@ -650,7 +653,20 @@ class GroqVerbLLM {
     clientFactory;
     toolName;
     toolDescription;
-    constructor(keys, model, toolSchema, clientFactory = (apiKey) => new groq_sdk_1.default({ apiKey }), toolName = VERB_TOOL_NAME, toolDescription = VERB_TOOL_DESCRIPTION) {
+    constructor(keys, model, toolSchema, 
+    // maxRetries: 0 — real, live-found latency bug this closes: the Groq
+    // SDK's own default (2 automatic retries with exponential backoff) ran
+    // UNDERNEATH respond()'s own key-rotation retry loop, so a single 429
+    // key attempt could silently eat several real seconds of SDK-internal
+    // backoff before respond() ever saw the rejection and moved on to a
+    // DIFFERENT key. With several keys in rotation genuinely rate-limited
+    // at once (the common case this closes for), that compounded into a
+    // real, live-reported multi-second-to-a-minute hang with no visible
+    // progress — worse than useless, since respond()'s own retry already
+    // tries a different key/quota entirely, which the SDK's blind same-key
+    // backoff can never fix. respond() is the sole source of retry policy
+    // here now.
+    clientFactory = (apiKey) => new groq_sdk_1.default({ apiKey, maxRetries: 0 }), toolName = VERB_TOOL_NAME, toolDescription = VERB_TOOL_DESCRIPTION) {
         this.keys = keys;
         this.model = model;
         this.toolSchema = toolSchema;
@@ -784,7 +800,14 @@ class GroqStreamingTextLLM {
     keys;
     model;
     clientFactory;
-    constructor(keys, model, clientFactory = (apiKey) => new groq_sdk_1.default({ apiKey })) {
+    constructor(keys, model, 
+    // maxRetries: 0 — same real latency bug as GroqVerbLLM's own
+    // clientFactory default; see its doc comment for the full reasoning.
+    // respondStreamed below already has its own key-rotation retry loop
+    // (maxAttempts bounded by keys.size), which makes the SDK's blind
+    // same-key backoff redundant AND a source of silent multi-second
+    // delay stacked underneath it.
+    clientFactory = (apiKey) => new groq_sdk_1.default({ apiKey, maxRetries: 0 })) {
         this.keys = keys;
         this.model = model;
         this.clientFactory = clientFactory;