@cairnvibe/sdk 0.3.0 → 0.4.0

package/src/server.ts

@@ -34,6 +34,7 @@ import {
 } from "@cairnvibe/core";
 import { looksMultiStep, MAX_HISTORY_TURNS, summarizeVerbForHistory } from "./agent-loop";
 import { formatArchivedFacts, formatRememberedFacts, seedHistoryFromMemory, type MemoryStore } from "./memory-sqlite";
+export { KeyRotator } from "./key-rotator";
 import { KeyRotator } from "./key-rotator";
 import type { SkillStore } from "./skill-store";
 
@@ -67,6 +68,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[];
@@ -498,11 +515,12 @@ function createToolLLM(options: CreateCopilotHandlerOptions, toolSchema: Record<
   const provider = options.provider ?? "anthropic";
 
   if (provider === "groq") {
-    const rotator = options.apiKeys
-      ? new KeyRotator(options.apiKeys)
-      : options.apiKey
-        ? new KeyRotator([options.apiKey])
-        : KeyRotator.fromEnvList(process.env.GROQ_API_KEYS);
+    const rotator = options.keyRotator
+      ?? (options.apiKeys
+        ? new KeyRotator(options.apiKeys)
+        : options.apiKey
+          ? new KeyRotator([options.apiKey])
+          : KeyRotator.fromEnvList(process.env.GROQ_API_KEYS));
     if (!rotator) {
       throw new Error("createToolLLM: provider 'groq' needs apiKey(s), or GROQ_API_KEYS in env");
     }
@@ -833,7 +851,19 @@ export class GroqVerbLLM implements VerbLLM {
     private keys: KeyRotator,
     private model: string,
     private toolSchema: Record<string, unknown>,
-    private clientFactory: (apiKey: string) => GroqLikeClient = (apiKey) => new Groq({ apiKey }),
+    // 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.
+    private clientFactory: (apiKey: string) => GroqLikeClient = (apiKey) => new Groq({ apiKey, maxRetries: 0 }),
     private toolName: string = VERB_TOOL_NAME,
     private toolDescription: string = VERB_TOOL_DESCRIPTION,
   ) {}
@@ -973,7 +1003,13 @@ export class GroqStreamingTextLLM implements StreamingTextLLM {
   constructor(
     private keys: KeyRotator,
     private model: string,
-    private clientFactory: (apiKey: string) => GroqLikeStreamingClient = (apiKey) => new Groq({ apiKey }),
+    // 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.
+    private clientFactory: (apiKey: string) => GroqLikeStreamingClient = (apiKey) => new Groq({ apiKey, maxRetries: 0 }),
   ) {}
 
   async respondStreamed(systemPrompt: string, userMessage: string, onChunk: (delta: string) => void): Promise<string> {

package/src/verb-executor.ts

@@ -7,6 +7,7 @@
 
 import { VerbResponseSchema, type ApiCall, type BatchAction, type TourStep, type VerbResponse } from "@cairnvibe/core";
 import { dragElement, findElement, findElementWithRetry, fillElement, highlightElement, logMiss, pressKey, readElement, selectOption, waitForDomSettle, type MissContext } from "./element-ladder";
+import { moveCursorTo } from "./cursor-overlay";
 import { executeWebMcpTool } from "./webmcp-client";
 
 /** The real result of one agent-loop step (click/fill/read/call_tool/
@@ -136,10 +137,15 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
         return;
       }
       highlightElement(el);
-      // "open" means make the thing actually appear (a menu, a modal, a
-      // panel) — highlighting alone doesn't do that; a real click does.
-      if (verb.verb === "open") el.click();
-      if (verb.text) options.onExplain(verb.text);
+      // The cursor visibly arrives before "open"'s real click fires — the
+      // whole point is a user watching sees where it's about to click
+      // BEFORE the menu/modal/panel actually opens, not simultaneously.
+      void moveCursorTo(el).then(() => {
+        // "open" means make the thing actually appear (a menu, a modal, a
+        // panel) — highlighting alone doesn't do that; a real click does.
+        if (verb.verb === "open") el.click();
+        if (verb.text) options.onExplain(verb.text);
+      });
       return;
     }
 
@@ -198,8 +204,10 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
           // on a different page) — never fired in addition to a real
           // click, so the action can't run twice.
           highlightElement(el);
-          el.click();
-          if (verb.text) options.onExplain(verb.text);
+          void moveCursorTo(el).then(() => {
+            el.click();
+            if (verb.text) options.onExplain(verb.text);
+          });
           return;
         }
         if (verb.target) (options.onMiss ?? logMiss)({ attempted: verb.target, route });
@@ -244,14 +252,16 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
         return;
       }
       highlightElement(el);
-      el.click();
-      // Real, live-found race this closes — see waitForDomSettle's own doc
-      // comment: a click can trigger an async re-render (a cart count
-      // updating, a filtered list refreshing) that hasn't happened yet the
-      // instant .click() returns. A subsequent read step in the same turn
-      // needs the SETTLED result, not whatever was on screen a moment ago.
-      void waitForDomSettle().then(() => {
-        options.onToolStep?.({ verb: "click", target: verb.target, ok: true, observation: "Clicked it." });
+      void moveCursorTo(el).then(() => {
+        el.click();
+        // Real, live-found race this closes — see waitForDomSettle's own
+        // doc comment: a click can trigger an async re-render (a cart count
+        // updating, a filtered list refreshing) that hasn't happened yet the
+        // instant .click() returns. A subsequent read step in the same turn
+        // needs the SETTLED result, not whatever was on screen a moment ago.
+        void waitForDomSettle().then(() => {
+          options.onToolStep?.({ verb: "click", target: verb.target, ok: true, observation: "Clicked it." });
+        });
       });
       return;
     }
@@ -259,23 +269,30 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
     case "fill": {
       if (verb.text) options.onExplain(verb.text);
       const el = findElement(verb.target, options.liveElements);
-      if (!el || !fillElement(el, verb.value)) {
+      if (!el) {
         (options.onMiss ?? logMiss)({ attempted: verb.target, route });
-        options.onToolStep?.({
-          verb: "fill",
-          target: verb.target,
-          ok: false,
-          observation: el ? "That element isn't a real form field — can't type into it." : "Could not find that element on the page.",
-        });
+        options.onToolStep?.({ verb: "fill", target: verb.target, ok: false, observation: "Could not find that element on the page." });
         return;
       }
       highlightElement(el);
-      // See the click case's own comment — the exact real bug found live:
-      // typing into a search box, then reading the still-unfiltered
-      // results a moment later and reporting a match the real, since-
-      // filtered page never actually showed.
-      void waitForDomSettle().then(() => {
-        options.onToolStep?.({ verb: "fill", target: verb.target, ok: true, observation: `Typed "${verb.value}" into it.` });
+      // fillElement itself is both the "is this a real form field" check
+      // AND the commit (it sets the value the instant it returns true) —
+      // deliberately called from inside this .then(), not the synchronous
+      // miss-check above, so the cursor is genuinely seen arriving BEFORE
+      // any text appears, not simultaneously with it.
+      void moveCursorTo(el).then(() => {
+        if (!fillElement(el, verb.value)) {
+          (options.onMiss ?? logMiss)({ attempted: verb.target, route });
+          options.onToolStep?.({ verb: "fill", target: verb.target, ok: false, observation: "That element isn't a real form field — can't type into it." });
+          return;
+        }
+        // See the click case's own comment — the exact real bug found live:
+        // typing into a search box, then reading the still-unfiltered
+        // results a moment later and reporting a match the real, since-
+        // filtered page never actually showed.
+        void waitForDomSettle().then(() => {
+          options.onToolStep?.({ verb: "fill", target: verb.target, ok: true, observation: `Typed "${verb.value}" into it.` });
+        });
       });
       return;
     }
@@ -288,7 +305,12 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
         options.onToolStep?.({ verb: "read", target: verb.target, ok: false, observation: "Could not find that element on the page." });
         return;
       }
-      options.onToolStep?.({ verb: "read", target: verb.target, ok: true, observation: readElement(el) });
+      // No mutation here, but the cursor still visits what's being read —
+      // real visual proof of what the agent is actually looking at, not
+      // just a claim in the eventual reported observation.
+      void moveCursorTo(el).then(() => {
+        options.onToolStep?.({ verb: "read", target: verb.target, ok: true, observation: readElement(el) });
+      });
       return;
     }
 
@@ -310,12 +332,19 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
         return;
       }
       highlightElement(from);
-      dragElement(from, to);
-      // Same real re-render race as click/fill — a drop can trigger an
-      // async re-render (a canvas connection line, a reordered list) that
-      // hasn't settled the instant the pointer sequence finishes.
-      void waitForDomSettle().then(() => {
-        options.onToolStep?.({ verb: "drag", target: verb.target, ok: true, observation: `Dragged it to ${verb.to}.` });
+      void moveCursorTo(from).then(() => {
+        dragElement(from, to);
+        // The cursor also glides to the drop point — fire-and-forget, not
+        // awaited, since it's purely a visual echo of a drag that already
+        // happened via real pointer events; nothing downstream depends on
+        // it finishing.
+        void moveCursorTo(to);
+        // Same real re-render race as click/fill — a drop can trigger an
+        // async re-render (a canvas connection line, a reordered list) that
+        // hasn't settled the instant the pointer sequence finishes.
+        void waitForDomSettle().then(() => {
+          options.onToolStep?.({ verb: "drag", target: verb.target, ok: true, observation: `Dragged it to ${verb.to}.` });
+        });
       });
       return;
     }
@@ -323,19 +352,24 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
     case "select": {
       if (verb.text) options.onExplain(verb.text);
       const el = findElement(verb.target, options.liveElements);
-      if (!el || !selectOption(el, verb.value)) {
+      if (!el) {
         (options.onMiss ?? logMiss)({ attempted: verb.target, route });
-        options.onToolStep?.({
-          verb: "select",
-          target: verb.target,
-          ok: false,
-          observation: el ? `Could not find an option matching "${verb.value}".` : "Could not find that element on the page.",
-        });
+        options.onToolStep?.({ verb: "select", target: verb.target, ok: false, observation: "Could not find that element on the page." });
         return;
       }
       highlightElement(el);
-      void waitForDomSettle().then(() => {
-        options.onToolStep?.({ verb: "select", target: verb.target, ok: true, observation: `Selected "${verb.value}".` });
+      // Same reasoning as fill's own comment — selectOption is both the
+      // "does a matching option exist" check and the commit, so it's called
+      // from inside this .then(), after the cursor genuinely arrives.
+      void moveCursorTo(el).then(() => {
+        if (!selectOption(el, verb.value)) {
+          (options.onMiss ?? logMiss)({ attempted: verb.target, route });
+          options.onToolStep?.({ verb: "select", target: verb.target, ok: false, observation: `Could not find an option matching "${verb.value}".` });
+          return;
+        }
+        void waitForDomSettle().then(() => {
+          options.onToolStep?.({ verb: "select", target: verb.target, ok: true, observation: `Selected "${verb.value}".` });
+        });
       });
       return;
     }
@@ -348,10 +382,21 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
         options.onToolStep?.({ verb: "key", target: verb.target, ok: false, observation: "Could not find that element on the page." });
         return;
       }
-      pressKey(el, verb.key);
-      void waitForDomSettle().then(() => {
-        options.onToolStep?.({ verb: "key", target: verb.target, ok: true, observation: `Pressed ${verb.key}.` });
-      });
+      const afterMove = () => {
+        pressKey(el, verb.key);
+        void waitForDomSettle().then(() => {
+          options.onToolStep?.({ verb: "key", target: verb.target, ok: true, observation: `Pressed ${verb.key}.` });
+        });
+      };
+      // With no explicit target ("whatever's currently focused"), there's
+      // nothing sensible for the cursor to glide to — call straight through
+      // instead of routing through a promise callback for no reason, so
+      // this path stays exactly as synchronous as it always was.
+      if (verb.target) {
+        void moveCursorTo(el).then(afterMove);
+      } else {
+        afterMove();
+      }
       return;
     }
 
@@ -368,8 +413,10 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
       // exactly the real repositioning this verb exists for; the glow
       // also gives the user a visible cue of where the agent just moved.
       highlightElement(el);
-      void waitForDomSettle().then(() => {
-        options.onToolStep?.({ verb: "scroll", target: verb.target, ok: true, observation: "Scrolled it into view." });
+      void moveCursorTo(el).then(() => {
+        void waitForDomSettle().then(() => {
+          options.onToolStep?.({ verb: "scroll", target: verb.target, ok: true, observation: "Scrolled it into view." });
+        });
       });
       return;
     }
@@ -382,7 +429,9 @@ function dispatchVerb(verb: VerbResponse, route: string, options: VerbExecutorOp
           options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: false, observation: "It never appeared." });
           return;
         }
-        options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: true, observation: "It appeared." });
+        void moveCursorTo(el).then(() => {
+          options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: true, observation: "It appeared." });
+        });
       });
       return;
     }
@@ -438,6 +487,7 @@ async function executeOneBatchAction(action: BatchAction, route: string, options
         return { ok: false, observation: "Could not find that element on the page." };
       }
       highlightElement(el);
+      await moveCursorTo(el);
       el.click();
       // Same real race as the single-step case (see waitForDomSettle's own
       // doc comment) — arguably MORE likely here, since a batch's next
@@ -447,14 +497,19 @@ async function executeOneBatchAction(action: BatchAction, route: string, options
     }
     case "fill": {
       const el = await findElementWithRetry(action.target, options.liveElements);
-      if (!el || !fillElement(el, action.value)) {
+      if (!el) {
         (options.onMiss ?? logMiss)({ attempted: action.target, route });
-        return {
-          ok: false,
-          observation: el ? "That element isn't a real form field — can't type into it." : "Could not find that element on the page.",
-        };
+        return { ok: false, observation: "Could not find that element on the page." };
       }
       highlightElement(el);
+      // See the single-step fill case's own comment — fillElement is both
+      // the field-type check and the commit, called after the cursor
+      // genuinely arrives rather than in the synchronous miss-check.
+      await moveCursorTo(el);
+      if (!fillElement(el, action.value)) {
+        (options.onMiss ?? logMiss)({ attempted: action.target, route });
+        return { ok: false, observation: "That element isn't a real form field — can't type into it." };
+      }
       await waitForDomSettle();
       return { ok: true, observation: `Typed "${action.value}" into it.` };
     }
@@ -464,6 +519,7 @@ async function executeOneBatchAction(action: BatchAction, route: string, options
         (options.onMiss ?? logMiss)({ attempted: action.target, route });
         return { ok: false, observation: "Could not find that element on the page." };
       }
+      await moveCursorTo(el);
       return { ok: true, observation: readElement(el) };
     }
     case "call_tool": {
@@ -478,17 +534,24 @@ async function executeOneBatchAction(action: BatchAction, route: string, options
         return { ok: false, observation: from ? "Could not find the drop destination on the page." : "Could not find that element on the page." };
       }
       highlightElement(from);
+      await moveCursorTo(from);
       dragElement(from, to);
+      void moveCursorTo(to); // visual echo of the drop point — not awaited, purely decorative
       await waitForDomSettle();
       return { ok: true, observation: `Dragged it to ${action.to}.` };
     }
     case "select": {
       const el = await findElementWithRetry(action.target, options.liveElements);
-      if (!el || !selectOption(el, action.value)) {
+      if (!el) {
         (options.onMiss ?? logMiss)({ attempted: action.target, route });
-        return { ok: false, observation: el ? `Could not find an option matching "${action.value}".` : "Could not find that element on the page." };
+        return { ok: false, observation: "Could not find that element on the page." };
       }
       highlightElement(el);
+      await moveCursorTo(el);
+      if (!selectOption(el, action.value)) {
+        (options.onMiss ?? logMiss)({ attempted: action.target, route });
+        return { ok: false, observation: `Could not find an option matching "${action.value}".` };
+      }
       await waitForDomSettle();
       return { ok: true, observation: `Selected "${action.value}".` };
     }
@@ -498,6 +561,7 @@ async function executeOneBatchAction(action: BatchAction, route: string, options
         if (action.target) (options.onMiss ?? logMiss)({ attempted: action.target, route });
         return { ok: false, observation: "Could not find that element on the page." };
       }
+      if (action.target) await moveCursorTo(el);
       pressKey(el, action.key);
       await waitForDomSettle();
       return { ok: true, observation: `Pressed ${action.key}.` };
@@ -509,6 +573,7 @@ async function executeOneBatchAction(action: BatchAction, route: string, options
         return { ok: false, observation: "Could not find that element on the page." };
       }
       highlightElement(el);
+      await moveCursorTo(el);
       await waitForDomSettle();
       return { ok: true, observation: "Scrolled it into view." };
     }
@@ -518,6 +583,7 @@ async function executeOneBatchAction(action: BatchAction, route: string, options
         (options.onMiss ?? logMiss)({ attempted: action.target, route });
         return { ok: false, observation: "It never appeared." };
       }
+      await moveCursorTo(el);
       return { ok: true, observation: "It appeared." };
     }
   }

package/src/web-component.ts

@@ -24,6 +24,7 @@
 import type { HistoryTurn as HistoryEntry, TourStep } from "@cairnvibe/core";
 import { collectVisible } from "./context-collector";
 import { findElement, highlightElement, logMiss, type MissContext } from "./element-ladder";
+import { hideCursor } from "./cursor-overlay";
 import { executeVerbResponse } from "./verb-executor";
 import { createBargeInGate, createVadDetector } from "./vad";
 
@@ -56,9 +57,13 @@ const 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); } to { transform: rotate(360deg); } }
 @keyframes cairn-rt-dot {
@@ -75,7 +80,7 @@ const 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 {
@@ -83,14 +88,15 @@ const 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-spin { animation: cairn-spin 0.8s linear infinite; }
+.cairn-cursor-hover { animation: cairn-cursor-arrive 0.3s ease-out; }
 @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;
   }
@@ -381,6 +387,7 @@ export class CairnWidgetElement extends HTMLElement {
   // in parallel with whatever comes next.
   disconnectedCallback() {
     if (this.rtSocket || this.rtCleanup) this.endRealtime();
+    hideCursor();
   }
 
   // --- attributes -----------------------------------------------------
@@ -561,6 +568,7 @@ export class CairnWidgetElement extends HTMLElement {
     this.fab.innerHTML = this.isOpen ? CLOSE_ICON : MARK_ICON;
     this.fab.setAttribute("aria-label", this.isOpen ? `Close ${this.persona} help` : `Open ${this.persona} help`);
     if (this.isOpen && !this.realtimeActive) this.inputEl.focus();
+    if (!this.isOpen) hideCursor();
   }
 
   // --- rendering ------------------------------------------------------