@vellumai/assistant 0.8.0 → 0.8.2

package/src/tools/browser/cdp-client/__tests__/factory.test.ts

@@ -78,13 +78,26 @@ let desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
 const logWarnCalls: Array<{ args: unknown[] }> = [];
 const logDebugCalls: Array<{ args: unknown[] }> = [];
 
+// Spread-real-module pattern: bun's `mock.module` is process-global, so a
+// factory that returns ONLY `{ createExtensionCdpClient }` would clobber
+// the `ExtensionCdpClient` class export for every later test file that
+// imports from this module path (e.g. extension-cdp-client.test.ts). We
+// snapshot the real exports first and override only the symbols this
+// suite stubs out.
+import * as realCdpInspectClient from "../cdp-inspect-client.js";
+import * as realExtensionCdpClient from "../extension-cdp-client.js";
+import * as realLocalCdpClient from "../local-cdp-client.js";
+
 mock.module("../extension-cdp-client.js", () => ({
+  ...realExtensionCdpClient,
   createExtensionCdpClient: createExtensionCdpClientMock,
 }));
 mock.module("../local-cdp-client.js", () => ({
+  ...realLocalCdpClient,
   createLocalCdpClient: createLocalCdpClientMock,
 }));
 mock.module("../cdp-inspect-client.js", () => ({
+  ...realCdpInspectClient,
   createCdpInspectClient: createCdpInspectClientMock,
 }));
 mock.module("../../../../config/loader.js", () => ({
@@ -235,9 +248,15 @@ describe("getCdpClient", () => {
     );
     expect(result).toEqual({ ok: true, via: "extension" });
     expect(createExtensionCdpClientMock).toHaveBeenCalledTimes(1);
+    // Call signature includes optional cdpSessionId, sourceActorPrincipalId,
+    // and targetClientId (all undefined here — no pinned session id, no actor
+    // binding, no explicit client target in this legacy ctx).
     expect(createExtensionCdpClientMock).toHaveBeenCalledWith(
       fakeProxy,
       "test-convo",
+      undefined,
+      undefined,
+      undefined,
     );
     expect(createLocalCdpClientMock).not.toHaveBeenCalled();
     expect(createCdpInspectClientMock).not.toHaveBeenCalled();
@@ -658,6 +677,105 @@ describe("getCdpClient", () => {
     await client.send("Page.navigate");
     expect(createCdpInspectClientMock).toHaveBeenCalledTimes(1);
   });
+
+  test("threads sourceActorPrincipalId from ToolContext into createExtensionCdpClient", async () => {
+    // The proxy uses sourceActorPrincipalId to refuse cross-user dispatch
+    // when host_browser is exposed cross-client (web/iOS turn → connected
+    // extension/macOS bridge). The factory must thread the value from the
+    // ToolContext through to ExtensionCdpClient on every candidate-list path
+    // so the actor identity reaches the proxy at request time.
+    const fakeProxy = makeAvailableProxy();
+    mockSingletonProxy = fakeProxy;
+    const ctx = makeContext({
+      conversationId: "actor-bound",
+      sourceActorPrincipalId: "user-actor-1",
+    });
+
+    const client = getCdpClient(ctx);
+    await client.send("Page.navigate");
+
+    expect(createExtensionCdpClientMock).toHaveBeenCalledTimes(1);
+    expect(createExtensionCdpClientMock).toHaveBeenCalledWith(
+      fakeProxy,
+      "actor-bound",
+      undefined,
+      "user-actor-1",
+      undefined,
+    );
+  });
+
+  test("threads targetClientId from options into createExtensionCdpClient", async () => {
+    const fakeProxy = makeAvailableProxy();
+    mockSingletonProxy = fakeProxy;
+    const ctx = makeContext({
+      conversationId: "targeted-client",
+      sourceActorPrincipalId: "user-actor-1",
+    });
+
+    const client = getCdpClient(ctx, { targetClientId: "specific-ext-client" });
+    await client.send("Page.navigate");
+
+    expect(createExtensionCdpClientMock).toHaveBeenCalledTimes(1);
+    expect(createExtensionCdpClientMock).toHaveBeenCalledWith(
+      fakeProxy,
+      "targeted-client",
+      undefined,
+      "user-actor-1",
+      "specific-ext-client",
+    );
+  });
+
+  // ── auto mode + targetClientId: no fallback (Fix 2) ─────────────────
+
+  test("auto mode + targetClientId + no extension → throws targeting error, does not fall through to local", () => {
+    // No extension connected — without targetClientId, local would be the
+    // fallback. With targetClientId, the factory must fail immediately.
+    const ctx = makeContext({ conversationId: "auto-targeted-no-ext" });
+
+    expect(() =>
+      getCdpClient(ctx, { mode: "auto", targetClientId: "specific-host-client" }),
+    ).toThrow(
+      expect.objectContaining({
+        code: "transport_error",
+        message: expect.stringContaining("specific-host-client"),
+      }),
+    );
+    expect(createLocalCdpClientMock).not.toHaveBeenCalled();
+    expect(createCdpInspectClientMock).not.toHaveBeenCalled();
+  });
+
+  test("auto mode + targetClientId + extension available → routes only to extension, no other backends tried", async () => {
+    cdpInspectEnabled = true; // cdp-inspect would normally be in the candidate list
+    const fakeProxy = makeAvailableProxy();
+    mockSingletonProxy = fakeProxy;
+    const ctx = makeContext({
+      conversationId: "auto-targeted-ext-available",
+      sourceActorPrincipalId: "actor-42",
+    });
+
+    const client = getCdpClient(ctx, {
+      mode: "auto",
+      targetClientId: "specific-host-client",
+    });
+    expect(client.kind).toBe("extension");
+
+    const result = await client.send<{ ok: boolean; via: string }>(
+      "Page.navigate",
+    );
+    expect(result).toEqual({ ok: true, via: "extension" });
+
+    expect(createExtensionCdpClientMock).toHaveBeenCalledTimes(1);
+    expect(createExtensionCdpClientMock).toHaveBeenCalledWith(
+      fakeProxy,
+      "auto-targeted-ext-available",
+      undefined,
+      "actor-42",
+      "specific-host-client",
+    );
+    // cdp-inspect and local must NOT have been tried — no fallback.
+    expect(createCdpInspectClientMock).not.toHaveBeenCalled();
+    expect(createLocalCdpClientMock).not.toHaveBeenCalled();
+  });
 });
 
 // ── buildCandidateList tests ─────────────────────────────────────────────
@@ -748,6 +866,62 @@ describe("buildCandidateList", () => {
     expect(candidates.length).toBe(1);
     expect(candidates[0].kind).toBe("local");
   });
+
+  // ── targetClientId: no-fallback single-extension list (Fix 2) ────────
+
+  test("targetClientId: returns a single extension candidate when extension is available", () => {
+    const fakeProxy = makeAvailableProxy();
+    mockSingletonProxy = fakeProxy;
+    const ctx = makeContext({ conversationId: "target-with-ext" });
+
+    const candidates = buildCandidateList(ctx, "host-client-42");
+
+    // Must be exactly one candidate — no cdp-inspect or local fallbacks.
+    expect(candidates.length).toBe(1);
+    expect(candidates[0].kind).toBe("extension");
+    expect(candidates[0].reason).toContain("host-client-42");
+  });
+
+  test("targetClientId: throws transport_error immediately when no Chrome Extension is connected", () => {
+    // No extension — local would normally be the fallback, but targeting
+    // requires the proxy path and must fail loudly instead of routing elsewhere.
+    const ctx = makeContext({ conversationId: "target-no-ext" });
+
+    expect(() => buildCandidateList(ctx, "host-client-42")).toThrow(
+      expect.objectContaining({
+        code: "transport_error",
+        message: expect.stringContaining("host-client-42"),
+      }),
+    );
+    // Verify we did NOT silently fall through to a local candidate.
+    expect(createLocalCdpClientMock).not.toHaveBeenCalled();
+  });
+
+  test("targetClientId: threads targetClientId into the extension candidate's create() call", async () => {
+    const fakeProxy = makeAvailableProxy();
+    mockSingletonProxy = fakeProxy;
+    const ctx = makeContext({
+      conversationId: "target-threads-id",
+      sourceActorPrincipalId: "actor-1",
+    });
+
+    const candidates = buildCandidateList(ctx, "host-client-99");
+    expect(candidates.length).toBe(1);
+
+    // Clear accumulated calls from prior tests in this describe block before
+    // materialising the candidate so the call count is unambiguous.
+    createExtensionCdpClientMock.mockClear();
+    candidates[0].create();
+
+    expect(createExtensionCdpClientMock).toHaveBeenCalledTimes(1);
+    expect(createExtensionCdpClientMock).toHaveBeenCalledWith(
+      fakeProxy,
+      "target-threads-id",
+      undefined,
+      "actor-1",
+      "host-client-99",
+    );
+  });
 });
 
 // ── buildChainedClient failover tests ────────────────────────────────────

package/src/tools/browser/cdp-client/cdp-inspect/__tests__/ws-transport.test.ts

@@ -249,18 +249,22 @@ describe("connectCdpWsTransport", () => {
   });
 
   test("fans out events (frames with no id) to listeners", async () => {
+    // The server pushes the unsolicited event in direct response to
+    // a client trigger, sending the event frame BEFORE the response
+    // ack. WebSocket message ordering then guarantees the event
+    // arrives at the client (and is fanned out) before the trigger
+    // resolves — no setTimeout race between the server's open
+    // callback and the test attaching its listener.
     const server = startFakeWsServer({
-      onOpen(ws) {
-        // Push an unsolicited event shortly after open.
-        setTimeout(() => {
-          ws.send(
-            JSON.stringify({
-              method: "Target.targetCreated",
-              params: { targetId: "abc" },
-              sessionId: "S1",
-            }),
-          );
-        }, 5);
+      onMessage(ws, frame) {
+        ws.send(
+          JSON.stringify({
+            method: "Target.targetCreated",
+            params: { targetId: "abc" },
+            sessionId: "S1",
+          }),
+        );
+        ws.send(JSON.stringify({ id: frame.id, result: {} }));
       },
     });
     try {
@@ -273,8 +277,7 @@ describe("connectCdpWsTransport", () => {
         transport.addEventListener((ev) => {
           received.push(ev);
         });
-        // Wait for the event to arrive.
-        await new Promise((r) => setTimeout(r, 50));
+        await transport.send("Test.trigger");
         expect(received).toEqual([
           {
             method: "Target.targetCreated",

package/src/tools/browser/cdp-client/extension-cdp-client.ts

@@ -44,6 +44,19 @@ export class ExtensionCdpClient implements ScopedCdpClient {
     private readonly proxy: HostBrowserProxy,
     public readonly conversationId: string,
     private readonly cdpSessionId?: string,
+    /**
+     * Caller's actor principal id. When provided, the proxy will refuse to
+     * dispatch this CDP command to a host_browser-capable client owned by a
+     * different actor — closing the cross-client exposure path's same-user
+     * boundary.
+     */
+    private readonly sourceActorPrincipalId?: string,
+    /**
+     * Explicit target client id. When provided, the proxy routes directly
+     * to that client instead of auto-resolving to the most-recently-active
+     * same-actor host_browser client.
+     */
+    private readonly targetClientId?: string,
   ) {}
 
   async send<T = unknown>(
@@ -74,6 +87,8 @@ export class ExtensionCdpClient implements ScopedCdpClient {
         },
         this.conversationId,
         signal,
+        this.sourceActorPrincipalId,
+        this.targetClientId,
       );
     } catch (err) {
       throw new CdpError(
@@ -194,6 +209,14 @@ export function createExtensionCdpClient(
   proxy: HostBrowserProxy,
   conversationId: string,
   cdpSessionId?: string,
+  sourceActorPrincipalId?: string,
+  targetClientId?: string,
 ): ExtensionCdpClient {
-  return new ExtensionCdpClient(proxy, conversationId, cdpSessionId);
+  return new ExtensionCdpClient(
+    proxy,
+    conversationId,
+    cdpSessionId,
+    sourceActorPrincipalId,
+    targetClientId,
+  );
 }

package/src/tools/browser/cdp-client/factory.ts

@@ -97,6 +97,13 @@ export interface GetCdpClientOptions {
    * and disables failover.
    */
   mode?: BrowserMode;
+  /**
+   * Explicit target client id. When provided, the extension backend routes
+   * to this specific client instead of auto-resolving to the most-recently-
+   * active same-actor host_browser client. Mirrors the `target_client_id`
+   * pattern on host_bash/host_file/host_cu.
+   */
+  targetClientId?: string;
 }
 
 /**
@@ -151,10 +158,11 @@ export function getCdpClient(
   options?: GetCdpClientOptions,
 ): ScopedCdpClient {
   const mode: BrowserMode = options?.mode ?? "auto";
+  const targetClientId = options?.targetClientId;
   const candidates =
     mode === "auto"
-      ? buildCandidateList(context)
-      : buildPinnedCandidateList(context, mode);
+      ? buildCandidateList(context, targetClientId)
+      : buildPinnedCandidateList(context, mode, targetClientId);
 
   log.debug(
     {
@@ -182,8 +190,9 @@ export function getCdpClient(
 export function buildPinnedCandidateList(
   context: ToolContext,
   mode: Exclude<BrowserMode, "auto">,
+  targetClientId?: string,
 ): BackendCandidate[] {
-  const { conversationId } = context;
+  const { conversationId, sourceActorPrincipalId } = context;
 
   switch (mode) {
     case "extension": {
@@ -213,6 +222,9 @@ export function buildPinnedCandidateList(
             const client = createExtensionCdpClient(
               hostBrowserProxy,
               conversationId,
+              undefined,
+              sourceActorPrincipalId,
+              targetClientId,
             );
             const backend = createExtensionBackend({
               isAvailable: () => true,
@@ -286,11 +298,57 @@ export function buildPinnedCandidateList(
  *
  * Exported for testing.
  */
-export function buildCandidateList(context: ToolContext): BackendCandidate[] {
-  const { conversationId } = context;
+export function buildCandidateList(context: ToolContext, targetClientId?: string): BackendCandidate[] {
+  const { conversationId, sourceActorPrincipalId } = context;
   const candidates: BackendCandidate[] = [];
   const hostBrowserProxy = HostBrowserProxy.instance;
 
+  // When a specific host client is targeted, only the extension proxy can
+  // route to it. Skip the fallback chain entirely: if the extension is
+  // unavailable, fail loudly rather than silently routing to a different
+  // browser.
+  if (targetClientId != null) {
+    if (!hostBrowserProxy.hasExtensionClient()) {
+      throw new CdpError(
+        "transport_error",
+        `Cannot reach target_client_id "${targetClientId}": no Chrome Extension connected`,
+        {
+          attemptDiagnostics: [
+            {
+              candidateKind: "extension",
+              inclusionReason: "target_client_id requires extension proxy",
+              stage: "candidate_selection",
+              errorCode: "transport_error",
+              errorMessage: "no Chrome Extension connected",
+            },
+          ],
+        },
+      );
+    }
+    return [
+      {
+        kind: "extension",
+        reason: `target_client_id override: ${targetClientId}`,
+        create() {
+          const client = createExtensionCdpClient(
+            hostBrowserProxy,
+            conversationId,
+            undefined,
+            sourceActorPrincipalId,
+            targetClientId,
+          );
+          const backend = createExtensionBackend({
+            isAvailable: () => true,
+            sendCdp: (command, signal) =>
+              dispatchThroughClient(client, command, signal),
+            dispose: () => client.dispose(),
+          });
+          return { client, backend };
+        },
+      },
+    ];
+  }
+
   // 1. Extension -- preferred when a Chrome Extension client is connected.
   if (hostBrowserProxy.hasExtensionClient()) {
     candidates.push({
@@ -300,6 +358,9 @@ export function buildCandidateList(context: ToolContext): BackendCandidate[] {
         const client = createExtensionCdpClient(
           hostBrowserProxy,
           conversationId,
+          undefined,
+          sourceActorPrincipalId,
+          targetClientId,
         );
         const backend = createExtensionBackend({
           isAvailable: () => true,

package/src/tools/browser/runtime-check.ts

@@ -2,8 +2,11 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { ensureBun } from "../../util/bun-runtime.js";
+import { getLogger } from "../../util/logger.js";
 import { getExternalDir } from "../../util/platform.js";
 
+const log = getLogger("runtime-check");
+
 export interface BrowserRuntimeStatus {
   playwrightAvailable: boolean;
   chromiumInstalled: boolean;
@@ -110,6 +113,80 @@ export async function importPlaywright(): Promise<typeof import("playwright")> {
   return mod as unknown as typeof import("playwright");
 }
 
+/** In-flight headless shell install promise to deduplicate concurrent callers. */
+let headlessShellInstalling: Promise<void> | undefined;
+
+/**
+ * Ensure the Chromium headless shell binary is available on disk.
+ * Downloads it on-demand via `playwright install --only-shell chromium`
+ * if the binary is missing. Only installs the lightweight headless shell
+ * (~111 MB), not the full Chrome for Testing browser.
+ */
+export async function ensureChromiumHeadlessShell(
+  pw: typeof import("playwright"),
+): Promise<void> {
+  try {
+    const execPath = pw.chromium.executablePath();
+    if (existsSync(execPath)) return;
+  } catch {
+    // executablePath() may throw if the browser registry is missing
+  }
+
+  if (headlessShellInstalling) {
+    await headlessShellInstalling;
+    return;
+  }
+
+  headlessShellInstalling = (async () => {
+    log.info("Chromium headless shell not found, installing...");
+    const bunPath = await ensureBun();
+
+    // Run the CLI from the same directory where importPlaywright() installed
+    // the package so the resolved playwright version matches the pw module.
+    const externalDir = getExternalDir();
+    const externalPwExists = existsSync(
+      join(externalDir, "node_modules", "playwright", "package.json"),
+    );
+
+    const proc = Bun.spawn(
+      [bunPath, "x", "playwright", "install", "--only-shell", "chromium"],
+      {
+        stdout: "pipe",
+        stderr: "pipe",
+        cwd: externalPwExists ? externalDir : undefined,
+      },
+    );
+    const timeoutMs = 120_000;
+    let timer: ReturnType<typeof setTimeout>;
+    const exitCode = await Promise.race([
+      proc.exited.finally(() => clearTimeout(timer)),
+      new Promise<never>(
+        (_, reject) =>
+          (timer = setTimeout(() => {
+            proc.kill();
+            reject(
+              new Error(
+                `Chromium headless shell install timed out after ${timeoutMs / 1000}s`,
+              ),
+            );
+          }, timeoutMs)),
+      ),
+    ]);
+    if (exitCode === 0) {
+      log.info("Chromium headless shell installed successfully");
+    } else {
+      const stderr = await new Response(proc.stderr).text();
+      throw new Error(
+        `Failed to install Chromium headless shell: ${stderr.trim() || `exit code ${exitCode}`}`,
+      );
+    }
+  })().finally(() => {
+    headlessShellInstalling = undefined;
+  });
+
+  await headlessShellInstalling;
+}
+
 export async function checkBrowserRuntime(): Promise<BrowserRuntimeStatus> {
   // Diagnostic only - no side effects (no playwright installation)
   let chromium: { executablePath: () => string };

package/src/tools/computer-use/definitions.ts

@@ -374,7 +374,7 @@ export const computerUseOpenAppTool: Tool = {
 export const computerUseRunAppleScriptTool: Tool = {
   name: "computer_use_run_applescript",
   description:
-    "Run an AppleScript command. Prefer this over click/type when possible - it doesn't move the cursor or interrupt the user. Never use 'do shell script' inside AppleScript (blocked for security).",
+    "Run an AppleScript command. Prefer this over click/type when possible - it doesn't move the cursor or interrupt foreground activity. Never use 'do shell script' inside AppleScript (blocked for security).",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
@@ -448,7 +448,7 @@ export const computerUseDoneTool: Tool = {
 export const computerUseRespondTool: Tool = {
   name: "computer_use_respond",
   description:
-    "Respond to the user with a text answer instead of performing computer actions. Use this when you can answer directly without interacting with the screen.",
+    "Reply with a text answer instead of performing computer actions. Use this when you can answer directly without interacting with the screen.",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionMode: "proxy",
@@ -462,7 +462,7 @@ export const computerUseRespondTool: Tool = {
         properties: {
           answer: {
             type: "string",
-            description: "The text answer to display to the user",
+            description: "The text answer to display",
           },
           reasoning: {
             type: "string",

package/src/tools/credentials/vault.ts

@@ -88,7 +88,7 @@ class CredentialStoreTool implements Tool {
             type: "string",
             enum: ["store", "list", "delete", "prompt"],
             description:
-              'The operation to perform. Use "prompt" to ask the user for a secret via secure UI - the value never enters the conversation.',
+              'The operation to perform. Use "prompt" to request a secret via secure UI - the value never enters the conversation.',
           },
           service: {
             type: "string",

package/src/tools/document/document-tool.ts

@@ -1,11 +1,40 @@
 import { randomUUID } from "node:crypto";
 
 import {
+  deleteDocument,
+  getDocumentById,
+  getDocumentsForConversation,
+  isDocumentAssociatedWithConversation,
   saveDocument,
+  searchDocumentsByTitle,
   updateDocumentContent,
 } from "../../documents/document-store.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
+function isPrivilegedDocumentActor(context: ToolContext): boolean {
+  return (
+    context.trustClass === "guardian" || context.executionChannel === "vellum"
+  );
+}
+
+function documentNotFound(surfaceId: string): ToolExecutionResult {
+  return {
+    content: JSON.stringify({
+      success: false,
+      surface_id: surfaceId,
+      error: "Document not found",
+    }),
+    isError: true,
+  };
+}
+
+function canAccessDocument(surfaceId: string, context: ToolContext): boolean {
+  return (
+    isPrivilegedDocumentActor(context) ||
+    isDocumentAssociatedWithConversation(surfaceId, context.conversationId)
+  );
+}
+
 // ── Exported execute functions ──────────────────────────────────────
 
 export function executeDocumentCreate(
@@ -85,7 +114,21 @@ export function executeDocumentUpdate(
   const content = input.content as string;
   const mode = (input.mode as string | undefined) || "append";
 
-  updateDocumentContent(surfaceId, content, mode);
+  if (!canAccessDocument(surfaceId, context)) {
+    return documentNotFound(surfaceId);
+  }
+
+  const result = updateDocumentContent(surfaceId, content, mode);
+  if (!result.success) {
+    return {
+      content: JSON.stringify({
+        success: false,
+        surface_id: surfaceId,
+        error: result.error,
+      }),
+      isError: true,
+    };
+  }
 
   // Send document_editor_update message to update the built-in RTE
   if (context.sendToClient) {
@@ -117,3 +160,83 @@ export function executeDocumentUpdate(
     isError: true,
   };
 }
+
+export function executeDocumentRead(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): ToolExecutionResult {
+  const surfaceId = input.surface_id as string;
+  if (!canAccessDocument(surfaceId, context)) {
+    return documentNotFound(surfaceId);
+  }
+
+  const doc = getDocumentById(surfaceId);
+  if (!doc) {
+    return documentNotFound(surfaceId);
+  }
+  return {
+    content: JSON.stringify({
+      success: true,
+      surface_id: doc.surfaceId,
+      title: doc.title,
+      content: doc.content,
+      word_count: doc.wordCount,
+      updated_at: doc.updatedAt,
+    }),
+    isError: false,
+  };
+}
+
+export function executeDocumentList(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): ToolExecutionResult {
+  const query =
+    typeof input.query === "string" && input.query.trim().length > 0
+      ? input.query.trim()
+      : undefined;
+  const docs = query
+    ? searchDocumentsByTitle(
+        query,
+        isPrivilegedDocumentActor(context)
+          ? {}
+          : { conversationId: context.conversationId },
+      )
+    : getDocumentsForConversation(context.conversationId);
+  return {
+    content: JSON.stringify({
+      success: true,
+      documents: docs.map((d) => ({
+        surface_id: d.surfaceId,
+        title: d.title,
+        word_count: d.wordCount,
+        created_at: d.createdAt,
+        updated_at: d.updatedAt,
+      })),
+    }),
+    isError: false,
+  };
+}
+
+export function executeDocumentDelete(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): ToolExecutionResult {
+  const surfaceId = input.surface_id as string;
+  if (!canAccessDocument(surfaceId, context)) {
+    return documentNotFound(surfaceId);
+  }
+
+  const deleted = deleteDocument(surfaceId);
+  if (!deleted) {
+    return documentNotFound(surfaceId);
+  }
+  return {
+    content: JSON.stringify({
+      success: true,
+      surface_id: surfaceId,
+      message: "Document deleted",
+    }),
+    isError: false,
+  };
+}