@vellumai/assistant 0.12.0-dev.202609111819.3dcbf21 → 0.12.0-dev.202609112015.230c060

package/ARCHITECTURE.md

@@ -609,7 +609,7 @@ Every phone call connects over Twilio Media Streams: the voice webhook emits `<C
 
 Transcription mode is selected once per session in `media-stream-stt-session.ts`:
 
-- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials.
+- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials. While something is interruptible (an assistant turn in flight, thinking or speaking, or a completed turn's tail still playing from Twilio's buffer), caller speech arms the shared sustained-speech barge-in guard (`src/calls/barge-in-guard.ts`, the same accounting live voice uses: speech accumulates toward 250 ms, short gaps are tolerated, a run that is mostly silence resets) and every inbound frame feeds it; outside that window the guard is dropped, so the caller's own utterance never carries into a turn that starts before the local VAD ends it. Only a fired guard reaches `CallController.handleBargeIn`, which interrupts a turn in either phase and ignores an idle controller (the playing tail is cleared instead).
 - **Batch fallback**: otherwise the session segments turns with the energy-based `MediaTurnDetector` and transcribes each completed turn via the same role's batch API. Both halves of a call read the `telephony` role, which is why a role names its consumer rather than a boundary.
 
 Every phone turn runs the same two-leg triage as live voice through `startVoiceTurn` (`src/calls/voice-session-bridge.ts`): `call-controller.ts` opens on a toolless front-door leg (`routingLeg: "front-door"`, the `voiceFrontDoor` call site) and drives it through the shared `createFrontDoorLegCoordinator` (`src/calls/voice-leg-coordinator.ts`), which reads the stream through the verdict machine and sequences the hand-off (pause narration, abort the leg, resolve and speak the bridge, mark it as the floor holder, start the escalated leg pinned to the conversation's own model, re-arm narration); each driver supplies only a host for how text and the bridge are spoken, how a leg is started or aborted, and (live voice only) the speculative hold and commit. Phone has no partial transcripts, so the hold verdict is never taught and routing is escalate-only. The controller also passes the bridge's turn callbacks (tool activity is recorded as `tool_use_started` / `tool_use_completed` call events, persisted row ids ride the `assistant_spoke` event), `launchedAtMs` for dispatch timing, and a `voiceTelemetry` bag keyed by the call session with a `phone_inbound` / `phone_outbound` entry. Both drivers share the spoken progress narration cadence (`src/calls/voice-progress-cadence.ts`, tuned by `voice.frontModel.progress`): the cadence owns the tool-activity log, the triggers (an ops burst, a long operation completing, a full interval of audible silence with news, the `maxSilenceMs` heartbeat) and the generated or static phrase, while each driver supplies its own view of audible silence (live voice from its TTS queue and playback-tail estimate; the media-stream transport from `isPlaybackIdle()` and a running sum of sent frame durations) and how to speak a phrase.

package/docs/architecture/turn-actor.md

@@ -60,14 +60,21 @@ and restore the prior value afterwards, each guarding the restore so a turn that
 started in between is not clobbered. They are supplying the acting actor for
 their run, and are covered by this contract.
 
-A queued message commits to a run at its drain, not at its enqueue. The drains
-(`drainSingleMessage` and `drainBatch` in `conversation-process.ts`) stamp the
-queued sender the way `processMessage` stamps its committing actor, and re-scope
-the resident history to them, so a turn drained behind another actor's turn
-runs as its sender everywhere the resting actor is read, not only in the
-per-turn snapshot. A steered drain skips the re-scope: its sender owned the
-turn it cut off, and the resident history may carry the in-memory repair of the
-abandoned `tool_use`.
+The queue drains are deliberately not in that set. `drainSingleMessage` and
+`drainBatch` carry the queued sender on the per-turn field and into the run,
+and leave the resting slot alone: at the point they stamp, the drain has not
+yet proved it holds the processing lock. Its `isProcessing()` check is a
+time-of-check guard whose documented backstop is the persist that can still
+fail busy, and the requeue on that path restores the queue and the steer flag
+only. A drain that stamped the slot would therefore leave the conversation
+attributed to a sender whose turn never ran.
+
+The consequence is that a cross-actor drain runs against history scoped for the
+previous actor, because `ensureActorScopedHistory` reads the slot. That is a
+real defect and it is LUM-3344's, which owns the fix: scope the transcript at
+assembly time from the turn's actor, rather than mutating a shared transcript
+and tracking who it was scoped for. Do not close it by making the drain stamp
+the slot first.
 
 `call-controller` keeps its own `trustContext` on its own object and never reads
 the conversation's. It is outside this contract.

package/openapi.yaml

@@ -596,6 +596,16 @@ paths:
                     type: string
                   agent:
                     type: string
+                  requestedModel:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: The model explicitly requested for this spawn, if any.
+                  effectiveModel:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: The top-level session model reported by the ACP adapter, if any.
                   modelWarning:
                     description: Why the requested model was not applied. The session is running on the agent's own model.
                     type: string
@@ -603,6 +613,8 @@ paths:
                   - acpSessionId
                   - protocolSessionId
                   - agent
+                  - requestedModel
+                  - effectiveModel
                 additionalProperties: false
   /v1/activation/dismiss:
     post:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.0-dev.202609111819.3dcbf21",
+  "version": "0.12.0-dev.202609112015.230c060",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/always-loaded-tools-guard.test.ts

@@ -26,7 +26,7 @@ afterAll(() => {
 });
 
 describe("always-loaded tool count", () => {
-  test("should be exactly 11 with recall occupying the existing slot", async () => {
+  test("should be exactly 14 with recall occupying the existing slot", async () => {
     await initializeTools();
     const allDefs = getAllToolDefinitions();
 
@@ -48,10 +48,11 @@ describe("always-loaded tool count", () => {
     // connected — without a human in the loop, the guardian auto-approve
     // path would allow unchecked host command execution.
     //
-    // `watch_retro_report` is here for the same reason the ui_surface tools are
-    // NOT: a watch retrospective runs clientless, so it can only report through
-    // a tool that survives this baseline. Its description and schema are kept
-    // deliberately terse because that is the cost of the slot.
+    // `watch_retro_report` survives this baseline for the same reason the
+    // ui_* tools do: a watch retrospective runs clientless, so it can only
+    // report through a tool that survives this baseline. The ui_* tools are
+    // here because background UI surfaces persist and return instead of
+    // awaiting action, so they no longer need a connected client.
     const expectedNames = [
       "bash",
       "file_edit",
@@ -61,6 +62,9 @@ describe("always-loaded tool count", () => {
       "remember",
       "skill_execute",
       "skill_load",
+      "ui_dismiss",
+      "ui_show",
+      "ui_update",
       "watch_retro_report",
       "web_fetch",
       "web_search",
@@ -68,6 +72,6 @@ describe("always-loaded tool count", () => {
 
     expect(activeNames).toEqual(expectedNames);
     expect(activeNames.filter((name) => name === "recall")).toHaveLength(1);
-    expect(activeTools.length).toBe(11);
+    expect(activeTools.length).toBe(14);
   });
 });

package/src/__tests__/conversation-process-app-control-preactivation.test.ts

@@ -161,12 +161,6 @@ function makeFakeContext(opts: {
       trustClass: "guardian" as const,
       guardianPrincipalId: "user-1",
     },
-    setTrustContext(
-      this: { trustContext?: TrustContext },
-      trustContext: TrustContext | null,
-    ) {
-      this.trustContext = trustContext ?? undefined;
-    },
     setTransportHints() {},
     applyHostEnvFromTransport() {},
     ensureHostProxiesForTurn() {},
@@ -415,10 +409,10 @@ describe("drainQueue preactivation re-add for host-proxy interfaces", () => {
       "U-contact",
     );
     expect(ctx.currentTurnTrustContext?.sourceChannel).toBe("slack");
-    // The drain is where a queued message commits to a run, so the resting
-    // slot names the sender too: history is scoped from it, and a slot still
-    // naming the guardian would hand the contact's turn the guardian's rows.
-    expect(ctx.trustContext).toBe(contactTrust);
+    // The slot itself is left alone; only the turn's view is corrected. A
+    // drain stamping it would attribute the conversation to a sender whose
+    // turn can still lose the processing lock at persist time.
+    expect(ctx.trustContext?.trustClass).toBe("guardian");
   });
 
   test("buildPassthroughBatch refuses to coalesce two channel senders", async () => {

package/src/__tests__/conversation-queue.test.ts

@@ -450,17 +450,6 @@ async function waitForCondition(
   }
 }
 
-/** Count the history reloads a conversation performs from this point on. */
-function countHistoryReloads(conversation: Conversation): () => number {
-  const originalLoad = conversation.loadFromDb.bind(conversation);
-  let reloads = 0;
-  conversation.loadFromDb = async () => {
-    reloads++;
-    return originalLoad();
-  };
-  return () => reloads;
-}
-
 /**
  * Resolve the Nth pending AgentLoop.run() call. Fires the minimal events
  * that `runAgentLoop` expects (usage + message_complete) so the conversation
@@ -726,22 +715,21 @@ describe("Conversation message queue", () => {
     await new Promise((r) => setTimeout(r, 10));
   });
 
-  test("a drained turn commits its sender as the resting actor and re-scopes history", async () => {
-    // A contact's channel turn leaves the resting slot, and the resident
-    // history scoped from it, naming the contact. The guardian's message
-    // queued behind that turn must run as the guardian everywhere the slot is
-    // read, not only in the per-turn snapshot: the `<turn_context>` actor
-    // section is derived at turn start and history is scoped from the slot,
-    // so a drain that stamped only the snapshot rendered the guardian's own
-    // web turn as a trusted contact's and hid the guardian's rows from it.
+  test("the turn-context actor section describes the turn's actor, not the conversation's resting actor", async () => {
+    // The drain carries its sender on the per-turn field and leaves the
+    // resting slot naming the previous actor. The actor section is frozen at
+    // turn start, so it has to read the turn's actor: reading the slot is what
+    // told the guardian's own drained turn it was talking to a trusted
+    // contact.
     const conversation = makeConversation();
     await conversation.loadFromDb();
 
-    conversation.setTrustContext({
-      trustClass: "trusted_contact",
-      sourceChannel: "slack",
+    const contact = {
+      trustClass: "trusted_contact" as const,
+      sourceChannel: "slack" as const,
       requesterExternalUserId: "U-contact",
-    });
+    };
+    conversation.setTrustContext(contact);
 
     const p1 = conversation.processMessage({
       content: "msg-1",
@@ -756,7 +744,6 @@ describe("Conversation message queue", () => {
       sourceChannel: "vellum" as const,
       requesterExternalUserId: "guardian-principal",
     };
-    const reloads = countHistoryReloads(conversation);
     conversation.enqueueMessage({
       content: "msg-2",
       requestId: "req-2",
@@ -767,83 +754,30 @@ describe("Conversation message queue", () => {
     await p1;
     await waitForPendingRun(2);
 
-    // Read while run 2 is in flight: the slot, the snapshot, and the frozen
-    // actor section all describe the guardian, and the history was reloaded
-    // for that scope exactly once.
-    expect(conversation.getTrustContext()).toBe(guardian);
+    // Guard the test itself: the slot must disagree with the turn, or the
+    // assertion below passes for the wrong reason.
+    expect(conversation.getTrustContext()).toBe(contact);
     expect(conversation.currentTurnTrustContext).toBe(guardian);
+    // A guardian turn renders no actor section, whatever the slot says.
     expect(conversation.currentTurnInboundActorContext).toBeNull();
-    expect(reloads()).toBe(1);
 
     await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
-  test("a batched drain commits the head's sender as the resting actor", async () => {
-    // Same commitment on the batched path, which coalesces only messages that
-    // share a trust identity, so the head's sender is the batch's actor.
+  test("the actor section names the drained contact while the slot holds the guardian", async () => {
+    // The inverse direction, so the assertion above cannot pass merely because
+    // the section is always absent: a contact's message drained behind the
+    // guardian's turn must be described as that contact.
     const conversation = makeConversation();
     await conversation.loadFromDb();
 
-    conversation.setTrustContext({
-      trustClass: "trusted_contact",
-      sourceChannel: "slack",
-      requesterExternalUserId: "U-contact",
-    });
-
-    const p1 = conversation.processMessage({
-      content: "msg-1",
-      attachments: [],
-      onEvent: () => {},
-      requestId: "req-1",
-    });
-    await waitForPendingRun(1);
-
     const guardian = {
       trustClass: "guardian" as const,
       sourceChannel: "vellum" as const,
       requesterExternalUserId: "guardian-principal",
     };
-    const reloads = countHistoryReloads(conversation);
-    conversation.enqueueMessage({
-      content: "msg-2",
-      requestId: "req-2",
-      trustContext: guardian,
-    });
-    conversation.enqueueMessage({
-      content: "msg-3",
-      requestId: "req-3",
-      trustContext: guardian,
-    });
-
-    await resolveRun(0);
-    await p1;
-    await waitForPendingRun(2);
-
-    // One batched run for both siblings, committed as the guardian.
-    expect(pendingRuns.length).toBe(2);
-    expect(conversation.getTrustContext()).toBe(guardian);
-    expect(conversation.currentTurnTrustContext).toBe(guardian);
-    expect(conversation.currentTurnInboundActorContext).toBeNull();
-    expect(reloads()).toBe(1);
-
-    await resolveRun(1);
-    await new Promise((r) => setTimeout(r, 10));
-  });
-
-  test("a drained turn keeps its sender when the slot moves during the history reload", async () => {
-    // The commit captures the sender before the reload awaits. A writer that
-    // moves the slot inside that await (a wake's stamp, a pointer elevation)
-    // must not become the turn's actor: the history was reloaded for the
-    // sender, and running someone else's trust over it is the escalation.
-    const conversation = makeConversation();
-    await conversation.loadFromDb();
-
-    conversation.setTrustContext({
-      trustClass: "trusted_contact",
-      sourceChannel: "slack",
-      requesterExternalUserId: "U-contact",
-    });
+    conversation.setTrustContext(guardian);
 
     const p1 = conversation.processMessage({
       content: "msg-1",
@@ -853,49 +787,39 @@ describe("Conversation message queue", () => {
     });
     await waitForPendingRun(1);
 
-    const guardian = {
-      trustClass: "guardian" as const,
-      sourceChannel: "vellum" as const,
-      requesterExternalUserId: "guardian-principal",
-    };
-    const intruder = {
-      trustClass: "unknown" as const,
-      sourceChannel: "telegram" as const,
-      requesterExternalUserId: "T-stranger",
+    const contact = {
+      trustClass: "trusted_contact" as const,
+      sourceChannel: "slack" as const,
+      requesterExternalUserId: "U-contact",
     };
     conversation.enqueueMessage({
       content: "msg-2",
       requestId: "req-2",
-      trustContext: guardian,
+      trustContext: contact,
     });
 
-    // The drain's reload is the await the writer lands inside.
-    const originalLoad = conversation.loadFromDb.bind(conversation);
-    let movedDuringReload = false;
-    conversation.loadFromDb = async () => {
-      const result = await originalLoad();
-      conversation.setTrustContext(intruder);
-      movedDuringReload = true;
-      return result;
-    };
-
     await resolveRun(0);
     await p1;
     await waitForPendingRun(2);
 
-    expect(movedDuringReload).toBe(true);
-    expect(conversation.getTrustContext()).toBe(intruder);
-    expect(conversation.currentTurnTrustContext).toBe(guardian);
-    expect(conversation.currentTurnInboundActorContext).toBeNull();
+    expect(conversation.getTrustContext()).toBe(guardian);
+    expect(conversation.currentTurnTrustContext).toBe(contact);
+    expect(conversation.currentTurnInboundActorContext).toMatchObject({
+      trustClass: "trusted_contact",
+      sourceChannel: "slack",
+      canonicalActorIdentity: "U-contact",
+    });
 
     await resolveRun(1);
     await new Promise((r) => setTimeout(r, 10));
   });
 
-  test("a drain whose history reload fails puts the resting actor back", async () => {
-    // A reload that fails starts no turn: the message is requeued for the
-    // next drain, so the slot must not keep naming a sender whose turn never
-    // began, or conversation-level readers report an owner that is not there.
+  test("a processMessage turn whose history reload fails puts the resting actor back", async () => {
+    // `processMessage` is the commitment point, so it stamps the slot before
+    // scoping history. A reload that throws starts no turn, and leaving the
+    // stamp would attribute the conversation to a sender that never ran: an
+    // actorless dispatch afterwards (a deferred wake) resolves the resting
+    // slot and would inherit it.
     const conversation = makeConversation();
     await conversation.loadFromDb();
 
@@ -906,110 +830,27 @@ describe("Conversation message queue", () => {
     };
     conversation.setTrustContext(contact);
 
-    const p1 = conversation.processMessage({
-      content: "msg-1",
-      attachments: [],
-      onEvent: () => {},
-      requestId: "req-1",
-    });
-    await waitForPendingRun(1);
-
-    const guardian = {
-      trustClass: "guardian" as const,
-      sourceChannel: "vellum" as const,
-      requesterExternalUserId: "guardian-principal",
-    };
-    conversation.enqueueMessage({
-      content: "msg-2",
-      requestId: "req-2",
-      trustContext: guardian,
-    });
-
-    let reloadAttempts = 0;
     conversation.loadFromDb = async () => {
-      reloadAttempts++;
       throw new Error("history store exploded");
     };
 
-    // Finish the first turn; the drain (and its one retry) fail on the reload.
-    await resolveRun(0);
-    await p1;
-    await waitForCondition(() => reloadAttempts >= 2);
-    await new Promise((r) => setTimeout(r, 20));
-
-    expect(pendingRuns.length).toBe(1);
-    expect(conversation.getQueueDepth()).toBe(1);
-    expect(conversation.getTrustContext()).toBe(contact);
-  });
-
-  test("the turn-context actor section follows the turn's actor when the slot moves before the loop opens", async () => {
-    // The actor section is frozen at turn start from the turn's own actor,
-    // not from the resting slot. The drain stamps the slot and then awaits
-    // (persist) before the loop opens; an out-of-band writer landing in that
-    // window (pointer elevation restore, a wake's restore) moves the slot
-    // without owning the turn, and a read of the slot there would describe
-    // that writer's actor to the model.
-    const conversation = makeConversation();
-    await conversation.loadFromDb();
-
-    const contact = {
-      trustClass: "trusted_contact" as const,
-      sourceChannel: "slack" as const,
-      requesterExternalUserId: "U-contact",
-    };
-    conversation.setTrustContext(contact);
-
-    const p1 = conversation.processMessage({
-      content: "msg-1",
-      attachments: [],
-      onEvent: () => {},
-      requestId: "req-1",
-    });
-    await waitForPendingRun(1);
-
     const guardian = {
       trustClass: "guardian" as const,
       sourceChannel: "vellum" as const,
       requesterExternalUserId: "guardian-principal",
     };
-    conversation.enqueueMessage({
-      content: "msg-2",
-      requestId: "req-2",
-      trustContext: guardian,
-    });
-
-    // Land the out-of-band slot write inside the drain's window, after its
-    // stamp and before the loop opens: the drain awaits persistUserMessage
-    // there. The resting slot alone is moved; the per-turn snapshot is the
-    // drain's to carry into the run.
-    const originalPersist = conversation.persistUserMessage.bind(conversation);
-    let slotMoved = false;
-    (
-      conversation as unknown as {
-        persistUserMessage: typeof conversation.persistUserMessage;
-      }
-    ).persistUserMessage = async (opts) => {
-      const result = await originalPersist(opts);
-      conversation.setTrustContext(contact);
-      slotMoved = true;
-      return result;
-    };
-
-    await resolveRun(0);
-    await p1;
-    await waitForPendingRun(2);
+    await expect(
+      conversation.processMessage({
+        content: "msg-1",
+        attachments: [],
+        onEvent: () => {},
+        requestId: "req-1",
+        trustContext: guardian,
+      }),
+    ).rejects.toThrow("history store exploded");
 
-    // Guard the test itself: the injection must have run, and the slot must
-    // disagree with the turn, or the assertion below passes for the wrong
-    // reason.
-    expect(slotMoved).toBe(true);
     expect(conversation.getTrustContext()).toBe(contact);
-    expect(conversation.currentTurnTrustContext).toBe(guardian);
-    // The guardian's turn renders no actor section, whatever the slot says.
-    expect(conversation.currentTurnInboundActorContext).toBeNull();
-
-    await resolveRun(1);
-    await new Promise((r) => setTimeout(r, 10));
+    expect(pendingRuns.length).toBe(0);
   });
 
   test("a processMessage turn keeps its turn-start trust when the slot moves before the loop opens", async () => {

package/src/__tests__/conversation-surfaces-task-progress.test.ts

@@ -21,6 +21,7 @@ import {
 function makeContext(
   sent: AssistantEvent[] = [],
   channelCapabilities?: { channel: string; supportsDynamicUi: boolean },
+  opts?: { hasNoClient?: boolean },
 ): Conversation {
   return asConversation({
     conversationId: "session-1",
@@ -37,6 +38,7 @@ function makeContext(
     accumulatedSurfaceState: new Map<string, Record<string, unknown>>(),
     surfaceActionRequestIds: new Set<string>(),
     currentTurnSurfaces: [],
+    hasNoClient: opts?.hasNoClient ?? false,
     isProcessing: () => false,
     enqueueMessage: () => ({ queued: false, requestId: "req-1" }),
     getQueueDepth: () => 0,
@@ -65,6 +67,71 @@ describe("task_progress surface compatibility", () => {
     expect(sent).toHaveLength(0);
   });
 
+  test("persists a clientless choice from a non-rendering channel without waiting", async () => {
+    const sent: AssistantEvent[] = [];
+    const ctx = makeContext(
+      sent,
+      {
+        channel: "phone",
+        supportsDynamicUi: false,
+      },
+      { hasNoClient: true },
+    );
+
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "choice",
+      title: "Choose a focus",
+      data: {
+        options: [
+          { id: "inbox", title: "Inbox" },
+          { id: "calendar", title: "Calendar" },
+        ],
+      },
+    });
+
+    expect(result.isError).toBe(false);
+    expect(result.yieldToUser).toBeUndefined();
+    const { surfaceId } = JSON.parse(result.content) as { surfaceId: string };
+    expect(ctx.currentTurnSurfaces.some((s) => s.surfaceId === surfaceId)).toBe(
+      true,
+    );
+    expect(ctx.pendingSurfaceActions.has(surfaceId)).toBe(false);
+    expect(sent.some((msg) => msg.type === "ui_surface_show")).toBe(true);
+  });
+
+  test("persists a clientless update in the current-turn surface snapshot", async () => {
+    const sent: AssistantEvent[] = [];
+    const ctx = makeContext(
+      sent,
+      {
+        channel: "phone",
+        supportsDynamicUi: false,
+      },
+      { hasNoClient: true },
+    );
+    const shown = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      title: "Background work",
+      data: {
+        template: "task_progress",
+        templateData: { status: "in_progress", steps: [] },
+      },
+    });
+    const { surfaceId } = JSON.parse(shown.content) as { surfaceId: string };
+
+    const result = await surfaceProxyResolver(ctx, "ui_update", {
+      surface_id: surfaceId,
+      data: { templateData: { status: "completed" } },
+    });
+
+    expect(result.isError).toBe(false);
+    const data = ctx.currentTurnSurfaces.find((s) => s.surfaceId === surfaceId)
+      ?.data as CardSurfaceData;
+    expect((data.templateData as Record<string, unknown>).status).toBe(
+      "completed",
+    );
+  });
+
   test("blocks ui_update when channel lacks dynamic UI support", async () => {
     const sent: AssistantEvent[] = [];
     const ctx = makeContext(sent, {

package/src/__tests__/drain-kick-guard.test.ts

@@ -79,8 +79,6 @@ function makeFakeConversation(
     getTurnInterfaceContext: () => null,
     setTurnInterfaceContext: () => {},
     setTransportHints: () => {},
-    setTrustContext: () => {},
-    ensureActorScopedHistory: async () => {},
     emitActivityState: () => {
       if (activityFailures > 0) {
         activityFailures -= 1;

package/src/__tests__/drain-requeue-on-contention.test.ts

@@ -78,12 +78,6 @@ function makeFakeConversation(options: {
     setTransportHints: () => {
       mutationCalls.push("setTransportHints");
     },
-    setTrustContext: () => {
-      mutationCalls.push("setTrustContext");
-    },
-    ensureActorScopedHistory: async () => {
-      mutationCalls.push("ensureActorScopedHistory");
-    },
     emitActivityState: () => {
       mutationCalls.push("emitActivityState");
     },

package/src/__tests__/subagent-tool-gate-mode.test.ts

@@ -249,14 +249,19 @@ describe("createResolveToolsCallback — toolContextPin", () => {
     });
   }
 
-  test("control: without a pin, a clientless fork drops every client-gated tool from the wire", () => {
+  test("control: without a pin, a clientless fork drops every client-gated tool but ui_show", () => {
     projectedSkillToolNames = [];
     const resolve = createResolveToolsCallback(
       CLIENT_GATED_DEFS,
       clientlessExecutionCtx(),
     )!;
 
-    expect(resolve(EMPTY_HISTORY).map((t) => t.name)).toEqual(["remember"]);
+    // ui_show stays on the wire: background UI surfaces persist and return
+    // instead of awaiting action, so they no longer need a connected client.
+    expect(resolve(EMPTY_HISTORY).map((t) => t.name)).toEqual([
+      "remember",
+      "ui_show",
+    ]);
   });
 
   test("a desktop-source pin restores the host/UI/client tool defs on the wire", () => {
@@ -291,7 +296,11 @@ describe("createResolveToolsCallback — toolContextPin", () => {
       }),
     )!;
 
-    expect(resolve(EMPTY_HISTORY).map((t) => t.name)).toEqual(["remember"]);
+    // ui_show survives the clientless pin: it persists and returns.
+    expect(resolve(EMPTY_HISTORY).map((t) => t.name)).toEqual([
+      "remember",
+      "ui_show",
+    ]);
   });
 
   test("invariant: a pinned-in tool is on the wire but can never execute", async () => {