@vellumai/assistant 0.4.11 → 0.4.13

package/src/runtime/http-types.ts

@@ -1,15 +1,18 @@
 /**
  * Shared types for the runtime HTTP server and its route handlers.
  */
-import type { ChannelId, InterfaceId } from '../channels/types.js';
-import type { Session } from '../daemon/session.js';
-import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
-import type { ApprovalMessageContext, ComposeApprovalMessageGenerativeOptions } from './approval-message-composer.js';
-import type { AssistantEventHub } from './assistant-event-hub.js';
+import type { ChannelId, InterfaceId } from "../channels/types.js";
+import type { Session } from "../daemon/session.js";
+import type { GuardianRuntimeContext } from "../daemon/session-runtime-assembly.js";
+import type {
+  ApprovalMessageContext,
+  ComposeApprovalMessageGenerativeOptions,
+} from "./approval-message-composer.js";
+import type { AssistantEventHub } from "./assistant-event-hub.js";
 import type {
   ComposeGuardianActionMessageOptions,
   GuardianActionMessageContext,
-} from './guardian-action-message-composer.js';
+} from "./guardian-action-message-composer.js";
 /**
  * Daemon-injected function that generates approval copy using a provider.
  * Returns generated text or `null` on failure (caller falls back to deterministic text).
@@ -25,10 +28,10 @@ export type ApprovalCopyGenerator = (
 
 /** The disposition returned by the approval conversation engine. */
 export type ApprovalConversationDisposition =
-  | 'keep_pending'
-  | 'approve_once'
-  | 'approve_always'
-  | 'reject';
+  | "keep_pending"
+  | "approve_once"
+  | "approve_always"
+  | "reject";
 
 /** Structured result from a single turn of the approval conversation. */
 export interface ApprovalConversationResult {
@@ -42,7 +45,7 @@ export interface ApprovalConversationResult {
 export interface ApprovalConversationContext {
   toolName: string;
   allowedActions: string[];
-  role: 'requester' | 'guardian';
+  role: "requester" | "guardian";
   pendingApprovals: Array<{ requestId: string; toolName: string }>;
   userMessage: string;
 }
@@ -70,10 +73,10 @@ export type GuardianActionCopyGenerator = (
 
 /** The disposition returned by the guardian follow-up conversation engine. */
 export type GuardianFollowUpDisposition =
-  | 'call_back'
-  | 'message_back'
-  | 'decline'
-  | 'keep_pending';
+  | "call_back"
+  | "message_back"
+  | "decline"
+  | "keep_pending";
 
 /** Structured result from a single turn of the guardian follow-up conversation. */
 export interface GuardianFollowUpTurnResult {
@@ -180,6 +183,8 @@ export interface RuntimeHttpServerOptions {
   guardianFollowUpConversationGenerator?: GuardianFollowUpConversationGenerator;
   /** Dependencies for the POST /v1/messages queue-if-busy handler. */
   sendMessageDeps?: SendMessageDeps;
+  /** Lookup an active session by ID (for surface actions). Returns undefined if not found. */
+  findSession?: (sessionId: string) => Session | undefined;
 }
 
 export interface RuntimeAttachmentMetadata {
@@ -196,6 +201,11 @@ export interface RuntimeMessagePayload {
   content: string;
   timestamp: string;
   attachments: RuntimeAttachmentMetadata[];
-  toolCalls?: Array<{ name: string; input: Record<string, unknown>; result?: string; isError?: boolean }>;
+  toolCalls?: Array<{
+    name: string;
+    input: Record<string, unknown>;
+    result?: string;
+    isError?: boolean;
+  }>;
   interfaces?: string[];
 }

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

@@ -1,7 +1,7 @@
 import { API_KEY_PROVIDERS, getConfig, invalidateConfigCache } from '../../config/loader.js';
 import { initializeProviders } from '../../providers/registry.js';
-import { setSecureKey } from '../../security/secure-keys.js';
-import { assertMetadataWritable, upsertCredentialMetadata } from '../../tools/credentials/metadata-store.js';
+import { deleteSecureKey, setSecureKey } from '../../security/secure-keys.js';
+import { assertMetadataWritable, deleteCredentialMetadata, upsertCredentialMetadata } from '../../tools/credentials/metadata-store.js';
 import { getLogger } from '../../util/logger.js';
 import { httpError } from '../http-errors.js';
 
@@ -66,3 +66,58 @@ export async function handleAddSecret(req: Request): Promise<Response> {
     return httpError('INTERNAL_ERROR', message, 500);
   }
 }
+
+export async function handleDeleteSecret(req: Request): Promise<Response> {
+  const body = await req.json() as {
+    type?: string;
+    name?: string;
+  };
+
+  const { type, name } = body;
+
+  if (!type || typeof type !== 'string') {
+    return httpError('BAD_REQUEST', 'type is required', 400);
+  }
+  if (!name || typeof name !== 'string') {
+    return httpError('BAD_REQUEST', 'name is required', 400);
+  }
+
+  try {
+    if (type === 'api_key') {
+      if (!API_KEY_PROVIDERS.includes(name as typeof API_KEY_PROVIDERS[number])) {
+        return httpError('BAD_REQUEST', `Unknown API key provider: ${name}. Valid providers: ${API_KEY_PROVIDERS.join(', ')}`, 400);
+      }
+      const deleted = deleteSecureKey(name);
+      if (!deleted) {
+        return httpError('NOT_FOUND', `API key not found: ${name}`, 404);
+      }
+      invalidateConfigCache();
+      initializeProviders(getConfig());
+      log.info({ provider: name }, 'API key deleted via HTTP');
+      return Response.json({ success: true, type, name });
+    }
+
+    if (type === 'credential') {
+      const colonIdx = name.indexOf(':');
+      if (colonIdx < 1 || colonIdx === name.length - 1) {
+        return httpError('BAD_REQUEST', 'For credential type, name must be in "service:field" format (e.g. "github:api_token")', 400);
+      }
+      const service = name.slice(0, colonIdx);
+      const field = name.slice(colonIdx + 1);
+      const key = `credential:${service}:${field}`;
+      const deleted = deleteSecureKey(key);
+      if (!deleted) {
+        return httpError('NOT_FOUND', `Credential not found: ${name}`, 404);
+      }
+      deleteCredentialMetadata(service, field);
+      log.info({ service, field }, 'Credential deleted via HTTP');
+      return Response.json({ success: true, type, name });
+    }
+
+    return httpError('BAD_REQUEST', `Unknown secret type: ${type}. Valid types: api_key, credential`, 400);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, type, name }, 'Failed to delete secret via HTTP');
+    return httpError('INTERNAL_ERROR', message, 500);
+  }
+}

package/src/runtime/routes/surface-action-routes.ts

@@ -0,0 +1,66 @@
+/**
+ * Route handler for surface action operations.
+ *
+ * POST /v1/surface-actions — dispatch a surface action to an active session.
+ * Requires the session to already exist (does not create new sessions).
+ */
+import type { Session } from "../../daemon/session.js";
+import { getLogger } from "../../util/logger.js";
+import { httpError } from "../http-errors.js";
+
+const log = getLogger("surface-action-routes");
+
+export type SessionLookup = (sessionId: string) => Session | undefined;
+
+/**
+ * POST /v1/surface-actions — handle a UI surface action.
+ *
+ * Body: { sessionId, surfaceId, actionId, data? }
+ */
+export async function handleSurfaceAction(
+  req: Request,
+  findSession: SessionLookup,
+): Promise<Response> {
+  const body = (await req.json()) as {
+    sessionId?: string;
+    surfaceId?: string;
+    actionId?: string;
+    data?: Record<string, unknown>;
+  };
+
+  const { sessionId, surfaceId, actionId, data } = body;
+
+  if (!sessionId || typeof sessionId !== "string") {
+    return httpError("BAD_REQUEST", "sessionId is required", 400);
+  }
+  if (!surfaceId || typeof surfaceId !== "string") {
+    return httpError("BAD_REQUEST", "surfaceId is required", 400);
+  }
+  if (!actionId || typeof actionId !== "string") {
+    return httpError("BAD_REQUEST", "actionId is required", 400);
+  }
+
+  const session = findSession(sessionId);
+  if (!session) {
+    return httpError(
+      "NOT_FOUND",
+      "No active session found for this sessionId",
+      404,
+    );
+  }
+
+  try {
+    session.handleSurfaceAction(surfaceId, actionId, data);
+    log.info(
+      { sessionId, surfaceId, actionId },
+      "Surface action handled via HTTP",
+    );
+    return Response.json({ ok: true });
+  } catch (err) {
+    log.error(
+      { err, sessionId, surfaceId, actionId },
+      "Failed to handle surface action via HTTP",
+    );
+    return httpError("INTERNAL_ERROR", "Failed to handle surface action", 500);
+  }
+}

package/src/runtime/routes/trust-rules-routes.ts

@@ -0,0 +1,140 @@
+/**
+ * Route handlers for trust rule CRUD operations.
+ *
+ * These endpoints manage persistent trust rules independently of
+ * the approval-flow trust-rule endpoint in approval-routes.ts.
+ * All endpoints are bearer-token authenticated (standard runtime auth).
+ */
+import {
+  addRule,
+  getAllRules,
+  removeRule,
+  updateRule,
+} from "../../permissions/trust-store.js";
+import { getLogger } from "../../util/logger.js";
+import { httpError } from "../http-errors.js";
+
+const log = getLogger("trust-rules-routes");
+
+/**
+ * GET /v1/trust-rules/manage — list all trust rules.
+ */
+export function handleListTrustRules(): Response {
+  const rules = getAllRules();
+  return Response.json({ type: "trust_rules_list_response", rules });
+}
+
+/**
+ * POST /v1/trust-rules/manage — add a trust rule (standalone, not approval-flow).
+ *
+ * Body: { toolName, pattern, scope, decision, allowHighRisk?, executionTarget? }
+ */
+export async function handleAddTrustRuleManage(
+  req: Request,
+): Promise<Response> {
+  const body = (await req.json()) as {
+    toolName?: string;
+    pattern?: string;
+    scope?: string;
+    decision?: string;
+    allowHighRisk?: boolean;
+    executionTarget?: string;
+  };
+
+  const { toolName, pattern, scope, decision, allowHighRisk, executionTarget } =
+    body;
+
+  if (!toolName || typeof toolName !== "string") {
+    return httpError("BAD_REQUEST", "toolName is required", 400);
+  }
+  if (!pattern || typeof pattern !== "string") {
+    return httpError("BAD_REQUEST", "pattern is required", 400);
+  }
+  if (!scope || typeof scope !== "string") {
+    return httpError("BAD_REQUEST", "scope is required", 400);
+  }
+  const validDecisions = ["allow", "deny", "ask"] as const;
+  if (
+    !decision ||
+    !validDecisions.includes(decision as (typeof validDecisions)[number])
+  ) {
+    return httpError(
+      "BAD_REQUEST",
+      "decision must be one of: allow, deny, ask",
+      400,
+    );
+  }
+
+  try {
+    const hasMetadata = allowHighRisk != null || executionTarget != null;
+    addRule(
+      toolName,
+      pattern,
+      scope,
+      decision as "allow" | "deny" | "ask",
+      undefined,
+      hasMetadata ? { allowHighRisk, executionTarget } : undefined,
+    );
+    log.info(
+      { toolName, pattern, scope, decision },
+      "Trust rule added via HTTP",
+    );
+    return Response.json({ ok: true });
+  } catch (err) {
+    log.error(
+      { err, toolName, pattern, scope },
+      "Failed to add trust rule via HTTP",
+    );
+    return httpError("INTERNAL_ERROR", "Failed to add trust rule", 500);
+  }
+}
+
+/**
+ * DELETE /v1/trust-rules/manage/:id — remove a trust rule by ID.
+ */
+export function handleRemoveTrustRuleManage(id: string): Response {
+  try {
+    const removed = removeRule(id);
+    if (!removed) {
+      return httpError("NOT_FOUND", "Trust rule not found", 404);
+    }
+    log.info({ id }, "Trust rule removed via HTTP");
+    return Response.json({ ok: true });
+  } catch (err) {
+    log.error({ err, id }, "Failed to remove trust rule via HTTP");
+    return httpError("INTERNAL_ERROR", "Failed to remove trust rule", 500);
+  }
+}
+
+/**
+ * PATCH /v1/trust-rules/manage/:id — update fields on an existing trust rule.
+ *
+ * Body: { tool?, pattern?, scope?, decision?, priority? }
+ */
+export async function handleUpdateTrustRuleManage(
+  req: Request,
+  id: string,
+): Promise<Response> {
+  const body = (await req.json()) as {
+    tool?: string;
+    pattern?: string;
+    scope?: string;
+    decision?: string;
+    priority?: number;
+  };
+
+  try {
+    updateRule(id, {
+      tool: body.tool,
+      pattern: body.pattern,
+      scope: body.scope,
+      decision: body.decision as "allow" | "deny" | "ask" | undefined,
+      priority: body.priority,
+    });
+    log.info({ id }, "Trust rule updated via HTTP");
+    return Response.json({ ok: true });
+  } catch (err) {
+    log.error({ err, id }, "Failed to update trust rule via HTTP");
+    return httpError("INTERNAL_ERROR", "Failed to update trust rule", 500);
+  }
+}

package/src/security/keychain-to-encrypted-migration.ts

@@ -0,0 +1,59 @@
+/**
+ * One-time migration: copies existing macOS keychain items into the
+ * encrypted file store so the daemon can stop using the keychain CLI.
+ * Runs once on first startup after the change, then skips via a marker key.
+ */
+
+import { API_KEY_PROVIDERS } from "../config/loader.js";
+import { getLogger } from "../util/logger.js";
+import { isMacOS } from "../util/platform.js";
+import * as encryptedStore from "./encrypted-store.js";
+import * as keychain from "./keychain.js";
+
+const log = getLogger("keychain-migration");
+const MIGRATION_MARKER = "keychain-to-encrypted-migrated";
+
+/** Known credential keys that the daemon may have stored in the keychain. */
+const CREDENTIAL_KEYS = [
+  "credential:twilio:account_sid",
+  "credential:twilio:auth_token",
+  "credential:twilio:phone_number",
+  "credential:twilio:user_phone_number",
+  "credential:telegram:bot_token",
+  "credential:telegram:webhook_secret",
+  "credential:elevenlabs:api_key",
+  "credential:integration:gmail:access_token",
+  "credential:integration:gmail:refresh_token",
+  "credential:integration:twitter:access_token",
+  "credential:integration:twitter:refresh_token",
+  "credential:integration:slack:access_token",
+  "credential:integration:slack:refresh_token",
+];
+
+export function migrateKeychainToEncrypted(): void {
+  if (!isMacOS()) return;
+  if (encryptedStore.getKey(MIGRATION_MARKER) === "true") return;
+
+  let migrated = 0;
+  const allKeys = [...API_KEY_PROVIDERS, ...CREDENTIAL_KEYS];
+
+  for (const account of allKeys) {
+    try {
+      const value = keychain.getKey(account);
+      if (value != null && !encryptedStore.getKey(account)) {
+        encryptedStore.setKey(account, value);
+        migrated++;
+      }
+    } catch {
+      // Keychain unavailable or locked -- skip silently
+    }
+  }
+
+  encryptedStore.setKey(MIGRATION_MARKER, "true");
+  if (migrated > 0) {
+    log.info(
+      { count: migrated },
+      "Migrated keys from keychain to encrypted store",
+    );
+  }
+}

package/src/security/secure-keys.ts

@@ -7,6 +7,7 @@
  */
 
 import { getLogger } from '../util/logger.js';
+import { isMacOS } from '../util/platform.js';
 import * as encryptedStore from './encrypted-store.js';
 import * as keychain from './keychain.js';
 
@@ -20,6 +21,14 @@ let downgradedFromKeychain = false;
 function getBackend(): Backend {
   if (resolvedBackend !== undefined) return resolvedBackend;
 
+  // On macOS, skip keychain probing and use encrypted file storage directly
+  // to avoid repeated Keychain Access authorization prompts.
+  if (isMacOS()) {
+    log.debug('macOS detected, using encrypted file storage (skipping keychain)');
+    resolvedBackend = 'encrypted';
+    return resolvedBackend;
+  }
+
   if (keychain.isKeychainAvailable()) {
     log.debug('Using OS keychain for secure key storage');
     resolvedBackend = 'keychain';
@@ -33,6 +42,14 @@ function getBackend(): Backend {
 async function getBackendAsync(): Promise<Backend> {
   if (resolvedBackend !== undefined) return resolvedBackend;
 
+  // On macOS, skip keychain probing and use encrypted file storage directly
+  // to avoid repeated Keychain Access authorization prompts.
+  if (isMacOS()) {
+    log.debug('macOS detected, using encrypted file storage (skipping keychain)');
+    resolvedBackend = 'encrypted';
+    return resolvedBackend;
+  }
+
   if (await keychain.isKeychainAvailableAsync()) {
     log.debug('Using OS keychain for secure key storage');
     resolvedBackend = 'keychain';

package/src/skills/frontmatter.ts

@@ -2,8 +2,8 @@
  * Shared frontmatter parsing for SKILL.md files.
  *
  * Frontmatter is a YAML-like block delimited by `---` at the top of a file.
- * This module provides a single implementation used by the skill catalog loader,
- * the Vellum catalog installer, and the CC command registry.
+ * This module provides a single implementation used by the skill catalog loader
+ * and the CC command registry.
  */
 
 /** Matches a `---` delimited frontmatter block at the start of a file. */
@@ -25,7 +25,9 @@ export interface FrontmatterParseResult {
  *
  * Returns `null` if no frontmatter block is found.
  */
-export function parseFrontmatterFields(content: string): FrontmatterParseResult | null {
+export function parseFrontmatterFields(
+  content: string,
+): FrontmatterParseResult | null {
   const match = content.match(FRONTMATTER_REGEX);
   if (!match) return null;
 
@@ -34,8 +36,8 @@ export function parseFrontmatterFields(content: string): FrontmatterParseResult
 
   for (const line of frontmatter.split(/\r?\n/)) {
     const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const separatorIndex = trimmed.indexOf(':');
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const separatorIndex = trimmed.indexOf(":");
     if (separatorIndex === -1) continue;
 
     const key = trimmed.slice(0, separatorIndex).trim();
@@ -50,8 +52,8 @@ export function parseFrontmatterFields(content: string): FrontmatterParseResult
         // Only for double-quoted values — single-quoted YAML treats backslashes literally.
         // Single-pass to avoid misinterpreting \\n (escaped backslash + n) as a newline.
         value = value.replace(/\\(["\\nr])/g, (_, ch) => {
-          if (ch === 'n') return '\n';
-          if (ch === 'r') return '\r';
+          if (ch === "n") return "\n";
+          if (ch === "r") return "\r";
           return ch; // handles \\ → \ and \" → "
         });
       }

package/src/tools/apps/executors.ts

@@ -125,7 +125,8 @@ export async function executeAppCreate(
 
   // Auto-open the app via the shared open-proxy helper
   if (autoOpen && proxyToolResolver) {
-    const extraInput = preview ? { preview } : undefined;
+    const createPreview = { ...(preview ?? {}), context: 'app_create' as const };
+    const extraInput = { preview: createPreview };
     const openResultText = await openAppViaSurface(app.id, proxyToolResolver, extraInput);
 
     // Determine whether the open succeeded by checking for the fallback text

package/src/tools/tool-manifest.ts

@@ -6,17 +6,20 @@
  * so adding/removing tools only requires editing this manifest.
  */
 
-import { accountManageTool } from './credentials/account-registry.js';
-import { credentialStoreTool } from './credentials/vault.js';
-import { memorySaveTool, memorySearchTool, memoryUpdateTool } from './memory/register.js';
-import type { LazyToolDescriptor } from './registry.js';
-import { vellumSkillsCatalogTool } from './skills/vellum-catalog.js';
-import { setAvatarTool } from './system/avatar-generator.js';
-import { navigateSettingsTabTool } from './system/navigate-settings.js';
-import { openSystemSettingsTool } from './system/open-system-settings.js';
-import { voiceConfigUpdateTool } from './system/voice-config.js';
-import type { Tool } from './types.js';
-import { screenWatchTool } from './watch/screen-watch.js';
+import { accountManageTool } from "./credentials/account-registry.js";
+import { credentialStoreTool } from "./credentials/vault.js";
+import {
+  memorySaveTool,
+  memorySearchTool,
+  memoryUpdateTool,
+} from "./memory/register.js";
+import type { LazyToolDescriptor } from "./registry.js";
+import { setAvatarTool } from "./system/avatar-generator.js";
+import { navigateSettingsTabTool } from "./system/navigate-settings.js";
+import { openSystemSettingsTool } from "./system/open-system-settings.js";
+import { voiceConfigUpdateTool } from "./system/voice-config.js";
+import type { Tool } from "./types.js";
+import { screenWatchTool } from "./watch/screen-watch.js";
 
 // ── Eager side-effect modules ───────────────────────────────────────
 // These static imports trigger top-level `registerTool()` side effects.
@@ -27,21 +30,21 @@ import { screenWatchTool } from './watch/screen-watch.js';
 // filesystem root rather than the module's own directory, causing
 // "Cannot find module './filesystem/read.js'" crashes in production builds.
 // Static imports are resolved at bundle time and are always safe.
-import './assets/materialize.js';
-import './assets/search.js';
-import './filesystem/edit.js';
-import './filesystem/read.js';
-import './filesystem/view-image.js';
-import './filesystem/write.js';
-import './network/web-fetch.js';
-import './network/web-search.js';
-import './skills/delete-managed.js';
-import './skills/load.js';
-import './skills/scaffold-managed.js';
-import './swarm/delegate.js';
-import './system/request-permission.js';
-import './system/version.js';
-import './terminal/shell.js';
+import "./assets/materialize.js";
+import "./assets/search.js";
+import "./filesystem/edit.js";
+import "./filesystem/read.js";
+import "./filesystem/view-image.js";
+import "./filesystem/write.js";
+import "./network/web-fetch.js";
+import "./network/web-search.js";
+import "./skills/delete-managed.js";
+import "./skills/load.js";
+import "./skills/scaffold-managed.js";
+import "./swarm/delegate.js";
+import "./system/request-permission.js";
+import "./system/version.js";
+import "./terminal/shell.js";
 
 // loadEagerModules is a no-op now that all eager registrations happen via
 // static imports above. Kept for API compatibility with registry.ts callers.
@@ -54,21 +57,21 @@ export function loadEagerModules(): Promise<void> {
 // already in the registry before init ran (e.g. when a test file imports
 // an eager module at the top level).
 export const eagerModuleToolNames: string[] = [
-  'bash',
-  'file_read',
-  'file_write',
-  'file_edit',
-  'web_search',
-  'web_fetch',
-  'skill_load',
-  'scaffold_managed_skill',
-  'delete_managed_skill',
-  'request_system_permission',
-  'asset_search',
-  'asset_materialize',
-  'swarm_delegate',
-  'view_image',
-  'version',
+  "bash",
+  "file_read",
+  "file_write",
+  "file_edit",
+  "web_search",
+  "web_fetch",
+  "skill_load",
+  "scaffold_managed_skill",
+  "delete_managed_skill",
+  "request_system_permission",
+  "asset_search",
+  "asset_materialize",
+  "swarm_delegate",
+  "view_image",
+  "version",
 ];
 
 // ── Explicit tool instances ─────────────────────────────────────────
@@ -82,7 +85,6 @@ export const explicitTools: Tool[] = [
   credentialStoreTool,
   accountManageTool,
   screenWatchTool,
-  vellumSkillsCatalogTool,
   voiceConfigUpdateTool,
   setAvatarTool,
   openSystemSettingsTool,

package/src/tools/types.ts

@@ -143,6 +143,8 @@ export interface ToolContext {
   executionChannel?: string;
   /** Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption. */
   callSessionId?: string;
+  /** True when the tool invocation was triggered by a user clicking a surface action button (not a regular message). */
+  triggeredBySurfaceAction?: boolean;
   /** External user ID of the requester (non-guardian actor). Used for scoped grant consumption. */
   requesterExternalUserId?: string;
   /** Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications. */
@@ -172,6 +174,13 @@ export interface ToolExecutionResult {
    * replacement. MUST NOT be emitted in client-facing events or logs.
    */
   sensitiveBindings?: SensitiveOutputBinding[];
+  /**
+   * When true, the agent loop should yield control back to the user after
+   * returning this result. Used by interactive surfaces (tables with action
+   * buttons, file uploads) to force-stop the loop so the LLM cannot bypass
+   * the "wait for user action" instruction.
+   */
+  yieldToUser?: boolean;
 }
 
 export interface Tool {