@mindstudio-ai/remy 0.1.265 → 0.1.266

package/README.md

@@ -265,6 +265,8 @@ The headless IPC protocol uses request correlation and a unified response patter
 - System events (lifecycle, shutdown) never have a `requestId`
 - Every command ends with exactly one `completed` event: `{event:"completed", requestId, success, error?}`
 - Messages sent while a turn is running are queued. When the turn ends, all contiguous queued user messages and background results are delivered together as **one merged turn**: the first queued message's `requestId` becomes the turn's primary id (stamped on `turn_started` and all streaming events), each absorbed message echoes its own `user_message` with its original `requestId` and `queued: true`, and at turn end the primary `completed` is emitted first, followed immediately by one `completed {…same outcome, absorbed: true}` per other absorbed `requestId`. Automated-action (`@@automated::…@@`) messages and chain steps never merge — they always run one turn each.
+- A queued **user** message can be promoted to ASAP delivery via `setQueuedDelivery`. ASAP items are pulled into the **running** turn at its next tool boundary (injected as plain user messages — no abort, no restart), echo `user_message` with `queued: true` and their own `requestId`, and get a `{…, absorbed: true}` completed with the turn's outcome at turn end. Promotion deliberately jumps ahead of anything else in the queue, including chain steps. If the turn ends before injection, the tag is ignored and the item drains in normal FIFO order.
+- Background tool completions have two delivery classes (per-tool `backgroundNotify` on the tool definition). `wake` (default): the result is queued as a `background_results` message and may start a turn when the agent is idle. `passive` (e.g. `specSync`): the result never enters the queue and never wakes the agent — it parks in a persisted holding pen and rides the next real turn as a hidden `background_results` entry (so it never appears in `queuedMessages`, never affects queue-derived busy state, and never triggers resume-on-restart). Both classes emit `tool_background_complete` immediately.
 - The caller distinguishes command responses from system events with a single check: `if (msg.requestId)`
 
 This enables a simple promise-based RPC layer: send a command with a unique ID, store a pending promise keyed by that ID, resolve it when you see `completed` with the matching ID.
@@ -327,6 +329,14 @@ Cancel pending **queued** messages without touching the in-flight turn. Omit `id
 {"action": "cancelQueued", "requestId": "r6", "id": "r2"}
 ```
 
+#### `setQueuedDelivery`
+
+Change a queued message's delivery semantics: `"asap"` (inject into the running turn at its next tool boundary) or `"afterTurn"` (default — wait for the turn to end). `id` is the `requestId` of a queued message. Only plain queued **user** messages qualify; automated-action messages and chain/background items respond `completed(success:false, error:"message not found or not promotable")` — as does an item already consumed by the running turn. On success a `queue_changed` event carries the updated snapshot (each item's `delivery` field rides on it).
+
+```json
+{"action": "setQueuedDelivery", "requestId": "r7", "id": "r2", "delivery": "asap"}
+```
+
 #### `clear`
 
 Clear conversation history and delete the session file.
@@ -353,7 +363,7 @@ Events are emitted as newline-delimited JSON. Command responses include `request
 |-------|--------|-------------|
 | `ready` | | Headless mode initialized, ready for input |
 | `session_restored` | `messageCount` | Previous session loaded |
-| `queue_changed` | `queuedMessages` | Queue contents changed (any push/shift/drain/cancel). Carries the full current snapshot — an empty array when the queue drains. The live queue-state signal; for the initial snapshot on connect/reconnect, read `queuedMessages` from `get_history`. |
+| `queue_changed` | `queuedMessages` | Queue contents changed (any push/shift/drain/cancel/retag). Carries the full current snapshot — an empty array when the queue drains. Items carry `delivery: "asap"` when promoted (absent = after-turn). The live queue-state signal; for the initial snapshot on connect/reconnect, read `queuedMessages` from `get_history`. |
 | `stopping` | | Shutdown initiated |
 | `stopped` | | Shutdown complete |
 
@@ -365,7 +375,7 @@ All command responses include the `requestId` from the originating command.
 |-------|--------|-------------|
 | `text` | `text`, `parentToolId?` | Streaming text chunk |
 | `thinking` | `text`, `parentToolId?` | Agent's internal reasoning |
-| `user_message` | `text`, `attachments?`, `queued?` | Echo of a user message entering the turn. Queue-delivered messages carry `queued: true` and their own original `requestId` (a merged turn emits one per absorbed message); idle sends echo with the turn's requestId and no `queued` flag. |
+| `user_message` | `text`, `attachments?`, `queued?`, `hidden?` | Echo of a user message entering the turn. Queue-delivered messages (including ASAP items injected mid-turn) carry `queued: true` and their own original `requestId` (a merged turn emits one per absorbed message); idle sends echo with the turn's requestId and no `queued` flag. `hidden: true` marks internal entries (e.g. passive background results) that should not render. |
 | `tool_start` | `id`, `name`, `input`, `partial?`, `parentToolId?` | Tool execution started. `partial: true` means more `tool_start` events will follow for this id (progressive input streaming). |
 | `tool_input_delta` | `id`, `name`, `result`, `parentToolId?` | Progressive tool content (streaming tools only) |
 | `tool_done` | `id`, `name`, `result`, `isError`, `parentToolId?` | Tool execution completed |

package/dist/headless.d.ts

@@ -70,6 +70,15 @@ declare class HeadlessSession {
      * to .remy-stats.json so queued work survives process restarts.
      */
     private queue;
+    /**
+     * Holding pen for passive background results (tools with
+     * `backgroundNotify: 'passive'`, e.g. specSync). Deliberately outside the
+     * message queue: pen contents never initiate a turn, never latch the
+     * sandbox's queue-derived busy state, and never trigger resume-on-restart.
+     * Swept into the next real turn as a hidden background_results entry.
+     * Persisted to .remy-stats.json alongside the queue.
+     */
+    private passivePen;
     private pendingTools;
     private earlyResults;
     private pendingBlockUpdates;
@@ -87,7 +96,7 @@ declare class HeadlessSession {
     private primaryOutcome;
     /** Dispatch a simple (non-streaming) command: call handler, emit response + completed. */
     private dispatchSimple;
-    /** Persist sessionStats + queue snapshot to .remy-stats.json. */
+    /** Persist sessionStats + queue snapshot + passive pen to .remy-stats.json. */
     private persistStats;
     /** Apply queued tool block updates to state.messages. Safe to call any time. */
     private applyPendingBlockUpdates;

package/dist/headless.js

@@ -4099,7 +4099,7 @@ var BROWSER_TOOLS = [
                   "screenshotViewport",
                   "setViewport"
                 ],
-                description: 'snapshot: accessibility tree of the page (waits for network to settle). click: click an element (animated cursor, full event sequence). type: type text into input (one char at a time, works with React/Vue/Svelte). select: select a dropdown option by text. wait: wait for an element to appear (polls 100ms, waits for network). navigate: navigate to a URL within the app (waits for load, subsequent steps run on new page). evaluate: run JS in the page. styles: read computed CSS styles from elements (pass properties array with camelCase names, or omit for defaults). screenshotFullPage: screenshot of the whole page top-to-bottom (returns a CDN url with dimensions and a written analysis). screenshotViewport: screenshot of just the visible viewport \u2014 pass `scrollToSelector` (or `scrollY`) on this step to scroll a section into view and capture it in one atomic step (no separate scroll needed). setViewport: switch the browser between desktop and mobile rendering (pass `mode`: "desktop" or "mobile"). Reloads the page so responsive layouts, media queries, and matchMedia re-evaluate \u2014 use it to QA mobile/responsive views.'
+                description: 'snapshot: accessibility tree of the page (waits for network to settle). click: click an element (animated cursor, full event sequence). type: type text into input (one char at a time, works with React/Vue/Svelte). select: select a dropdown option by text. wait: wait for an element to appear (polls 100ms, waits for network). navigate: navigate to a URL within the app (waits for the route, subsequent steps run on the new page; soft in-app route change by default \u2014 pass `fresh: true` for a real full page load; the result reports the URL actually landed on, so app redirects are visible). evaluate: run JS in the page. styles: read computed CSS styles from elements (pass properties array with camelCase names, or omit for defaults). screenshotFullPage: screenshot of the whole page top-to-bottom (returns a CDN url with dimensions and a written analysis). screenshotViewport: screenshot of just the visible viewport \u2014 pass `scrollToSelector` (or `scrollY`) on this step to scroll a section into view and capture it in one atomic step (no separate scroll needed). setViewport: switch the browser between desktop and mobile rendering (pass `mode`: "desktop" or "mobile"). Reloads the page so responsive layouts, media queries, and matchMedia re-evaluate \u2014 use it to QA mobile/responsive views.'
               },
               ref: {
                 type: "string",
@@ -4141,6 +4141,10 @@ var BROWSER_TOOLS = [
                 type: "string",
                 description: 'For navigate: the URL to navigate to (e.g., "/quiz", "/settings").'
               },
+              fresh: {
+                type: "boolean",
+                description: "For navigate: force a real full page load (fresh document) instead of a soft in-app route change. Use when testing what a user sees on entry \u2014 landing pages, join/invite links, signed-out views \u2014 where reusing the SPA\u2019s in-memory state would test the wrong thing."
+              },
               properties: {
                 type: "array",
                 items: { type: "string" },
@@ -5955,10 +5959,13 @@ ${readAsset(
 </mindstudio_flavored_markdown_spec_docs>`;
 var specSyncTool = {
   backgroundOnly: true,
+  // Fire-and-forget: completion never wakes the agent. The outcome rides the
+  // next real turn as a hidden background_results note instead.
+  backgroundNotify: "passive",
   definition: {
     clearable: false,
     name: "specSync",
-    description: "Reconcile the spec to bring it in line with code changes you have made. Provide a brief, bulleted list of what changed and why; it finds the affected spec sections and updates them to match. Always runs in the background \u2014 it returns immediately and reports back when done.",
+    description: "Reconcile the spec to bring it in line with code changes you have made. Provide a brief, bulleted list of what changed and why; it finds the affected spec sections and updates them to match. Always runs in the background and completes silently \u2014 do not wait for it; its outcome appears as an automated note at the start of a later turn.",
     inputSchema: {
       type: "object",
       properties: {
@@ -7627,6 +7634,7 @@ async function runTurn(params) {
     onboardingState,
     signal,
     onEvent,
+    takeSteering,
     resolveExternalTool,
     requestId,
     toolRegistry,
@@ -7661,7 +7669,7 @@ async function runTurn(params) {
     onEvent({ type: "error", error: "Empty message" });
     return;
   }
-  for (const entry of keptEntries) {
+  const appendEntry = (entry) => {
     const hasAttachments = (entry.attachments?.length ?? 0) > 0;
     const userMsg = { role: "user", content: entry.text };
     if (entry.hidden) {
@@ -7684,6 +7692,9 @@ async function runTurn(params) {
       ...entry.requestId && { requestId: entry.requestId },
       ...entry.queued && { queued: true }
     });
+  };
+  for (const entry of keptEntries) {
+    appendEntry(entry);
   }
   const isFirstMessage = state.messages.filter((m) => m.role === "user").length === 1;
   const STATUS_EXCLUDED_TOOLS = /* @__PURE__ */ new Set([
@@ -8200,6 +8211,18 @@ async function runTurn(params) {
         isToolError: r.isError
       });
     }
+    if (takeSteering && !signal?.aborted) {
+      const injected = (await takeSteering()).filter(
+        (e) => e.text.trim().length > 0 || (e.attachments?.length ?? 0) > 0
+      );
+      if (injected.length > 0) {
+        for (const entry of injected) {
+          appendEntry(entry);
+          keptEntries.push(entry);
+        }
+        saveSession(state);
+      }
+    }
     if (signal?.aborted) {
       onEvent({ type: "turn_cancelled" });
       saveSession(state);
@@ -8375,13 +8398,24 @@ function loadQueue() {
   }
   return [];
 }
-function writeStats(stats, queue) {
+function loadPassiveResults() {
+  try {
+    const stats = JSON.parse(readFileSync2(STATS_FILE, "utf-8"));
+    if (Array.isArray(stats.passiveResults)) {
+      return stats.passiveResults;
+    }
+  } catch {
+  }
+  return [];
+}
+function writeStats(stats, queue, passiveResults) {
   try {
     writeFileSync2(
       STATS_FILE,
       JSON.stringify({
         ...stats,
-        queue
+        queue,
+        passiveResults
       })
     );
   } catch {
@@ -8445,6 +8479,21 @@ var MessageQueue = class {
     }
     return removed;
   }
+  /**
+   * Change a queued item's delivery semantics, keyed by its command
+   * requestId. Fires onChange (→ persist + queue_changed) on success.
+   * Returns the item, or undefined if no queued item matches (e.g. it was
+   * already consumed).
+   */
+  setDelivery(id, delivery) {
+    const item = this.items.find((it) => it.command.requestId === id);
+    if (!item) {
+      return void 0;
+    }
+    item.delivery = delivery;
+    this.onChange?.();
+    return item;
+  }
   /** Copy of current queue contents (for surfacing on events). */
   snapshot() {
     return [...this.items];
@@ -8559,6 +8608,15 @@ var HeadlessSession = class {
    * to .remy-stats.json so queued work survives process restarts.
    */
   queue;
+  /**
+   * Holding pen for passive background results (tools with
+   * `backgroundNotify: 'passive'`, e.g. specSync). Deliberately outside the
+   * message queue: pen contents never initiate a turn, never latch the
+   * sandbox's queue-derived busy state, and never trigger resume-on-restart.
+   * Swept into the next real turn as a hidden background_results entry.
+   * Persisted to .remy-stats.json alongside the queue.
+   */
+  passivePen = [];
   // External tool bridge
   pendingTools = /* @__PURE__ */ new Map();
   earlyResults = /* @__PURE__ */ new Map();
@@ -8594,6 +8652,7 @@ var HeadlessSession = class {
       this.persistStats();
       this.emit("queue_changed", { queuedMessages: this.queue.snapshot() });
     });
+    this.passivePen = loadPassiveResults();
     if (resumed) {
       this.emit("session_restored", {
         messageCount: this.state.messages.length,
@@ -8705,10 +8764,10 @@ var HeadlessSession = class {
   //////////////////////////////////////////////////////////////////////////////
   // Stats + queue persistence
   //////////////////////////////////////////////////////////////////////////////
-  /** Persist sessionStats + queue snapshot to .remy-stats.json. */
+  /** Persist sessionStats + queue snapshot + passive pen to .remy-stats.json. */
   persistStats() {
     this.sessionStats.updatedAt = Date.now();
-    writeStats(this.sessionStats, this.queue.snapshot());
+    writeStats(this.sessionStats, this.queue.snapshot(), this.passivePen);
   }
   //////////////////////////////////////////////////////////////////////////////
   // Background completions (tool-block mutation; message delivery via queue)
@@ -8770,10 +8829,12 @@ var HeadlessSession = class {
     }
   }
   onBackgroundComplete = (toolCallId, name, result, subAgentMessages) => {
+    const notify = getToolByName(name)?.backgroundNotify ?? "wake";
     this.pendingBlockUpdates.push({ toolCallId, result, subAgentMessages });
     log16.info("Background complete", {
       toolCallId,
       name,
+      notify,
       requestId: this.currentRequestId
     });
     this.onEvent({
@@ -8782,6 +8843,14 @@ var HeadlessSession = class {
       name,
       result
     });
+    if (notify === "passive") {
+      this.passivePen.push({ toolCallId, name, result });
+      this.persistStats();
+      if (!this.running) {
+        this.applyPendingBlockUpdates();
+      }
+      return;
+    }
     this.queue.push({
       command: {
         action: "message",
@@ -8850,7 +8919,10 @@ var HeadlessSession = class {
             ...e.attachments && { attachments: e.attachments },
             // Queue-delivered entries are flagged so the frontend renders the
             // echo (idle sends are rendered optimistically instead).
-            ...e.queued && { queued: true }
+            ...e.queued && { queued: true },
+            // Hidden entries (e.g. the passive background_results sweep) are
+            // flagged so the sandbox/frontend suppress the bubble.
+            ...e.hidden && { hidden: true }
           },
           // A merged turn emits one user_message per absorbed entry — each
           // carries its own original requestId, not the turn's.
@@ -9160,6 +9232,37 @@ var HeadlessSession = class {
     this.completedEmitted = false;
     this.lastCompleted = null;
     this.turnStart = Date.now();
+    if (this.passivePen.length > 0) {
+      const swept = this.passivePen.splice(0);
+      this.persistStats();
+      entries.unshift({
+        text: buildBackgroundResultsMessage(swept),
+        hidden: true
+      });
+    }
+    const consumedRids = [];
+    const takeSteering = async () => {
+      const items = this.queue.removeWhere(
+        (it) => it.source === "user" && it.delivery === "asap" && !this.isDrainBarrier(it)
+      );
+      const steered = [];
+      for (const it of items) {
+        const attachments = it.command.attachments;
+        const attachmentHeader = await this.persistEntryAttachments(attachments);
+        const rid = it.command.requestId;
+        if (rid) {
+          consumedRids.push(rid);
+        }
+        steered.push({
+          text: it.command.text ?? "",
+          attachments,
+          attachmentHeader,
+          requestId: rid,
+          queued: true
+        });
+      }
+      return steered;
+    };
     await this.runForcedCompactionIfNeeded(requestId);
     try {
       await runTurn({
@@ -9173,6 +9276,7 @@ var HeadlessSession = class {
         requestId,
         signal: this.currentAbort.signal,
         onEvent: this.onEvent,
+        takeSteering,
         resolveExternalTool: this.resolveExternalTool,
         toolRegistry: this.toolRegistry,
         onBackgroundComplete: this.onBackgroundComplete
@@ -9202,7 +9306,7 @@ var HeadlessSession = class {
       });
     }
     const outcome = this.primaryOutcome();
-    for (const rid of absorbedRids) {
+    for (const rid of [...absorbedRids, ...consumedRids]) {
       this.emit(
         "completed",
         {
@@ -9497,6 +9601,33 @@ var HeadlessSession = class {
       );
       return;
     }
+    if (action === "setQueuedDelivery") {
+      const id = parsed.id;
+      const delivery = parsed.delivery;
+      if (!id || delivery !== "asap" && delivery !== "afterTurn") {
+        this.emit(
+          "completed",
+          {
+            success: false,
+            error: 'setQueuedDelivery requires id and delivery ("asap" | "afterTurn")'
+          },
+          requestId
+        );
+        return;
+      }
+      const target = this.queue.snapshot().find((it) => it.command.requestId === id);
+      if (!target || target.source !== "user" || this.isDrainBarrier(target)) {
+        this.emit(
+          "completed",
+          { success: false, error: "message not found or not promotable" },
+          requestId
+        );
+        return;
+      }
+      this.queue.setDelivery(id, delivery);
+      this.emit("completed", { success: true }, requestId);
+      return;
+    }
     if (action === "stop_tool") {
       const id = parsed.id;
       const mode = parsed.mode ?? "hard";

package/dist/index.js

@@ -4934,7 +4934,7 @@ var init_tools2 = __esm({
                       "screenshotViewport",
                       "setViewport"
                     ],
-                    description: 'snapshot: accessibility tree of the page (waits for network to settle). click: click an element (animated cursor, full event sequence). type: type text into input (one char at a time, works with React/Vue/Svelte). select: select a dropdown option by text. wait: wait for an element to appear (polls 100ms, waits for network). navigate: navigate to a URL within the app (waits for load, subsequent steps run on new page). evaluate: run JS in the page. styles: read computed CSS styles from elements (pass properties array with camelCase names, or omit for defaults). screenshotFullPage: screenshot of the whole page top-to-bottom (returns a CDN url with dimensions and a written analysis). screenshotViewport: screenshot of just the visible viewport \u2014 pass `scrollToSelector` (or `scrollY`) on this step to scroll a section into view and capture it in one atomic step (no separate scroll needed). setViewport: switch the browser between desktop and mobile rendering (pass `mode`: "desktop" or "mobile"). Reloads the page so responsive layouts, media queries, and matchMedia re-evaluate \u2014 use it to QA mobile/responsive views.'
+                    description: 'snapshot: accessibility tree of the page (waits for network to settle). click: click an element (animated cursor, full event sequence). type: type text into input (one char at a time, works with React/Vue/Svelte). select: select a dropdown option by text. wait: wait for an element to appear (polls 100ms, waits for network). navigate: navigate to a URL within the app (waits for the route, subsequent steps run on the new page; soft in-app route change by default \u2014 pass `fresh: true` for a real full page load; the result reports the URL actually landed on, so app redirects are visible). evaluate: run JS in the page. styles: read computed CSS styles from elements (pass properties array with camelCase names, or omit for defaults). screenshotFullPage: screenshot of the whole page top-to-bottom (returns a CDN url with dimensions and a written analysis). screenshotViewport: screenshot of just the visible viewport \u2014 pass `scrollToSelector` (or `scrollY`) on this step to scroll a section into view and capture it in one atomic step (no separate scroll needed). setViewport: switch the browser between desktop and mobile rendering (pass `mode`: "desktop" or "mobile"). Reloads the page so responsive layouts, media queries, and matchMedia re-evaluate \u2014 use it to QA mobile/responsive views.'
                   },
                   ref: {
                     type: "string",
@@ -4976,6 +4976,10 @@ var init_tools2 = __esm({
                     type: "string",
                     description: 'For navigate: the URL to navigate to (e.g., "/quiz", "/settings").'
                   },
+                  fresh: {
+                    type: "boolean",
+                    description: "For navigate: force a real full page load (fresh document) instead of a soft in-app route change. Use when testing what a user sees on entry \u2014 landing pages, join/invite links, signed-out views \u2014 where reusing the SPA\u2019s in-memory state would test the wrong thing."
+                  },
                   properties: {
                     type: "array",
                     items: { type: "string" },
@@ -7149,10 +7153,13 @@ ${readAsset(
 </mindstudio_flavored_markdown_spec_docs>`;
     specSyncTool = {
       backgroundOnly: true,
+      // Fire-and-forget: completion never wakes the agent. The outcome rides the
+      // next real turn as a hidden background_results note instead.
+      backgroundNotify: "passive",
       definition: {
         clearable: false,
         name: "specSync",
-        description: "Reconcile the spec to bring it in line with code changes you have made. Provide a brief, bulleted list of what changed and why; it finds the affected spec sections and updates them to match. Always runs in the background \u2014 it returns immediately and reports back when done.",
+        description: "Reconcile the spec to bring it in line with code changes you have made. Provide a brief, bulleted list of what changed and why; it finds the affected spec sections and updates them to match. Always runs in the background and completes silently \u2014 do not wait for it; its outcome appears as an automated note at the start of a later turn.",
         inputSchema: {
           type: "object",
           properties: {
@@ -8104,6 +8111,7 @@ async function runTurn(params) {
     onboardingState,
     signal,
     onEvent,
+    takeSteering,
     resolveExternalTool,
     requestId,
     toolRegistry,
@@ -8138,7 +8146,7 @@ async function runTurn(params) {
     onEvent({ type: "error", error: "Empty message" });
     return;
   }
-  for (const entry of keptEntries) {
+  const appendEntry = (entry) => {
     const hasAttachments = (entry.attachments?.length ?? 0) > 0;
     const userMsg = { role: "user", content: entry.text };
     if (entry.hidden) {
@@ -8161,6 +8169,9 @@ async function runTurn(params) {
       ...entry.requestId && { requestId: entry.requestId },
       ...entry.queued && { queued: true }
     });
+  };
+  for (const entry of keptEntries) {
+    appendEntry(entry);
   }
   const isFirstMessage = state.messages.filter((m) => m.role === "user").length === 1;
   const STATUS_EXCLUDED_TOOLS = /* @__PURE__ */ new Set([
@@ -8677,6 +8688,18 @@ async function runTurn(params) {
         isToolError: r.isError
       });
     }
+    if (takeSteering && !signal?.aborted) {
+      const injected = (await takeSteering()).filter(
+        (e) => e.text.trim().length > 0 || (e.attachments?.length ?? 0) > 0
+      );
+      if (injected.length > 0) {
+        for (const entry of injected) {
+          appendEntry(entry);
+          keptEntries.push(entry);
+        }
+        saveSession(state);
+      }
+    }
     if (signal?.aborted) {
       onEvent({ type: "turn_cancelled" });
       saveSession(state);
@@ -9244,13 +9267,24 @@ function loadQueue() {
   }
   return [];
 }
-function writeStats(stats, queue) {
+function loadPassiveResults() {
+  try {
+    const stats = JSON.parse(readFileSync2(STATS_FILE, "utf-8"));
+    if (Array.isArray(stats.passiveResults)) {
+      return stats.passiveResults;
+    }
+  } catch {
+  }
+  return [];
+}
+function writeStats(stats, queue, passiveResults) {
   try {
     writeFileSync2(
       STATS_FILE,
       JSON.stringify({
         ...stats,
-        queue
+        queue,
+        passiveResults
       })
     );
   } catch {
@@ -9325,6 +9359,21 @@ var init_messageQueue = __esm({
         }
         return removed;
       }
+      /**
+       * Change a queued item's delivery semantics, keyed by its command
+       * requestId. Fires onChange (→ persist + queue_changed) on success.
+       * Returns the item, or undefined if no queued item matches (e.g. it was
+       * already consumed).
+       */
+      setDelivery(id, delivery) {
+        const item = this.items.find((it) => it.command.requestId === id);
+        if (!item) {
+          return void 0;
+        }
+        item.delivery = delivery;
+        this.onChange?.();
+        return item;
+      }
       /** Copy of current queue contents (for surfacing on events). */
       snapshot() {
         return [...this.items];
@@ -9431,6 +9480,7 @@ var init_headless = __esm({
     init_attachments();
     init_planFile();
     init_stats();
+    init_tools8();
     init_messageQueue();
     init_resolve();
     init_sentinel();
@@ -9474,6 +9524,15 @@ var init_headless = __esm({
        * to .remy-stats.json so queued work survives process restarts.
        */
       queue;
+      /**
+       * Holding pen for passive background results (tools with
+       * `backgroundNotify: 'passive'`, e.g. specSync). Deliberately outside the
+       * message queue: pen contents never initiate a turn, never latch the
+       * sandbox's queue-derived busy state, and never trigger resume-on-restart.
+       * Swept into the next real turn as a hidden background_results entry.
+       * Persisted to .remy-stats.json alongside the queue.
+       */
+      passivePen = [];
       // External tool bridge
       pendingTools = /* @__PURE__ */ new Map();
       earlyResults = /* @__PURE__ */ new Map();
@@ -9509,6 +9568,7 @@ var init_headless = __esm({
           this.persistStats();
           this.emit("queue_changed", { queuedMessages: this.queue.snapshot() });
         });
+        this.passivePen = loadPassiveResults();
         if (resumed) {
           this.emit("session_restored", {
             messageCount: this.state.messages.length,
@@ -9620,10 +9680,10 @@ var init_headless = __esm({
       //////////////////////////////////////////////////////////////////////////////
       // Stats + queue persistence
       //////////////////////////////////////////////////////////////////////////////
-      /** Persist sessionStats + queue snapshot to .remy-stats.json. */
+      /** Persist sessionStats + queue snapshot + passive pen to .remy-stats.json. */
       persistStats() {
         this.sessionStats.updatedAt = Date.now();
-        writeStats(this.sessionStats, this.queue.snapshot());
+        writeStats(this.sessionStats, this.queue.snapshot(), this.passivePen);
       }
       //////////////////////////////////////////////////////////////////////////////
       // Background completions (tool-block mutation; message delivery via queue)
@@ -9685,10 +9745,12 @@ var init_headless = __esm({
         }
       }
       onBackgroundComplete = (toolCallId, name, result, subAgentMessages) => {
+        const notify = getToolByName(name)?.backgroundNotify ?? "wake";
         this.pendingBlockUpdates.push({ toolCallId, result, subAgentMessages });
         log16.info("Background complete", {
           toolCallId,
           name,
+          notify,
           requestId: this.currentRequestId
         });
         this.onEvent({
@@ -9697,6 +9759,14 @@ var init_headless = __esm({
           name,
           result
         });
+        if (notify === "passive") {
+          this.passivePen.push({ toolCallId, name, result });
+          this.persistStats();
+          if (!this.running) {
+            this.applyPendingBlockUpdates();
+          }
+          return;
+        }
         this.queue.push({
           command: {
             action: "message",
@@ -9765,7 +9835,10 @@ var init_headless = __esm({
                 ...e.attachments && { attachments: e.attachments },
                 // Queue-delivered entries are flagged so the frontend renders the
                 // echo (idle sends are rendered optimistically instead).
-                ...e.queued && { queued: true }
+                ...e.queued && { queued: true },
+                // Hidden entries (e.g. the passive background_results sweep) are
+                // flagged so the sandbox/frontend suppress the bubble.
+                ...e.hidden && { hidden: true }
               },
               // A merged turn emits one user_message per absorbed entry — each
               // carries its own original requestId, not the turn's.
@@ -10075,6 +10148,37 @@ var init_headless = __esm({
         this.completedEmitted = false;
         this.lastCompleted = null;
         this.turnStart = Date.now();
+        if (this.passivePen.length > 0) {
+          const swept = this.passivePen.splice(0);
+          this.persistStats();
+          entries.unshift({
+            text: buildBackgroundResultsMessage(swept),
+            hidden: true
+          });
+        }
+        const consumedRids = [];
+        const takeSteering = async () => {
+          const items = this.queue.removeWhere(
+            (it) => it.source === "user" && it.delivery === "asap" && !this.isDrainBarrier(it)
+          );
+          const steered = [];
+          for (const it of items) {
+            const attachments = it.command.attachments;
+            const attachmentHeader = await this.persistEntryAttachments(attachments);
+            const rid = it.command.requestId;
+            if (rid) {
+              consumedRids.push(rid);
+            }
+            steered.push({
+              text: it.command.text ?? "",
+              attachments,
+              attachmentHeader,
+              requestId: rid,
+              queued: true
+            });
+          }
+          return steered;
+        };
         await this.runForcedCompactionIfNeeded(requestId);
         try {
           await runTurn({
@@ -10088,6 +10192,7 @@ var init_headless = __esm({
             requestId,
             signal: this.currentAbort.signal,
             onEvent: this.onEvent,
+            takeSteering,
             resolveExternalTool: this.resolveExternalTool,
             toolRegistry: this.toolRegistry,
             onBackgroundComplete: this.onBackgroundComplete
@@ -10117,7 +10222,7 @@ var init_headless = __esm({
           });
         }
         const outcome = this.primaryOutcome();
-        for (const rid of absorbedRids) {
+        for (const rid of [...absorbedRids, ...consumedRids]) {
           this.emit(
             "completed",
             {
@@ -10412,6 +10517,33 @@ var init_headless = __esm({
           );
           return;
         }
+        if (action === "setQueuedDelivery") {
+          const id = parsed.id;
+          const delivery = parsed.delivery;
+          if (!id || delivery !== "asap" && delivery !== "afterTurn") {
+            this.emit(
+              "completed",
+              {
+                success: false,
+                error: 'setQueuedDelivery requires id and delivery ("asap" | "afterTurn")'
+              },
+              requestId
+            );
+            return;
+          }
+          const target = this.queue.snapshot().find((it) => it.command.requestId === id);
+          if (!target || target.source !== "user" || this.isDrainBarrier(target)) {
+            this.emit(
+              "completed",
+              { success: false, error: "message not found or not promotable" },
+              requestId
+            );
+            return;
+          }
+          this.queue.setDelivery(id, delivery);
+          this.emit("completed", { success: true }, requestId);
+          return;
+        }
         if (action === "stop_tool") {
           const id = parsed.id;
           const mode = parsed.mode ?? "hard";

package/dist/prompt/skills/agentInterfaces.md

@@ -103,6 +103,30 @@ const { threads, nextCursor } = await chat.listThreads();
 const full = await chat.getThread(thread.id);
 await chat.updateThread(thread.id, 'New title');
 await chat.deleteThread(thread.id);
+
+// Progressive auth: threads started anonymously become unreachable after the
+// user signs in (login replaces the session and its visitor identity). Claim
+// them right after your verification/login succeeds so the conversation
+// survives — the client remembers each thread's pre-login token automatically
+// for threads touched this page session.
+await chat.claimThread(thread.id);
+```
+
+**Client tools** — a tool whose effect happens in the browser (open a sheet, navigate, highlight)
+is declared with `target: "client"` and a `name` + inline `inputSchema` instead of a `method`
+(names must not collide with method ids; the schema is authored — there's no method contract to
+derive it from). The agent's invocation arrives as the `client_tool_call` stream event / the
+`onClientToolCall` callback on `sendMessage`; run the action there. Fire-and-forget on this
+surface: the agent is told the action was displayed and keeps going — the user's next message
+closes the loop.
+
+```js
+await chat.sendMessage(thread.id, text, {
+  onText: (delta) => append(delta),
+  onClientToolCall: (name, input) => {
+    if (name === 'showVerification') openVerifySheet(input);
+  },
+});
 ```
 
 **Sending messages (streaming):**

package/dist/prompt/skills/voiceInterfaces.md

@@ -1,7 +1,7 @@
 ---
 name: Voice Interfaces
 what: Realtime voice conversation as a first-class interface — the user talks to the app and its voice agent talks back in sub-second, interruptible speech, calling the app's methods mid-conversation as the authenticated user. The platform handles the media transport, turn-taking, barge-in, and transcripts, so the work is authorship — a persona written for the ear, a small toolset where every tool carries a latency class, and descriptions that say results out loud. Any app whose methods do something interesting can pick up a voice, and it is often the most impressive surface it has.
-when: Before authoring `src/interfaces/voice.md`, choosing a voice model or pipeline, deciding which methods a voice agent gets, or building the voice UI with `createVoiceClient()`.
+when: Before authoring `src/interfaces/voice.md`, choosing a voice model or pipeline, deciding which methods a voice agent gets, building the voice UI with `createVoiceClient()`, or working out why a voice agent behaved the way it did on a call.
 ---
 
 # Building Voice Interfaces
@@ -57,7 +57,8 @@ precisely: "confirm before any tool that changes data," not "always confirm ever
 `always`/`never` makes the agent rigid and unable to handle reasonable exceptions. And start
 minimal: state the role, the boundaries, and the voice mechanics above, then add rules only for
 behaviors that actually misfire in test calls (the transcripts in the call log are the feedback
-loop) rather than front-loading a policy manual.
+loop — `mindstudio-prod voice sessions get` reads a call verbatim) rather than front-loading a
+policy manual.
 
 ### The latency classes
 
@@ -78,25 +79,65 @@ Classify by how the method actually behaves, not by what it is named. A "lookup"
 external service is `slow`. When in doubt between `fast` and `slow`, pick `slow` — a needless
 preamble is mildly chatty; an unexplained silence feels broken.
 
-### Forwarding results to the screen (`forwardResult`)
+### Tool results reach the screen
 
-A tool block may declare `forwardResult: true`. On completion, the platform then delivers the
-tool's raw return value to the session's browser on the SDK's `toolCall` event (`result` field) —
-so the UI can render what the agent just did (the citation it found, the record it pulled up, the
-booking it made) in lockstep with the spoken answer. No polling, no key-threading, no model
-involvement: the correlation is platform-guaranteed and scoped to that one session's client.
+Every successful tool call delivers its raw return value to the session's browser on the SDK's
+`toolCall` event (`result` field, on `done`) — so the UI can render what the agent just did (the
+citation it found, the record it pulled up, the booking it made) in lockstep with the spoken
+answer. No flag, no polling, no key-threading, no model involvement: delivery to the invoking
+session's own client is the same security context as the invocation itself (an RPC response), and
+it's scoped to that one session.
 
-Opt in deliberately, per tool. The forwarded payload is the method's raw return — the same data
-the model sees — so only enable it on tools whose returns are safe to render for the user in the
-call (no internal fields you wouldn't show on screen). Payloads over ~32KB serialized arrive as
-`resultTruncated: true` with no data — keep forwarded returns compact, or have the UI fetch big
-data itself. Failed calls never forward anything.
+Consequence for authoring: **a tool's return value is user-visible by definition.** Return what
+the user may see — no internal fields, keys, or diagnostics you wouldn't put on screen (the same
+discipline as agent-interface tools, whose results render in chat). Payloads over ~32KB serialized
+arrive as `resultTruncated: true` with no data — keep returns compact, or have the UI fetch big
+data itself. Failed calls deliver nothing to the client (the model gets the `{ error }` and speaks
+a decline).
 
 For backend-side correlation (writing results to a table keyed by the call, custom channels), the
 method itself can read `session.voiceSessionId` / `session.visitorId` from the agent SDK
 (`import { session } from '@mindstudio-ai/agent'`) — the same id the browser holds as
 `session.sessionId`, guaranteed by the platform rather than echoed by the model.
 
+### Client tools: actions that happen on screen (`target: "client"`)
+
+A tool whose effect belongs in the browser — open the verification sheet, navigate to a page,
+highlight a record — is declared with `target: "client"` instead of a `method`:
+
+```json
+{
+  "target": "client",
+  "name": "showVerification",
+  "description": "tools/showVerification.md",
+  "inputSchema": { "type": "object", "properties": { "reason": { "type": "string" } } }
+}
+```
+
+The platform never touches the backend for these: the agent's invocation is delivered to the
+session's browser, the app's registered handler runs, and the handler's **return value goes back
+to the agent as the tool result** — a real request/response, so the agent knows the sheet
+actually opened (or that the user dismissed it) and speaks accordingly. Rules:
+
+- `name` instead of `method`; must not collide with any backend method id. No latency class —
+  the agent holds the turn while the browser responds (up to ~30s, then a timeout error).
+- `inputSchema` is authored inline (an object schema) — there's no method contract to derive
+  it from. Keep it small; these are UI directives, not data payloads.
+- The frontend must register a handler, or invocations fail as `unhandled_client_tool`:
+
+```js
+session.registerClientTool('showVerification', async ({ reason }) => {
+  openVerifySheet(reason);
+  return { opened: true };   // what the agent hears back
+});
+```
+
+- One client tool runs at a time per session; the description should tell the agent when to use
+  it and what to say while it's on screen. Throwing from the handler (or returning nothing)
+  becomes an error/ack the agent can speak around.
+- The progressive-auth pattern above is the canonical use: make the verification sheet a client
+  tool and the agent opens it deliberately instead of the frontend inferring it from tool events.
+
 ### Tool descriptions say results out loud
 
 Follow the agent-interface principles for tool descriptions (when to use and when not, parameter
@@ -124,24 +165,45 @@ caller.
 
 ### Choosing the model
 
-Two shapes, one `model` field:
-
-- **Native speech-to-speech** (`{"model": ..., "voice": ...}`) — one realtime model hears and
-  speaks. Lowest latency, most natural prosody, hears tone and hesitation. The default for
-  personality-forward, conversational apps.
-- **Cascaded** (`{"llm": ..., "stt": ..., "tts": ..., "voice": ...}`) — streaming transcription
-  into any chat model in the catalog, streaming speech out. Slightly higher latency, but the brain
-  can be *any* chat model — the right choice when the app's reasoning demands a specific model, or
-  when the agent interface already uses one and the voice should think identically. The blessed
-  streaming pairing is `"stt": "deepgram-nova-3", "tts": "cartesia-sonic-3"` — the lowest-latency
-  combination the platform wires; prefer it unless there's a reason not to (ElevenLabs TTS,
-  `"tts": "elevenlabs-tts"`, is also wired when its voice library fits better). One nuance: cascaded
-  engines speak the `greeting` verbatim (they have a real TTS); speech-to-speech engines have the
-  model say it, so it may paraphrase slightly.
-
-Ask `askMindStudioSdk` for available ids — realtime, transcription, and speech models are separate
-catalogs, and MindStudio ids don't match vendor ids, so treat ids in this document as illustrative.
-Voice ids are model-specific; query for those too. The user's UI has a picker for changing the model
+Two shapes, one `model` field. **Use native speech-to-speech unless the user specifically asks
+for a cascaded pipeline** — one realtime model hears and speaks: lowest latency, most natural
+prosody, hears tone and hesitation.
+
+**Native** (`{"model": ..., "voice": ...}`) — **default to `gpt-realtime-2.1` with voice
+`marin`.**
+
+- `gpt-realtime-2.1` — the default. Voices: `marin` (default), `cedar`, `alloy`, `ash`,
+  `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`.
+- `gpt-realtime-2.1-mini` — the same family, lighter; same voices.
+- `gemini-2.5-flash-native-audio-preview-12-2025` — the Gemini pick, with a large expressive
+  roster: `Puck` (default, upbeat), `Zephyr` (bright), `Charon` (informative), `Kore` (firm),
+  `Fenrir` (excitable), `Leda` (youthful), `Orus` (firm), `Aoede` (breezy), `Callirrhoe`
+  (easy-going), `Autonoe` (bright), `Enceladus` (breathy), `Iapetus` (clear), `Umbriel`
+  (easy-going), `Algieba` (smooth), `Despina` (smooth), `Erinome` (clear), `Algenib` (gravelly),
+  `Rasalgethi` (informative), `Laomedeia` (upbeat), `Achernar` (soft), `Alnilam` (firm),
+  `Schedar` (even), `Gacrux` (mature), `Pulcherrima` (forward), `Achird` (friendly),
+  `Zubenelgenubi` (casual), `Vindemiatrix` (gentle), `Sadachbia` (lively), `Sadaltager`
+  (knowledgeable), `Sulafat` (warm).
+- `gemini-3.1-flash-live-preview` — newer Gemini, same voices as 2.5, but currently can't speak
+  an opening greeting or take mid-call prompt updates (a plugin limitation expected to resolve
+  upstream) — prefer 2.5 until then.
+- `grok-voice-think-fast-2.0` — a distinct personality register. Voices: `eve` (default),
+  `altair`, `ara`, `atlas`, `aurora`, `carina`, `castor`, `celeste`, `cosmo`, `helios`, `helix`,
+  `iris`, `kepler`, `leo`, `liora`, `lumen`, `luna`, `lux`, `naksh`, `orion`, `perseus`, `rex`,
+  `rigel`, `sal`, `sirius`, `ursa`, `zagan`, `zenith`.
+
+**Cascaded** (`{"llm": ..., "stt": ..., "tts": ..., "voice": ...}`) — streaming transcription
+into any chat model in the catalog, streaming speech out. Slightly higher latency; reach for it
+only when the user wants it or the app's reasoning demands a specific chat model (e.g. the agent
+interface already uses one and the voice should think identically). Slots: `stt` is
+`deepgram-nova-3`; `tts` is `cartesia-sonic-3` (voices are per-account Cartesia UUIDs — see
+play.cartesia.ai) or `elevenlabs-tts` (the account's ElevenLabs voice library); `llm` is any chat
+model — ask `askMindStudioSdk` for chat model ids. One nuance: cascaded engines speak the
+`greeting` verbatim (they have a real TTS); speech-to-speech engines have the model say it, so it
+may paraphrase slightly.
+
+The model and voice ids above are current and maintained with the platform — use them as written
+(they are MindStudio ids, not vendor ids). The user's UI has a picker for changing the model
 later, so validate only when you set it.
 
 ### Seeding from an existing agent
@@ -204,13 +266,15 @@ session.on('stateChange', (state) => { });          // on() returns an unsubscri
 // far (never a delta) — render by upserting on segmentId, not appending.
 session.on('transcript', ({ role, segmentId, text, final }) => { });
 
-// status: 'running' | 'done' | 'failed'. Tools declared with `forwardResult: true`
-// carry their return value in `result` on 'done' (or `resultTruncated: true` if >~32KB).
+// status: 'running' | 'done' | 'failed'. Every 'done' carries the tool's raw
+// return value in `result` (or `resultTruncated: true` if >~32KB serialized).
 session.on('toolCall', ({ method, status, result }) => { });
 session.on('error', (err) => { });
 
 session.mute(); session.unmute(); session.isMuted;
 session.sendText('123 Main Street');  // inject text into the live conversation
+await session.refreshIdentity();      // after in-app verification — upgrade the
+                                      // live session anonymous → signed-in in place
 session.end();
 ```
 
@@ -277,7 +341,7 @@ export async function callMeAboutMyOrder(input: { phone: string }) {
   session, not the phone). Omitted/false → anonymous call; role-gated tools decline.
   System/cron invocations have no human identity and always run anonymously.
 - **Production needs a dedicated phone number.** The app owner attaches one ($1/month) via the
-  dashboard or `mindstudio-prod voice numbers` (see "Managing the phone side from the CLI"
+  dashboard or `mindstudio-prod voice numbers` (see "The voice CLI"
   below) — it becomes the caller ID for every call, in dev sessions too, so users always see
   the same number. Without one, deployed calls throw `phone_out_requires_dedicated_number`, and
   dev sessions fall back to a shared platform test number that varies per call (tighter limits
@@ -338,7 +402,7 @@ wrong one wherever the agent's tools can move money, reveal sensitive records, o
 destructive actions. It lives in the interface config deliberately: enabling it is a code
 change, visible in review and auditable via deploys, not a dashboard toggle.
 
-## Managing the phone side from the CLI
+## The voice CLI
 
 The `mindstudio-prod voice` family covers numbers, the call log, and voice policy:
 
@@ -377,7 +441,7 @@ section.
 name: Front Desk
 description: Books appointments and answers questions by voice.
 type: interface/voice
-model: {"model": "gpt-realtime-mini", "voice": "marin"}
+model: {"model": "gpt-realtime-2.1", "voice": "marin"}
 turnDetection: {"eagerness": "medium"}
 greeting: Hey! I can help you book, reschedule, or answer questions — what do you need?
 ---
@@ -435,7 +499,7 @@ The top-level key must match the interface type (`voice`):
   "voice": {
     "name": "Front Desk",
     "description": "Books appointments and answers questions by voice.",
-    "model": "gpt-realtime-mini",
+    "model": "gpt-realtime-2.1",
     "voice": "marin",
     "turnDetection": { "eagerness": "medium" },
     "greeting": "Hey! I can help you book, reschedule, or answer questions — what do you need?",
@@ -537,3 +601,30 @@ frontend or the agent interface. Anonymous sessions (when allowed) have no user
 gated methods reject, and the caller's history is scoped to their browser's visitor identity.
 That's why role restrictions belong in the tool descriptions — the agent should decline in
 character, not relay a rejection.
+
+### Progressive auth: verify mid-call without dropping the conversation
+
+The best pattern for apps that allow anonymous sessions (`requireUser: false`): let visitors
+explore by voice, and verify only when they hit an account-bound action — without killing the
+live call. Four pieces, all platform rails:
+
+1. **Account-gated tools return a standard not-verified shape** instead of doing the work:
+   `{ verified: false, message: 'The caller is not verified. Offer to verify them before sharing
+   account details.' }`. The agent speaks the offer in character (reinforce tone in the system
+   prompt's verification section). Check with the agent SDK's `auth.userId` inside the method.
+2. **The frontend opens its verification sheet off the same signal.** It already receives every
+   tool's `toolCall` event (and the tool's return in `result`) — when an account tool fires (or
+   returns `verified: false`) while the app has no signed-in user, open the sheet.
+3. **The sheet runs the platform's auth rails** — `auth.sendSmsCode()` / `auth.verifySmsCode()`
+   (or the email pair) from `@mindstudio-ai/interface`. On success the app's session becomes the
+   verified user.
+4. **Hand the verified session back to the live call**: `await session.refreshIdentity()`. The
+   platform upgrades the running voice session in place — subsequent tool calls carry the user's
+   identity and roles, and the agent's Current User context refreshes — no teardown, no lost
+   conversation. (Phone calls don't need this: they verify through the agent's built-in flow.)
+
+`refreshIdentity()` is upgrade-only (anonymous → signed-in; an already-identified session rejects
+with `already_identified`) and requires the session to have been started by this same browser. If
+it fails, ending and restarting the session is the graceful fallback. The chat sibling for agent
+interfaces is `claimThread(threadId)` — anonymous threads become unreachable after login until
+claimed.

package/dist/subagents/browserAutomation/prompt.md

@@ -13,6 +13,8 @@ When the content you need to test is behind authentication, use the `setupBrowse
 
 If you need to test the login/signup flow itself (e.g., verifying the UI, error states, or the verification code input), navigate it manually: use `remy@mindstudio.ai` for email and `+15551234567` for phone. In the dev environment, verification codes are bypassed for this email and any 555-prefixed phone number — enter any 6-digit code (e.g., `123456`).
 
+To test as a **signed-out visitor** (public pages, landing/join links), call `setupBrowser` with NO `auth` — it clears the auth cookie and reloads at the given path, giving you a clean unauthenticated session. Combine with `navigate` + `fresh: true` when you need a fresh-document view of an entry page mid-run.
+
 ## Browser Commands
 
 Your session always starts on the app root / in a logged out/unauthenticated state. Use `setupBrowser` to authenticate before testing protected pages.
@@ -40,13 +42,43 @@ Note: the snapshot concatenates inline text and strips whitespace. If you need t
 - `type`: Type text into an input. Characters appear one at a time. Set `clear: true` to clear the field first.
 - `select`: Select a dropdown option by text. Target the `<select>` element, set `option` to the option text.
 - `wait`: Wait for an element to appear (polls every 100ms, default 5s timeout). Also waits for network to settle after the element is found.
-- `navigate`: Navigate to a new URL within the app. Waits for the new page to load before continuing with subsequent steps. Use this instead of evaluate with `window.location.href` when you need to navigate and then continue interacting with the new page. Steps after navigate execute on the new page automatically.
+- `navigate`: Navigate to a new URL within the app. Waits for the route to load before continuing with subsequent steps. Use this instead of evaluate with `window.location.href` when you need to navigate and then continue interacting with the new page. Steps after navigate execute on the new page automatically. Same-origin navigation is a soft in-app route change (like clicking a link in an SPA — in-memory app state survives); set `fresh: true` to force a real full page load with a fresh document instead. Use `fresh: true` when the test is about what a user sees on *entry* — landing pages, join/invite links, "what does a signed-out visitor see" — where reusing the SPA's in-memory state would test the wrong thing. The result reports the URL the page actually landed on, so if the app redirected you (e.g. an auth wall bounced you off a public page), you'll see the real destination — check it instead of assuming the navigation stuck.
 - `evaluate`: Run arbitrary JavaScript in the page and return the result.
 - `styles`: Read computed CSS styles from page elements. Pass a `properties` array with camelCase CSS property names (e.g., `["backgroundColor", "borderRadius", "fontSize"]`). Omit `properties` for a default set covering colors, typography, spacing, borders, shadows, dimensions, and layout. Uses the same targeting as click/type (ref, text, role, label, selector). Omit the target to get styles for all elements from the last snapshot.
 - `screenshotFullPage`: Take a screenshot of the whole page, top to bottom. Returns CDN url with full text analysis and dimensions. Use for overall composition or content past the fold.
 - `screenshotViewport`: Take a screenshot of the visible viewport. Returns CDN url with full text analysis and dimensions. To capture a specific section, set `scrollToSelector` (a CSS selector) — or `scrollY` (an absolute offset) — on this same step; it scrolls the target into view and captures it atomically, so you do NOT need a separate scroll step. Do not use if you can get what you need with other tools - only use when you need to visually see the viewport.
 - `setViewport`: Switch the browser between desktop and mobile rendering. Set `mode` to `"desktop"` or `"mobile"`. Mobile emulates a phone (390-wide, touch, device pixel ratio 2); desktop is the standard wide viewport. This reloads the page so media queries, responsive layouts, and `matchMedia` re-evaluate — the reload clears in-page state, so switch before you set up the state you want to inspect. The mode persists across navigations within a run. Each run starts in the app's default mode, so only use this when you need to check the other one.
 
+### Voice interfaces
+
+Apps with a voice interface are testable end to end — the UI layer included. The sandbox browser
+auto-grants a (silent) microphone, and while a session is live the SDK publishes a handle at
+`window.__MS_VOICE__` so you can converse by text: the agent treats injected text exactly like
+user speech (interrupts and replies), backend tools run for real, and client tools render their
+real UI (cards, sheets) in the page.
+
+The loop:
+
+1. Start a session through the app's real UI — `click` its voice affordance (orb/button). No mic
+   prompt appears. Then `wait` briefly and confirm the session is live:
+   `evaluate: window.__MS_VOICE__?.state` (undefined means no session started — report that,
+   don't improvise).
+2. Speak by injection: `evaluate: window.__MS_VOICE__.sendText("I'd like to book Tuesday at 2")`.
+3. Give the agent a few seconds to respond (replies are generated speech — slower than chat).
+   `wait` for the UI you expect (client-tool cards appear via the app's real handlers), and read
+   the conversation: `evaluate: window.__MS_VOICE__.transcript` (one entry per utterance, both
+   sides, `final` marks settled ones) and `window.__MS_VOICE__.toolCalls` (which tools ran;
+   `done` entries carry the tool's return value).
+4. Verify visuals with `screenshotViewport` like any other flow.
+5. Read `transcript`/`toolCalls` BEFORE ending — then `evaluate: window.__MS_VOICE__.end()` (the
+   handle is removed when the session ends).
+
+Voice sessions are the most expensive thing you can run — real voice-model minutes are metered,
+and the agent speaks its replies out loud even when you type at it. Keep voice tests short and
+purposeful: a handful of turns that exercise the target behavior, then end the session. What you
+cannot test is the audio layer itself (mishearing, interruptions, pronunciation) — never attempt
+to simulate audio; report that scope limit instead.
+
 ### Element targeting (tried in order)
 
 1. `ref`: From the last snapshot. Most reliable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.265",
+  "version": "0.1.266",
   "description": "Remy coding agent",
   "repository": {
     "type": "git",