@vellumai/assistant 0.12.2-staging.1 → 0.12.2-staging.3

package/src/runtime/routes/mcp-auth-routes.ts

@@ -17,7 +17,12 @@ import { z } from "zod";
 import type { McpServerConfig } from "../../config/schemas/mcp.js";
 import { estimateToolDefinitionTokens } from "../../context/token-estimator.js";
 import { reloadMcpServers } from "../../daemon/mcp-reload-service.js";
-import { McpClient } from "../../mcp/client.js";
+import {
+  mcpOAuthCredentialKey,
+  resolveMcpOAuthCredentialTarget,
+  workspaceMcpOAuthCredentialTarget,
+} from "../../mcp/credential-target.js";
+import { readEffectiveMcpConfig } from "../../mcp/effective-config.js";
 import { getMcpServerManager } from "../../mcp/manager.js";
 import { orchestrateMcpOAuthConnect } from "../../mcp/mcp-auth-orchestrator.js";
 import { getMcpAuthState } from "../../mcp/mcp-auth-state.js";
@@ -74,9 +79,7 @@ function persistWorkspaceMcpConfig(config: {
   try {
     saveWorkspaceMcpConfig(config);
   } catch (err) {
-    throw new InternalError(
-      err instanceof Error ? err.message : String(err),
-    );
+    throw new InternalError(err instanceof Error ? err.message : String(err));
   }
 }
 
@@ -91,8 +94,9 @@ async function handleMcpAuthStart({
 }> {
   const { serverId } = parseBody(McpServerIdParams, body);
 
-  const servers = loadWorkspaceMcpConfig().servers;
-  const serverConfig = servers[serverId];
+  const serverConfig = readEffectiveMcpConfig(loadWorkspaceMcpConfig()).servers[
+    serverId
+  ];
 
   if (!serverConfig) {
     throw new BadRequestError(`MCP server "${serverId}" not configured`);
@@ -105,10 +109,29 @@ async function handleMcpAuthStart({
     );
   }
 
+  const credentialTarget = resolveMcpOAuthCredentialTarget(
+    serverId,
+    serverConfig,
+  );
+  if (!credentialTarget) {
+    throw new BadRequestError(
+      `OAuth only supported for sse/streamable-http transports (server "${serverId}" uses ${transport.type})`,
+    );
+  }
+
+  try {
+    mcpOAuthCredentialKey(credentialTarget, "tokens");
+  } catch {
+    throw new BadRequestError(
+      `MCP server "${serverId}" has an invalid transport URL`,
+    );
+  }
+
   let result: { auth_url: string; already_authenticated?: boolean };
   try {
     result = await orchestrateMcpOAuthConnect({
       serverId,
+      credentialTarget,
       transport: {
         url: transport.url,
         type: transport.type,
@@ -135,7 +158,19 @@ function handleMcpAuthStatus({
   | { status: "complete" }
   | { status: "error"; error: string } {
   const { serverId } = pathParams as { serverId: string };
-  const state = getMcpAuthState(serverId);
+  const serverConfig = readEffectiveMcpConfig(loadWorkspaceMcpConfig()).servers[
+    serverId
+  ];
+  const target = serverConfig
+    ? resolveMcpOAuthCredentialTarget(serverId, serverConfig)
+    : null;
+  let targetKey: string | undefined;
+  try {
+    targetKey = target ? mcpOAuthCredentialKey(target, "tokens") : undefined;
+  } catch {
+    targetKey = undefined;
+  }
+  const state = targetKey ? getMcpAuthState(serverId, targetKey) : null;
 
   if (state === null) {
     throw new NotFoundError(`No active OAuth flow for server "${serverId}"`);
@@ -170,53 +205,6 @@ function handleMcpReload(_args: { body?: Record<string, unknown> }): {
   return { ok: true };
 }
 
-// ---------------------------------------------------------------------------
-// Health check helper
-// ---------------------------------------------------------------------------
-
-const HEALTH_CHECK_TIMEOUT_MS = 10_000;
-
-async function checkMachineReadableHealth(
-  serverId: string,
-  config: McpServerConfig,
-  timeoutMs = HEALTH_CHECK_TIMEOUT_MS,
-): Promise<string> {
-  const client = new McpClient(serverId);
-  try {
-    await Promise.race([
-      client.connect(config.transport),
-      new Promise<never>((_, reject) => {
-        const t = setTimeout(() => reject(new Error("timeout")), timeoutMs);
-        if (typeof t === "object" && "unref" in t) {
-          t.unref();
-        }
-      }),
-    ]);
-
-    if (client.isConnected) {
-      await client.disconnect();
-      return "connected";
-    }
-
-    const err = client.lastError;
-    if (err) {
-      if (err.message.includes("timeout")) {
-        return "error";
-      }
-      return "error";
-    }
-
-    return "needs-auth";
-  } catch {
-    try {
-      await client.disconnect();
-    } catch {
-      /* ignore */
-    }
-    return "error";
-  }
-}
-
 // ---------------------------------------------------------------------------
 // List
 // ---------------------------------------------------------------------------
@@ -271,12 +259,19 @@ async function handleMcpList(_args: {
   const configEntries = (
     Object.entries(servers) as [string, McpServerConfig][]
   ).filter(([, config]) => config && typeof config === "object");
+  const manager = getMcpServerManager();
 
   const workspaceEntries: McpServerEntry[] = await Promise.all(
     configEntries.map(async ([id, config]) => {
-      const status = await checkMachineReadableHealth(id, config);
+      const runtimeState = manager.getServerState(id, "workspace");
+      const status =
+        runtimeState === "connected" || runtimeState === "needs-auth"
+          ? runtimeState
+          : "error";
       const hasOAuth =
-        config.transport.type !== "stdio" ? await hasMcpOAuthTokens(id) : false;
+        config.transport.type !== "stdio"
+          ? await hasMcpOAuthTokens(workspaceMcpOAuthCredentialTarget(id))
+          : false;
 
       // Check credential store for stored static auth headers
       const storedHeaders = await getMcpHeaders(id);
@@ -316,21 +311,23 @@ async function handleMcpList(_args: {
   );
 
   return {
-    servers: [...workspaceEntries, ...listPluginServerEntries(configEntries)],
+    servers: [
+      ...workspaceEntries,
+      ...(await listPluginServerEntries(configEntries)),
+    ],
   };
 }
 
 /**
  * Project plugin-declared servers onto listing entries.
  *
- * Nothing here touches the credential store or the network: a plugin
- * server carries no auth state the assistant owns, and its status comes
- * from the manager's in-memory client rather than a probe (see
- * {@link PLUGIN_SERVER_STATUS}).
+ * OAuth presence is read from the plugin's scoped credential identity. Static
+ * workspace headers are never consulted, no network probe runs, and status
+ * comes from the manager's in-memory client (see {@link PLUGIN_SERVER_STATUS}).
  */
-function listPluginServerEntries(
+async function listPluginServerEntries(
   configEntries: [string, McpServerConfig][],
-): McpServerEntry[] {
+): Promise<McpServerEntry[]> {
   const { servers, issues } = readPluginMcpServers();
   for (const issue of issues) {
     log.warn(
@@ -349,36 +346,51 @@ function listPluginServerEntries(
   const workspaceIds = new Set(configEntries.map(([id]) => id));
   const manager = getMcpServerManager();
 
-  return servers
-    .filter((server) => {
-      if (!workspaceIds.has(server.id)) {
-        return true;
-      }
-      log.warn(
-        { plugin: server.pluginName, serverId: server.id },
-        "Plugin MCP server shadowed by a workspace server of the same id; skipping",
-      );
-      return false;
-    })
-    .map((server) => {
-      const { headers: _stripped, ...safeTransport } = server.config
-        .transport as Record<string, unknown>;
-      return {
-        id: server.id,
-        status: manager.getClient(server.id)?.isConnected
-          ? "connected"
-          : PLUGIN_SERVER_STATUS,
-        transport: safeTransport as McpServerEntry["transport"],
-        // A plugin server has no assistant-owned credentials. Resolving
-        // these against `mcp:<id>:*` would report, and could disclose, a
-        // workspace credential that happens to share the id.
-        hasOAuth: false,
-        hasStaticAuth: false,
-        authType: "none" as const,
-        source: "plugin" as const,
-        pluginName: server.pluginName,
-      };
-    });
+  return Promise.all(
+    servers
+      .filter((server) => {
+        if (!workspaceIds.has(server.id)) {
+          return true;
+        }
+        log.warn(
+          { plugin: server.pluginName, serverId: server.id },
+          "Plugin MCP server shadowed by a workspace server of the same id; skipping",
+        );
+        return false;
+      })
+      .map(async (server) => {
+        const { headers: _stripped, ...safeTransport } = server.config
+          .transport as Record<string, unknown>;
+        let hasOAuth = false;
+        const credentialTarget = resolveMcpOAuthCredentialTarget(
+          server.id,
+          server.config,
+        );
+        if (credentialTarget) {
+          try {
+            hasOAuth = await hasMcpOAuthTokens(credentialTarget);
+          } catch (err) {
+            log.warn(
+              { err, plugin: server.pluginName, serverId: server.id },
+              "Plugin MCP OAuth credential identity could not be resolved",
+            );
+          }
+        }
+        return {
+          id: server.id,
+          status:
+            manager.getServerState(server.id, "plugin") === "connected"
+              ? "connected"
+              : PLUGIN_SERVER_STATUS,
+          transport: safeTransport as McpServerEntry["transport"],
+          hasOAuth,
+          hasStaticAuth: false,
+          authType: "none" as const,
+          source: "plugin" as const,
+          pluginName: server.pluginName,
+        };
+      }),
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -687,7 +699,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "List MCP servers with health status",
     description:
-      "Returns configured MCP servers with live health-check results (connected, needs auth, error).",
+      "Returns configured MCP servers with recorded runtime status without opening new connections.",
     tags: ["internal"],
     responseBody: z.object({
       servers: z.array(

package/src/runtime/routes/oauth-commands-routes.ts

@@ -66,6 +66,7 @@ interface PlatformConnectionEntry {
   id: string;
   account_label?: string;
   scopes_granted?: string[];
+  provider_params?: Record<string, string> | null;
   status?: string;
 }
 
@@ -574,6 +575,9 @@ async function handleStatus({ queryParams = {} }: RouteHandlerArgs) {
       account: c.account_label ?? null,
       grantedScopes: c.scopes_granted ?? [],
       status: c.status ?? "ACTIVE",
+      // Values the provider scopes the connection by (QuickBooks' realm id),
+      // so a caller can address resources the proxy's base URL does not.
+      providerParams: c.provider_params ?? {},
     }));
 
     return {
@@ -1060,6 +1064,8 @@ async function handleManagedConnect({ body = {} }: RouteHandlerArgs) {
     provider: string;
     scopes?: string[];
     redirect_after_connect?: string;
+    /** Per-tenant providers (Shopify): the customer's own host. */
+    tenant_host?: string;
   };
 
   if (!b.provider) {
@@ -1076,6 +1082,13 @@ async function handleManagedConnect({ body = {} }: RouteHandlerArgs) {
   }
   reqBody.redirect_after_connect =
     b.redirect_after_connect ?? "/account/oauth/complete";
+  // Only forwarded when present: the platform validates it against the
+  // provider's pattern and rejects per-tenant providers that omit it.
+  const tenantHost =
+    typeof b.tenant_host === "string" ? b.tenant_host.trim() : "";
+  if (tenantHost) {
+    reqBody.tenant_host = tenantHost;
+  }
 
   const response = await client.fetch(startPath, {
     method: "POST",
@@ -1122,6 +1135,7 @@ async function handleManagedConnectPoll({
       id: e.id,
       account_label: e.account_label ?? null,
       scopes_granted: e.scopes_granted ?? [],
+      provider_params: e.provider_params ?? {},
     })),
   };
 }

package/src/runtime/routes/oauth-providers.ts

@@ -397,6 +397,13 @@ export const oauthProviderSummarySchema = z.object({
   supports_managed_mode: z.boolean(),
   managed_service_is_paid: z.boolean(),
   feature_flag: z.string().nullable(),
+  tenant_host: z
+    .object({
+      pattern: z.string(),
+      label: z.string(),
+      placeholder: z.string(),
+    })
+    .nullable(),
   acts_as: z.enum(["user", "assistant"]),
 });
 

package/src/runtime/routes/plugins-routes.ts

@@ -80,6 +80,7 @@ import {
   PluginDirectoryNotFoundError,
 } from "../../cli/lib/toggle-plugin.js";
 import {
+  PLUGIN_UNINSTALL_WARNING_KEYS,
   PluginNotInstalledError,
   uninstallPlugin,
 } from "../../cli/lib/uninstall-plugin.js";
@@ -255,6 +256,14 @@ const pluginUninstallResponseSchema = z.object({
     .describe(
       "Absolute path that was removed on the assistant host. Useful for audit logs and confirmation toasts.",
     ),
+  warnings: z
+    .array(
+      z.literal(PLUGIN_UNINSTALL_WARNING_KEYS.MCP_OAUTH_CREDENTIALS_UNCHECKED),
+    )
+    .optional()
+    .describe(
+      "Stable keys for non-fatal cleanup limitations that should be localized at the presentation edge.",
+    ),
 });
 
 const pluginDetailsResponseSchema = z.object({
@@ -1134,7 +1143,11 @@ async function handleUninstallPlugin({
     const result = await uninstallPlugin({ name: rawName });
     await reconcilePluginSourcesNow();
     publishPluginsChanged(getOriginClientId(headers));
-    return { name: result.name, target: result.target };
+    return {
+      name: result.name,
+      target: result.target,
+      ...(result.warnings && { warnings: result.warnings }),
+    };
   } catch (err) {
     if (err instanceof InvalidPluginNameError) {
       throw new BadRequestError(err.message);

package/src/runtime/sync/resource-sync-events.ts

@@ -152,6 +152,10 @@ export function publishPluginsChanged(originClientId?: string): void {
   void publishSyncInvalidation([SYNC_TAGS.pluginsList], originClientId);
 }
 
+export function publishMcpChanged(): void {
+  void publishSyncInvalidation([SYNC_TAGS.mcpList]);
+}
+
 /**
  * Invalidate the activation-checklist progress resource on every client.
  *

package/src/tools/browser/browser-execution.ts

@@ -1,4 +1,5 @@
 import { optimizeImageForTransport } from "../../agent/image-optimize.js";
+import type { BrowserOperationContext as ToolContext } from "../../browser/types.js";
 import { getConfig } from "../../config/loader.js";
 import { HostBrowserProxy } from "../../daemon/host-browser-proxy.js";
 import type { ImageContent } from "../../providers/types.js";
@@ -21,7 +22,7 @@ import {
   sanitizeUrlForOutput,
   sanitizeUrlStringForOutput,
 } from "../network/url-safety.js";
-import type { ToolContext, ToolExecutionResult } from "../types.js";
+import type { ToolExecutionResult } from "../types.js";
 import {
   type AuthChallenge,
   detectAuthChallenge,
@@ -515,6 +516,9 @@ async function acquireCdpClientWithMode(
     }
   | { cdp?: never; browserMode?: never; errorResult: ToolExecutionResult }
 > {
+  if (context.cdpClient) {
+    return { cdp: context.cdpClient, browserMode: "cdp-inspect" };
+  }
   const modeResult = parseBrowserMode(input);
   if (!modeResult.ok) {
     return {
@@ -746,6 +750,17 @@ export type ResolvedElement =
   | { kind: "backend"; backendNodeId: number; eid: string }
   | { kind: "selector"; selector: string };
 
+function snapshotConversationId(context: ToolContext): string {
+  return context.cdpClient?.conversationId ?? context.conversationId;
+}
+
+function clearBrowserSessionState(context: ToolContext): void {
+  browserManager.clearSnapshotBackendNodeMap(snapshotConversationId(context));
+  if (!context.cdpClient) {
+    browserManager.clearPreferredBackendKind(context.conversationId);
+  }
+}
+
 /**
  * Resolve an element reference (either `element_id` from a prior
  * snapshot or a raw `selector`) for CDP-native tools. Returns a
@@ -872,6 +887,9 @@ export async function executeBrowserNavigate(
     typeof input.target_client_id === "string" && input.target_client_id !== ""
       ? input.target_client_id
       : undefined;
+  if (context.cdpClient && forceNewTab) {
+    await cdp.send("Vellum.createTab", {}, context.signal);
+  }
   if (cdp.kind === "extension" && useActiveTab) {
     // Explicit opt-out: target the currently-active tab. Clear any
     // conversation pin and reset the live session so this navigate is
@@ -1188,7 +1206,7 @@ export async function executeBrowserNavigate(
     // Navigation changed the page content, so clear stale snapshot
     // mappings regardless of backend. The backendNodeId map is shared
     // per-conversation state that needs to be invalidated on any nav.
-    browserManager.clearSnapshotBackendNodeMap(context.conversationId);
+    browserManager.clearSnapshotBackendNodeMap(snapshotConversationId(context));
 
     // Auto-dismiss common blocker modals (regulatory notices, cookie
     // banners) that aren't exposed in the accessibility tree. Runs
@@ -1398,7 +1416,7 @@ export async function executeBrowserSnapshot(
     const { elements, selectorMap: backendNodeMap } = transformAxTree(rawTree);
 
     browserManager.storeSnapshotBackendNodeMap(
-      context.conversationId,
+      snapshotConversationId(context),
       backendNodeMap,
     );
 
@@ -1600,8 +1618,7 @@ export async function executeBrowserDetach(
     // Vellum.detach round-trip failed (target gone, transport dropped).
     // browser_detach is the user's recovery path — leaving a stale
     // sticky backend or snapshot map behind would defeat its purpose.
-    browserManager.clearSnapshotBackendNodeMap(context.conversationId);
-    browserManager.clearPreferredBackendKind(context.conversationId);
+    clearBrowserSessionState(context);
     cdp.dispose();
   }
 }
@@ -1653,8 +1670,7 @@ export async function executeBrowserClose(
         // Tolerate detach failures (already detached, tab closed, etc.)
       }
     }
-    browserManager.clearSnapshotBackendNodeMap(context.conversationId);
-    browserManager.clearPreferredBackendKind(context.conversationId);
+    clearBrowserSessionState(context);
     return {
       content:
         "Browser session cleared. (Your Chrome tab was not closed — close it yourself if desired.)",
@@ -1683,7 +1699,10 @@ export async function executeBrowserClick(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const { resolved, error } = resolveElement(context.conversationId, input);
+  const { resolved, error } = resolveElement(
+    snapshotConversationId(context),
+    input,
+  );
   if (error) {
     return { content: error, isError: true };
   }
@@ -1796,7 +1815,10 @@ export async function executeBrowserType(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const { resolved, error } = resolveElement(context.conversationId, input);
+  const { resolved, error } = resolveElement(
+    snapshotConversationId(context),
+    input,
+  );
   if (error) {
     return { content: error, isError: true };
   }
@@ -1887,7 +1909,7 @@ export async function executeBrowserPressKey(
   let targetDescription: string | null = null;
   let resolved: ResolvedElement | null = null;
   if (hasTarget) {
-    const res = resolveElement(context.conversationId, input);
+    const res = resolveElement(snapshotConversationId(context), input);
     if (res.error) {
       return { content: res.error, isError: true };
     }
@@ -2025,7 +2047,10 @@ export async function executeBrowserSelectOption(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const { resolved, error } = resolveElement(context.conversationId, input);
+  const { resolved, error } = resolveElement(
+    snapshotConversationId(context),
+    input,
+  );
   if (error) {
     return { content: error, isError: true };
   }
@@ -2162,7 +2187,10 @@ export async function executeBrowserHover(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const { resolved, error } = resolveElement(context.conversationId, input);
+  const { resolved, error } = resolveElement(
+    snapshotConversationId(context),
+    input,
+  );
   if (error) {
     return { content: error, isError: true };
   }
@@ -2410,7 +2438,10 @@ export async function executeBrowserFillCredential(
     return { content: "Error: field is required.", isError: true };
   }
 
-  const { resolved, error } = resolveElement(context.conversationId, input);
+  const { resolved, error } = resolveElement(
+    snapshotConversationId(context),
+    input,
+  );
   if (error) {
     return { content: error, isError: true };
   }

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

@@ -2804,3 +2804,72 @@ describe("macOS host-browser proxy without extension registry", () => {
     expect(result).toEqual({ ok: true, via: "extension" });
   });
 });
+
+describe("native renderer browser compatibility", () => {
+  beforeEach(() => {
+    setCdpInspectEnabled(false);
+    setDesktopAutoConfig({ enabled: true, cooldownMs: 30_000 });
+    _resetDesktopAutoCooldown();
+    _resetHostBridgeCooldown();
+    mockSingletonProxy = null;
+  });
+  test.each(["macos", "windows"] as const)(
+    "%s web renderer sends CDP to the connected host bridge",
+    async (clientOs) => {
+      mockSingletonProxy = makeMacosBridgeOnlyProxy();
+      const client = getCdpClient(
+        makeContext({
+          conversationId: "conv-native",
+          transportInterface: "web",
+          clientOs,
+        }),
+      );
+      try {
+        expect(await client.send("Page.getFrameTree", {})).toMatchObject({
+          via: "host-bridge",
+        });
+      } finally {
+        client.dispose();
+      }
+    },
+  );
+
+  test.each(["macos", "windows"] as const)(
+    "%s web renderer keeps the existing Playwright fallback without a bridge",
+    async (clientOs) => {
+      const client = getCdpClient(
+        makeContext({
+          conversationId: "conv-native",
+          transportInterface: "web",
+          clientOs,
+        }),
+      );
+      try {
+        expect(await client.send("Page.getFrameTree", {})).toMatchObject({
+          via: "local",
+        });
+      } finally {
+        client.dispose();
+      }
+    },
+  );
+
+  test("explicit Playwright choice overrides the native browser default", async () => {
+    mockSingletonProxy = makeMacosBridgeOnlyProxy();
+    const client = getCdpClient(
+      makeContext({
+        conversationId: "conv-native",
+        transportInterface: "web",
+        clientOs: "windows",
+      }),
+      { mode: "local" },
+    );
+    try {
+      expect(await client.send("Page.getFrameTree", {})).toMatchObject({
+        via: "local",
+      });
+    } finally {
+      client.dispose();
+    }
+  });
+});

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

@@ -417,6 +417,7 @@ describe("connectCdpWsTransport", () => {
         }
         expect(caught).toBeInstanceOf(CdpWsTransportError);
         expect((caught as CdpWsTransportError).code).toBe("closed");
+        expect(transport.closed).toBe(true);
 
         // After close, subsequent sends also reject with closed.
         let caught2: unknown;

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

@@ -99,6 +99,8 @@ export interface CdpTransportEvent {
  * CDP error mapping to the shared `CdpError` taxonomy.
  */
 export interface CdpWsTransport {
+  readonly closed?: boolean;
+
   /**
    * Send a CDP method call over the socket and await its response.
    *
@@ -464,6 +466,9 @@ function createTransport(ws: WsLike): CdpWsTransport {
   ws.addEventListener("error", handleError);
 
   const transport: CdpWsTransport = {
+    get closed() {
+      return disposed || closed;
+    },
     send<T = unknown>(
       method: string,
       params?: Record<string, unknown>,

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

@@ -352,7 +352,7 @@ export const computerUseOpenAppTool = {
 export const computerUseRunAppleScriptTool = {
   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 foreground activity. Never use 'do shell script' inside AppleScript (blocked for security).",
+    "Run an AppleScript on the Mac. Try the target app's own scripting dictionary first, asking it for the state you want rather than for the clicks that would produce it; fall back to System Events menu clicking for apps with no dictionary entry for what you need. Prefer this over click and type when the app supports it; it does not move the cursor. The result is the script's return value, and the accessibility tree may not change even when the script worked. Never use 'do shell script' inside AppleScript (blocked for security).",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionTarget: "host",
@@ -367,8 +367,7 @@ export const computerUseRunAppleScriptTool = {
       },
       reasoning: {
         type: "string",
-        description:
-          "Explanation of what this script does and why AppleScript is better than UI interaction for this step",
+        description: "What this script does",
       },
       target_client_id: {
         type: "string",
@@ -569,7 +568,7 @@ export const computerUseObserveTool = {
       include_screenshot: {
         type: "boolean",
         description:
-          "Force a screenshot with this observation. The accessibility tree is returned every step; ask for pixels whenever the tree is not enough to act on, such as a canvas, a game, a custom-drawn view, a window with few or unlabeled controls, or a question about layout.",
+          "Force a screenshot with this observation. The accessibility tree is returned every step and actions always return a screenshot of their result; ask for pixels on an observation whenever the tree is not enough to act on, such as a canvas, a game, a custom-drawn view, a window with few or unlabeled controls, or a question about layout.",
       },
       full_tree: {
         type: "boolean",