@cairnvibe/sdk 0.2.6 → 0.2.8

package/dist/verb-executor.js

@@ -6,9 +6,39 @@
 // explain — never guess, never wrong-click"). The server (`server.ts`)
 // enforces the same schema independently — never trust the client alone.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeToolStep = executeToolStep;
 exports.executeVerbResponse = executeVerbResponse;
 const core_1 = require("@cairnvibe/core");
 const element_ladder_1 = require("./element-ladder");
+const webmcp_client_1 = require("./webmcp-client");
+/**
+ * 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.
+ */
+function executeToolStep(raw, route, liveElements) {
+    return new Promise((resolve) => {
+        // executeVerbResponse only ever reaches onToolStep for a genuinely
+        // continuing verb — callers are only expected to call this after
+        // already confirming (via TERMINAL_VERBS) that the parsed verb is one,
+        // so this should always fire; a real timeout (not an immediate
+        // microtask — call_tool's own real network round trip needs the time)
+        // is the safety net for the case where it somehow doesn't, so a loop
+        // driver awaiting this can never hang forever.
+        const timer = setTimeout(() => resolve(null), 15000);
+        executeVerbResponse(raw, route, {
+            onExplain: () => { },
+            liveElements,
+            onToolStep: (result) => {
+                clearTimeout(timer);
+                resolve(result);
+            },
+        });
+    });
+}
 const FALLBACK_TEXT = "I'm not sure — I couldn't understand that response. Try rephrasing your question.";
 function executeVerbResponse(raw, route, options) {
     const parsed = core_1.VerbResponseSchema.safeParse(raw);
@@ -25,13 +55,17 @@ function dispatchVerb(verb, route, options) {
             return;
         case "highlight":
         case "open": {
-            const el = (0, element_ladder_1.findElement)(verb.target);
+            const el = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
             if (!el) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
                 options.onExplain(verb.text ?? "I know what you need, but I can't find it on this page right now.");
                 return;
             }
             (0, element_ladder_1.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);
             return;
@@ -50,24 +84,40 @@ function dispatchVerb(verb, route, options) {
                     options.onExplain(verb.text);
                 return;
             }
-            if (verb.apiCall) {
-                // Auto-discovered path: a real, indexer-found handler call on this
-                // exact target element, attached server-side after looking the
-                // target up in the manifest — never something the model emitted
-                // itself (see ApiCallSchema's doc comment in @cairnvibe/core).
-                const el = verb.target ? (0, element_ladder_1.findElement)(verb.target) : null;
-                if (el)
+            // Auto-discovered path: the server already verified `target` names a
+            // real element (the static manifest or this exact request's own
+            // live-DOM scan) before ever returning this verb — never something
+            // the model invented (see resolveVerb in server.ts).
+            if (verb.target || verb.apiCall) {
+                const el = verb.target ? (0, element_ladder_1.findElement)(verb.target, options.liveElements) : null;
+                if (el) {
+                    // Click-first: the real element's own handler runs in full (any
+                    // local state update, spinner, or non-network side effect a raw
+                    // fetch would silently skip), and it's the only way to fire an
+                    // action that has no fetch/axios call at all — a button that
+                    // just reveals a form, e.g. — which never gets an `apiCall` in
+                    // the first place. `apiCall` is only ever the fallback below,
+                    // for a target that can't be resolved live right now (e.g. it's
+                    // on a different page) — never fired in addition to a real
+                    // click, so the action can't run twice.
                     (0, element_ladder_1.highlightElement)(el);
-                else if (verb.target)
+                    el.click();
+                    if (verb.text)
+                        options.onExplain(verb.text);
+                    return;
+                }
+                if (verb.target)
                     (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
-                if (verb.text)
-                    options.onExplain(verb.text);
-                void executeApiCall(verb.apiCall).then((result) => {
-                    if (!result.ok) {
-                        options.onExplain("I tried to do that, but something went wrong — try again in a moment.");
-                    }
-                });
-                return;
+                if (verb.apiCall) {
+                    if (verb.text)
+                        options.onExplain(verb.text);
+                    void executeApiCall(verb.apiCall).then((result) => {
+                        if (!result.ok) {
+                            options.onExplain("I tried to do that, but something went wrong — try again in a moment.");
+                        }
+                    });
+                    return;
+                }
             }
             options.onExplain(verb.text ?? "That action isn't available here.");
             return;
@@ -83,6 +133,63 @@ function dispatchVerb(verb, route, options) {
                 options.onExplain(verb.steps.map((s) => s.text).join(" "));
             }
             return;
+        // The agent loop's steps (server.ts's runAgentLoop) — each executes for
+        // real and reports a real observation back via onToolStep, instead of
+        // ending the turn the way every verb above does. `target` for these
+        // always came from the manifest/currentPageElements/liveElements this
+        // exact turn showed the model — never invented, same invariant as do.
+        case "click": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            const el = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
+            if (!el) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                options.onToolStep?.({ verb: "click", target: verb.target, ok: false, observation: "Could not find that element on the page." });
+                return;
+            }
+            (0, element_ladder_1.highlightElement)(el);
+            el.click();
+            options.onToolStep?.({ verb: "click", target: verb.target, ok: true, observation: "Clicked it." });
+            return;
+        }
+        case "fill": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            const el = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
+            if (!el || !(0, element_ladder_1.fillElement)(el, verb.value)) {
+                (options.onMiss ?? element_ladder_1.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.",
+                });
+                return;
+            }
+            (0, element_ladder_1.highlightElement)(el);
+            options.onToolStep?.({ verb: "fill", target: verb.target, ok: true, observation: `Typed "${verb.value}" into it.` });
+            return;
+        }
+        case "read": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            const el = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
+            if (!el) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                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: (0, element_ladder_1.readElement)(el) });
+            return;
+        }
+        case "call_tool": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            void (0, webmcp_client_1.executeWebMcpTool)(verb.name, verb.args).then((result) => {
+                options.onToolStep?.({ verb: "call_tool", target: verb.name, ok: result.ok, observation: result.observation });
+            });
+            return;
+        }
     }
 }
 /**

package/dist/webmcp-client.d.ts

@@ -0,0 +1,13 @@
+import type { WebMcpTool } from "@cairnvibe/core";
+export declare function discoverWebMcpTools(): Promise<WebMcpTool[]>;
+/**
+ * Calls a real WebMCP tool by name — `name` must be one the model was
+ * actually shown this turn (server.ts only ever includes tools from this
+ * exact request's own discoverWebMcpTools() call), never invented.
+ * Returns a plain-text observation for the agent loop to reason about
+ * next, the same shape a click/fill/read result already takes.
+ */
+export declare function executeWebMcpTool(name: string, args: Record<string, unknown> | undefined): Promise<{
+    ok: boolean;
+    observation: string;
+}>;

package/dist/webmcp-client.js

@@ -0,0 +1,70 @@
+"use strict";
+// Discovers and calls real tools a page has registered via WebMCP
+// (https://webmachinelearning.github.io/webmcp/) — an in-progress web
+// standard letting a site expose its own functions as typed, parameterized
+// tools ("document.modelContext.registerTool(...)"), running in the page's
+// own JS with the user's real session. This is the highest-trust action
+// source there is: a real function the app's own developer wrote, with a
+// real return value — not a click simulated from static analysis. Almost
+// no site has adopted it yet, so this is deliberately a no-op (empty list,
+// nothing to call) everywhere it isn't present, not a hard dependency.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverWebMcpTools = discoverWebMcpTools;
+exports.executeWebMcpTool = executeWebMcpTool;
+function getModelContext() {
+    if (typeof document === "undefined")
+        return null;
+    return document.modelContext ?? null;
+}
+/** Bounded the same way LiveElementSchema/CopilotRequestSchema bound the
+ * live DOM scan — a hard cap on both count and description length, so a
+ * page that registers an unreasonable number of tools (or one with a huge
+ * description) can't blow the request payload or the prompt. */
+const MAX_TOOLS = 30;
+const MAX_DESCRIPTION_LENGTH = 500;
+async function discoverWebMcpTools() {
+    const modelContext = getModelContext();
+    if (!modelContext?.getTools)
+        return [];
+    try {
+        const tools = await modelContext.getTools();
+        if (!Array.isArray(tools))
+            return [];
+        return tools.slice(0, MAX_TOOLS).map((tool) => ({
+            name: String(tool.name),
+            description: String(tool.description ?? "").slice(0, MAX_DESCRIPTION_LENGTH),
+            inputSchema: tool.inputSchema,
+        }));
+    }
+    catch {
+        // A page's own registerTool()/getTools() implementation throwing is
+        // that page's bug, not Cairn's — degrade to "no WebMCP tools" rather
+        // than breaking the rest of the turn.
+        return [];
+    }
+}
+/**
+ * Calls a real WebMCP tool by name — `name` must be one the model was
+ * actually shown this turn (server.ts only ever includes tools from this
+ * exact request's own discoverWebMcpTools() call), never invented.
+ * Returns a plain-text observation for the agent loop to reason about
+ * next, the same shape a click/fill/read result already takes.
+ */
+async function executeWebMcpTool(name, args) {
+    const modelContext = getModelContext();
+    if (!modelContext?.getTools || !modelContext.executeTool) {
+        return { ok: false, observation: "This page no longer has that tool available." };
+    }
+    try {
+        const tools = await modelContext.getTools();
+        const tool = Array.isArray(tools) ? tools.find((t) => t.name === name) : undefined;
+        if (!tool)
+            return { ok: false, observation: `No tool named "${name}" is available on this page right now.` };
+        const result = await modelContext.executeTool(tool, args ?? {});
+        const observation = typeof result === "string" ? result : JSON.stringify(result ?? null);
+        return { ok: true, observation: observation.slice(0, 2000) };
+    }
+    catch (err) {
+        return { ok: false, observation: `That tool failed: ${err instanceof Error ? err.message : "unknown error"}` };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnvibe/sdk",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "In-app AI copilot — <Copilot/> for React/Next.js, <cairn-widget> for any framework — plus the server handlers and realtime voice relay behind them.",
   "license": "MIT",
   "publishConfig": { "access": "public" },

package/src/element-ladder.ts

@@ -1,12 +1,19 @@
-// The 4-step Element Ladder (BUILD_PLAN.md invariant #3): a lookup failure
-// must degrade to explain-only, never guess and click the wrong thing.
+// The Element Ladder (BUILD_PLAN.md invariant #3): a lookup failure must
+// degrade to explain-only, never guess and click the wrong thing.
 //
+//   0. liveElements map  — a runtime-scan.ts snapshot, when the caller has
+//      one: the id came from real elements the browser itself found this
+//      turn (a dynamically-rendered row with no data-ai included), so an
+//      exact map lookup is both the fastest and the most trustworthy path.
 //   1. data-ai="..."     — exact, authoritative
 //   2. aria-label / role — accessible-name fallback
 //   3. visible text      — last resort, exact then substring match
 //   4. FAIL               — caller degrades to explain + logs the miss
 
-export function findElement(target: string): HTMLElement | null {
+export function findElement(target: string, liveElements?: Map<string, HTMLElement>): HTMLElement | null {
+  const live = liveElements?.get(target);
+  if (live) return live;
+
   if (typeof document === "undefined") return null;
 
   const byDataAi = document.querySelector<HTMLElement>(`[data-ai="${cssEscape(target)}"]`);
@@ -39,6 +46,47 @@ export function highlightElement(el: HTMLElement, glowMs = 4000): void {
   window.setTimeout(() => el.classList.remove("cairn-glow"), glowMs);
 }
 
+// tagName, not `instanceof HTMLInputElement` — avoids depending on those
+// classes existing as globals at all (they don't in a plain Node test
+// environment, only a real browser/jsdom), and tagName is exactly what
+// distinguishes a real form field regardless.
+function isFormField(el: HTMLElement): el is HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement {
+  return el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.tagName === "SELECT";
+}
+
+/**
+ * Sets a real form field's value AND makes the framework that owns it (React,
+ * almost always, in this SDK's own target apps) actually notice — directly
+ * assigning `.value` bypasses React's tracked setter, so its own onChange
+ * never fires and the app's state silently doesn't update, a well-known
+ * React quirk. Going through the *native* prototype's value setter before
+ * dispatching a real "input" event is what makes React's synthetic event
+ * system pick it up the same way a real keystroke would.
+ */
+export function fillElement(el: HTMLElement, value: string): boolean {
+  if (!isFormField(el)) return false;
+
+  const ctorByTag: Record<string, unknown> = typeof window !== "undefined" ? { INPUT: window.HTMLInputElement, TEXTAREA: window.HTMLTextAreaElement, SELECT: window.HTMLSelectElement } : {};
+  const ctor = ctorByTag[el.tagName] as { prototype: object } | undefined;
+  const nativeSetter = ctor && (Object.getOwnPropertyDescriptor(ctor.prototype, "value")?.set as ((this: HTMLElement, v: string) => void) | undefined);
+  if (nativeSetter) nativeSetter.call(el, value);
+  else el.value = value;
+
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+  return true;
+}
+
+/** The real current value/text of an element — a form field's `.value`,
+ * otherwise its trimmed visible text, bounded the same way runtime-scan.ts
+ * bounds a live element's label (this is what the agent loop "observes"
+ * after a read step, so it needs the same payload/privacy discipline). */
+export function readElement(el: HTMLElement): string {
+  const raw = isFormField(el) ? el.value : (el.textContent ?? "");
+  const trimmed = raw.replace(/\s+/g, " ").trim();
+  return trimmed.length > 500 ? `${trimmed.slice(0, 499)}…` : trimmed || "(empty)";
+}
+
 export interface MissContext {
   attempted: string;
   route: string;