@cairnvibe/sdk 0.2.13 → 0.4.0

package/dist/verb-executor.js

@@ -10,20 +10,35 @@ exports.executeToolStep = executeToolStep;
 exports.executeVerbResponse = executeVerbResponse;
 const core_1 = require("@cairnvibe/core");
 const element_ladder_1 = require("./element-ladder");
+const cursor_overlay_1 = require("./cursor-overlay");
 const webmcp_client_1 = require("./webmcp-client");
+// wait_for's own real, bounded retry budget — longer than
+// findElementWithRetry's own default (2 attempts, 300ms apart, ~300ms
+// total), since this verb exists specifically for "I know something
+// async should show up" — a toast, a panel appearing after a click — not
+// the incidental transient-miss recovery findElementWithRetry's default
+// already covers for click/fill/batch steps.
+const WAIT_FOR_ATTEMPTS = 6;
+const WAIT_FOR_DELAY_MS = 500;
 /**
  * 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).
  */
-function executeToolStep(raw, route, liveElements) {
+function executeToolStep(raw, route, liveElements, onNavigate, onConfirmTool) {
     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,
+        // already confirming (via isTerminalVerb) 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
@@ -32,6 +47,8 @@ function executeToolStep(raw, route, liveElements) {
         executeVerbResponse(raw, route, {
             onExplain: () => { },
             liveElements,
+            onNavigate,
+            onConfirmTool,
             onToolStep: (result) => {
                 clearTimeout(timer);
                 resolve(result);
@@ -62,19 +79,49 @@ function dispatchVerb(verb, route, options) {
                 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);
+            // 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 (0, cursor_overlay_1.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;
         }
-        case "navigate":
+        case "navigate": {
+            // Real, live-reported gap this closes: navigate used to ALWAYS end
+            // the turn the instant it fired, even for a compound goal like "buy
+            // earbuds" that needs navigate, then search, then a real report
+            // back — see isTerminalVerb's own doc comment in @cairnvibe/core.
+            // `options.onToolStep` is only ever set by executeToolStep's own
+            // continuing-step wrapper — handleVerb's options never provide it —
+            // so this branch can only run when the caller already confirmed
+            // (via isTerminalVerb) that this navigate was genuinely marked
+            // continueAfter; the defensive `verb.continueAfter` check here is
+            // belt-and-suspenders, not the real gate.
+            if (verb.continueAfter && options.onToolStep) {
+                if (verb.text)
+                    options.onExplain(verb.text);
+                options.onNavigate?.(verb.route);
+                // A client-side route change is itself an async re-render (a new
+                // page's whole DOM mounting) — same real race waitForDomSettle
+                // already closes for fill/click, arguably more likely here. The
+                // NEXT resolveVerb call needs the settled new page's context, not
+                // whatever was on screen the instant router.push was called.
+                void (0, element_ladder_1.waitForDomSettle)(300, 200, 2000).then(() => {
+                    options.onToolStep?.({ verb: "navigate", target: verb.route, ok: true, observation: `Navigated to ${verb.route}.` });
+                });
+                return;
+            }
             options.onNavigate?.(verb.route);
             if (verb.text)
                 options.onExplain(verb.text);
             return;
+        }
         case "do": {
             const allowed = options.registeredActions ?? [];
             if (allowed.includes(verb.action)) {
@@ -101,9 +148,11 @@ function dispatchVerb(verb, route, options) {
                     // 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);
-                    el.click();
-                    if (verb.text)
-                        options.onExplain(verb.text);
+                    void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                        el.click();
+                        if (verb.text)
+                            options.onExplain(verb.text);
+                    });
                     return;
                 }
                 if (verb.target)
@@ -148,26 +197,48 @@ function dispatchVerb(verb, route, options) {
                 return;
             }
             (0, element_ladder_1.highlightElement)(el);
-            el.click();
-            options.onToolStep?.({ verb: "click", target: verb.target, ok: true, observation: "Clicked it." });
+            void (0, cursor_overlay_1.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 (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    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)) {
+            if (!el) {
                 (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.",
-                });
+                options.onToolStep?.({ verb: "fill", target: verb.target, ok: false, observation: "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.` });
+            // 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 (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                if (!(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: "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 (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "fill", target: verb.target, ok: true, observation: `Typed "${verb.value}" into it.` });
+                });
+            });
             return;
         }
         case "read": {
@@ -179,17 +250,138 @@ function dispatchVerb(verb, route, options) {
                 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) });
+            // 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 (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                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) => {
+            void (0, webmcp_client_1.executeWebMcpTool)(verb.name, verb.args, options.onConfirmTool).then((result) => {
                 options.onToolStep?.({ verb: "call_tool", target: verb.name, ok: result.ok, observation: result.observation });
             });
             return;
         }
+        case "drag": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            const from = (0, element_ladder_1.findElement)(verb.target, options.liveElements);
+            const to = from ? (0, element_ladder_1.findElement)(verb.to, options.liveElements) : null;
+            if (!from || !to) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: from ? verb.to : verb.target, route });
+                options.onToolStep?.({ verb: "drag", target: verb.target, ok: false, observation: from ? "Could not find the drop destination on the page." : "Could not find that element on the page." });
+                return;
+            }
+            (0, element_ladder_1.highlightElement)(from);
+            void (0, cursor_overlay_1.moveCursorTo)(from).then(() => {
+                (0, element_ladder_1.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 (0, cursor_overlay_1.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 (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "drag", target: verb.target, ok: true, observation: `Dragged it to ${verb.to}.` });
+                });
+            });
+            return;
+        }
+        case "select": {
+            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: "select", target: verb.target, ok: false, observation: "Could not find that element on the page." });
+                return;
+            }
+            (0, element_ladder_1.highlightElement)(el);
+            // 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 (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                if (!(0, element_ladder_1.selectOption)(el, verb.value)) {
+                    (options.onMiss ?? element_ladder_1.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 (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "select", target: verb.target, ok: true, observation: `Selected "${verb.value}".` });
+                });
+            });
+            return;
+        }
+        case "key": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            const el = verb.target ? (0, element_ladder_1.findElement)(verb.target, options.liveElements) : document.activeElement;
+            if (!el) {
+                if (verb.target)
+                    (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                options.onToolStep?.({ verb: "key", target: verb.target, ok: false, observation: "Could not find that element on the page." });
+                return;
+            }
+            const afterMove = () => {
+                (0, element_ladder_1.pressKey)(el, verb.key);
+                void (0, element_ladder_1.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 (0, cursor_overlay_1.moveCursorTo)(el).then(afterMove);
+            }
+            else {
+                afterMove();
+            }
+            return;
+        }
+        case "scroll": {
+            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: "scroll", target: verb.target, ok: false, observation: "Could not find that element on the page." });
+                return;
+            }
+            // A real, already-known element (never a coordinate or something
+            // not yet discovered) — highlightElement's own scrollIntoView is
+            // exactly the real repositioning this verb exists for; the glow
+            // also gives the user a visible cue of where the agent just moved.
+            (0, element_ladder_1.highlightElement)(el);
+            void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                void (0, element_ladder_1.waitForDomSettle)().then(() => {
+                    options.onToolStep?.({ verb: "scroll", target: verb.target, ok: true, observation: "Scrolled it into view." });
+                });
+            });
+            return;
+        }
+        case "wait_for": {
+            if (verb.text)
+                options.onExplain(verb.text);
+            void (0, element_ladder_1.findElementWithRetry)(verb.target, options.liveElements, WAIT_FOR_ATTEMPTS, WAIT_FOR_DELAY_MS).then((el) => {
+                if (!el) {
+                    (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                    options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: false, observation: "It never appeared." });
+                    return;
+                }
+                void (0, cursor_overlay_1.moveCursorTo)(el).then(() => {
+                    options.onToolStep?.({ verb: "wait_for", target: verb.target, ok: true, observation: "It appeared." });
+                });
+            });
+            return;
+        }
         // Several click/fill/read/call_tool steps in one round trip instead of
         // one each — server.ts's resolveVerb already validated every action's
         // target/name against real state before this ever arrived. Runs in
@@ -212,48 +404,132 @@ async function executeBatchActions(actions, route, options) {
     const steps = [];
     for (const action of actions) {
         const result = await executeOneBatchAction(action, route, options);
-        steps.push(`${action.verb} ${"target" in action ? action.target : action.name}: ${result.observation}`);
+        const label = ("target" in action && action.target) || ("name" in action && action.name) || "(focused element)";
+        steps.push(`${action.verb} ${label}: ${result.observation}`);
         if (!result.ok)
             return { ok: false, observation: steps.join(" | ") };
     }
     return { ok: true, observation: steps.join(" | ") };
 }
+// Phase 3 step 4 — real, bounded, LLM-free retry latitude for the
+// Executor's own lookups (CODA's own point: the Executor stays
+// opinion-free; anything requiring judgment escalates to the Critic,
+// which now genuinely exists as of step 3). Scoped to batch specifically,
+// per the plan's own build order — a batch's later steps are the ones
+// most likely to race a DOM update the batch's OWN earlier step just
+// triggered, which is exactly the "stale re-render" case this recovers
+// from; single-step click/fill/read stay unchanged (findElement, no
+// retry) rather than widening scope beyond what was actually planned.
 async function executeOneBatchAction(action, route, options) {
     switch (action.verb) {
         case "click": {
-            const el = (0, element_ladder_1.findElement)(action.target, options.liveElements);
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
             if (!el) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
                 return { ok: false, observation: "Could not find that element on the page." };
             }
             (0, element_ladder_1.highlightElement)(el);
+            await (0, cursor_overlay_1.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
+            // step often deliberately reads what THIS step just changed.
+            await (0, element_ladder_1.waitForDomSettle)();
             return { ok: true, observation: "Clicked it." };
         }
         case "fill": {
-            const el = (0, element_ladder_1.findElement)(action.target, options.liveElements);
-            if (!el || !(0, element_ladder_1.fillElement)(el, action.value)) {
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
+            if (!el) {
                 (options.onMiss ?? element_ladder_1.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." };
             }
             (0, element_ladder_1.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 (0, cursor_overlay_1.moveCursorTo)(el);
+            if (!(0, element_ladder_1.fillElement)(el, action.value)) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: "That element isn't a real form field — can't type into it." };
+            }
+            await (0, element_ladder_1.waitForDomSettle)();
             return { ok: true, observation: `Typed "${action.value}" into it.` };
         }
         case "read": {
-            const el = (0, element_ladder_1.findElement)(action.target, options.liveElements);
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
             if (!el) {
                 (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
                 return { ok: false, observation: "Could not find that element on the page." };
             }
+            await (0, cursor_overlay_1.moveCursorTo)(el);
             return { ok: true, observation: (0, element_ladder_1.readElement)(el) };
         }
         case "call_tool": {
-            const result = await (0, webmcp_client_1.executeWebMcpTool)(action.name, action.args);
+            const result = await (0, webmcp_client_1.executeWebMcpTool)(action.name, action.args, options.onConfirmTool);
             return { ok: result.ok, observation: result.observation };
         }
+        case "drag": {
+            const from = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
+            const to = from ? await (0, element_ladder_1.findElementWithRetry)(action.to, options.liveElements) : null;
+            if (!from || !to) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: from ? action.to : action.target, route });
+                return { ok: false, observation: from ? "Could not find the drop destination on the page." : "Could not find that element on the page." };
+            }
+            (0, element_ladder_1.highlightElement)(from);
+            await (0, cursor_overlay_1.moveCursorTo)(from);
+            (0, element_ladder_1.dragElement)(from, to);
+            void (0, cursor_overlay_1.moveCursorTo)(to); // visual echo of the drop point — not awaited, purely decorative
+            await (0, element_ladder_1.waitForDomSettle)();
+            return { ok: true, observation: `Dragged it to ${action.to}.` };
+        }
+        case "select": {
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
+            if (!el) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: "Could not find that element on the page." };
+            }
+            (0, element_ladder_1.highlightElement)(el);
+            await (0, cursor_overlay_1.moveCursorTo)(el);
+            if (!(0, element_ladder_1.selectOption)(el, action.value)) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: `Could not find an option matching "${action.value}".` };
+            }
+            await (0, element_ladder_1.waitForDomSettle)();
+            return { ok: true, observation: `Selected "${action.value}".` };
+        }
+        case "key": {
+            const el = action.target ? await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements) : document.activeElement;
+            if (!el) {
+                if (action.target)
+                    (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: "Could not find that element on the page." };
+            }
+            if (action.target)
+                await (0, cursor_overlay_1.moveCursorTo)(el);
+            (0, element_ladder_1.pressKey)(el, action.key);
+            await (0, element_ladder_1.waitForDomSettle)();
+            return { ok: true, observation: `Pressed ${action.key}.` };
+        }
+        case "scroll": {
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements);
+            if (!el) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: "Could not find that element on the page." };
+            }
+            (0, element_ladder_1.highlightElement)(el);
+            await (0, cursor_overlay_1.moveCursorTo)(el);
+            await (0, element_ladder_1.waitForDomSettle)();
+            return { ok: true, observation: "Scrolled it into view." };
+        }
+        case "wait_for": {
+            const el = await (0, element_ladder_1.findElementWithRetry)(action.target, options.liveElements, WAIT_FOR_ATTEMPTS, WAIT_FOR_DELAY_MS);
+            if (!el) {
+                (options.onMiss ?? element_ladder_1.logMiss)({ attempted: action.target, route });
+                return { ok: false, observation: "It never appeared." };
+            }
+            await (0, cursor_overlay_1.moveCursorTo)(el);
+            return { ok: true, observation: "It appeared." };
+        }
     }
 }
 /**

package/dist/webmcp-client.d.ts

@@ -6,8 +6,21 @@ export declare function discoverWebMcpTools(): Promise<WebMcpTool[]>;
  * 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.
+ *
+ * Architecture Pillar 6 (the safety layer) — `confirmTool` is only ever
+ * consulted for a tool whose OWN registration declared `riskTier:
+ * "confirm"` (never something the model or this call site can widen) — a
+ * real-world-effect tool (a payment, a delete, anything hard to undo)
+ * that must get a genuine yes from the END USER before it runs, not just
+ * the model's own decision to call it. No `confirmTool` provided (a host
+ * app that hasn't wired up a confirmation UI) is treated as a decline,
+ * never as an implicit yes — the safe default when there's no real way
+ * to ask.
  */
-export declare function executeWebMcpTool(name: string, args: Record<string, unknown> | undefined): Promise<{
+export declare function executeWebMcpTool(name: string, args: Record<string, unknown> | undefined, confirmTool?: (tool: {
+    name: string;
+    description: string;
+}) => Promise<boolean>): Promise<{
     ok: boolean;
     observation: string;
 }>;

package/dist/webmcp-client.js

@@ -34,6 +34,11 @@ async function discoverWebMcpTools() {
             name: String(tool.name),
             description: String(tool.description ?? "").slice(0, MAX_DESCRIPTION_LENGTH),
             inputSchema: tool.inputSchema,
+            // Architecture Pillar 6 — passed through only when the page's own
+            // registration declared a real "confirm" tier; anything else
+            // (absent, or a value that isn't literally "confirm") stays
+            // undefined/"safe" — never invented, never widened by a typo.
+            riskTier: tool.riskTier === "confirm" ? "confirm" : undefined,
         }));
     }
     catch {
@@ -49,8 +54,18 @@ async function discoverWebMcpTools() {
  * 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.
+ *
+ * Architecture Pillar 6 (the safety layer) — `confirmTool` is only ever
+ * consulted for a tool whose OWN registration declared `riskTier:
+ * "confirm"` (never something the model or this call site can widen) — a
+ * real-world-effect tool (a payment, a delete, anything hard to undo)
+ * that must get a genuine yes from the END USER before it runs, not just
+ * the model's own decision to call it. No `confirmTool` provided (a host
+ * app that hasn't wired up a confirmation UI) is treated as a decline,
+ * never as an implicit yes — the safe default when there's no real way
+ * to ask.
  */
-async function executeWebMcpTool(name, args) {
+async function executeWebMcpTool(name, args, confirmTool) {
     const modelContext = getModelContext();
     if (!modelContext?.getTools || !modelContext.executeTool) {
         return { ok: false, observation: "This page no longer has that tool available." };
@@ -60,6 +75,12 @@ async function executeWebMcpTool(name, args) {
         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.` };
+        if (tool.riskTier === "confirm") {
+            const confirmed = confirmTool ? await confirmTool({ name: tool.name, description: tool.description ?? "" }) : false;
+            if (!confirmed) {
+                return { ok: false, observation: "This action needs the user's real confirmation before it can run, and it wasn't confirmed." };
+            }
+        }
         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) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnvibe/sdk",
-  "version": "0.2.13",
+  "version": "0.4.0",
   "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" },
@@ -23,6 +23,8 @@
     "./server": "./dist/server.js",
     "./dashboard": "./dist/dashboard.js",
     "./dashboard-sqlite": "./dist/dashboard-sqlite.js",
+    "./memory-sqlite": "./dist/memory-sqlite.js",
+    "./skill-store": "./dist/skill-store.js",
     "./transcribe-server": "./dist/transcribe-server.js",
     "./speak-server": "./dist/speak-server.js",
     "./realtime-server": "./dist/realtime-server.js",