@vellumai/assistant 0.12.2-dev.202609182314.c515b72 → 0.12.2-dev.202609190043.ee5ba34

package/docs/desktop-browser-cli.md

@@ -24,7 +24,7 @@ The desktop client bypasses personal-browser discovery, extension reconnect wait
 
 Tab IDs are ephemeral numeric aliases for this managed browser's CDP target IDs. They are never personal extension tab IDs. Initial attachment selects an existing HTTP(S) page or opens a blank tab. Use `tabs list` and `tabs select --tab-id <id>` to choose explicitly. Navigation, tab selection, document replacement and release clear the desktop snapshot map. Personal-browser snapshots use a separate namespace.
 
-CDP mouse events use page viewport CSS coordinates. Before dispatching them, the client animates a purple arrow overlay to the same point. The overlay is excluded from accessibility and hit testing. It appears in the existing desktop stream and is removed on release. It does not move the OS pointer, appear in browser toolbar UI or visualize every programmatic DOM operation. Native dialogs and other applications are outside the browser CLI; users can interact with them directly in the expanded desktop. The picture-in-picture preview is view-only. Direct user interaction does not pause automation. For logins, the assistant uses saved credentials first and securely collects missing credentials with `assistant credentials prompt`, then fills the login form itself. Every CAPTCHA and bot-detection challenge, including sliders and press-and-hold checks, is handed to the user before the assistant attempts it. When human interaction is needed, the assistant calls `ask_question` with `desktopHelp: { message, doneLabel, skipLabel }` in the user's language. The tool releases held browser input and reserves the desktop before publishing a question with `presentation: "virtual_desktop"`. The live viewer mounts only in the attended Electron window, with browser focus as a fallback on older shells and the web, so conversations release it when focus changes. A busy viewer offers Reconnect if the previous connection has not finished closing. The compact card lives in the scrolling message transcript, with expandable instructions and a preview capped at 384 pixels wide. It hosts the shared live viewer, with Step In opening its full desktop modal and Done or Skip resolving the existing question response. The assistant retains an exclusive human-help reservation while waiting. Done resumes the same conversation's automation lease for its fresh snapshot; Skip, closure, timeout and cancellation release it. The browser idle timer does not expire a pending human-help reservation. The live preview connects after Show live preview or Step In, and reuses an already-open picture-in-picture viewer. Other devices receiving the card do not automatically open a stream. When the request resolves, its interactive viewer closes or returns to the read-only PiP session that was open before the request. Skip does not imply the obstacle was resolved. Older clients show the same request as a normal Done/Skip question, with model-localized labels retained in history. Channels without dynamic UI return guidance to continue in the app rather than waiting on an unusable card.
+CDP mouse events use page viewport CSS coordinates. Before dispatching them, the client animates a purple arrow overlay to the same point. The overlay is excluded from accessibility and hit testing. It appears in the existing desktop stream and is removed on release. It does not move the OS pointer, appear in browser toolbar UI or visualize every programmatic DOM operation. Native dialogs and other applications use the computer-use skill or direct interaction in the expanded desktop. The picture-in-picture preview is view-only. Direct user interaction does not pause automation. For logins, the assistant uses saved credentials first and securely collects missing credentials with `assistant credentials prompt`, then fills the login form itself. Every CAPTCHA and bot-detection challenge, including sliders and press-and-hold checks, is handed to the user before the assistant attempts it. When human interaction is needed, the assistant calls `ask_question` with `desktopHelp: { message, doneLabel, skipLabel }` in the user's language. The tool releases held browser input and reserves the desktop before publishing a question with `presentation: "virtual_desktop"`. The live viewer mounts only in the attended Electron window, with browser focus as a fallback on older shells and the web, so conversations release it when focus changes. A busy viewer offers Reconnect if the previous connection has not finished closing. The compact card lives in the scrolling message transcript, with expandable instructions and a preview capped at 384 pixels wide. It hosts the shared live viewer, with Step In opening its full desktop modal and Done or Skip resolving the existing question response. The assistant retains an exclusive human-help reservation while waiting. Done resumes the same conversation's automation lease for its fresh snapshot; Skip, closure, timeout and cancellation release it. The browser idle timer does not expire a pending human-help reservation. The live preview connects after Show live preview or Step In, and reuses an already-open picture-in-picture viewer. Other devices receiving the card do not automatically open a stream. When the request resolves, its interactive viewer closes or returns to the read-only PiP session that was open before the request. Skip does not imply the obstacle was resolved. Older clients show the same request as a normal Done/Skip question, with model-localized labels retained in history. Channels without dynamic UI return guidance to continue in the app rather than waiting on an unusable card.
 
 The client records key and mouse presses before dispatch. On release it opens a fresh bounded cleanup connection, attaches to the same live targets, releases uncertain held input and removes overlays. A failed cleanup preserves state and the automation slot for retry. Turn-triggered cancellation retries cleanup automatically until it succeeds or ownership changes. Dispatched actions are never automatically retried. Closed targets need no input cleanup. Browser-process loss disposes the client, and later requests discover the replacement process.
 
@@ -35,3 +35,22 @@ Validation: focused client tests exercise shared snapshot/click behavior, namesp
 The desktop header icon pulses in the assistant's avatar accent color while a browser automation lease is active, including between browser commands. It shares the progress indicator's accent and neutral fallback. Reduced-motion clients show a solid accent. Setup status exposes the optional `automationActive` field; `desktop_activity_changed` events refresh it on acquisition and cancellation or release. Installation progress retains its `assistant:self:desktop` sync invalidations. The indicator reads status without starting installation, and reconnects refetch the current lease state.
 
 Desktop streaming checks the current in-memory gateway feature flags during connection startup. Once connected, frame and drain callbacks do not check feature flags or load workspace configuration. Turning the flag off prevents new connections; an existing stream continues until it closes or the desktop stops.
+
+## Computer use on the same desktop
+
+The existing `computer-use` skill defaults to this desktop in platform-hosted
+web conversations. Native desktop clients, including the Mac app connected to a
+platform-hosted assistant, keep the connected-computer default and require
+`target: "assistant-desktop"` to select the virtual desktop explicitly.
+Non-platform assistants keep their connected-computer behavior.
+
+Explicit `target: "connected-computer"` or `target_client_id` selects a connected
+computer on every client. The selected target never falls back to another
+computer when unavailable. Virtual desktop observations return full-screen
+screenshots and mouse actions use screen coordinates.
+
+Observe first and pass the returned `observation_id` with each native action.
+Browser commands, user handoff, errors, and interruption require a fresh
+observation before returning to native input. Browser commands and computer use
+share session ownership, cancellation, and the user-help reservation. Use
+browser commands for page-level operations and computer use for desktop UI.

package/node_modules/@vellumai/gateway-client/src/gateway-ipc-contracts.ts

@@ -43,6 +43,26 @@ export type GatewayLogsTailRouteParams = z.infer<
   typeof GatewayLogsTailRouteParamsSchema
 >;
 
+/**
+ * `gateway_debug_export`: a consistent copy of the gateway database plus its
+ * recent log files, as one gzipped tar, for a debug bundle. No params.
+ */
+export const GatewayDebugExportIpcParamsSchema = z
+  .object({})
+  .strict()
+  .default({});
+
+export const GatewayDebugExportIpcResponseSchema = z.object({
+  ok: z.literal(true),
+  /** `tar.gz` bytes, base64. Contains gateway.sqlite and gateway-logs/. */
+  archive_base64: z.string(),
+  size_bytes: z.number().int().nonnegative(),
+});
+
+export type GatewayDebugExportIpcResponse = z.infer<
+  typeof GatewayDebugExportIpcResponseSchema
+>;
+
 export const GatewayLogsTailIpcResponseSchema = z.object({
   lines: z.array(z.record(z.string(), z.unknown())),
   truncated: z.boolean(),

package/openapi.yaml

@@ -23549,6 +23549,14 @@ paths:
                 description:
                   description: Human-readable export description.
                   type: string
+                profile:
+                  description:
+                    "Export profile. 'migration' (default) builds a teleport bundle. 'debug' builds a bundle for Vellum staff
+                    to open on a debug clone: no credentials, plus the gateway's database and logs under gateway/."
+                  type: string
+                  enum:
+                    - migration
+                    - debug
               required:
                 - upload_url
       responses:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609182314.c515b72",
+  "version": "0.12.2-dev.202609190043.ee5ba34",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/checker.test.ts

@@ -140,9 +140,17 @@ registerSkillTools("app-builder", [mockBundledSkillTool]);
 
 // Register CU tools so check() can look them up in the tool registry
 // instead of falling through to Medium (unknown tool).
-import { allComputerUseTools } from "../tools/computer-use/definitions.js";
-for (const tool of allComputerUseTools) {
-  registerTool(tool);
+import { COMPUTER_USE_TOOL_NAMES } from "./test-support/computer-use-skill-harness.js";
+for (const name of COMPUTER_USE_TOOL_NAMES) {
+  registerTool({
+    name,
+    description: name,
+    category: "computer-use",
+    defaultRiskLevel: RiskLevel.Low,
+    executionTarget: "host",
+    input_schema: { type: "object", properties: {} },
+    execute: async () => ({ content: "ok", isError: false }),
+  });
 }
 
 function writeSkill(

package/src/__tests__/computer-use-skill-manifest-regression.test.ts

@@ -3,7 +3,6 @@ import { resolve } from "node:path";
 import { afterAll, describe, expect, test } from "bun:test";
 
 import { RiskLevel } from "../permissions/types.js";
-import { allComputerUseTools } from "../tools/computer-use/definitions.js";
 import {
   __resetRegistryForTesting,
   getTool,
@@ -74,30 +73,6 @@ describe("computer-use skill manifest regression", () => {
     }
   });
 
-  test("manifest descriptions match core definitions", async () => {
-    await initializeTools();
-
-    for (const cuTool of allComputerUseTools) {
-      const manifestTool = manifest.tools.find(
-        (t: { name: string }) => t.name === cuTool.name,
-      );
-      expect(manifestTool).toBeDefined();
-      expect(manifestTool.description).toBe(cuTool.description);
-    }
-  });
-
-  test("manifest input_schema matches core definitions", async () => {
-    await initializeTools();
-
-    for (const cuTool of allComputerUseTools) {
-      const manifestTool = manifest.tools.find(
-        (t: { name: string }) => t.name === cuTool.name,
-      );
-      expect(manifestTool).toBeDefined();
-      expect(manifestTool.input_schema).toEqual(cuTool.input_schema);
-    }
-  });
-
   test("CU action tools are not registered as core tools after initializeTools()", async () => {
     await initializeTools();
 

package/src/__tests__/computer-use-tools.test.ts

@@ -1,246 +1,14 @@
 import { describe, expect, test } from "bun:test";
 
-import {
-  allComputerUseTools,
-  computerUseClickTool,
-  computerUseDoneTool,
-  computerUseDragTool,
-  computerUseKeyTool,
-  computerUseObserveTool,
-  computerUseOpenAppTool,
-  computerUseRespondTool,
-  computerUseRunAppleScriptTool,
-  computerUseScrollTool,
-  computerUseTypeTextTool,
-  computerUseWaitTool,
-} from "../tools/computer-use/definitions.js";
 import { forwardComputerUseProxyTool } from "../tools/computer-use/skill-proxy-bridge.js";
 import type { ToolContext } from "../tools/types.js";
 
-interface JsonSchema {
-  type?: string;
-  required?: string[];
-  properties?: Record<string, unknown>;
-}
-
-/** Cast a tool definition's input_schema to a usable JSON Schema shape. */
-function schema(tool: { input_schema?: object }): JsonSchema {
-  return tool.input_schema as JsonSchema;
-}
-
 const ctx: ToolContext = {
   workingDir: "/tmp",
-  conversationId: "test-conversation",
+  conversationId: "conv-123",
   trustClass: "guardian",
 };
 
-// ── Tool definitions ────────────────────────────────────────────────
-
-describe("computer-use tool definitions", () => {
-  test("allComputerUseTools contains 12 tools", () => {
-    expect(allComputerUseTools.length).toBe(12);
-  });
-
-  test("all tools belong to computer-use category", () => {
-    for (const tool of allComputerUseTools) {
-      expect(tool.category).toBe("computer-use");
-    }
-  });
-
-  test("all tools have unique names", () => {
-    const names = allComputerUseTools.map((t) => t.name);
-    expect(new Set(names).size).toBe(names.length);
-  });
-
-  test("all tools have descriptions", () => {
-    for (const tool of allComputerUseTools) {
-      expect(tool.description!.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-// ── observe ─────────────────────────────────────────────────────────
-
-describe("computer_use_observe", () => {
-  test("supports target_client_id", () => {
-    const props = schema(computerUseObserveTool).properties as Record<
-      string,
-      { type: string }
-    >;
-    expect(props.target_client_id.type).toBe("string");
-  });
-});
-
-// ── Unified click tool ──────────────────────────────────────────────
-
-describe("computer_use_click (unified)", () => {
-  test("has correct name", () => {
-    expect(computerUseClickTool.name).toBe("computer_use_click");
-  });
-
-  test("schema requires reasoning", () => {
-    expect(schema(computerUseClickTool).required).toContain("reasoning");
-  });
-
-  test("schema supports click_type enum", () => {
-    const props = schema(computerUseClickTool).properties as Record<
-      string,
-      { type: string; enum?: string[] }
-    >;
-    expect(props.click_type.type).toBe("string");
-    expect(props.click_type.enum).toEqual(["single", "double", "right"]);
-  });
-
-  test("schema supports element_id and coordinates", () => {
-    const props = schema(computerUseClickTool).properties as Record<
-      string,
-      { type: string }
-    >;
-    expect(props.element_id.type).toBe("integer");
-    expect(props.x.type).toBe("integer");
-    expect(props.y.type).toBe("integer");
-  });
-
-  test("execute returns isError when no proxy resolver is configured", async () => {
-    const result = await computerUseClickTool.execute({}, ctx);
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain(
-      "The Vellum desktop app is needed to view or control your screen",
-    );
-    expect(result.content).toContain("https://www.vellum.ai/downloads");
-  });
-});
-
-// ── type_text ───────────────────────────────────────────────────────
-
-describe("computer_use_type_text", () => {
-  test("requires text and reasoning", () => {
-    expect(schema(computerUseTypeTextTool).required).toContain("text");
-    expect(schema(computerUseTypeTextTool).required).toContain("reasoning");
-  });
-
-  test("execute returns isError when no proxy resolver is configured", async () => {
-    const result = await computerUseTypeTextTool.execute({}, ctx);
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain(
-      "The Vellum desktop app is needed to view or control your screen",
-    );
-    expect(result.content).toContain("https://www.vellum.ai/downloads");
-  });
-});
-
-// ── key ─────────────────────────────────────────────────────────────
-
-describe("computer_use_key", () => {
-  test("requires key and reasoning", () => {
-    expect(schema(computerUseKeyTool).required).toContain("key");
-    expect(schema(computerUseKeyTool).required).toContain("reasoning");
-  });
-
-  test("execute returns isError when no proxy resolver is configured", async () => {
-    const result = await computerUseKeyTool.execute({}, ctx);
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain(
-      "The Vellum desktop app is needed to view or control your screen",
-    );
-    expect(result.content).toContain("https://www.vellum.ai/downloads");
-  });
-});
-
-// ── scroll ──────────────────────────────────────────────────────────
-
-describe("computer_use_scroll", () => {
-  test("requires direction, amount, and reasoning", () => {
-    expect(schema(computerUseScrollTool).required).toContain("direction");
-    expect(schema(computerUseScrollTool).required).toContain("amount");
-    expect(schema(computerUseScrollTool).required).toContain("reasoning");
-  });
-
-  test("direction enum includes up, down, left, right", () => {
-    const props = schema(computerUseScrollTool).properties as Record<
-      string,
-      { enum?: string[] }
-    >;
-    expect(props.direction.enum).toEqual(["up", "down", "left", "right"]);
-  });
-});
-
-// ── drag ────────────────────────────────────────────────────────────
-
-describe("computer_use_drag", () => {
-  test("supports source and destination coordinates", () => {
-    const props = schema(computerUseDragTool).properties as Record<
-      string,
-      { type: string }
-    >;
-    expect(props.element_id.type).toBe("integer");
-    expect(props.to_element_id.type).toBe("integer");
-    expect(props.x.type).toBe("integer");
-    expect(props.y.type).toBe("integer");
-    expect(props.to_x.type).toBe("integer");
-    expect(props.to_y.type).toBe("integer");
-  });
-
-  test("requires reasoning only", () => {
-    expect(schema(computerUseDragTool).required).toEqual(["reasoning"]);
-  });
-});
-
-// ── wait ────────────────────────────────────────────────────────────
-
-describe("computer_use_wait", () => {
-  test("requires duration_ms and reasoning", () => {
-    expect(schema(computerUseWaitTool).required).toContain("duration_ms");
-    expect(schema(computerUseWaitTool).required).toContain("reasoning");
-  });
-});
-
-// ── open_app ────────────────────────────────────────────────────────
-
-describe("computer_use_open_app", () => {
-  test("requires app_name and reasoning", () => {
-    expect(schema(computerUseOpenAppTool).required).toContain("app_name");
-    expect(schema(computerUseOpenAppTool).required).toContain("reasoning");
-  });
-});
-
-// ── run_applescript ─────────────────────────────────────────────────
-
-describe("computer_use_run_applescript", () => {
-  test("requires script and reasoning", () => {
-    expect(schema(computerUseRunAppleScriptTool).required).toContain("script");
-    expect(schema(computerUseRunAppleScriptTool).required).toContain(
-      "reasoning",
-    );
-  });
-
-  test("description warns against do shell script", () => {
-    expect(computerUseRunAppleScriptTool.description).toContain(
-      "do shell script",
-    );
-    expect(computerUseRunAppleScriptTool.description).toContain("blocked");
-  });
-});
-
-// ── done ────────────────────────────────────────────────────────────
-
-describe("computer_use_done", () => {
-  test("requires summary", () => {
-    expect(schema(computerUseDoneTool).required).toContain("summary");
-  });
-});
-
-// ── respond ─────────────────────────────────────────────────────────
-
-describe("computer_use_respond", () => {
-  test("requires answer and reasoning", () => {
-    expect(schema(computerUseRespondTool).required).toContain("answer");
-    expect(schema(computerUseRespondTool).required).toContain("reasoning");
-  });
-});
-
-// ── skill-proxy-bridge ──────────────────────────────────────────────
-
 describe("forwardComputerUseProxyTool", () => {
   test("returns error when no proxy resolver available", async () => {
     const result = await forwardComputerUseProxyTool(

package/src/__tests__/conversation-tool-setup-attribution.test.ts

@@ -10,6 +10,7 @@
 import { beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
 
 import type { Conversation } from "../daemon/conversation.js";
+import { shouldUseVirtualDesktop } from "../desktop/virtual-desktop-feature.js";
 import type { PermissionPrompter } from "../permissions/prompter.js";
 import type { SecretPrompter } from "../permissions/secret-prompter.js";
 import type { ToolExecutor } from "../tools/executor.js";
@@ -307,6 +308,28 @@ describe("createToolExecutor attribution threading", () => {
   });
 });
 
+test("desktop routing honors the pinned interface when the live client changes", async () => {
+  for (const transportInterface of ["web", "macos"] as const) {
+    const { executor, calls } = makeCapturingExecutor();
+    await makeToolFn(
+      executor,
+      makeCtx({
+        transportInterface: transportInterface === "web" ? "macos" : "web",
+        toolContextPin: { hasNoClient: false, transportInterface },
+        getTurnActorPrincipalId: () => "user-123",
+        currentTurnTrustContext: {
+          sourceChannel: "vellum",
+          trustClass: "guardian",
+        },
+      }),
+    )("computer_use_observe", {});
+
+    expect(shouldUseVirtualDesktop(calls[0].context, true)).toBe(
+      transportInterface === "web",
+    );
+  }
+});
+
 describe("createToolExecutor isInteractive threading", () => {
   test("uses the resolved turn-level interactivity over live client state", async () => {
     // A scheduled/background turn (currentTurnIsNonInteractive=true) must read

package/src/__tests__/migration-export-to-gcs.test.ts

@@ -37,6 +37,23 @@ const testDbDir = join(testDir, "data", "db");
 const testDbPath = join(testDbDir, "assistant.db");
 const testConfigPath = join(testDir, "config.json");
 
+// The gateway's debug export arrives over IPC as a base64 tar.gz. Stand in
+// for the socket so the debug profile can be exercised without a gateway.
+const FAKE_GATEWAY_ARCHIVE = Buffer.from("not really a tar.gz");
+const gatewayDebugExportMock = mock(async () => ({
+  ok: true as const,
+  archive_base64: FAKE_GATEWAY_ARCHIVE.toString("base64"),
+  size_bytes: FAKE_GATEWAY_ARCHIVE.length,
+}));
+mock.module("../ipc/gateway-client.js", () => ({
+  ipcCallPersistent: (method: string) => {
+    if (method !== "gateway_debug_export") {
+      throw new Error(`unexpected IPC method ${method}`);
+    }
+    return gatewayDebugExportMock();
+  },
+}));
+
 mock.module("../permissions/trust-store.js", () => ({
   getAllRules: () => [],
   isStarterBundleAccepted: () => false,
@@ -328,6 +345,131 @@ describe("handleMigrationExportToGcs — happy path", () => {
   }, 15_000);
 });
 
+describe("handleMigrationExportToGcs — debug profile", () => {
+  test("adds the gateway's archive under gateway/ and marks the manifest", async () => {
+    gatewayDebugExportMock.mockClear();
+    let capturedBody: Buffer | undefined;
+    const fixture = await startFixtureServer(async (req, res) => {
+      capturedBody = await collectBody(req);
+      res.writeHead(200);
+      res.end();
+    });
+
+    try {
+      const req = new Request("http://localhost/v1/migrations/export-to-gcs", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          upload_url: makeFakeSignedUploadUrl(fixture.port),
+          profile: "debug",
+        }),
+      });
+      const res = await callHandler(
+        handleMigrationExportToGcs,
+        req,
+        undefined,
+        202,
+      );
+      const body = (await res.json()) as AcceptedResponse;
+      const terminal = await waitForJobTerminal(body.job_id);
+      expect(terminal.status).toBe("complete");
+
+      expect(gatewayDebugExportMock).toHaveBeenCalledTimes(1);
+      const validation = validateVBundle(new Uint8Array(capturedBody!));
+      expect(validation.is_valid).toBe(true);
+      const manifest = validation.manifest!;
+      expect(manifest.export_options.include_gateway).toBe(true);
+      const gatewayEntry = manifest.contents.find(
+        (f) => f.path === "gateway/export.tar.gz",
+      );
+      expect(gatewayEntry?.size_bytes).toBe(FAKE_GATEWAY_ARCHIVE.length);
+      // Staff never receive credentials. The store mock reports itself
+      // unreachable, which would force `secrets_redacted: false` had the
+      // handler tried to collect them.
+      expect(manifest.secrets_redacted).toBe(true);
+      expect(
+        manifest.contents.some((f) => f.path.startsWith("credentials/")),
+      ).toBe(false);
+    } finally {
+      await fixture.close();
+    }
+  }, 15_000);
+
+  test("the default profile never asks the gateway", async () => {
+    gatewayDebugExportMock.mockClear();
+    let capturedBody: Buffer | undefined;
+    const fixture = await startFixtureServer(async (req, res) => {
+      capturedBody = await collectBody(req);
+      res.writeHead(200);
+      res.end();
+    });
+
+    try {
+      const req = new Request("http://localhost/v1/migrations/export-to-gcs", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          upload_url: makeFakeSignedUploadUrl(fixture.port),
+        }),
+      });
+      const res = await callHandler(
+        handleMigrationExportToGcs,
+        req,
+        undefined,
+        202,
+      );
+      const body = (await res.json()) as AcceptedResponse;
+      const terminal = await waitForJobTerminal(body.job_id);
+      expect(terminal.status).toBe("complete");
+
+      expect(gatewayDebugExportMock).not.toHaveBeenCalled();
+      const manifest = validateVBundle(new Uint8Array(capturedBody!)).manifest!;
+      expect(manifest.export_options.include_gateway).toBeUndefined();
+      expect(manifest.contents.some((f) => f.path.startsWith("gateway/"))).toBe(
+        false,
+      );
+    } finally {
+      await fixture.close();
+    }
+  }, 15_000);
+
+  test("a debug bundle is not sent at all if the gateway cannot export", async () => {
+    gatewayDebugExportMock.mockImplementationOnce(async () => {
+      throw new Error("gateway socket missing");
+    });
+    let putCount = 0;
+    const fixture = await startFixtureServer(async (_req, res) => {
+      putCount += 1;
+      res.writeHead(200);
+      res.end();
+    });
+
+    try {
+      const req = new Request("http://localhost/v1/migrations/export-to-gcs", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          upload_url: makeFakeSignedUploadUrl(fixture.port),
+          profile: "debug",
+        }),
+      });
+      const res = await callHandler(
+        handleMigrationExportToGcs,
+        req,
+        undefined,
+        202,
+      );
+      const body = (await res.json()) as { job_id: string };
+      const terminal = await waitForJobTerminal(body.job_id);
+      expect(terminal.status).toBe("failed");
+      expect(terminal.error?.code).toBe("gateway_debug_export_failed");
+      expect(putCount).toBe(0);
+    } finally {
+      await fixture.close();
+    }
+  }, 15_000);
+});
+
 describe("handleMigrationExportToGcs — concurrency", () => {
   test("second export while first is running returns 409 export_in_progress", async () => {
     // First fixture: deliberately slow so the first job stays pending long

package/src/__tests__/plugin-api-provider.test.ts

@@ -21,4 +21,9 @@ describe("plugin-api provider access", () => {
     // registry), not a disjoint, uninitialized module copy.
     expect(PLUGIN_API_EXPORTS).toContain("getConfiguredProvider");
   });
+
+  test("getEffectiveContextWindow is exported and shim-rebound", () => {
+    expect(typeof pluginApi.getEffectiveContextWindow).toBe("function");
+    expect(PLUGIN_API_EXPORTS).toContain("getEffectiveContextWindow");
+  });
 });