@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/runtime/__tests__/host-observe.test.ts

@@ -9,7 +9,8 @@
  *  3. `executionError` from the client surfaces as a structured failure.
  *  4. The pending interaction is unregistered on every path.
  *  5. No capable client connected: failure rather than a throw.
- *  6. `includeScreenshot: false` drops the screenshot from the result.
+ *  6. `includeScreenshot: false` drops the screenshot from the result, and
+ *     is sent to the helper only for an unscoped observation.
  *  7. Actor binding: another user's client is never selected by default, an
  *     explicit clientId owned by another user is rejected, a caller with no
  *     actor principal reaches nothing, and two same-user clients are
@@ -226,6 +227,44 @@ describe("observeHostScreen", () => {
     expect(pendingInteractions.getAll()).toHaveLength(0);
   });
 
+  test("tells the helper when no screenshot is wanted on an unscoped observation, and only then", async () => {
+    const skipped = observe({ includeScreenshot: false });
+    const skippedRequest = sentMessages.find(
+      (m) => m.type === "host_cu_request",
+    );
+    expect(skippedRequest?.input).toEqual({ includeScreenshot: false });
+    await postResult({ requestId: sentRequestId(), axTree: "Window [1]" });
+    await skipped;
+
+    sentMessages.length = 0;
+    const wanted = observe();
+    const wantedRequest = sentMessages.find(
+      (m) => m.type === "host_cu_request",
+    );
+    expect(wantedRequest?.input).toEqual({});
+    await postResult({ requestId: sentRequestId(), axTree: "Window [1]" });
+    await wanted;
+  });
+
+  test("a scoped observation sends no opt-out and still drops the screenshot", async () => {
+    const observation = observe({
+      includeScreenshot: false,
+      captureTarget: { kind: "window", windowId: 4211 },
+    });
+    const request = sentMessages.find((m) => m.type === "host_cu_request");
+    expect(request?.input).toEqual({ captureWindowId: 4211 });
+
+    await postResult({
+      requestId: sentRequestId(),
+      axTree: "Window [1]",
+      screenshot: "base64png",
+      screenshotWidthPx: 1200,
+      screenshotHeightPx: 800,
+    });
+
+    expect(await observation).toEqual({ ok: true, axTree: "Window [1]" });
+  });
+
   test("drops the screenshot when includeScreenshot is false", async () => {
     const observation = observe({ includeScreenshot: false });
     await postResult({

package/src/runtime/__tests__/live-voice-upgrade.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { RuntimeHttpServer } from "../http-server.js";
+import {
+  mintActorToken,
+  mintGatewayToken,
+  requireHttpAuth,
+  upgradeHeaders,
+} from "./runtime-ws-test-utils.js";
+
+describe("Live voice through the shared runtime upgrade", () => {
+  let restoreAuth: () => void;
+  beforeEach(() => {
+    restoreAuth = requireHttpAuth();
+  });
+  afterEach(() => restoreAuth());
+
+  function upgrade(token: string, guardianPrincipalId?: string) {
+    const runtime = new RuntimeHttpServer();
+    const server = {
+      requestIP: () => ({ address: "127.0.0.1" }),
+      upgrade: mock(() => true),
+    };
+    const query = new URLSearchParams({ token });
+    if (guardianPrincipalId !== undefined) {
+      query.set("guardianPrincipalId", guardianPrincipalId);
+    }
+    const response = runtime["handleLiveVoiceUpgrade"](
+      new Request(`http://127.0.0.1/v1/live-voice?${query}`, {
+        headers: upgradeHeaders,
+      }),
+      server as unknown as ReturnType<typeof Bun.serve>,
+    );
+    return { response, server };
+  }
+
+  test("forwards the gateway-admitted guardian identity to the session", () => {
+    const { response, server } = upgrade(mintGatewayToken(), "user-123");
+    expect(response).toBeUndefined();
+    expect(server.upgrade).toHaveBeenCalledWith(expect.any(Request), {
+      data: { wsType: "live-voice", guardianPrincipalId: "user-123" },
+    });
+  });
+
+  test("accepts gateway clients without a guardian identity", () => {
+    const { response, server } = upgrade(mintGatewayToken());
+    expect(response).toBeUndefined();
+    expect(server.upgrade).toHaveBeenCalledWith(expect.any(Request), {
+      data: { wsType: "live-voice" },
+    });
+  });
+
+  test("rejects actor tokens even when they supply a guardian identity", () => {
+    const { response, server } = upgrade(mintActorToken(), "user-123");
+    expect(response?.status).toBe(401);
+    expect(server.upgrade).not.toHaveBeenCalled();
+  });
+});

package/src/runtime/__tests__/runtime-ws-test-utils.ts

@@ -0,0 +1,72 @@
+/** Shared pieces for suites that open WebSockets against `RuntimeHttpServer`. */
+
+import { CURRENT_POLICY_EPOCH } from "../auth/policy.js";
+import { mintToken } from "../auth/token-service.js";
+
+export function mintGatewayToken(): string {
+  return mintToken({
+    aud: "vellum-daemon",
+    sub: "svc:gateway:self",
+    scope_profile: "gateway_ingress_v1",
+    policy_epoch: CURRENT_POLICY_EPOCH,
+    ttlSeconds: 3600,
+  });
+}
+
+export function mintActorToken(): string {
+  return mintToken({
+    aud: "vellum-daemon",
+    sub: "actor:self:user-123",
+    scope_profile: "actor_client_v1",
+    policy_epoch: CURRENT_POLICY_EPOCH,
+    ttlSeconds: 3600,
+  });
+}
+
+/** Headers of a WebSocket upgrade sent through plain `fetch`. */
+export const upgradeHeaders = {
+  Upgrade: "websocket",
+  Connection: "Upgrade",
+  "Sec-WebSocket-Key": "dGhlIHNhbXBsZSBub25jZQ==",
+  "Sec-WebSocket-Version": "13",
+};
+
+export function waitForClose(
+  ws: WebSocket,
+  timeoutMs = 2000,
+): Promise<CloseEvent> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error("Timed out waiting for WebSocket close"));
+    }, timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      ws.removeEventListener("close", onClose);
+      ws.removeEventListener("error", onError);
+    };
+    const onClose = (event: CloseEvent) => {
+      cleanup();
+      resolve(event);
+    };
+    const onError = () => {
+      cleanup();
+      reject(new Error("WebSocket close failed"));
+    };
+    ws.addEventListener("close", onClose);
+    ws.addEventListener("error", onError);
+  });
+}
+
+/** Turn real HTTP auth on for a test; the returned function restores the env. */
+export function requireHttpAuth(): () => void {
+  const saved = process.env.DISABLE_HTTP_AUTH;
+  delete process.env.DISABLE_HTTP_AUTH;
+  return () => {
+    if (saved === undefined) {
+      delete process.env.DISABLE_HTTP_AUTH;
+    } else {
+      process.env.DISABLE_HTTP_AUTH = saved;
+    }
+  };
+}

package/src/runtime/__tests__/watch-stream-upgrade.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { RuntimeHttpServer } from "../http-server.js";
+import {
+  mintGatewayToken,
+  requireHttpAuth,
+  upgradeHeaders,
+} from "./runtime-ws-test-utils.js";
+
+describe("Watch capture target through the shared runtime upgrade", () => {
+  let restoreAuth: () => void;
+  beforeEach(() => {
+    restoreAuth = requireHttpAuth();
+  });
+  afterEach(() => restoreAuth());
+
+  function upgrade(params: string) {
+    const runtime = new RuntimeHttpServer();
+    const server = {
+      requestIP: () => ({ address: "127.0.0.1" }),
+      upgrade: mock(() => true),
+    };
+    const response = runtime["handleWatchStreamUpgrade"](
+      new Request(
+        `http://127.0.0.1/v1/watch/stream?token=${mintGatewayToken()}&mimeType=audio/pcm&sampleRate=16000&${params}`,
+        { headers: upgradeHeaders },
+      ),
+      server as unknown as ReturnType<typeof Bun.serve>,
+    );
+    return { response, server };
+  }
+
+  test.each([
+    ["captureWindowId=4242", { kind: "window", windowId: 4242 }],
+    ["captureDisplayId=7", { kind: "display", displayId: 7 }],
+    ["", undefined],
+  ])("preserves the selected target: %s", (params, captureTarget) => {
+    const { response, server } = upgrade(params);
+    expect(response).toBeUndefined();
+    expect(server.upgrade).toHaveBeenCalledWith(expect.any(Request), {
+      data: expect.objectContaining({
+        wsType: "watch-stream",
+        mimeType: "audio/pcm",
+        sampleRate: 16000,
+        captureTarget,
+      }),
+    });
+  });
+
+  test.each([
+    "captureWindowId=abc",
+    "captureDisplayId=-1",
+    "captureWindowId=1&captureDisplayId=2",
+  ])("refuses an invalid target before upgrading: %s", (params) => {
+    const { response, server } = upgrade(params);
+    expect(response?.status).toBe(400);
+    expect(server.upgrade).not.toHaveBeenCalled();
+  });
+});

package/src/runtime/agent-wake.ts

@@ -126,6 +126,7 @@ import {
 import type { CompletedBackgroundTool } from "../tools/background-tool-registry.js";
 import { getLogger } from "../util/logger.js";
 import { createKeyedSingleFlight } from "../util/single-flight.js";
+import { safeStringSlice } from "../util/unicode.js";
 
 const log = getLogger("agent-wake");
 
@@ -139,7 +140,7 @@ const WAKE_POSTAMBLE =
 
 /** Sanitize a value for use as an XML attribute (no quotes/brackets/newlines). */
 function sanitizeEventAttr(value: string): string {
-  return value.replace(/[<>"&\r\n]/g, "").slice(0, 200);
+  return safeStringSlice(value.replace(/[<>"&\r\n]/g, ""), 0, 200);
 }
 
 /**

package/src/runtime/assistant-event-hub.ts

@@ -745,9 +745,8 @@ export function broadcastMessage(
   // A reconnect can overlap an older executor with the same device ID.
   // Filter at delivery too, not only when HostCuProxy resolves its target.
   const targetCapability =
-    msg.type === "host_cu_request" &&
-    Object.hasOwn(msg.input, "capture_window_id")
-      ? "host_cu_window_capture"
+    msg.type === "host_cu_request"
+      ? hostCuRequestCapability(msg.toolName, msg.input)
       : capabilityForMessageType(msg.type);
   // Self-echo suppression: a `sync_changed` carrying an `originClientId`
   // means a specific client just mutated the resource. The hub must not
@@ -782,6 +781,25 @@ export function broadcastMessage(
     });
 }
 
+/**
+ * The capability a `host_cu_request` needs from the client that receives it.
+ * Window-scoped observation and batched actions are answered only by a helper
+ * that claimed them; an older helper would capture the whole desktop or end
+ * the session on the unknown tool.
+ */
+function hostCuRequestCapability(
+  toolName: string,
+  input: Record<string, unknown>,
+): HostProxyCapability {
+  if (Object.hasOwn(input, "capture_window_id")) {
+    return "host_cu_window_capture";
+  }
+  if (toolName === "computer_use_sequence") {
+    return "host_cu_sequence";
+  }
+  return "host_cu";
+}
+
 function extractConversationId(msg: AssistantEvent): string | undefined {
   const record = msg as unknown as Record<string, unknown>;
   if ("conversationId" in msg && typeof record.conversationId === "string") {

package/src/runtime/auth/same-actor.ts

@@ -142,9 +142,7 @@ function detectRejection(
     ? args.hub.getActorPrincipalIdForClient(args.targetClientId)
     : (args.targetActorPrincipalId ??
       (isHttpAuthDisabled() && targetClientId
-        ? args.hubForMissingTarget?.getActorPrincipalIdForClient(
-            targetClientId,
-          )
+        ? args.hubForMissingTarget?.getActorPrincipalIdForClient(targetClientId)
         : undefined));
 
   let reason: RejectionReason | undefined;
@@ -264,6 +262,43 @@ export function pickSameUserAutoResolve(args: {
   return { kind: "ambiguous" };
 }
 
+/**
+ * Pick the most recently active capable client owned by the turn actor.
+ * `listClientsByCapability` is ordered by recent activity, so the first
+ * same-user match provides deterministic routing without broadcasting a host
+ * request across multiple devices.
+ */
+export function pickMostRecentSameUserClient(args: {
+  hub: Pick<AssistantEventHub, "listClientsByCapability">;
+  capability: HostProxyCapability;
+  sourceActorPrincipalId: string | undefined;
+}): string | undefined {
+  const { hub, capability, sourceActorPrincipalId } = args;
+  if (sourceActorPrincipalId == null) {
+    return undefined;
+  }
+  return hub
+    .listClientsByCapability(capability)
+    .find((client) => client.actorPrincipalId === sourceActorPrincipalId)
+    ?.clientId;
+}
+
+/**
+ * Error result for an automatic host route with no capable client owned by the
+ * actor that initiated the turn.
+ */
+export function unavailableSameUserClientError(
+  capability: HostProxyCapability,
+): {
+  content: string;
+  isError: true;
+} {
+  return {
+    content: `No connected ${capability} client belongs to this user. Connect a capable client signed in as the same user, then retry.`,
+    isError: true,
+  };
+}
+
 /**
  * Actor principal persisted on a host-proxy pending interaction.
  *

package/src/runtime/channel-send.ts

@@ -0,0 +1,316 @@
+/**
+ * A model-directed text send to a channel chat, through the channel's
+ * transport, recorded after the channel acknowledges it.
+ *
+ * This is the one send implementation per addressable channel. The
+ * messaging tool's channel branch and the `channels send` route both call
+ * it, so a send costs the same and leaves the same record whichever door it
+ * came through. The transport owns the routing: the caller names a neutral
+ * target, the transport resolves it into its own callback context, and
+ * nothing here switches on a channel's name.
+ *
+ * Nothing is written before the channel acknowledges. The record carries
+ * every id the text became, so a failed send leaves no row that reads as
+ * something the assistant said, and a reaction, edit, or delete naming any
+ * chunk resolves to the row; the inbound binding a transport asks for is
+ * written after the same acknowledgement, so a failed send does not move
+ * where the chat's next message lands. A send into the sending turn's own
+ * chat and thread writes no row: its tool call and result already sit in
+ * that conversation's history, and a second assistant row beside the tool
+ * pair would break history repair.
+ */
+
+import { type ChannelId, isChannelId } from "../channels/types.js";
+import type {
+  ProactiveAddress,
+  ProactiveTarget,
+} from "../messaging/providers/channel-transport.js";
+import { getTransportForChannel } from "../messaging/providers/index.js";
+import { resolveProactiveHomeConversation } from "../notifications/conversation-pairing.js";
+import { recordDeliveredChannelPost } from "../notifications/delivered-post-record.js";
+import { getConversation } from "../persistence/conversation-crud.js";
+import { syncMessageToDisk } from "../persistence/conversation-disk-view.js";
+import { getOrCreateConversation } from "../persistence/conversation-key-store.js";
+import { buildScopedConversationKey } from "../persistence/delivery-crud.js";
+import {
+  normalizeExternalThreadId,
+  upsertOutboundBinding,
+} from "../persistence/external-conversation-store.js";
+import { getLogger } from "../util/logger.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
+import { publishConversationListChanged } from "./sync/resource-sync-events.js";
+
+const log = getLogger("channel-send");
+
+/**
+ * The turn a send is made from, as a snapshot taken when the turn started:
+ * the channel it arrived on, the chat, and the thread. Read from the turn
+ * rather than from the live binding, which a concurrent inbound can rewrite
+ * while the send runs. A caller with no turn (a script) names only the
+ * conversation it acts for, and the home comparison decides on its own.
+ */
+export interface ChannelSendSender {
+  readonly conversationId: string;
+  readonly executionChannel?: string;
+  readonly requesterChatId?: string;
+  readonly sourceThreadId?: string;
+}
+
+export interface ChannelSendParams {
+  readonly channel: string;
+  readonly target: ProactiveTarget;
+  readonly text: string;
+  /** Ask the channel for its rich rendering of the text, where it has one. */
+  readonly renderRichly?: boolean;
+  /** The assistant the send acts for; absent or `self` is this assistant. */
+  readonly assistantId?: string;
+  readonly sender?: ChannelSendSender;
+}
+
+export interface ChannelSendResult {
+  readonly channel: ChannelId;
+  /** The chat the post landed in, in the channel's own id space. */
+  readonly chatId: string;
+  /** The thread the post landed in, absent when it is not in one. */
+  readonly threadId?: string;
+  /** Every id the channel acknowledged for the text, in send order; never empty. */
+  readonly messageIds: readonly string[];
+  /** The id of the final post, the one a later edit or withdrawal addresses. */
+  readonly lastMessageId: string;
+  /** The conversation the post was recorded in, absent when it was not. */
+  readonly recordedIn?: string;
+}
+
+/** The channel cannot be reached from a named target. */
+export class ChannelNotAddressableError extends Error {
+  constructor(
+    readonly channel: string,
+    reason: string,
+  ) {
+    super(`Channel "${channel}" ${reason}.`);
+    this.name = "ChannelNotAddressableError";
+  }
+}
+
+/**
+ * The transport ran but the channel did not acknowledge the send. A success
+ * that names no message id counts: an id is what makes the post addressable
+ * afterwards, and without one there is nothing to record.
+ */
+export class ChannelSendFailedError extends Error {
+  constructor(
+    readonly channel: ChannelId,
+    reason = "did not acknowledge the send",
+  ) {
+    super(`Channel "${channel}" ${reason}.`);
+    this.name = "ChannelSendFailedError";
+  }
+}
+
+/**
+ * Whether a channel's transport declares it can be addressed from a named
+ * chat. A channel with no transport, or one that only answers on an inbound
+ * callback, is not.
+ */
+export function isProactivelyAddressable(channel: string): boolean {
+  return getTransportForChannel(channel)?.addressFor !== undefined;
+}
+
+/**
+ * Deliver `text` to `target` on `channel` and record what was sent.
+ *
+ * Throws {@link ChannelNotAddressableError} before any delivery when the
+ * channel or the target shape cannot be addressed, and
+ * {@link ChannelSendFailedError} when the transport reports no
+ * acknowledgement or no message id. A binding or recording failure never
+ * fails the send: the message is already out.
+ */
+export async function sendChannelText(
+  params: ChannelSendParams,
+): Promise<ChannelSendResult> {
+  const { channel, target, text } = params;
+  if (!isChannelId(channel)) {
+    throw new ChannelNotAddressableError(channel, "is not a channel");
+  }
+  const transport = getTransportForChannel(channel);
+  if (!transport?.addressFor) {
+    throw new ChannelNotAddressableError(
+      channel,
+      "cannot be addressed from a named chat",
+    );
+  }
+  const address = transport.addressFor(target);
+  if (!address) {
+    throw new ChannelNotAddressableError(channel, "cannot address that chat");
+  }
+
+  const result = await transport.deliver(address.ctx, {
+    chatId: address.chatId,
+    text,
+    ...(params.renderRichly ? { renderRichly: true } : {}),
+    ...(params.assistantId ? { assistantId: params.assistantId } : {}),
+  });
+  if (!result.ok) {
+    throw new ChannelSendFailedError(channel);
+  }
+  const messageIds = result.messageIds ?? (result.ts ? [result.ts] : []);
+  const lastMessageId = result.ts ?? messageIds[messageIds.length - 1];
+  if (!lastMessageId) {
+    throw new ChannelSendFailedError(channel, "acknowledged no message id");
+  }
+
+  const actsForSelf =
+    !params.assistantId || params.assistantId === DAEMON_INTERNAL_ASSISTANT_ID;
+  if (transport.bindsChatOnProactiveSend && actsForSelf) {
+    bindChatForNextInbound(channel, address);
+  }
+
+  const recordedIn = await recordProactivePost({
+    channel,
+    address,
+    text,
+    messageIds,
+    sender: params.sender,
+  });
+
+  return {
+    channel,
+    chatId: address.chatId,
+    ...(address.threadId ? { threadId: address.threadId } : {}),
+    messageIds,
+    lastMessageId,
+    ...(recordedIn ? { recordedIn } : {}),
+  };
+}
+
+/**
+ * Bind the chat's inbound conversation to the delivered chat and thread, so
+ * the next message from there resolves to the conversation ingress uses for
+ * it. The key is the one ingress builds, thread-scoped where the channel
+ * scopes conversations by thread, so a topic's replies continue the topic's
+ * conversation. Runs after acknowledgement: the message is out, so the
+ * binding it asks for is owed. Best effort: a binding failure must not fail
+ * the send.
+ */
+function bindChatForNextInbound(
+  channel: ChannelId,
+  address: ProactiveAddress,
+): void {
+  try {
+    const { conversationId, created } = getOrCreateConversation(
+      buildScopedConversationKey(channel, address.chatId, address.threadId),
+    );
+    // Published before the binding, not after: the conversation exists as
+    // soon as it is minted, the record that follows finds it rather than
+    // minting it, and a binding that throws must not leave a conversation
+    // holding a real message out of the list.
+    if (created) {
+      publishConversationListChanged("created");
+    }
+    upsertOutboundBinding({
+      conversationId,
+      sourceChannel: channel,
+      externalChatId: address.chatId,
+      externalThreadId: address.threadId ?? null,
+    });
+  } catch (e) {
+    log.warn(
+      {
+        err: e,
+        channel,
+        externalChatId: address.chatId,
+        externalThreadId: address.threadId,
+      },
+      "Failed to bind the chat's inbound conversation after the send",
+    );
+  }
+}
+
+/**
+ * Record the acknowledged post where the chat's proactive posts live, so
+ * the chat's own conversation and `recall` can see what was sent from
+ * elsewhere. The row names the thread the post landed in, as the transport
+ * resolved it. Returns the conversation it was recorded in, or `undefined`
+ * when nothing was recorded: the send went into the sending turn's own chat
+ * and thread, or the home is the sender.
+ */
+async function recordProactivePost(params: {
+  channel: ChannelId;
+  address: ProactiveAddress;
+  text: string;
+  messageIds: readonly string[];
+  sender: ChannelSendSender | undefined;
+}): Promise<string | undefined> {
+  const { channel, address, sender } = params;
+  const [firstId, ...restIds] = params.messageIds;
+  if (!firstId) {
+    return undefined;
+  }
+  try {
+    if (
+      sender &&
+      isSendIntoOwnChat(sender, channel, address.chatId, address.threadId)
+    ) {
+      return undefined;
+    }
+    const home = await resolveProactiveHomeConversation({
+      sourceChannel: channel,
+      externalChatId: address.chatId,
+      threadId: address.threadId,
+      source: "notification",
+      conversationType: "background",
+      title: `Messages to ${address.chatId}`,
+    });
+    if (home.conversationId === sender?.conversationId) {
+      return undefined;
+    }
+    const recorded = await recordDeliveredChannelPost({
+      conversationId: home.conversationId,
+      channel,
+      externalChatId: address.chatId,
+      ...(address.threadId ? { threadId: address.threadId } : {}),
+      text: params.text,
+      providerMessageId: firstId,
+      ...(restIds.length > 0 ? { additionalProviderMessageIds: restIds } : {}),
+      ...(sender ? { crossPostedFrom: sender.conversationId } : {}),
+    });
+    const homeConversation = getConversation(home.conversationId);
+    if (homeConversation) {
+      syncMessageToDisk(
+        home.conversationId,
+        recorded.messageId,
+        homeConversation.createdAt,
+      );
+    }
+    return home.conversationId;
+  } catch (e) {
+    log.warn(
+      { err: e, channel, externalChatId: address.chatId },
+      "Failed to record the sent message in the chat's conversation",
+    );
+    return undefined;
+  }
+}
+
+/**
+ * True when the delivered chat and thread are the ones the sending turn
+ * arrived in. Thread ids compare in the binding store's normalized form, so
+ * an absent thread on both sides matches and a thread-less delivery never
+ * matches a turn that arrived in a thread.
+ */
+function isSendIntoOwnChat(
+  sender: ChannelSendSender,
+  channel: ChannelId,
+  chatId: string,
+  deliveredThreadId: string | undefined,
+): boolean {
+  if (!sender.executionChannel || !sender.requesterChatId) {
+    return false;
+  }
+  return (
+    sender.executionChannel === channel &&
+    sender.requesterChatId === chatId &&
+    normalizeExternalThreadId(sender.sourceThreadId) ===
+      normalizeExternalThreadId(deliveredThreadId)
+  );
+}

package/src/runtime/host-observe.ts

@@ -257,7 +257,17 @@ export async function observeHostScreen(
             // conversation is attached.
             conversationId: options.stateKey ?? "",
             toolName: "computer_use_observe",
-            input: captureTargetInput(options.captureTarget),
+            // An unscoped request tells the helper up front when no
+            // screenshot is wanted, so it can skip capturing and uploading
+            // one. The helper always captures a scoped observation, so the
+            // flag is not sent there. The strip below removes the picture in
+            // both cases.
+            input: {
+              ...captureTargetInput(options.captureTarget),
+              ...(includeScreenshot || options.captureTarget !== undefined
+                ? {}
+                : { includeScreenshot: false }),
+            },
             stepNumber: 1,
           },
           undefined,