@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/providers/retry.ts

@@ -1,5 +1,3 @@
-import { randomUUID } from "node:crypto";
-
 import {
   resolveCallSiteConfig,
   selectWinningProfile,
@@ -10,7 +8,6 @@ import {
   sanitizeUsageMetadataValue,
 } from "../usage/attribution.js";
 import { resolveSubagentAttribution } from "../usage/subagent-attribution.js";
-import { getExistingDeviceId } from "../util/device-id.js";
 import {
   type ProviderCredentialSource,
   ProviderError,
@@ -43,7 +40,8 @@ import {
   isAdaptiveThinkingOnlyModel,
   isAdaptiveThinkingUnsupportedModel,
 } from "./model-catalog.js";
-import { buildOpenCodeRequestHeaders } from "./opencode/client.js";
+import { resolveOpenCodeRequestHeaders } from "./opencode/client.js";
+import { sanitizeOutboundRequest } from "./outbound-request-sanitize.js";
 import { dispatchProviderResolvable } from "./provider-resolvability.js";
 import {
   isThinkingConfigAdaptive,
@@ -646,18 +644,11 @@ function normalizeSendMessageOptions(
       typeof config.conversationId === "string"
         ? config.conversationId
         : undefined;
-    const requestHeaders = buildOpenCodeRequestHeaders({
-      conversationId,
-      // Background call paths (memory/commit-message enrichment,
-      // proactivity, workflow runs) have no conversationId - reuse the
-      // existing stable per-device ID so those requests still carry a
-      // session header instead of persisting a new ID for this purpose.
-      fallbackSessionId: getExistingDeviceId() ?? undefined,
-      requestId: randomUUID(),
-    });
-    if (Object.keys(requestHeaders).length > 0) {
-      nextConfig.requestHeaders = requestHeaders;
-    }
+    // Profile probes and background call paths (memory/commit-message
+    // enrichment, proactivity, workflow runs) have no conversationId; the
+    // fallback keeps a session header on every request since zen/go rejects
+    // requests without one.
+    nextConfig.requestHeaders = resolveOpenCodeRequestHeaders(conversationId);
   }
 
   // `overrideProfile`, `forceOverrideProfile`, `selectionSeed`,
@@ -1142,8 +1133,9 @@ export class RetryProvider implements Provider {
 
   // Forward the optional token-counting endpoint so the capability survives
   // the wrapper chain (callers gate on its presence). Bound straight to the
-  // inner provider — count_tokens is a cheap separate endpoint and its caller
-  // already falls back on error, so it needs no retry wrapping.
+  // inner provider behind the same surrogate sanitizer as `sendMessage` —
+  // count_tokens is a cheap separate endpoint and its caller already falls
+  // back on error, so it needs no retry wrapping.
   // Deliberately not re-bound when a credential refresh swaps `inner`: every
   // outer wrapper snapshots this the same way at construction, so a re-bind
   // here would never reach callers. count_tokens on the pre-refresh credential
@@ -1188,7 +1180,18 @@ export class RetryProvider implements Provider {
     this.inner = inner;
     this.name = inner.name;
     if (inner.countInputTokens) {
-      this.countInputTokens = inner.countInputTokens.bind(inner);
+      const countInputTokens = inner.countInputTokens.bind(inner);
+      this.countInputTokens = (messages, systemPrompt, tools) => {
+        const clean = sanitizeOutboundRequest(this.name, {
+          messages,
+          options: { systemPrompt, tools },
+        });
+        return countInputTokens(
+          clean.messages,
+          clean.options?.systemPrompt ?? systemPrompt,
+          clean.options?.tools,
+        );
+      };
     }
   }
 
@@ -1262,6 +1265,14 @@ export class RetryProvider implements Provider {
     let credentialRefreshAttempted = false;
     let correctiveResendAttempted = false;
     let fallbackAttempted = false;
+
+    // Every attempt below, the backup route included, sends what this
+    // wrapper was handed, so an orphaned UTF-16 surrogate is stripped here
+    // once rather than rejected by the upstream parser on every resend.
+    ({ messages, options } = sanitizeOutboundRequest(this.name, {
+      messages,
+      options,
+    }));
     let messagesForAttempt = messages;
 
     const normalizedOptions = normalizeSendMessageOptions(this.name, options, {

package/src/providers/unparseable-tool-args.ts

@@ -12,6 +12,8 @@
  * an error tool result, so the model sees the failure and can retry, instead
  * of a tool executing with garbage input.
  */
+
+import { safeStringSlice } from "../util/unicode.js";
 const UNPARSEABLE_TOOL_ARGS_KEY = "_raw";
 
 /**
@@ -56,7 +58,9 @@ export function unparseableToolArgsMessage(
 ): string {
   const PREVIEW_LIMIT = 200;
   const preview =
-    raw.length > PREVIEW_LIMIT ? `${raw.slice(0, PREVIEW_LIMIT)}…` : raw;
+    raw.length > PREVIEW_LIMIT
+      ? `${safeStringSlice(raw, 0, PREVIEW_LIMIT)}…`
+      : raw;
   return (
     `Error: the arguments for "${toolName}" were not valid JSON — the argument stream was malformed or truncated, so the tool was NOT executed. ` +
     `Received: ${preview || "(empty)"}\n` +

package/src/runtime/AGENTS.md

@@ -12,6 +12,8 @@ The single HTTP send endpoint is `POST /v1/messages`. Key behaviors:
 
 Do NOT add new send endpoints. All message ingress should go through `POST /v1/messages` (HTTP).
 
+`POST /v1/channels/send` is not ingress: it is outbound delivery, the assistant posting text to a channel chat. It runs `sendChannelText` (`runtime/channel-send.ts`), the one send implementation for every channel whose transport declares proactive addressing (`ChannelTransport.addressFor`), and the messaging tool's channel branch runs the same function in-process, as the CLI's channel send door does over the route. A model-directed channel send goes through that function or it is not recorded; do not add a provider-side send for a channel that has a transport. The route names no sending turn: only the in-process tool call can claim a send landed in the turn's own chat, so everything sent through the route is recorded.
+
 **`interrupt-on-send`: a send may stop the running turn instead of queueing behind it.** With the flag on, a busy conversation is handed to `interruptRunningTurn` (`daemon/conversation-interrupt.ts`), which aborts the turn with `preempted_by_new_message`, waits for it to release the processing lock AND for its turn-boundary commit to finish, repairs the abandoned `tool_use` blocks with a persisted synthetic `tool_result`, and answers `released`. The route then falls through to the code an idle conversation already uses, so there is one turn dispatch rather than a second one for interrupts. The queue is not discarded: it may hold another actor's messages.
 
 **The handover runs off the response, not on it.** Fire-and-forget is not suspended for an interrupt. The eligibility decision is synchronous (`classifyInterruptEligibility`), so the route answers `202 { accepted, requestId }` the moment it accepts the message, then runs the abort, the release wait, the commit wait, the repair, the persist and the dispatch in a detached task. Holding the request would cost the abort budget (`ABORT_RELEASE_WAIT_MS`) plus the turn-boundary commit wait, long enough for a client to time out and retry a message the daemon is still placing. That 202 carries `messageId` as well as `requestId`, and they are the same value: a user turn persists its row under its `requestId` (`persistUserMessage` passes `id: requestId`), which is what lets the id be answered before the row exists. Both are required, not decorative: `postChatMessage` rejects an accepted, non-queued response without a string `messageId` and the client drops the optimistic row. Clients reconcile that row on `user_message_echo`. Two rules for anything added to that task: it must not be able to drop the message (every failure path falls back to `queueSend`, which never takes the enqueue's idle fast path, and a queue that refuses the fallback is reported to the sender as a `QUEUE_FULL` error keyed on the `requestId` the 202 carried, since the 429 itself reaches nobody), and a duplicate `clientMessageId` is answered from the existing row BEFORE the abort, since the insert's own dedup settles too late to un-abort a turn.
@@ -95,7 +97,7 @@ Host CU allows the assistant to proxy computer-use actions (screenshots, mouse/k
 
 - **Discovery**: Clients discover pending host CU requests via SSE events (`host_cu_request`) which include a `requestId`.
 - **Resolution**: Clients execute the CU action on the host and respond via:
-  - `POST /v1/host-cu-result` — `{ requestId, axTree?, axDiff?, screenshot?, screenshotWidthPx?, screenshotHeightPx?, screenWidthPt?, screenHeightPt?, executionResult?, executionError?, secondaryWindows?, userGuidance? }`
+  - `POST /v1/host-cu-result`: `{ requestId, axTree?, axDiff?, screenshot?, screenshotWidthPx?, screenshotHeightPx?, screenWidthPt?, screenHeightPt?, executionResult?, executionError?, secondaryWindows?, userGuidance?, timings? }`, where `timings` is optional per-phase helper timings in milliseconds
 - **Tracking**: Uses the same `pending-interactions` tracker as the other host proxy types, with `kind: "host_cu"`. Registration happens in `conversation-routes.ts` and the route handler is in `host-cu-routes.ts`.
 - **Conversation-agnostic observation**: `observeHostScreen()` in `host-observe.ts` issues a `computer_use_observe` request with no conversation, for callers outside an agent turn (`HostCuProxy` only exists inside one). It takes the initiating actor's principal id and reaches only that actor's own `host_cu` clients: `pickSameUserAutoResolve` picks the default target and `enforceSameActorOrErrorResult` gates an explicitly named one, both before the request is registered or broadcast. Its pending interaction carries no `conversationId`, so `host-cu-routes.ts` hands the raw observation fields straight to the waiting caller instead of routing through a conversation's CU proxy. On the desktop side the ordinary `host_cu` executor services the request.
 

package/src/runtime/__tests__/channel-send.test.ts

@@ -0,0 +1,443 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type {
+  ChannelTransport,
+  ProactiveTarget,
+} from "../../messaging/providers/channel-transport.js";
+
+// The seam under test is the send function: it must ask the transport for
+// the address, deliver through it, and record only what the channel
+// acknowledged. The transport is a fake registered by channel id; the
+// recording dependencies are stubbed so the tests read what was recorded.
+
+const deliverCalls: Array<{
+  ctx: { callbackUrl: string; params: Record<string, string> };
+  payload: Record<string, unknown>;
+}> = [];
+let deliverResult: Record<string, unknown> = {
+  ok: true,
+  ts: "1700000000.000100",
+  messageIds: ["1700000000.000100"],
+};
+
+function fakeTransport(
+  channel: "slack" | "telegram",
+  opts: { binds?: boolean; addressable?: boolean; refuses?: boolean } = {},
+): ChannelTransport {
+  const transport: ChannelTransport = {
+    channel,
+    async deliver(ctx, payload) {
+      deliverCalls.push({
+        ctx: { callbackUrl: ctx.callbackUrl, params: { ...ctx.params } },
+        payload: payload as unknown as Record<string, unknown>,
+      });
+      return deliverResult as unknown as Awaited<
+        ReturnType<ChannelTransport["deliver"]>
+      >;
+    },
+  };
+  if (opts.addressable !== false) {
+    transport.addressFor = (target: ProactiveTarget) => {
+      if (opts.refuses) {
+        return undefined;
+      }
+      const threadId = target.threadId?.trim();
+      const params: Record<string, string> = threadId ? { threadId } : {};
+      return {
+        ctx: { callbackUrl: `/deliver/${channel}`, params },
+        chatId: target.chatId,
+        ...(threadId ? { threadId } : {}),
+      };
+    };
+  }
+  if (opts.binds) {
+    (
+      transport as { bindsChatOnProactiveSend?: boolean }
+    ).bindsChatOnProactiveSend = true;
+  }
+  return transport;
+}
+
+let transports: Record<string, ChannelTransport> = {};
+mock.module("../../messaging/providers/index.js", () => ({
+  getTransportForChannel: (channel: string | undefined) =>
+    channel ? transports[channel] : undefined,
+}));
+
+const resolveHomeMock = mock(async (_params: Record<string, unknown>) => ({
+  conversationId: "home-1",
+  createdNewConversation: false,
+}));
+const recordMock = mock(async (_post: Record<string, unknown>) => ({
+  messageId: "row-1",
+}));
+const bindCalls: Array<Record<string, unknown>> = [];
+const getOrCreateCalls: string[] = [];
+
+mock.module("../../notifications/conversation-pairing.js", () => ({
+  resolveProactiveHomeConversation: resolveHomeMock,
+}));
+mock.module("../../notifications/delivered-post-record.js", () => ({
+  recordDeliveredChannelPost: recordMock,
+}));
+mock.module("../../persistence/conversation-crud.js", () => ({
+  getConversation: (id: string) => ({ id, createdAt: 1700000000000 }),
+}));
+mock.module("../../persistence/conversation-disk-view.js", () => ({
+  syncMessageToDisk: () => {},
+}));
+let bindCreates = true;
+let bindThrows = false;
+mock.module("../../persistence/conversation-key-store.js", () => ({
+  getOrCreateConversation: (key: string) => {
+    getOrCreateCalls.push(key);
+    return { conversationId: `conv-for-${key}`, created: bindCreates };
+  },
+}));
+const listChangedMock = mock((_reason: string) => {});
+const actualSync = await import("../sync/resource-sync-events.js");
+mock.module("../sync/resource-sync-events.js", () => ({
+  ...actualSync,
+  publishConversationListChanged: listChangedMock,
+}));
+mock.module("../../persistence/delivery-crud.js", () => ({
+  buildScopedConversationKey: (
+    channel: string,
+    chatId: string,
+    threadId?: string | null,
+  ) =>
+    threadId
+      ? `asst:self:${channel}:${chatId}:thread:${threadId}`
+      : `asst:self:${channel}:${chatId}`,
+}));
+mock.module("../../persistence/external-conversation-store.js", () => ({
+  normalizeExternalThreadId: (value: string | null | undefined) => {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : null;
+  },
+  upsertOutboundBinding: (input: Record<string, unknown>) => {
+    if (bindThrows) {
+      throw new Error("binding store unavailable");
+    }
+    bindCalls.push(input);
+  },
+}));
+
+const {
+  ChannelNotAddressableError,
+  ChannelSendFailedError,
+  isProactivelyAddressable,
+  sendChannelText,
+} = await import("../channel-send.js");
+
+beforeEach(() => {
+  deliverCalls.length = 0;
+  bindCalls.length = 0;
+  getOrCreateCalls.length = 0;
+  bindCreates = true;
+  bindThrows = false;
+  listChangedMock.mockClear();
+  resolveHomeMock.mockClear();
+  recordMock.mockClear();
+  deliverResult = {
+    ok: true,
+    ts: "1700000000.000100",
+    messageIds: ["1700000000.000100"],
+  };
+  transports = {
+    slack: fakeTransport("slack"),
+    telegram: fakeTransport("telegram", { binds: true }),
+  };
+});
+
+const sender = {
+  conversationId: "conv-A",
+  executionChannel: "slack",
+  requesterChatId: "C123",
+  sourceThreadId: "1690000000.000001",
+};
+
+describe("addressability", () => {
+  test("a channel is addressable exactly when its transport declares it", () => {
+    transports.a2a = fakeTransport("slack", { addressable: false });
+    expect(isProactivelyAddressable("slack")).toBe(true);
+    expect(isProactivelyAddressable("a2a")).toBe(false);
+    expect(isProactivelyAddressable("email")).toBe(false);
+    expect(isProactivelyAddressable("not-a-channel")).toBe(false);
+  });
+
+  test("refuses before delivery when the channel has no addressing, or refuses the chat", async () => {
+    await expect(
+      sendChannelText({
+        channel: "email",
+        target: { kind: "chat", chatId: "x" },
+        text: "hi",
+      }),
+    ).rejects.toBeInstanceOf(ChannelNotAddressableError);
+
+    transports.slack = fakeTransport("slack", { refuses: true });
+    await expect(
+      sendChannelText({
+        channel: "slack",
+        target: { kind: "chat", chatId: "C-unreachable" },
+        text: "hi",
+      }),
+    ).rejects.toBeInstanceOf(ChannelNotAddressableError);
+    expect(deliverCalls).toEqual([]);
+  });
+});
+
+describe("delivery through the transport", () => {
+  test("delivers to the address the transport resolves, with the rich render asked for", async () => {
+    const result = await sendChannelText({
+      channel: "slack",
+      target: { kind: "chat", chatId: "C123", threadId: "1690000000.000001" },
+      text: "hello",
+      renderRichly: true,
+      assistantId: "self",
+    });
+
+    expect(deliverCalls).toEqual([
+      {
+        ctx: {
+          callbackUrl: "/deliver/slack",
+          params: { threadId: "1690000000.000001" },
+        },
+        payload: {
+          chatId: "C123",
+          text: "hello",
+          renderRichly: true,
+          assistantId: "self",
+        },
+      },
+    ]);
+    expect(result).toMatchObject({
+      channel: "slack",
+      chatId: "C123",
+      threadId: "1690000000.000001",
+      messageIds: ["1700000000.000100"],
+      lastMessageId: "1700000000.000100",
+    });
+  });
+
+  test("a send the channel does not acknowledge fails and records nothing", async () => {
+    deliverResult = { ok: false };
+    await expect(
+      sendChannelText({
+        channel: "slack",
+        target: { kind: "chat", chatId: "C123" },
+        text: "hello",
+      }),
+    ).rejects.toBeInstanceOf(ChannelSendFailedError);
+    expect(recordMock).not.toHaveBeenCalled();
+  });
+
+  test("binds the chat's inbound conversation after acknowledgement, only where the transport declares it", async () => {
+    await sendChannelText({
+      channel: "telegram",
+      target: { kind: "chat", chatId: "123456789" },
+      text: "hello",
+    });
+    expect(getOrCreateCalls).toEqual(["asst:self:telegram:123456789"]);
+    expect(bindCalls).toEqual([
+      {
+        conversationId: "conv-for-asst:self:telegram:123456789",
+        sourceChannel: "telegram",
+        externalChatId: "123456789",
+        externalThreadId: null,
+      },
+    ]);
+
+    bindCalls.length = 0;
+    await sendChannelText({
+      channel: "slack",
+      target: { kind: "chat", chatId: "C123" },
+      text: "hello",
+    });
+    expect(bindCalls).toEqual([]);
+  });
+
+  test("a topic send binds the topic's own conversation, the one its replies resolve to", async () => {
+    await sendChannelText({
+      channel: "telegram",
+      target: { kind: "chat", chatId: "123456789", threadId: "42" },
+      text: "hello",
+    });
+    expect(getOrCreateCalls).toEqual([
+      "asst:self:telegram:123456789:thread:42",
+    ]);
+    expect(bindCalls).toEqual([
+      {
+        conversationId: "conv-for-asst:self:telegram:123456789:thread:42",
+        sourceChannel: "telegram",
+        externalChatId: "123456789",
+        externalThreadId: "42",
+      },
+    ]);
+  });
+
+  test("a conversation the binding mints reaches the list; one it finds does not", async () => {
+    await sendChannelText({
+      channel: "telegram",
+      target: { kind: "chat", chatId: "123456789", threadId: "42" },
+      text: "hello",
+    });
+    expect(listChangedMock).toHaveBeenCalledTimes(1);
+    expect(listChangedMock).toHaveBeenCalledWith("created");
+
+    listChangedMock.mockClear();
+    bindCreates = false;
+    await sendChannelText({
+      channel: "telegram",
+      target: { kind: "chat", chatId: "123456789", threadId: "42" },
+      text: "again",
+    });
+    expect(listChangedMock).not.toHaveBeenCalled();
+  });
+
+  test("a binding that throws still leaves its minted conversation in the list", async () => {
+    bindThrows = true;
+    const result = await sendChannelText({
+      channel: "telegram",
+      target: { kind: "chat", chatId: "123456789", threadId: "42" },
+      text: "hello",
+    });
+    expect(bindCalls).toEqual([]);
+    expect(listChangedMock).toHaveBeenCalledWith("created");
+    expect(result.messageIds).toEqual(["1700000000.000100"]);
+  });
+
+  test("a failed send binds nothing, so it does not move where the next inbound lands", async () => {
+    deliverResult = { ok: false };
+    await expect(
+      sendChannelText({
+        channel: "telegram",
+        target: { kind: "chat", chatId: "123456789" },
+        text: "hello",
+      }),
+    ).rejects.toBeInstanceOf(ChannelSendFailedError);
+    expect(getOrCreateCalls).toEqual([]);
+    expect(bindCalls).toEqual([]);
+  });
+
+  test("does not bind a chat when acting for another assistant", async () => {
+    await sendChannelText({
+      channel: "telegram",
+      target: { kind: "chat", chatId: "123456789" },
+      text: "hello",
+      assistantId: "asst-other",
+    });
+    expect(bindCalls).toEqual([]);
+  });
+});
+
+describe("recording after acknowledgement", () => {
+  test("records every acknowledged id in the chat's home, cross-posted from the sender", async () => {
+    deliverResult = { ok: true, messageIds: ["10", "11", "12"] };
+    const result = await sendChannelText({
+      channel: "telegram",
+      target: { kind: "chat", chatId: "123456789" },
+      text: "a long message",
+      sender: { conversationId: "conv-A" },
+    });
+
+    expect(resolveHomeMock.mock.calls[0]![0]).toMatchObject({
+      sourceChannel: "telegram",
+      externalChatId: "123456789",
+    });
+    expect(recordMock).toHaveBeenCalledTimes(1);
+    expect(recordMock.mock.calls[0]![0]).toEqual({
+      conversationId: "home-1",
+      channel: "telegram",
+      externalChatId: "123456789",
+      text: "a long message",
+      providerMessageId: "10",
+      additionalProviderMessageIds: ["11", "12"],
+      crossPostedFrom: "conv-A",
+    });
+    expect(result).toMatchObject({
+      messageIds: ["10", "11", "12"],
+      lastMessageId: "12",
+      recordedIn: "home-1",
+    });
+  });
+
+  test("a success that names no message id is not an acknowledgement", async () => {
+    deliverResult = { ok: true, messageIds: [] };
+    await expect(
+      sendChannelText({
+        channel: "slack",
+        target: { kind: "chat", chatId: "C123" },
+        text: "hello",
+      }),
+    ).rejects.toThrow("acknowledged no message id");
+    expect(recordMock).not.toHaveBeenCalled();
+  });
+
+  test("records nothing when the post landed in the turn's own chat and thread", async () => {
+    await sendChannelText({
+      channel: "slack",
+      target: { kind: "chat", chatId: "C123", threadId: "1690000000.000001" },
+      text: "hello",
+      sender,
+    });
+    expect(resolveHomeMock).not.toHaveBeenCalled();
+    expect(recordMock).not.toHaveBeenCalled();
+  });
+
+  test("a send into the turn's chat but a different thread is a cross-post, recorded in that thread", async () => {
+    await sendChannelText({
+      channel: "slack",
+      target: { kind: "chat", chatId: "C123", threadId: "1690000000.000009" },
+      text: "hello",
+      sender,
+    });
+    expect(resolveHomeMock.mock.calls[0]![0]).toMatchObject({
+      sourceChannel: "slack",
+      externalChatId: "C123",
+      threadId: "1690000000.000009",
+    });
+    expect(recordMock).toHaveBeenCalledTimes(1);
+    expect(recordMock.mock.calls[0]![0]).toMatchObject({
+      externalChatId: "C123",
+      threadId: "1690000000.000009",
+    });
+  });
+
+  test("a thread-less delivery never matches a turn that arrived in a thread", async () => {
+    await sendChannelText({
+      channel: "slack",
+      target: { kind: "chat", chatId: "C123" },
+      text: "hello",
+      sender,
+    });
+    expect(recordMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("a sender that arrived through no channel falls back to the home comparison", async () => {
+    resolveHomeMock.mockImplementationOnce(async () => ({
+      conversationId: "conv-A",
+      createdNewConversation: false,
+    }));
+    await sendChannelText({
+      channel: "slack",
+      target: { kind: "chat", chatId: "C123" },
+      text: "hello",
+      sender: { conversationId: "conv-A" },
+    });
+    expect(recordMock).not.toHaveBeenCalled();
+  });
+
+  test("a recording failure does not fail the send", async () => {
+    recordMock.mockImplementationOnce(async () => {
+      throw new Error("db unavailable");
+    });
+    const result = await sendChannelText({
+      channel: "slack",
+      target: { kind: "chat", chatId: "C123" },
+      text: "hello",
+    });
+    expect(result.messageIds).toEqual(["1700000000.000100"]);
+    expect(result.recordedIn).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { setOverridesForTesting } from "../../__tests__/feature-flag-test-helpers.js";
+import { RuntimeHttpServer } from "../http-server.js";
+import {
+  mintActorToken,
+  mintGatewayToken,
+  requireHttpAuth,
+  upgradeHeaders,
+  waitForClose,
+} from "./runtime-ws-test-utils.js";
+
+describe("RuntimeHttpServer /v1/desktop/stream upgrade", () => {
+  let server: RuntimeHttpServer;
+  let baseUrl: string;
+  let restoreAuthEnv: () => void;
+  const originalContainerized = process.env.IS_CONTAINERIZED;
+
+  beforeEach(async () => {
+    restoreAuthEnv = requireHttpAuth();
+    const port = 21400 + Math.floor(Math.random() * 300);
+    server = new RuntimeHttpServer({ port, hostname: "127.0.0.1" });
+    await server.start();
+    baseUrl = `127.0.0.1:${server.actualPort}`;
+  });
+
+  afterEach(async () => {
+    await server.stop();
+    restoreAuthEnv();
+    if (originalContainerized === undefined) {
+      delete process.env.IS_CONTAINERIZED;
+    } else {
+      process.env.IS_CONTAINERIZED = originalContainerized;
+    }
+    setOverridesForTesting({});
+  });
+
+  test("refuses a non-private origin with 403", async () => {
+    const res = await fetch(
+      `http://${baseUrl}/v1/desktop/stream?token=${mintGatewayToken()}`,
+      {
+        headers: { ...upgradeHeaders, Origin: "https://external.example.com" },
+      },
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { message: string } };
+    expect(body.error.message).toContain(
+      "Direct desktop stream access disabled",
+    );
+  });
+
+  test("refuses a missing or non-gateway token with 401", async () => {
+    const missing = await fetch(`http://${baseUrl}/v1/desktop/stream`, {
+      headers: upgradeHeaders,
+    });
+    expect(missing.status).toBe(401);
+
+    const actor = await fetch(
+      `http://${baseUrl}/v1/desktop/stream?token=${mintActorToken()}`,
+      { headers: upgradeHeaders },
+    );
+    expect(actor.status).toBe(401);
+  });
+
+  test("upgrades a gateway request and reports the feature gate as close code 4008", async () => {
+    // The test daemon is not containerized, so the socket opens and is then
+    // closed by the desktop-stream open handler rather than refused pre-upgrade.
+    const ws = new WebSocket(
+      `ws://${baseUrl}/v1/desktop/stream?token=${encodeURIComponent(mintGatewayToken())}`,
+    );
+    const closed = await waitForClose(ws);
+    expect(closed.code).toBe(4008);
+    expect(closed.reason).toBe("Desktop is not available on this assistant");
+  });
+  for (const flag of [false, undefined]) {
+    test(`refuses a containerized stream with a disabled or missing flag (${flag})`, async () => {
+      process.env.IS_CONTAINERIZED = "true";
+      setOverridesForTesting(
+        flag === undefined ? {} : { "assistant-desktop": flag },
+      );
+      const ws = new WebSocket(
+        `ws://${baseUrl}/v1/desktop/stream?token=${encodeURIComponent(mintGatewayToken())}`,
+      );
+      const closed = await waitForClose(ws);
+      expect(closed.code).toBe(4008);
+      expect(closed.reason).toBe("Desktop is not available on this assistant");
+    });
+  }
+});