@vellumai/assistant 0.12.1 → 0.12.2-dev.202609162214.308bda0

package/src/api/events/assistant-outbound-attachment.ts

@@ -28,6 +28,9 @@ export const AssistantOutboundAttachmentSchema = z.object({
    *  true and the client should hydrate via the /content endpoint. */
   data: z.string(),
   sourceType: z.enum(["sandbox_file", "host_file", "tool_block"]).optional(),
+  /** True when this existing computer-use screenshot was linked to the reply
+   *  automatically. Missing or false identifies legacy or explicit placement. */
+  computerUseScreenshot: z.boolean().optional(),
   /** Original file size in bytes. Present when `data` was omitted to
    *  keep payloads small. */
   sizeBytes: z.number().optional(),

package/src/api/events/desktop-activity-changed.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+/** Transient browser activity changed; refetch desktop status. */
+export const DesktopActivityChangedEventSchema = z.object({
+  type: z.literal("desktop_activity_changed"),
+});
+
+export type DesktopActivityChangedEvent = z.infer<
+  typeof DesktopActivityChangedEventSchema
+>;

package/src/api/events/notification-intent.ts

@@ -20,6 +20,8 @@ import { z } from "zod";
 export const NotificationIntentEventSchema = z.object({
   type: z.literal("notification_intent"),
   sourceEventName: z.string(),
+  /** Verified assistant name supplied by the assistant when available. */
+  assistantName: z.string().optional(),
   title: z.string(),
   body: z.string(),
   deliveryId: z.string().optional(),

package/src/api/events/user-message-echo.ts

@@ -1,7 +1,7 @@
 /**
  * `user_message_echo` SSE event.
  *
- * Emitted when a user message is persisted to a conversation — direct
+ * Emitted when a user message is persisted to a conversation: direct
  * sends, slash/canned/compaction turns, and synthetic surface-action
  * prompts. Carries the user's outbound `text` so clients that did not
  * originate the send (passive viewers, other devices) can render the
@@ -15,6 +15,11 @@
  * 202 response. `requestId` correlates with `message_queued` /
  * `message_dequeued` for the same turn.
  *
+ * `cameraFrame` is present only on standalone ambient camera-frame echoes,
+ * before `sync_changed` refetches hydrate their images. Photos and spoken
+ * turns omit it. Older strict parsers drop marked echoes and recover the
+ * persisted rows through the following `sync_changed` invalidation.
+ *
  * Canonical wire-contract source. Daemon code imports the type directly
  * from this file; external consumers import via `@vellumai/assistant-api`.
  */
@@ -29,6 +34,7 @@ export const UserMessageEchoEventSchema = z
     messageId: z.string().optional(),
     requestId: z.string().optional(),
     clientMessageId: z.string().optional(),
+    cameraFrame: z.literal(true).optional(),
   })
   .strict();
 

package/src/api/index.ts

@@ -1,8 +1,14 @@
 import { z } from "zod";
 
+export {
+  isComputerUseToolCall,
+  resolveComputerUseToolName,
+} from "./computer-use-tool.js";
+
 import { AcpAuthRequiredEventSchema } from "./events/acp-auth-required.js";
 import { AcpSessionCompletedEventSchema } from "./events/acp-session-completed.js";
 import { AcpSessionErrorEventSchema } from "./events/acp-session-error.js";
+import { AcpSessionModelUpdateEventSchema } from "./events/acp-session-model-update.js";
 import { AcpSessionSpawnedEventSchema } from "./events/acp-session-spawned.js";
 import { AcpSessionUpdateEventSchema } from "./events/acp-session-update.js";
 import { AcpSessionUsageEventSchema } from "./events/acp-session-usage.js";
@@ -33,6 +39,7 @@ import { ConversationErrorEventSchema } from "./events/conversation-error.js";
 import { ConversationInferenceProfileUpdatedEventSchema } from "./events/conversation-inference-profile-updated.js";
 import { ConversationNoticeEventSchema } from "./events/conversation-notice.js";
 import { ConversationTitleUpdatedEventSchema } from "./events/conversation-title-updated.js";
+import { DesktopActivityChangedEventSchema } from "./events/desktop-activity-changed.js";
 import { DiskPressureStatusChangedEventSchema } from "./events/disk-pressure-status-changed.js";
 import { DocumentCommentCreatedEventSchema } from "./events/document-comment-created.js";
 import { DocumentCommentDeletedEventSchema } from "./events/document-comment-deleted.js";
@@ -186,6 +193,10 @@ export {
   type AcpSessionErrorEvent,
   AcpSessionErrorEventSchema,
 } from "./events/acp-session-error.js";
+export {
+  type AcpSessionModelUpdateEvent,
+  AcpSessionModelUpdateEventSchema,
+} from "./events/acp-session-model-update.js";
 export {
   type AcpSessionSpawnedEvent,
   AcpSessionSpawnedEventSchema,
@@ -337,6 +348,10 @@ export {
   type ConversationTitleUpdatedEvent,
   ConversationTitleUpdatedEventSchema,
 } from "./events/conversation-title-updated.js";
+export {
+  type DesktopActivityChangedEvent,
+  DesktopActivityChangedEventSchema,
+} from "./events/desktop-activity-changed.js";
 export {
   type DiskPressureBlockedCapability,
   DiskPressureBlockedCapabilitySchema,
@@ -964,6 +979,7 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   AcpAuthRequiredEventSchema,
   AcpSessionCompletedEventSchema,
   AcpSessionErrorEventSchema,
+  AcpSessionModelUpdateEventSchema,
   AcpSessionSpawnedEventSchema,
   AcpSessionUpdateEventSchema,
   AcpSessionUsageEventSchema,
@@ -994,6 +1010,7 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   ConversationInferenceProfileUpdatedEventSchema,
   ConversationNoticeEventSchema,
   ConversationTitleUpdatedEventSchema,
+  DesktopActivityChangedEventSchema,
   DiskPressureStatusChangedEventSchema,
   DocumentCommentCreatedEventSchema,
   DocumentCommentDeletedEventSchema,

package/src/api/responses/conversation-message.ts

@@ -51,6 +51,9 @@ export const ConversationMessageAttachmentSchema = z.object({
   thumbnailData: z.string().optional(),
   /** True when the attachment bytes are backed by a file on disk. */
   fileBacked: z.boolean().optional(),
+  /** True when this computer-use screenshot was placed on the reply
+   *  automatically. Missing or false identifies legacy or explicit placement. */
+  computerUseScreenshot: z.boolean().optional(),
 });
 export type ConversationMessageAttachment = z.infer<
   typeof ConversationMessageAttachmentSchema
@@ -615,6 +618,11 @@ export const ConversationMessageSchema = z.object({
    *  sentinel text, and treat the row as the turn's reply so nothing keeps
    *  waiting for one. */
   noResponse: z.boolean().optional(),
+  /** Set only on standalone ambient camera-frame rows, derived from
+   *  `messageMetadataIsAmbientSightKeep`. Clients may fold consecutive frames
+   *  into the following user message. Absent on shutter photos, spoken turns
+   *  carrying parked frames, and every other row. */
+  cameraFrame: z.literal(true).optional(),
   /** How this assistant row's plain text reached the user, set only on a turn
    *  that routed its reply through the `send_user_message` tool. `"private"`
    *  means the row's text blocks are the model's working notes and the text

package/src/approvals/approval-primitive.ts

@@ -213,7 +213,10 @@ function consumeGrantSync(params: ConsumeGrantParams): ConsumeGrantResult {
       return { ok: true, grant: reqResult.grant };
     }
 
-    log.info(
+    // Debug, not info: `consumeGrantForInvocation` and the inline grant wait
+    // poll this function, so a miss is the expected steady state while a
+    // guardian decides. Hits and the wait's outcome are logged at info.
+    log.debug(
       {
         event: "approval_primitive_consume_miss",
         mode: "request_id",
@@ -255,7 +258,7 @@ function consumeGrantSync(params: ConsumeGrantParams): ConsumeGrantResult {
     return { ok: true, grant: sigResult.grant };
   }
 
-  log.info(
+  log.debug(
     {
       event: "approval_primitive_consume_miss",
       mode: "tool_signature",

package/src/approvals/scoped-approval-grants.ts

@@ -193,7 +193,10 @@ function consumeScopedApprovalGrantByRequestId(
       .get();
 
     if (!candidate) {
-      log.info(
+      // Debug, not info: the inline grant wait and the voice retry loop call
+      // this every poll, so a miss is the expected steady state while a
+      // guardian decides. The caller logs the outcome of the wait.
+      log.debug(
         {
           event: "scoped_grant_consume_miss",
           requestId,
@@ -364,7 +367,8 @@ function consumeScopedApprovalGrantByToolSignature(
       .get();
 
     if (!candidate) {
-      log.info(
+      // Debug for the same reason as the request-id miss above: polled.
+      log.debug(
         {
           event: "scoped_grant_consume_miss",
           toolName: params.toolName,

package/src/apps/app-store.ts

@@ -43,6 +43,7 @@ import type { EditEngineResult } from "../tools/shared/filesystem/edit-engine.js
 import { applyEdit } from "../tools/shared/filesystem/edit-engine.js";
 import { getLogger } from "../util/logger.js";
 import { getDataDir, getWorkspacePluginsDir } from "../util/platform.js";
+import { hasPluginManifest } from "../util/plugin-manifest.js";
 
 const log = getLogger("app-store");
 
@@ -114,7 +115,7 @@ export function resolveEffectiveAppHtmlFromDir(sourceDir: string): string {
   if (isLegacySingleFileDir(sourceDir)) {
     return UNSUPPORTED_LEGACY_APP_HTML;
   }
-  return `<p>App compilation failed. Edit a source file to trigger a rebuild.</p>`;
+  return `<p>App compilation failed. Run <code>assistant apps refresh</code> to rebuild.</p>`;
 }
 
 /**
@@ -787,8 +788,8 @@ function listAppsForPlugin(
  * `<workspace>/plugins/<name>/apps/`.
  *
  * Plugin discovery mirrors the plugin loader's `scanPlugins`: a plugin is an
- * entry that resolves to a directory (following symlinks) and carries a
- * `package.json` manifest. Stray directories without a manifest are ignored,
+ * entry that resolves to a directory (following symlinks) and carries a root
+ * plugin manifest. Stray directories without a manifest are ignored,
  * and disabled plugins (those with a `.disabled` sentinel) contribute nothing,
  * matching how their other surfaces (tools, hooks, routes) are gated.
  */
@@ -813,7 +814,7 @@ export function listPluginApps(): EnumeratedApp[] {
     } catch {
       continue;
     }
-    if (!existsSync(join(pluginDir, "package.json"))) {
+    if (!hasPluginManifest(pluginDir)) {
       continue;
     }
     if (isPluginDisabled(name)) {
@@ -874,7 +875,7 @@ function isSafeIdSegment(segment: string): boolean {
  * (`plugins~<name>~<app>`, resolved by direct path build). Returns null when
  * the app does not exist, when the id is not a safe path segment, or when a
  * plugin id fails the same installed-plugin gates as discovery (directory,
- * `package.json` manifest, not disabled).
+ * root manifest, not disabled).
  */
 export function resolveAppSource(id: string): ResolvedAppSource | null {
   if (id.startsWith(PLUGIN_APP_ID_PREFIX)) {
@@ -900,7 +901,7 @@ export function resolveAppSource(id: string): ResolvedAppSource | null {
     } catch {
       return null;
     }
-    if (!existsSync(join(pluginDir, "package.json"))) {
+    if (!hasPluginManifest(pluginDir)) {
       return null;
     }
     if (isPluginDisabled(pluginName)) {

package/src/apps/resolve-app.ts

@@ -0,0 +1,81 @@
+/**
+ * Resolve a user-facing app query (display name, slug, or id) to an
+ * enumerated app. Used by `assistant apps inspect` / `refresh`.
+ */
+
+import { basename } from "node:path";
+
+import { type EnumeratedApp, listAllApps } from "./app-store.js";
+
+export type ResolveAppQueryResult =
+  | { readonly ok: true; readonly app: EnumeratedApp }
+  | { readonly ok: false; readonly reason: "not_found"; readonly query: string }
+  | {
+      readonly ok: false;
+      readonly reason: "ambiguous";
+      readonly query: string;
+      readonly matches: readonly EnumeratedApp[];
+    };
+
+function matchesQuery(app: EnumeratedApp, query: string): boolean {
+  if (app.id === query) {
+    return true;
+  }
+  const lowered = query.toLowerCase();
+  if (app.name.toLowerCase() === lowered) {
+    return true;
+  }
+  const dirName = basename(app.sourcePath);
+  return dirName.toLowerCase() === lowered;
+}
+
+/**
+ * Resolve `query` against every surfaced app. Matching is exact on id, and
+ * case-insensitive on display name and directory slug. Multiple distinct apps
+ * that match yield `ambiguous` rather than picking a winner.
+ */
+export function resolveAppQuery(query: string): ResolveAppQueryResult {
+  const trimmed = query.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, reason: "not_found", query };
+  }
+
+  const matches: EnumeratedApp[] = [];
+  const seen = new Set<string>();
+  for (const app of listAllApps()) {
+    if (!matchesQuery(app, trimmed) || seen.has(app.id)) {
+      continue;
+    }
+    seen.add(app.id);
+    matches.push(app);
+  }
+
+  if (matches.length === 1) {
+    return { ok: true, app: matches[0] };
+  }
+  if (matches.length > 1) {
+    return { ok: false, reason: "ambiguous", query: trimmed, matches };
+  }
+  return { ok: false, reason: "not_found", query: trimmed };
+}
+
+export function formatAppMatch(app: EnumeratedApp): string {
+  const origin =
+    app.origin.kind === "plugin"
+      ? `plugin ${app.origin.pluginName}`
+      : "workspace";
+  return `${app.name} (${origin}, ${app.id})`;
+}
+
+export function appNotFoundMessage(query: string): string {
+  return `App "${query}" not found. Run 'assistant apps list' to see available apps.`;
+}
+
+export function appAmbiguousMessage(
+  query: string,
+  matches: readonly EnumeratedApp[],
+): string {
+  const listed = matches.map((app) => `  ${formatAppMatch(app)}`).join("\n");
+  return `Ambiguous app name "${query}". Matches:\n${listed}\nRun 'assistant apps list' and pass a unique name, slug, or id.`;
+}
+

package/src/apps/source-fingerprint.ts

@@ -0,0 +1,266 @@
+/**
+ * Content fingerprint of an app's source tree, recorded at compile time so
+ * later inspects can tell whether source has drifted from the last successful
+ * build.
+ *
+ * The fingerprint is a one-way per-file digest map written into
+ * `dist/.source-fingerprint.json` after a successful compile. It answers "did
+ * this change?" and "which files?", not a reconstructable diff.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+/** Digest algorithm recorded alongside the file map, for forward compatibility. */
+export type FingerprintAlgorithm = "sha256";
+
+/** Filename written into `dist/` next to compiled output. */
+export const SOURCE_FINGERPRINT_FILENAME = ".source-fingerprint.json";
+
+/** Directory names skipped at the app root only (compile output and records). */
+const ROOT_SKIP_DIRS: ReadonlySet<string> = new Set(["dist", "records"]);
+
+/** Directory names skipped at any depth. */
+const SKIP_DIRS_ANY_DEPTH: ReadonlySet<string> = new Set([
+  "node_modules",
+  ".git",
+]);
+
+/**
+ * Per-file content digest of an app source tree. Keys are POSIX-style
+ * (forward-slash) paths relative to the app directory; values are lowercase
+ * hex SHA-256 digests of each file's bytes.
+ */
+export interface AppSourceFingerprint {
+  readonly algorithm: FingerprintAlgorithm;
+  readonly files: Readonly<Record<string, string>>;
+  /** ISO-8601 timestamp of the compile that produced this baseline, when known. */
+  readonly compiledAt?: string;
+}
+
+/**
+ * Difference between a recorded fingerprint and the current on-disk source.
+ * Paths are POSIX-relative. A rename surfaces as one `removed` plus one `added`.
+ */
+export interface FingerprintComparison {
+  readonly modified: readonly string[];
+  readonly added: readonly string[];
+  readonly removed: readonly string[];
+  readonly clean: boolean;
+}
+
+export type AppSourceInspectStatus =
+  | "clean"
+  | "stale"
+  | "never_compiled"
+  | "unknown_baseline";
+
+export interface AppSourceInspectResult {
+  readonly status: AppSourceInspectStatus;
+  readonly compiledAt: string | null;
+  readonly modified: readonly string[];
+  readonly added: readonly string[];
+  readonly removed: readonly string[];
+}
+
+function hashFile(absPath: string): string | null {
+  try {
+    return createHash("sha256").update(readFileSync(absPath)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk `appDir` and digest every regular source file. Skips `dist/` and
+ * `records/` at the app root, and `node_modules` / `.git` at any depth.
+ * Symlinks are neither visited nor followed.
+ */
+export function computeAppSourceFingerprint(
+  appDir: string,
+): AppSourceFingerprint {
+  const files: Record<string, string> = {};
+
+  const walk = (relDir: string): void => {
+    const absDir = relDir ? join(appDir, relDir) : appDir;
+    let entries;
+    try {
+      entries = readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (relDir === "" && ROOT_SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
+      if (entry.isDirectory() && SKIP_DIRS_ANY_DEPTH.has(entry.name)) {
+        continue;
+      }
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(rel);
+      } else if (entry.isFile()) {
+        const digest = hashFile(join(absDir, entry.name));
+        if (digest !== null) {
+          files[rel] = digest;
+        }
+      }
+    }
+  };
+
+  walk("");
+  return { algorithm: "sha256", files };
+}
+
+export function compareAppSourceFingerprint(
+  appDir: string,
+  baseline: AppSourceFingerprint,
+): FingerprintComparison {
+  const current = computeAppSourceFingerprint(appDir).files;
+  const modified: string[] = [];
+  const added: string[] = [];
+  const removed: string[] = [];
+
+  for (const [path, digest] of Object.entries(current)) {
+    const recorded = baseline.files[path];
+    if (recorded === undefined) {
+      added.push(path);
+    } else if (recorded !== digest) {
+      modified.push(path);
+    }
+  }
+  for (const path of Object.keys(baseline.files)) {
+    if (current[path] === undefined) {
+      removed.push(path);
+    }
+  }
+
+  modified.sort();
+  added.sort();
+  removed.sort();
+  return {
+    modified,
+    added,
+    removed,
+    clean: modified.length === 0 && added.length === 0 && removed.length === 0,
+  };
+}
+
+/**
+ * Parse a fingerprint from already-decoded JSON. Lenient: any shape problem
+ * yields `null` so a missing or hand-edited sidecar reports "no baseline"
+ * rather than throwing.
+ */
+export function parseAppSourceFingerprint(
+  value: unknown,
+): AppSourceFingerprint | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const obj = value as Record<string, unknown>;
+  if (obj.algorithm !== "sha256") {
+    return null;
+  }
+  const rawFiles = obj.files;
+  if (
+    typeof rawFiles !== "object" ||
+    rawFiles === null ||
+    Array.isArray(rawFiles)
+  ) {
+    return null;
+  }
+  const files: Record<string, string> = {};
+  for (const [path, digest] of Object.entries(rawFiles)) {
+    if (typeof digest !== "string") {
+      return null;
+    }
+    files[path] = digest;
+  }
+  const compiledAt =
+    typeof obj.compiledAt === "string" ? obj.compiledAt : undefined;
+  return compiledAt === undefined
+    ? { algorithm: "sha256", files }
+    : { algorithm: "sha256", files, compiledAt };
+}
+
+export function readAppSourceFingerprint(
+  appDir: string,
+): AppSourceFingerprint | null {
+  const path = join(appDir, "dist", SOURCE_FINGERPRINT_FILENAME);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return parseAppSourceFingerprint(JSON.parse(readFileSync(path, "utf-8")));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a source fingerprint into `distDir`. Pass the snapshot taken
+ * before compile so inspect compares against the tree that produced this
+ * dist, even if source changes during the build.
+ */
+export function writeAppSourceFingerprint(
+  appDir: string,
+  distDir: string,
+  fingerprint: AppSourceFingerprint = computeAppSourceFingerprint(appDir),
+): void {
+  const payload: AppSourceFingerprint = {
+    algorithm: fingerprint.algorithm,
+    compiledAt: fingerprint.compiledAt ?? new Date().toISOString(),
+    files: fingerprint.files,
+  };
+  writeFileSync(
+    join(distDir, SOURCE_FINGERPRINT_FILENAME),
+    `${JSON.stringify(payload)}\n`,
+    "utf-8",
+  );
+}
+
+/**
+ * Compare current app source against the fingerprint recorded at last
+ * successful compile.
+ */
+export function inspectAppSource(appDir: string): AppSourceInspectResult {
+  const compiled = existsSync(join(appDir, "dist", "index.html"));
+  if (!compiled) {
+    return {
+      status: "never_compiled",
+      compiledAt: null,
+      modified: [],
+      added: [],
+      removed: [],
+    };
+  }
+
+  const baseline = readAppSourceFingerprint(appDir);
+  if (baseline === null) {
+    return {
+      status: "unknown_baseline",
+      compiledAt: null,
+      modified: [],
+      added: [],
+      removed: [],
+    };
+  }
+
+  const comparison = compareAppSourceFingerprint(appDir, baseline);
+  return {
+    status: comparison.clean ? "clean" : "stale",
+    compiledAt: baseline.compiledAt ?? null,
+    modified: comparison.modified,
+    added: comparison.added,
+    removed: comparison.removed,
+  };
+}

package/src/avatar/identity-avatar.ts

@@ -5,6 +5,7 @@ import type { AvatarState } from "@vellumai/avatar-manifest";
 import { isTemplateContent } from "../prompts/template-detection.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspacePromptPath } from "../util/platform.js";
+import { safeStringSlice } from "../util/unicode.js";
 
 const log = getLogger("identity-avatar");
 
@@ -26,7 +27,7 @@ export const AVATAR_IDENTITY_NOTE_MAX_CHARS = 240;
 function toIdentityLine(text: string): string {
   const line = text.replace(/\s+/g, " ").trim();
   return line.length > AVATAR_IDENTITY_NOTE_MAX_CHARS
-    ? `${line.slice(0, AVATAR_IDENTITY_NOTE_MAX_CHARS - 3).trimEnd()}...`
+    ? `${safeStringSlice(line, 0, AVATAR_IDENTITY_NOTE_MAX_CHARS - 3).trimEnd()}...`
     : line;
 }
 
@@ -117,7 +118,11 @@ export function updateIdentityAvatarSection(description: string): void {
   }
 
   try {
-    writeFileSync(identityPath, withAvatarSection(content, description), "utf-8");
+    writeFileSync(
+      identityPath,
+      withAvatarSection(content, description),
+      "utf-8",
+    );
   } catch (err) {
     log.warn({ err }, "Failed to update IDENTITY.md avatar section");
   }

package/src/browser/operations.ts

@@ -32,7 +32,8 @@ import {
 } from "../tools/browser/browser-execution.js";
 import { browserManager } from "../tools/browser/browser-manager.js";
 import { normalizeBrowserMode } from "../tools/browser/browser-mode.js";
-import type { ToolContext, ToolExecutionResult } from "../tools/types.js";
+import type { ToolExecutionResult } from "../tools/types.js";
+import type { BrowserOperationContext as ToolContext } from "./types.js";
 import type { BrowserOperation } from "./types.js";
 
 // ── Dispatch handlers ────────────────────────────────────────────────

package/src/browser/types.ts

@@ -1,3 +1,10 @@
+import type { ScopedCdpClient } from "../tools/browser/cdp-client/types.js";
+import type { ToolContext } from "../tools/types.js";
+
+export interface BrowserOperationContext extends ToolContext {
+  cdpClient?: ScopedCdpClient;
+}
+
 /**
  * Canonical browser operation identifiers and typed metadata.
  *

package/src/browser/virtual-desktop-target.ts

@@ -0,0 +1,34 @@
+import { getConfig } from "../config/loader.js";
+import { isVirtualDesktopEnabled } from "../desktop/virtual-desktop-feature.js";
+import { browserManager } from "../tools/browser/browser-manager.js";
+import { normalizeBrowserMode } from "../tools/browser/browser-mode.js";
+import { getPinnedTab } from "../tools/browser/pinned-tabs.js";
+import type { ToolContext } from "../tools/types.js";
+
+export function shouldUseVirtualDesktopBrowser(
+  desktop: boolean | undefined,
+  input: Record<string, unknown>,
+  context: ToolContext,
+): boolean {
+  if (desktop !== undefined) {
+    return desktop;
+  }
+  const mode = normalizeBrowserMode(input.browser_mode);
+  if (
+    "error" in mode ||
+    mode.mode !== "auto" ||
+    input.target_client_id ||
+    input.use_active_tab ||
+    context.transportInterface !== "web" ||
+    context.clientOs === "macos" ||
+    context.clientOs === "windows" ||
+    context.clientOs === "linux" ||
+    context.trustClass !== "guardian" ||
+    !context.sourceActorPrincipalId ||
+    browserManager.getPreferredBackendKind(context.conversationId) !== null ||
+    getPinnedTab(context.conversationId)
+  ) {
+    return false;
+  }
+  return isVirtualDesktopEnabled(getConfig());
+}