@vellumai/assistant 0.6.2 → 0.6.3

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

@@ -0,0 +1,125 @@
+import type { HostBrowserProxy } from "../../../daemon/host-browser-proxy.js";
+import { getLogger } from "../../../util/logger.js";
+import { CdpError } from "./errors.js";
+import type { CdpClientKind, ScopedCdpClient } from "./types.js";
+
+const log = getLogger("extension-cdp-client");
+
+/**
+ * CdpClient backed by HostBrowserProxy. Each `send` becomes a
+ * host_browser_request / host_browser_result round-trip over the
+ * chrome-extension WebSocket.
+ *
+ * Unlike LocalCdpClient, this implementation cannot deliver
+ * CDP events (subscribing to "Page.lifecycleEvent" etc.) because
+ * HostBrowserProxy is request/reply only. Helpers that need
+ * event subscription (waitForLifecycleEvent) must fall back to
+ * polling via Runtime.evaluate — see cdp-dom-helpers.ts#navigateAndWait.
+ */
+export class ExtensionCdpClient implements ScopedCdpClient {
+  readonly kind: CdpClientKind = "extension";
+  private disposed = false;
+
+  constructor(
+    private readonly proxy: HostBrowserProxy,
+    public readonly conversationId: string,
+    private readonly cdpSessionId?: string,
+  ) {}
+
+  async send<T = unknown>(
+    method: string,
+    params?: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    if (this.disposed) {
+      throw new CdpError("disposed", "ExtensionCdpClient already disposed", {
+        cdpMethod: method,
+        cdpParams: params,
+      });
+    }
+    if (signal?.aborted) {
+      throw new CdpError("aborted", "Aborted before send", {
+        cdpMethod: method,
+        cdpParams: params,
+      });
+    }
+
+    let result;
+    try {
+      result = await this.proxy.request(
+        {
+          cdpMethod: method,
+          cdpParams: params,
+          cdpSessionId: this.cdpSessionId,
+        },
+        this.conversationId,
+        signal,
+      );
+    } catch (err) {
+      throw new CdpError(
+        "transport_error",
+        err instanceof Error ? err.message : String(err),
+        {
+          cdpMethod: method,
+          cdpParams: params,
+          underlying: err,
+        },
+      );
+    }
+
+    if (signal?.aborted || result.content === "Aborted") {
+      throw new CdpError("aborted", "CDP call aborted", {
+        cdpMethod: method,
+        cdpParams: params,
+      });
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(result.content);
+    } catch (err) {
+      throw new CdpError(
+        "transport_error",
+        `Non-JSON content from host_browser_result: ${result.content.slice(0, 200)}`,
+        {
+          cdpMethod: method,
+          cdpParams: params,
+          underlying: err,
+        },
+      );
+    }
+
+    if (result.isError) {
+      const msg =
+        (typeof parsed === "object" &&
+          parsed !== null &&
+          "message" in parsed &&
+          typeof (parsed as { message: unknown }).message === "string" &&
+          (parsed as { message: string }).message) ||
+        `CDP error for ${method}`;
+      log.debug({ method, params, parsed }, "ExtensionCdpClient: CDP error");
+      throw new CdpError("cdp_error", msg, {
+        cdpMethod: method,
+        cdpParams: params,
+        underlying: parsed,
+      });
+    }
+
+    return parsed as T;
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    // HostBrowserProxy is owned by the conversation — do NOT dispose
+    // it here. In-flight requests will be cancelled by the AbortSignal
+    // the tool passes in, or by conversation teardown.
+  }
+}
+
+export function createExtensionCdpClient(
+  proxy: HostBrowserProxy,
+  conversationId: string,
+  cdpSessionId?: string,
+): ExtensionCdpClient {
+  return new ExtensionCdpClient(proxy, conversationId, cdpSessionId);
+}

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

@@ -0,0 +1,204 @@
+import {
+  type BrowserBackend,
+  BrowserSessionManager,
+  type CdpCommand,
+  type CdpResult,
+  createCdpInspectBackend,
+  createExtensionBackend,
+  createLocalBackend,
+} from "../../../browser-session/index.js";
+import { getConfig } from "../../../config/loader.js";
+import type { ToolContext } from "../../types.js";
+import { createCdpInspectClient } from "./cdp-inspect-client.js";
+import { CdpError } from "./errors.js";
+import { createExtensionCdpClient } from "./extension-cdp-client.js";
+import { createLocalCdpClient } from "./local-cdp-client.js";
+import type { CdpClient, CdpClientKind, ScopedCdpClient } from "./types.js";
+
+/**
+ * Select the appropriate CdpClient implementation for a tool
+ * invocation based on the ToolContext and config. Three backends are
+ * considered in priority order:
+ *
+ *  1. **Extension** — When `context.hostBrowserProxy` is set (macOS
+ *     desktop / cloud-hosted with a chrome-extension bound to the
+ *     conversation), register an extension backend so CDP commands
+ *     ride the host_browser_request / host_browser_result round-trip.
+ *  2. **cdp-inspect** — When the extension is absent and
+ *     `hostBrowser.cdpInspect.enabled` is `true` in config, construct
+ *     a `CdpInspectClient` that attaches to an already-running Chrome
+ *     via the DevTools JSON protocol (`--remote-debugging-port`).
+ *  3. **Local** — Default. Drives Playwright's CDPSession
+ *     against the sacrificial-profile browser managed by
+ *     browserManager.
+ *
+ * All three paths go through a per-invocation `BrowserSessionManager`
+ * so the manager is the single choke point for CDP routing, session
+ * lifetime, and (future) session invalidation handling. The returned
+ * client is `kind`-tagged so tools can branch on transport — e.g.
+ * browser_navigate skips Playwright-specific screencast and handoff
+ * hooks when `kind === "extension"`.
+ *
+ * IMPORTANT: the returned client is per-invocation. Tools MUST call
+ * `dispose()` in a finally block. Dispose tears down the manager's
+ * session and the underlying CDP client. Disposing an extension-backed
+ * client does NOT dispose the underlying HostBrowserProxy — that is
+ * owned by the conversation.
+ */
+export function getCdpClient(context: ToolContext): ScopedCdpClient {
+  const { conversationId, hostBrowserProxy } = context;
+
+  // 1. Extension backend — preferred when a chrome-extension is bound.
+  if (hostBrowserProxy) {
+    const client = createExtensionCdpClient(hostBrowserProxy, conversationId);
+    const backend = createExtensionBackend({
+      isAvailable: () => true,
+      sendCdp: (command, signal) =>
+        dispatchThroughClient(client, command, signal),
+      dispose: () => client.dispose(),
+    });
+    return buildManagedClient("extension", conversationId, backend);
+  }
+
+  // 2. cdp-inspect backend — opt-in via config when the extension is absent.
+  const cdpInspectConfig = getConfig().hostBrowser.cdpInspect;
+  if (cdpInspectConfig.enabled) {
+    const client = createCdpInspectClient(conversationId, {
+      host: cdpInspectConfig.host,
+      port: cdpInspectConfig.port,
+      discoveryTimeoutMs: cdpInspectConfig.probeTimeoutMs,
+    });
+    const backend = createCdpInspectBackend({
+      isAvailable: () => true,
+      sendCdp: (command, signal) =>
+        dispatchThroughClient(client, command, signal),
+      dispose: () => client.dispose(),
+    });
+    return buildManagedClient("cdp-inspect", conversationId, backend);
+  }
+
+  // 3. Local backend — default (Playwright-backed Chromium).
+  const client = createLocalCdpClient(conversationId);
+  const backend = createLocalBackend({
+    isAvailable: () => true,
+    sendCdp: (command, signal) =>
+      dispatchThroughClient(client, command, signal),
+    dispose: () => client.dispose(),
+  });
+  return buildManagedClient("local", conversationId, backend);
+}
+
+/**
+ * Build a ScopedCdpClient whose `send()` routes through a
+ * BrowserSessionManager seeded with a single backend + session. This
+ * lets tool call sites remain backend-agnostic while giving the
+ * manager a seam for future session-invalidation and multi-target
+ * routing work.
+ */
+function buildManagedClient(
+  kind: CdpClientKind,
+  conversationId: string,
+  backend: BrowserBackend,
+): ScopedCdpClient {
+  const manager = new BrowserSessionManager({ backends: [backend] });
+  const session = manager.createSession();
+  let disposed = false;
+
+  return {
+    kind,
+    conversationId,
+    async send<T = unknown>(
+      method: string,
+      params?: Record<string, unknown>,
+      signal?: AbortSignal,
+    ): Promise<T> {
+      if (disposed) {
+        const clientName =
+          kind === "extension"
+            ? "ExtensionCdpClient"
+            : kind === "cdp-inspect"
+              ? "CdpInspectClient"
+              : "LocalCdpClient";
+        throw new CdpError("disposed", `${clientName} already disposed`, {
+          cdpMethod: method,
+          cdpParams: params,
+        });
+      }
+      const command: CdpCommand = { method, params };
+      const envelope = await manager.send(session.id, command, signal);
+      return unwrapResult<T>(envelope, method, params);
+    },
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      // disposeAll() tears down the per-invocation backend (which in
+      // turn disposes the underlying CdpClient) and clears the single
+      // session we created in buildManagedClient.
+      manager.disposeAll();
+    },
+  };
+}
+
+/**
+ * Adapter that makes an existing `CdpClient` look like a
+ * `BrowserBackend.send`. Converts thrown CdpErrors back into a
+ * `CdpResult` envelope with an `error` payload so the manager does
+ * not need to know about our thrown-error convention, then the
+ * envelope is unwrapped again on the way out of the managed client.
+ *
+ * The per-command `command.sessionId` (populated by the manager from
+ * a session's opaque `targetId`) is intentionally not forwarded to
+ * the underlying CdpClient today — both LocalCdpClient and
+ * ExtensionCdpClient take their CDP sessionId at construction time
+ * and tools run one client per invocation. The seam is preserved so
+ * a future multi-target backend can read it off the CdpCommand.
+ */
+async function dispatchThroughClient(
+  client: CdpClient,
+  command: CdpCommand,
+  signal: AbortSignal | undefined,
+): Promise<CdpResult> {
+  try {
+    const result = await client.send(command.method, command.params, signal);
+    return { result };
+  } catch (err) {
+    if (err instanceof CdpError) {
+      // Preserve the original CdpError so unwrapResult can re-throw it
+      // verbatim. CdpResult's error channel is opaque to the manager,
+      // so stashing the instance under `data` is safe.
+      return {
+        error: {
+          code: -1,
+          message: err.message,
+          data: err,
+        },
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Unwrap a CdpResult envelope into the raw CDP result `T` or throw
+ * the underlying CdpError. If the envelope carries an error but the
+ * `data` is not a CdpError (e.g. a future backend surfaces a JSON-RPC
+ * error envelope directly), synthesize a transport_error CdpError so
+ * call sites keep their uniform error handling.
+ */
+function unwrapResult<T>(
+  envelope: CdpResult,
+  method: string,
+  params?: Record<string, unknown>,
+): T {
+  if (envelope.error) {
+    if (envelope.error.data instanceof CdpError) {
+      throw envelope.error.data;
+    }
+    throw new CdpError("cdp_error", envelope.error.message, {
+      cdpMethod: method,
+      cdpParams: params,
+      underlying: envelope.error,
+    });
+  }
+  return envelope.result as T;
+}

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

@@ -0,0 +1,14 @@
+export {
+  CdpInspectClient,
+  type CdpInspectClientOptions,
+  type CdpInspectHelpers,
+  createCdpInspectClient,
+} from "./cdp-inspect-client.js";
+export { CdpError, type CdpErrorCode } from "./errors.js";
+export {
+  createExtensionCdpClient,
+  ExtensionCdpClient,
+} from "./extension-cdp-client.js";
+export { getCdpClient } from "./factory.js";
+export { createLocalCdpClient, LocalCdpClient } from "./local-cdp-client.js";
+export type { CdpClient, CdpClientKind, ScopedCdpClient } from "./types.js";

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

@@ -0,0 +1,187 @@
+import { getLogger } from "../../../util/logger.js";
+import { browserManager } from "../browser-manager.js";
+import { CdpError } from "./errors.js";
+import type { CdpClientKind, ScopedCdpClient } from "./types.js";
+
+const log = getLogger("local-cdp-client");
+
+/**
+ * Minimal shape of the Playwright CDPSession we depend on. Avoids a
+ * direct Playwright type import so the CDP client stays buildable
+ * even when Playwright types are not present (dev builds, CI jobs
+ * that skip the playwright install).
+ */
+interface PlaywrightCdpSession {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  detach(): Promise<void>;
+}
+
+/**
+ * Minimal shape of the Playwright Page we use for CDP session
+ * creation. Intentionally narrow so we never have to import the
+ * Playwright types directly from this module.
+ */
+interface RawPlaywrightPage {
+  context(): {
+    newCDPSession(page: unknown): Promise<PlaywrightCdpSession>;
+  };
+}
+
+/**
+ * Playwright-backed implementation of {@link ScopedCdpClient}. Used
+ * for CLI conversations, headless cloud conversations, unit tests,
+ * and any desktop conversation that does not have a `hostBrowserProxy`
+ * configured.
+ *
+ * LocalCdpClient owns only the per-conversation CDP session; the
+ * underlying Chromium is still launched and torn down by
+ * `browserManager.ensureContext()` / `browserManager.shutdown()`.
+ */
+export class LocalCdpClient implements ScopedCdpClient {
+  readonly kind: CdpClientKind = "local";
+
+  private sessionPromise: Promise<PlaywrightCdpSession> | null = null;
+  private disposed = false;
+
+  constructor(public readonly conversationId: string) {}
+
+  /**
+   * Lazily create (and cache) a Playwright CDP session for this
+   * conversation. Concurrent callers share the same in-flight promise
+   * so `newCDPSession` is only called once per LocalCdpClient
+   * instance.
+   *
+   * If the underlying browser launch / `newCDPSession` rejects (e.g.
+   * a transient Chromium spawn failure), the cached promise is
+   * cleared so the next `ensureSession()` call retries from scratch
+   * instead of replaying the same rejection forever.
+   */
+  private async ensureSession(): Promise<PlaywrightCdpSession> {
+    if (this.disposed) {
+      throw new CdpError("disposed", "LocalCdpClient already disposed");
+    }
+    if (this.sessionPromise) return this.sessionPromise;
+    const created = this.createSession();
+    this.sessionPromise = created;
+    // Clear the cached promise on rejection so the next call retries
+    // from scratch instead of replaying the same failure forever.
+    // Only clear if `created` is still the cached promise — a
+    // concurrent dispose may have already nulled it.
+    created.catch(() => {
+      if (this.sessionPromise === created) {
+        this.sessionPromise = null;
+      }
+    });
+    return created;
+  }
+
+  private async createSession(): Promise<PlaywrightCdpSession> {
+    const page = await browserManager.getOrCreateSessionPage(
+      this.conversationId,
+    );
+    const rawPage = page as unknown as RawPlaywrightPage;
+    const session = await rawPage.context().newCDPSession(rawPage);
+    log.debug(
+      { conversationId: this.conversationId },
+      "Created Playwright CDP session for LocalCdpClient",
+    );
+    return session;
+  }
+
+  async send<T = unknown>(
+    method: string,
+    params?: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    if (this.disposed) {
+      throw new CdpError("disposed", "LocalCdpClient already disposed", {
+        cdpMethod: method,
+        cdpParams: params,
+      });
+    }
+    if (signal?.aborted) {
+      throw new CdpError("aborted", "Aborted before send", {
+        cdpMethod: method,
+        cdpParams: params,
+      });
+    }
+    let session: PlaywrightCdpSession;
+    try {
+      session = await this.ensureSession();
+    } catch (err) {
+      if (signal?.aborted) {
+        throw new CdpError("aborted", "Aborted during send", {
+          cdpMethod: method,
+          cdpParams: params,
+          underlying: err,
+        });
+      }
+      // Re-throw existing CdpError instances unchanged so we don't
+      // double-wrap (e.g. a "disposed" error raised by a concurrent
+      // dispose landing during ensureSession()).
+      if (err instanceof CdpError) {
+        throw err;
+      }
+      // ensureSession failures (browser launch errors, Chromium
+      // spawn failures, etc) are surfaced as transport_error so
+      // callers can distinguish them from CDP protocol errors raised
+      // by session.send below.
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new CdpError("transport_error", msg, {
+        cdpMethod: method,
+        cdpParams: params,
+        underlying: err,
+      });
+    }
+    try {
+      const result = (await session.send(method, params)) as T;
+      return result;
+    } catch (err) {
+      if (signal?.aborted) {
+        throw new CdpError("aborted", "Aborted during send", {
+          cdpMethod: method,
+          cdpParams: params,
+          underlying: err,
+        });
+      }
+      if (err instanceof CdpError) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new CdpError("cdp_error", msg, {
+        cdpMethod: method,
+        cdpParams: params,
+        underlying: err,
+      });
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    const pending = this.sessionPromise;
+    this.sessionPromise = null;
+    if (!pending) return;
+    pending
+      .then(async (session) => {
+        try {
+          await session.detach();
+        } catch (err) {
+          log.debug({ err }, "LocalCdpClient: session.detach threw (ignored)");
+        }
+      })
+      .catch(() => {
+        // Session never resolved — nothing to detach.
+      });
+  }
+}
+
+/**
+ * Factory for a fresh {@link LocalCdpClient} bound to a conversation.
+ * Keeping the constructor + factory split lets the cdp-client factory
+ * branch between local and extension transports without
+ * exposing the class directly to callers.
+ */
+export function createLocalCdpClient(conversationId: string): LocalCdpClient {
+  return new LocalCdpClient(conversationId);
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Minimal typed surface over Chrome DevTools Protocol. Implemented by
+ * LocalCdpClient (Playwright-backed, same-process Chromium),
+ * ExtensionCdpClient (routes through HostBrowserProxy to the user's
+ * Chrome via chrome.debugger), and CdpInspectClient (connects to a
+ * remote browser over a raw CDP WebSocket URL). Tools call
+ * `send(method, params)` with a CDP method name and return the raw
+ * CDP result object; errors are thrown as {@link CdpError}.
+ */
+export interface CdpClient {
+  /**
+   * Send a CDP command and await the result. `method` must be a
+   * well-known CDP method name (e.g. "Page.navigate",
+   * "Runtime.evaluate", "Accessibility.getFullAXTree"). `params` is
+   * forwarded verbatim.
+   *
+   * On success, returns the raw `result` object from the CDP response
+   * as `T`. On JSON-RPC error or transport failure, throws a
+   * {@link CdpError}. Abort propagates via `signal`; aborted calls
+   * throw an {@link CdpError} with `code === "aborted"`.
+   */
+  send<T = unknown>(
+    method: string,
+    params?: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<T>;
+
+  /**
+   * Release any backend-side resources (CDP sessions, in-flight
+   * requests, listeners). Idempotent. Calling `send` after `dispose`
+   * is allowed but should surface as an error.
+   */
+  dispose(): void;
+}
+
+/**
+ * Backend kind exposed by a concrete CdpClient. Used by tools that
+ * want to branch on the transport (e.g. browser_navigate should skip
+ * the sacrificial-profile screencast setup when running against the
+ * user's own Chrome via the extension).
+ */
+export type CdpClientKind = "local" | "extension" | "cdp-inspect";
+
+/**
+ * Concrete CdpClient instance returned by the factory. Carries the
+ * backend `kind` for transport-aware branches in tool code.
+ */
+export interface ScopedCdpClient extends CdpClient {
+  readonly kind: CdpClientKind;
+  /** Stable conversation id this client is bound to. */
+  readonly conversationId: string;
+}

package/src/tools/filesystem/edit.ts

@@ -9,7 +9,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class FileEditTool implements Tool {
   name = "file_edit";
   description =
-    "Replace an exact string in a file with a new string. Use this for surgical edits instead of rewriting entire files. To delete a file, use bash with rm instead.";
+    "Replace an exact string in a file on your own machine with a new string. Use this for surgical edits instead of rewriting entire files. Use host_file_edit for files on your guardian's device instead.";
   category = "filesystem";
   defaultRiskLevel = RiskLevel.Low;
 

package/src/tools/filesystem/list.ts

@@ -8,7 +8,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class FileListTool implements Tool {
   name = "file_list";
   description =
-    "List the contents of a directory. Returns file and subdirectory names with type indicators and sizes.";
+    "List the contents of a directory on your own machine. Returns file and subdirectory names with type indicators and sizes.";
   category = "filesystem";
   defaultRiskLevel = RiskLevel.Low;
 

package/src/tools/filesystem/read.ts

@@ -14,7 +14,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class FileReadTool implements Tool {
   name = "file_read";
   description =
-    "Read the contents of a file. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. Always use this tool (not host_file_read) for workspace files under .vellum.";
+    "Read the contents of a file on your own machine. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. Use host_file_read for files on your guardian's device instead.";
   category = "filesystem";
   defaultRiskLevel = RiskLevel.Low;
 

package/src/tools/filesystem/write.ts

@@ -8,7 +8,8 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 class FileWriteTool implements Tool {
   name = "file_write";
-  description = "Write content to a file, creating it if it does not exist";
+  description =
+    "Write content to a file on your own machine, creating it if it does not exist. Use host_file_write for files on your guardian's device instead.";
   category = "filesystem";
   defaultRiskLevel = RiskLevel.Low;
 

package/src/tools/host-filesystem/edit.ts

@@ -8,7 +8,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class HostFileEditTool implements Tool {
   name = "host_file_edit";
   description =
-    "Replace exact text in a host filesystem file with new text. Not for workspace files under .vellum (use file_edit instead).";
+    "Replace exact text in a file on your guardian's device with new text. For files on your own machine, use file_edit instead.";
   category = "host-filesystem";
   defaultRiskLevel = RiskLevel.Medium;
 

package/src/tools/host-filesystem/read.ts

@@ -13,7 +13,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 class HostFileReadTool implements Tool {
   name = "host_file_read";
   description =
-    "Read the contents of a file on the host filesystem, including images (JPEG, PNG, GIF, WebP). Not for workspace files under .vellum (use file_read instead).";
+    "Read the contents of a file on your guardian's device, including images (JPEG, PNG, GIF, WebP). For files on your own machine, use file_read instead.";
   category = "host-filesystem";
   defaultRiskLevel = RiskLevel.Medium;
 
@@ -54,21 +54,9 @@ class HostFileReadTool implements Tool {
       };
     }
 
-    // Image files must be handled locally — the host-file proxy protocol
-    // only carries {content, isError} and cannot transport contentBlocks
-    // (base64 image data). Check for image extensions before the proxy
-    // short-circuit so image reads work in managed/macOS+iOS sessions.
-    const ext = extname(rawPath).toLowerCase();
-    if (IMAGE_EXTENSIONS.has(ext)) {
-      const pathCheck = hostPolicy(rawPath);
-      if (!pathCheck.ok) {
-        return { content: `Error: ${pathCheck.error}`, isError: true };
-      }
-      return readImageFile(pathCheck.resolved);
-    }
-
     // Proxy to connected client for execution on the user's machine
-    // when a capable client is available (managed/cloud-hosted mode).
+    // when a capable client is available (managed/cloud-hosted mode),
+    // including image reads that need the host filesystem view.
     if (context.hostFileProxy?.isAvailable()) {
       return context.hostFileProxy.request(
         {
@@ -82,6 +70,15 @@ class HostFileReadTool implements Tool {
       );
     }
 
+    const ext = extname(rawPath).toLowerCase();
+    if (IMAGE_EXTENSIONS.has(ext)) {
+      const pathCheck = hostPolicy(rawPath);
+      if (!pathCheck.ok) {
+        return { content: `Error: ${pathCheck.error}`, isError: true };
+      }
+      return readImageFile(pathCheck.resolved);
+    }
+
     const ops = new FileSystemOps(hostPolicy);
 
     const result = ops.readFileSafe({