@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/providers/server-tool-pairing.ts

@@ -57,7 +57,8 @@ function contentBlocks(msg: ServerToolPairingMessage): ReadonlyArray<unknown> {
  * `tool_use`, no result emitted) and executes it on the next request, placing
  * the web_search_tool_result at the head of the next assistant message. Both
  * the deferred tail and the resulting split pair must be sent back verbatim
- * for the provider to pair and execute them.
+ * for the provider to pair and execute them, and the user message answering
+ * a deferred tail must hold tool_result blocks alone.
  */
 export interface ServerToolPairing {
   /**
@@ -67,8 +68,12 @@ export interface ServerToolPairing {
   resolvedPairIds: Set<string>;
   /**
    * Unanswered use ids in the final assistant message of an active tool-loop
-   * continuation (only user messages after it, carrying tool_result blocks or
-   * nothing at all). The provider executes these on this request.
+   * continuation: nothing follows it, or only user messages made solely of
+   * tool_result blocks. The provider executes these on this request. Any
+   * other trailing block (guidance text after the results, a queued user
+   * message) closes the assistant turn on the provider side, which then
+   * rejects the unanswered use as unpaired, so such a use is an orphan to
+   * repair rather than a deferral to preserve.
    */
   deferredUseIds: Set<string>;
   /** Ids whose use/result pair spans two messages. */
@@ -118,10 +123,14 @@ export function analyzeServerToolPairing(
   if (lastAssistantIndex >= 0) {
     const trailing = messages.slice(lastAssistantIndex + 1);
     const trailingAllUser = trailing.every((m) => m.role === "user");
-    const trailingHasToolResult = trailing.some((m) =>
-      contentBlocks(m).some(isToolResultShapedBlock),
-    );
-    if (trailingAllUser && (trailing.length === 0 || trailingHasToolResult)) {
+    const trailingBlocks = trailing.flatMap((m) => [...contentBlocks(m)]);
+    const trailingIsToolResultsOnly =
+      trailingBlocks.length > 0 &&
+      trailingBlocks.every(isToolResultShapedBlock);
+    if (
+      trailingAllUser &&
+      (trailing.length === 0 || trailingIsToolResultsOnly)
+    ) {
       for (const block of contentBlocks(messages[lastAssistantIndex])) {
         if (isServerToolUseBlock(block) && !resolvedPairIds.has(block.id)) {
           deferredUseIds.add(block.id);

package/src/providers/speech-to-text/__tests__/deepgram-flux-frames.test.ts

@@ -129,6 +129,30 @@ describe("parseFluxFrame", () => {
     ]);
   });
 
+  test.each(["model", "timeout", "manual"])(
+    "retains the %s turn-end trigger and decoded audio position",
+    (trigger) => {
+      expect(
+        parseFluxFrame({ ...END_OF_TURN, trigger, audio_window_end: 12.5 })[1],
+      ).toMatchObject({
+        type: "turn-end",
+        confidence: 0.88,
+        trigger,
+        audioWindowEndSeconds: 12.5,
+      });
+    },
+  );
+
+  test("omits unknown triggers and malformed audio positions", () => {
+    expect(
+      parseFluxFrame({
+        ...END_OF_TURN,
+        trigger: "future-trigger",
+        audio_window_end: "invalid",
+      }),
+    ).toEqual(parseFluxFrame(END_OF_TURN));
+  });
+
   test("flat frames without a nested event field are accepted", () => {
     expect(parseFluxFrame({ type: "StartOfTurn" })).toEqual([
       { type: "turn-start" },

package/src/providers/speech-to-text/__tests__/deepgram-flux-realtime.test.ts

@@ -334,6 +334,7 @@ describe("DeepgramFluxRealtimeTranscriber", () => {
           type: "turn-end",
           text: "what is the weather",
           confidence: 0.91,
+          audioWindowEndSeconds: 1.5,
           turnIndex: 0,
         },
       ]);
@@ -382,7 +383,12 @@ describe("DeepgramFluxRealtimeTranscriber", () => {
       );
       expect(events).toEqual([
         { type: "final", text: "still here" },
-        { type: "turn-end", text: "still here", turnIndex: 0 },
+        {
+          type: "turn-end",
+          text: "still here",
+          turnIndex: 0,
+          audioWindowEndSeconds: 1.5,
+        },
       ]);
     });
   });

package/src/providers/speech-to-text/__tests__/vellum-managed-realtime.test.ts

@@ -8,6 +8,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import { SttError, type SttStreamServerEvent } from "../../../stt/types.js";
+import { VellumManagedFluxRealtimeTranscriber } from "../vellum-managed-flux-realtime.js";
 import { VellumManagedRealtimeTranscriber } from "../vellum-managed-realtime.js";
 import type { SpeechRelayConnection } from "../vellum-speech-relay-connection.js";
 
@@ -99,7 +100,7 @@ const CONNECTION: SpeechRelayConnection = {
 
 const tick = () => new Promise<void>((r) => setTimeout(r, 0));
 
-describe("VellumManagedRealtimeTranscriber", () => {
+describe("Vellum managed realtime transcribers", () => {
   let sockets: MockWebSocket[];
   let originalWebSocket: unknown;
   let originalFetch: unknown;
@@ -262,6 +263,54 @@ describe("VellumManagedRealtimeTranscriber", () => {
     expect(new URL(sockets[1]!.url).searchParams.get("key")).toBe("vk-secret");
   });
 
+  test("Flux turn indices stay in one sequence across relay reconnects", async () => {
+    const adapter = new VellumManagedFluxRealtimeTranscriber(CONNECTION);
+    const { events, onEvent } = collector();
+    const started = adapter.start(onEvent);
+    sockets[0]!.simulateOpen();
+    await started;
+    try {
+      for (let generation = 0; generation < 3; generation += 1) {
+        const socket = sockets[generation]!;
+        const turnIndex = generation === 0 ? 5 : 0;
+        const startFrame = JSON.stringify({
+          type: "TurnInfo",
+          event: "StartOfTurn",
+          turn_index: turnIndex,
+        });
+        socket.simulateMessage(startFrame);
+        socket.simulateMessage(startFrame);
+        socket.simulateMessage(
+          JSON.stringify({
+            type: "TurnInfo",
+            event: "EndOfTurn",
+            // A later end without its start still advances the sequence.
+            turn_index: generation === 1 ? 2 : turnIndex,
+            transcript: "hello",
+          }),
+        );
+        if (generation < 2) {
+          socket.simulateMessage(velayErrorFrame("session_duration_exceeded"));
+          socket.simulateClose(1000, "session_duration_exceeded");
+          await tick();
+          sockets[generation + 1]!.simulateOpen();
+          await tick();
+        }
+      }
+      expect(
+        events.flatMap((event) =>
+          event.type === "turn-start" || event.type === "turn-end"
+            ? [event.turnIndex]
+            : [],
+        ),
+      ).toEqual([5, 5, 5, 6, 6, 8, 9, 9, 9]);
+      expect(events.some((event) => event.type === "closed")).toBe(false);
+    } finally {
+      adapter.stop();
+      sockets.at(-1)!.simulateClose();
+    }
+  });
+
   test("finalize during a re-dial settles immediately", async () => {
     const { adapter, events } = await startAdapter();
 

package/src/providers/speech-to-text/deepgram-flux-frames.ts

@@ -71,6 +71,7 @@ export interface FluxTurnFrame {
   transcript?: string;
   /** Flux's end-of-turn confidence in [0, 1]. */
   end_of_turn_confidence?: number;
+  trigger?: "model" | "manual" | "timeout";
 }
 
 /**
@@ -153,6 +154,8 @@ export function parseFluxFrame(raw: unknown): SttStreamServerEvent[] {
     case "EndOfTurn": {
       const text = readTranscript(frame);
       const confidence = readNumber(frame.end_of_turn_confidence);
+      const trigger = frame.trigger;
+      const audioWindowEndSeconds = readNumber(frame.audio_window_end);
       return [
         { type: "final", text },
         {
@@ -160,6 +163,14 @@ export function parseFluxFrame(raw: unknown): SttStreamServerEvent[] {
           text,
           ...(confidence !== undefined ? { confidence } : {}),
           ...(turnIndex !== undefined ? { turnIndex } : {}),
+          ...(trigger === "model" ||
+          trigger === "manual" ||
+          trigger === "timeout"
+            ? { trigger }
+            : {}),
+          ...(audioWindowEndSeconds !== undefined
+            ? { audioWindowEndSeconds }
+            : {}),
         },
       ];
     }

package/src/providers/speech-to-text/vellum-managed-flux-realtime.ts

@@ -79,6 +79,9 @@ export class VellumManagedFluxRealtimeTranscriber implements StreamingTranscribe
   private redialOnClose = false;
   private stopping = false;
   private closedEmitted = false;
+  // Consumers see one stream across relay reconnects, with one turn sequence.
+  private turnIndexOffset = 0;
+  private latestTurnIndex = -1;
 
   constructor(
     connection: SpeechRelayConnection,
@@ -225,6 +228,15 @@ export class VellumManagedFluxRealtimeTranscriber implements StreamingTranscribe
       return;
     }
 
+    if (
+      (event.type === "turn-start" || event.type === "turn-end") &&
+      event.turnIndex !== undefined
+    ) {
+      const turnIndex = this.turnIndexOffset + event.turnIndex;
+      this.latestTurnIndex = Math.max(this.latestTurnIndex, turnIndex);
+      this.emit({ ...event, turnIndex });
+      return;
+    }
     this.emit(event);
   }
 
@@ -236,6 +248,7 @@ export class VellumManagedFluxRealtimeTranscriber implements StreamingTranscribe
   private beginRedial(): void {
     log.info("Managed Flux relay session hit velay's duration cap, re-dialing");
     this.inner = null;
+    this.turnIndexOffset = this.latestTurnIndex + 1;
     void (async () => {
       try {
         const inner = await this.dial();

package/src/providers/types.ts

@@ -551,6 +551,8 @@ export interface ContextOverflowErrorOptions {
   cause?: unknown;
   /** Semantic reason override; defaults to `context_overflow`. */
   reason?: ProviderErrorReason;
+  /** Inspectable SDK/wire request payload for the overflowing call. */
+  rawRequest?: unknown;
 }
 
 /**
@@ -581,6 +583,9 @@ export class ContextOverflowError extends ProviderError {
     super(message, provider, options.statusCode ?? 400, {
       reason: options.reason ?? "context_overflow",
       ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      ...(options.rawRequest !== undefined
+        ? { rawRequest: options.rawRequest }
+        : {}),
     });
     this.name = "ContextOverflowError";
     this.actualTokens = options.actualTokens;

package/src/routes/control.ts

@@ -44,13 +44,15 @@ function routeHostPidPath(): string {
   return getProcPidPath(ROUTE_HOST_PROC_NAME);
 }
 
+const ROUTE_HOST_ENTRY = new URL("./worker.ts", import.meta.url);
+
 /**
  * Read the PID file and report liveness. A missing or malformed file reports
- * not_running; a file pointing at a dead process is cleaned up and reported as
- * not_running.
+ * not_running; a file pointing at a dead process, or at a live process that
+ * is not this worker, is cleaned up and reported as not_running.
  */
 export function probeRouteHostWorker(): WorkerProcessStatus {
-  return probeWorkerPidFile(routeHostPidPath());
+  return probeWorkerPidFile(routeHostPidPath(), ROUTE_HOST_ENTRY, "routes");
 }
 
 export class RouteHostSpawnError extends WorkerProcessSpawnError {}
@@ -67,7 +69,7 @@ export async function spawnRouteHostWorkerProcess(
   try {
     return await spawnWorkerProcess({
       pidPath: routeHostPidPath(),
-      entry: new URL("./worker.ts", import.meta.url),
+      entry: ROUTE_HOST_ENTRY,
       packagedEntry: "routes",
       workerLabel: "Route host",
       options: opts,
@@ -86,7 +88,7 @@ export async function spawnRouteHostWorkerProcess(
  * (e.g. EPERM) — a not-running host is a no-op.
  */
 export function stopRouteHostWorkerProcess(): WorkerProcessStatus {
-  return stopWorkerProcess(routeHostPidPath());
+  return stopWorkerProcess(routeHostPidPath(), ROUTE_HOST_ENTRY, "routes");
 }
 
 /**

package/src/runtime/AGENTS.md

@@ -24,7 +24,7 @@ Queueing remains the fallback, not a legacy path, and every non-`released` outco
 
 A repair that fell back to the queue carries its durable requirement onto the drain that runs the queued message, and `pendingInterruptRepair` is what carries it: the drain reads that flag and asks `repairInterruptedToolUseBlocks` for `requireDurable`, so a second persist failure leaves the flag armed and the message queued instead of persisting the prompt behind an unmatched durable `tool_use`. Only a steered drain settles for an in-memory repair, because it has no row of its own to persist behind it.
 
-**The model has to be told its turn was cut off, once.** An interrupt caught mid-tool says so through the synthetic `tool_result` (`PREEMPTED_TOOL_RESULT_TEXT`). An interrupt caught during the provider call has no `tool_use` to answer, so `repairInterruptedToolUseBlocks` reports `preemptedToolResultOnTail: false` and the handover arms `pendingInterruptNote`. The persist of the interrupting user message consumes that flag exactly once: it stamps `interruptedPriorTurn` on the row and appends `INTERRUPTED_TURN_NOTE_TEXT` to the message's LLM-facing content only, so the persisted row stays what the user typed and no client renders the note. `reinjectInterruptTurnNote` rebuilds the identical block at history load, next to the attachment annotations and for the same reason: a reload that rebuilds it differently breaks provider prefix-cache parity. Do not add a second annotation for the same interrupt; one notice per cut-off turn.
+**The two interrupt texts are split by job, and the behavior instruction lives in exactly one of them.** A synthetic `tool_result` (`PREEMPTED_TOOL_RESULT_TEXT`) states the fact about the one call it answers: the call stopped early and may have taken effect anyway. It is repeated once per stopped call in a parallel batch, so it holds no instruction. Every completed handover arms `pendingInterruptNote`, whether or not a tool call was stopped. The persist of the interrupting user message consumes that flag exactly once: it stamps `interruptedPriorTurn` on the row and appends `INTERRUPTED_TURN_NOTE_TEXT` to the message's LLM-facing content only, so the persisted row stays what the user typed and no client renders the note. That note is the single place the behavior after an interrupt is written, it leads with the short acknowledgement the user is waiting for, and it sits after the user's words instead of before them. `reinjectInterruptTurnNote` rebuilds the identical block at history load, next to the attachment annotations and for the same reason: a reload that rebuilds it differently breaks provider prefix-cache parity. Do not add a third annotation, and do not put instructions back in the tool result.
 
 Two ordering rules a change here must not break. The synthetic `tool_result` is persisted BEFORE the caller writes the interrupting user row, because a user message between a `tool_use` and its result is a sequence every provider rejects. And the `thinking` / `message_interrupted` activity state is emitted by the agent loop at the head of the replacement turn, never at the handover: activity states are cached in `lastActivityStateMsg` and replayed to reconnecting clients, so a send that fails before its turn starts would otherwise strand every client on a busy conversation that is running nothing.
 
@@ -163,7 +163,7 @@ In the CDP factory the bridge is the internal `"host-bridge"` candidate kind (`I
 
 ### Browser CLI surface defaults
 
-The browser execute and tab routes share `browser/virtual-desktop-target.ts`. Platform-hosted web guardian conversations use installed, enabled virtual desktop Chrome by default. The shared `isVirtualDesktopEnabled` gate requires both `IS_PLATFORM` and `IS_CONTAINERIZED` alongside the `assistant-desktop` flag. Native renderer turns also use the `web` transport, so the frozen turn `clientOs` excludes native apps from automatic streamed-browser selection. Native apps retain their existing backend selection and fallback behavior. Explicit desktop/backend/client targets and existing personal-browser sessions override the surface default. Disabled or uninstalled desktop support retains the existing browser path; selection never triggers installation.
+The browser execute and tab routes share `browser/virtual-desktop-target.ts`. Platform-hosted web guardian conversations use image-provided virtual desktop Chrome by default when enabled. The shared `isVirtualDesktopEnabled` gate requires both `IS_PLATFORM` and `IS_CONTAINERIZED` alongside the `assistant-desktop` flag. Native renderer turns also use the `web` transport, so the frozen turn `clientOs` excludes native apps from automatic streamed-browser selection. Native apps retain their existing backend selection and fallback behavior. Explicit desktop/backend/client targets and existing personal-browser sessions override the surface default. Disabled desktop support retains the existing browser path. Missing image components fail the managed operation without installing dependencies or falling back to a personal browser.
 
 ### Per-tool `browser_mode` override
 
@@ -277,6 +277,8 @@ Verification SESSION state (sessions, secrets, rate limits, validate+consume) AN
 
 The daemon relays session lifecycle operations over the `verification_sessions_*` IPC routes via `assistant/src/channels/gateway-verification-sessions.ts` and keeps what is presentation: message composition and channel delivery (`channel-verification-routes.ts`, `verification-outbound-actions.ts`). `channel-verification-service.ts` retains only guardian-delivery reads (`getGuardianBinding`, `isGuardian`, `isGuardianBoundForChannel`).
 
+The gateway answers a code (or an invite) it consumed at ingress with a reply it composes itself, and delivers it through the daemon's IPC-only `deliver_gateway_reply` method (`ipc/routes/channel-reply-ipc-routes.ts`), which hands it to the channel transport the inbound message's callback URL names. The gateway never sends to a provider itself: the transports are the one outbound path per channel, whoever composed the text. The reply is not recorded in a conversation, since the message it answers never entered one.
+
 The verified outcome is written in-process by the gateway: the HTTP guardian-attest handler calls `ContactStore.markChannelVerified` directly (verifiedVia "manual"); the code-match paths (text and the `verification_sessions_validate_consume` engine route) apply role side effects in-engine — guardian phone binding commits in the same gateway transaction as the consume. The revoke/downgrade outcome is relayed from the daemon via `ipcCallPersistent("mark_channel_revoked", …)` to `ContactStore.markChannelRevoked`.
 
 ## Rate Limiting & Diagnostics
@@ -301,6 +303,6 @@ The provider-level rate limiter (`providers/ratelimit.ts`) also logs warnings (m
 
 ## HTTP-Only Transport
 
-HTTP is the sole transport for client-daemon communication. The runtime HTTP server (`assistant/src/runtime/http-server.ts`) is the canonical API surface. Clients connect via HTTP for request/response operations and SSE (`GET /v1/events`) for streaming server-to-client events.
+HTTP is the sole transport for browser and desktop clients; the CLI and the gateway reach the daemon over the IPC socket (see `assistant/AGENTS.md`). The runtime HTTP server (`assistant/src/runtime/http-server.ts`) is the canonical API surface. Clients connect via HTTP for request/response operations and SSE (`GET /v1/events`) for streaming server-to-client events.
 
-When writing skills that need to call daemon configuration endpoints, use `curl` with the runtime HTTP API (JWT-authenticated via `Authorization: Bearer <jwt>`). The assistant already knows how to use `curl`.
+A skill never calls the runtime HTTP API directly: every request from a skill targets the gateway, and `gateway-only-guard.test.ts` fails CI on a runtime-port URL in a skill. For configuration reads, use the CLI (`assistant config get`); for control-plane writes with no CLI verb, use `$INTERNAL_GATEWAY_BASE_URL`. See "Gateway-Only API Consumption" in `gateway/AGENTS.md` for the rule and its exceptions.

package/src/runtime/__tests__/agent-wake.test.ts

@@ -18,9 +18,10 @@
  * route captured calls back to the originating conversation's probe arrays.
  */
 
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
 
 import type { DiskPressureStatus } from "../../daemon/disk-pressure-guard.js";
+import { desktopAutomationLease } from "../../desktop/desktop-automation-lease.js";
 
 // ── Per-conversation capture registry ────────────────────────────────
 //
@@ -501,6 +502,13 @@ function makeWakeConversation(options: {
         `tools:${snapshotAllowedTools()?.join(",") ?? "all"}`,
       );
     },
+    // Mirrors Conversation.setPreactivatedSkillIds; the wake's tool-scope
+    // restore calls it, and a double without it throws inside the restore
+    // closure, leaving every field restored after it untouched.
+    preactivatedSkillIds: undefined as string[] | undefined,
+    setPreactivatedSkillIds(ids: string[] | undefined) {
+      this.preactivatedSkillIds = ids;
+    },
     get wakePersonaOverride() {
       return wakePersonaOverride;
     },
@@ -1357,6 +1365,50 @@ describe("wakeAgentForOpportunity", () => {
     expect(conversation.toolContextPin).toBeUndefined();
   });
 
+  test("applies wireToolDefinitions and the delegation state alongside the allowlist and restores both after the wake", async () => {
+    const replay = [
+      { name: "remember", description: "Save", input_schema: {} },
+      { name: "bell_jingle", description: "Ring", input_schema: {} },
+    ];
+    let replayDuringRun: unknown;
+    let delegationDuringRun: unknown;
+    const conversation = makeWakeConversation({
+      runImpl: async (input) => {
+        replayDuringRun = conversation.wireToolReplay;
+        delegationDuringRun = conversation.delegateIndependentTasksReplay;
+        return runResult([
+          ...input,
+          { role: "assistant", content: [{ type: "text", text: "Saved." }] },
+        ]);
+      },
+    });
+
+    const result = await wakeAgentForOpportunity(
+      {
+        conversationId: conversation.conversationId,
+        hint: "review for memories",
+        source: "memory-retrospective",
+        allowedTools: ["remember"],
+        toolGateMode: "execution",
+        wireToolDefinitions: replay,
+        delegateIndependentTasks: true,
+      },
+      { resolveTarget: async () => conversation },
+    );
+
+    expect(result).toEqual({ invoked: true, producedToolCalls: false });
+    // The replay array is live on the conversation for the duration of the
+    // run (the tool resolver returns it as the wire array), as is the
+    // delegation-section state the source's prompt rendered (the prompt
+    // build reads it)...
+    expect(replayDuringRun).toEqual(replay);
+    expect(delegationDuringRun).toBe(true);
+    // ...and both are cleared alongside the allowlist + gate mode after the
+    // wake.
+    expect(conversation.wireToolReplay).toBeUndefined();
+    expect(conversation.delegateIndependentTasksReplay).toBeUndefined();
+  });
+
   test("defaults to the wire gate mode when toolGateMode is absent", async () => {
     let gateModeDuringRun: string | undefined;
     const conversation = makeWakeConversation({
@@ -1517,6 +1569,47 @@ describe("wakeAgentForOpportunity", () => {
     expect(conversation.pushedMessages[2]).toEqual(followupAssistant);
   });
 
+  for (const fails of [false, true]) {
+    test(`releases desktop control before a ${fails ? "failed" : "completed"} wake drains the queue`, async () => {
+      const conversation = makeWakeConversation({
+        scriptedAssistant: {
+          role: "assistant",
+          content: [{ type: "text", text: "reply" }],
+        },
+        ...(fails
+          ? {
+              runImpl: async () => {
+                throw new Error("wake failed");
+              },
+            }
+          : {}),
+      });
+      const release = spyOn(desktopAutomationLease, "releaseForConversation");
+      const setProcessing = conversation.setProcessing.bind(conversation);
+      conversation.setProcessing = (processing) => {
+        if (!processing) {
+          expect(release).toHaveBeenCalledWith(conversation.conversationId);
+        }
+        setProcessing(processing);
+      };
+      try {
+        const result = await wakeAgentForOpportunity(
+          {
+            conversationId: conversation.conversationId,
+            hint: "x",
+            source: "unit-test",
+          },
+          { resolveTarget: async () => conversation },
+        );
+        expect(result.invoked).toBe(!fails);
+        expect(release).toHaveBeenCalledTimes(1);
+        expect(conversation.drainQueueCalls).toBe(1);
+      } finally {
+        release.mockRestore();
+      }
+    });
+  }
+
   test("marks processing true during the run and false afterwards", async () => {
     const conversation = makeWakeConversation({
       baseline: [{ role: "user", content: [{ type: "text", text: "hi" }] }],

package/src/runtime/actor-trust-resolver.ts

@@ -42,9 +42,9 @@ const log = getLogger("actor-trust-resolver");
 // ---------------------------------------------------------------------------
 
 /**
- * Trust classification for an inbound actor. Defined once in `./trust-class.ts`
- * (shared with the persistence metadata schema) and re-exported here, the
- * canonical import site for the resolver's consumers.
+ * Trust classification for an inbound actor. Declared in
+ * `@vellumai/gateway-client` and re-exported here for the resolver's
+ * consumers.
  */
 export type { TrustClass };
 

package/src/runtime/agent-wake.ts

@@ -107,6 +107,7 @@ import {
   persistWakeTriggerMessage,
   scopeWakeAllowedTools,
 } from "../daemon/wake-conversation-ops.js";
+import { desktopAutomationLease } from "../desktop/desktop-automation-lease.js";
 import {
   recordCompactionEndBestEffort,
   recordCompactionStartBestEffort,
@@ -118,7 +119,7 @@ import {
   setAgentLoopExitReasonOnLatestLog,
 } from "../persistence/llm-request-log-store.js";
 import type { SystemPromptPersonaOverride } from "../prompts/system-prompt.js";
-import type { Message } from "../providers/types.js";
+import type { Message, ToolDefinition } from "../providers/types.js";
 import {
   type UntrustedContentSource,
   wrapUntrustedContent,
@@ -350,6 +351,27 @@ export interface WakeOptions {
    * skill-management authoring tools callable directly.
    */
   preactivateSkillIds?: readonly string[];
+  /**
+   * Tool definitions to send verbatim as the wake's wire tool array, in place
+   * of the ones the conversation would resolve for itself. Used by fork-based
+   * memory retrospectives to replay the SOURCE conversation's recorded surface
+   * (`getRecordedConversationToolSurface`) so the provider prompt-cache prefix matches
+   * the source's live turns byte for byte. Definitions only: what may execute
+   * is still decided by `allowedTools` and the turn's own active set. Applied
+   * and restored alongside `allowedTools`; ignored when `allowedTools` is
+   * absent.
+   */
+  wireToolDefinitions?: readonly ToolDefinition[];
+  /**
+   * Whether the source's recorded surface rendered the system prompt's
+   * parallel-delegation section, replayed into the wake's prompt so that
+   * tier of the provider cache prefix matches the source's too (the wake's
+   * own scope cannot spawn, so deriving it would render the section off where
+   * an interactive source rendered it on). Prompt only: a spawn attempt is
+   * still rejected at execution. Applied and restored alongside
+   * `allowedTools`; ignored when `allowedTools` is absent.
+   */
+  delegateIndependentTasks?: boolean;
   /**
    * Explicit persona/channel slugs for the wake's system-prompt build,
    * applied to the conversation for the duration of the run and restored
@@ -1090,7 +1112,7 @@ export async function wakeAgentForOpportunity(
       try {
         recordRequestLog(
           conversationId,
-          JSON.stringify(record.rawRequest),
+          JSON.stringify(record.rawRequest ?? null),
           JSON.stringify(record.rawResponse),
           undefined,
           record.provider,
@@ -1410,6 +1432,7 @@ export async function wakeAgentForOpportunity(
      * is one function rather than a rebuild bolted onto either half.
      */
     const restoreWakeTurnScope = (): void => {
+      desktopAutomationLease.releaseForConversation(conversationId);
       restoreWakeAllowedTools();
       clearWakePersonaOverride();
       syncWakeLoopSystemPrompt();
@@ -1422,9 +1445,13 @@ export async function wakeAgentForOpportunity(
         restoreWakeToolScope = scopeWakeAllowedTools(
           conversation,
           new Set(opts.allowedTools),
-          opts.toolGateMode,
-          opts.toolContextPin,
-          opts.preactivateSkillIds,
+          {
+            gateMode: opts.toolGateMode,
+            toolContextPin: opts.toolContextPin,
+            preactivateSkillIds: opts.preactivateSkillIds,
+            wireToolDefinitions: opts.wireToolDefinitions,
+            delegateIndependentTasks: opts.delegateIndependentTasks,
+          },
         );
         return true;
       } catch (err) {