@vellumai/assistant 0.4.26 → 0.4.29

package/src/tools/types.ts

@@ -1,9 +1,15 @@
-import type { SecretPromptResult } from '../permissions/secret-prompter.js';
-import type { AllowlistOption, RiskLevel, ScopeOption } from '../permissions/types.js';
-import type { ContentBlock,ToolDefinition } from '../providers/types.js';
-import type { SensitiveOutputBinding } from './sensitive-output-placeholders.js';
-
-export type ExecutionTarget = 'sandbox' | 'host';
+import type { ProxyApprovalCallback } from "../outbound-proxy/index.js";
+import type { SecretPromptResult } from "../permissions/secret-prompter.js";
+import type {
+  AllowlistOption,
+  RiskLevel,
+  ScopeOption,
+} from "../permissions/types.js";
+import type { ContentBlock, ToolDefinition } from "../providers/types.js";
+import type { TrustClass } from "../runtime/actor-trust-resolver.js";
+import type { SensitiveOutputBinding } from "./sensitive-output-placeholders.js";
+
+export type ExecutionTarget = "sandbox" | "host";
 
 interface ToolLifecycleEventBase {
   toolName: string;
@@ -16,12 +22,12 @@ interface ToolLifecycleEventBase {
 }
 
 export interface ToolExecutionStartEvent extends ToolLifecycleEventBase {
-  type: 'start';
+  type: "start";
   startedAtMs: number;
 }
 
 export interface ToolPermissionPromptEvent extends ToolLifecycleEventBase {
-  type: 'permission_prompt';
+  type: "permission_prompt";
   riskLevel: string;
   reason: string;
   allowlistOptions: AllowlistOption[];
@@ -32,25 +38,29 @@ export interface ToolPermissionPromptEvent extends ToolLifecycleEventBase {
 }
 
 export interface ToolPermissionDeniedEvent extends ToolLifecycleEventBase {
-  type: 'permission_denied';
+  type: "permission_denied";
   riskLevel: string;
-  decision: 'deny' | 'always_deny';
+  decision: "deny" | "always_deny";
   reason: string;
   durationMs: number;
 }
 
 export interface ToolExecutedEvent extends ToolLifecycleEventBase {
-  type: 'executed';
+  type: "executed";
   riskLevel: string;
   decision: string;
   durationMs: number;
   result: ToolExecutionResult;
 }
 
-export type ErrorCategory = 'permission_denied' | 'auth' | 'tool_failure' | 'unexpected';
+export type ErrorCategory =
+  | "permission_denied"
+  | "auth"
+  | "tool_failure"
+  | "unexpected";
 
 export interface ToolExecutionErrorEvent extends ToolLifecycleEventBase {
-  type: 'error';
+  type: "error";
   riskLevel: string;
   decision: string;
   durationMs: number;
@@ -63,9 +73,9 @@ export interface ToolExecutionErrorEvent extends ToolLifecycleEventBase {
 }
 
 export interface ToolSecretDetectedEvent extends ToolLifecycleEventBase {
-  type: 'secret_detected';
+  type: "secret_detected";
   matches: Array<{ type: string; redactedValue: string }>;
-  action: 'redact' | 'warn' | 'block' | 'prompt';
+  action: "redact" | "warn" | "block" | "prompt";
   detectedAtMs: number;
 }
 
@@ -77,7 +87,9 @@ export type ToolLifecycleEvent =
   | ToolExecutionErrorEvent
   | ToolSecretDetectedEvent;
 
-export type ToolLifecycleEventHandler = (event: ToolLifecycleEvent) => void | Promise<void>;
+export type ToolLifecycleEventHandler = (
+  event: ToolLifecycleEvent,
+) => void | Promise<void>;
 
 export type ProxyToolResolver = (
   toolName: string,
@@ -113,7 +125,7 @@ export interface ToolContext {
     riskLevel: string;
     executionTarget?: ExecutionTarget;
     principal?: string;
-  }) => Promise<{ decision: 'allow' | 'deny' }>;
+  }) => Promise<{ decision: "allow" | "deny" }>;
   /** Prompt the user for a secret value via native SecureField UI. */
   requestSecret?: (params: {
     service: string;
@@ -134,11 +146,16 @@ export interface ToolContext {
   /** When true, tools with private side-effects should always prompt for confirmation. */
   forcePromptSideEffects?: boolean;
   /** Approval callback for proxy policy decisions that require user confirmation. */
-  proxyApprovalCallback?: import('./network/script-proxy/types.js').ProxyApprovalCallback;
+  proxyApprovalCallback?: ProxyApprovalCallback;
   /** Optional principal identifier propagated to sub-tool confirmation flows. */
   principal?: string;
-  /** Inbound trust classification for the session — used by trust/policy gates. */
-  guardianTrustClass: 'guardian' | 'trusted_contact' | 'unknown';
+  /**
+   * Trust classification of the actor who initiated this tool invocation.
+   * Determines permission level: guardians self-approve, trusted contacts
+   * may escalate to guardian for approval, unknown actors are fail-closed.
+   * See {@link TrustClass} in actor-trust-resolver.ts for value semantics.
+   */
+  trustClass: TrustClass;
   /** Channel through which the tool invocation originates (e.g. 'telegram', 'voice'). Used for scoped grant consumption. */
   executionChannel?: string;
   /** Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption. */
@@ -189,9 +206,9 @@ export interface Tool {
   category: string;
   defaultRiskLevel: RiskLevel;
   /** When set to 'proxy', the tool is forwarded to a connected client rather than executed locally. */
-  executionMode?: 'local' | 'proxy';
+  executionMode?: "local" | "proxy";
   /** Whether this tool is a core built-in, provided by a skill, or from an MCP server. */
-  origin?: 'core' | 'skill' | 'mcp';
+  origin?: "core" | "skill" | "mcp";
   /** If origin is 'skill', the ID of the owning skill. */
   ownerSkillId?: string;
   /** If origin is 'mcp', the ID of the owning MCP server. */
@@ -204,5 +221,8 @@ export interface Tool {
    * to accurately label lifecycle events for skill-provided tools. */
   executionTarget?: ExecutionTarget;
   getDefinition(): ToolDefinition;
-  execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult>;
+  execute(
+    input: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolExecutionResult>;
 }

package/src/tools/ui-surface/definitions.ts

@@ -7,16 +7,18 @@
  * handled locally by the daemon.
  */
 
-import { RiskLevel } from '../../permissions/types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import type { Tool, ToolExecutionResult } from '../types.js';
+import { RiskLevel } from "../../permissions/types.js";
+import type { ToolDefinition } from "../../providers/types.js";
+import type { Tool, ToolExecutionResult } from "../types.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 function proxyExecute(): Promise<ToolExecutionResult> {
-  throw new Error('Proxy tool: execution must be forwarded to the connected client');
+  throw new Error(
+    "Proxy tool: execution must be forwarded to the connected client",
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -24,98 +26,114 @@ function proxyExecute(): Promise<ToolExecutionResult> {
 // ---------------------------------------------------------------------------
 
 export const uiShowTool: Tool = {
-  name: 'ui_show',
+  name: "ui_show",
   description:
     'Show structured data or UI to the user. Use for displaying weather, flights, stock prices, quick tables, cards, lists, forms, or any temporary data visualization. Use display: "inline" (default) to embed in chat, or "panel" for a floating window. For long-form writing use the document skill instead; for interactive apps use the app-builder skill instead.\n\n' +
-    'Supported surface types:\n' +
-    '- card: Informational card with title, subtitle, body text, and optional metadata key-value pairs. ' +
-    'Cards support an optional template field for specialized native rendering. ' +
-    'data shape: { title: string, subtitle?: string, body: string, metadata?: Array<{ label: string, value: string }>, template?: string, templateData?: object }\n' +
+    "Supported surface types:\n" +
+    "- card: Informational card with title, subtitle, body text, and optional metadata key-value pairs. " +
+    "Cards support an optional template field for specialized native rendering. " +
+    "data shape: { title: string, subtitle?: string, body: string, metadata?: Array<{ label: string, value: string }>, template?: string, templateData?: object }\n" +
     '  Template "weather_forecast": renders an Apple Weather-style forecast widget. ' +
     'templateData shape: { location: string, currentTemp: number, feelsLike: number, unit: "F"|"C", condition: string, humidity: number, windSpeed: number, windDirection: string, ' +
-    'hourly: Array<{ time: string, icon: string (SF Symbol name), temp: number }>, ' +
-    'forecast: Array<{ day: string, icon: string (SF Symbol name), low: number, high: number, precip: number|null, condition: string }> }\n' +
+    "hourly: Array<{ time: string, icon: string (SF Symbol name), temp: number }>, " +
+    "forecast: Array<{ day: string, icon: string (SF Symbol name), low: number, high: number, precip: number|null, condition: string }> }\n" +
     '  Template "task_progress": renders a live-updating task progress widget showing structured step-by-step progress. ' +
     'templateData shape: { title: string, status: "in_progress"|"completed"|"failed", ' +
     'steps: Array<{ label: string, status: "pending"|"in_progress"|"completed"|"failed", detail?: string }> }\n' +
-    '- table: Data table with columns, selectable rows, and action buttons. ' +
+    "- table: Data table with columns, selectable rows, and action buttons. " +
     'data shape: { columns: Array<{ id: string, label: string, width?: number }>, rows: Array<{ id: string, cells: Record<string, string | { text: string, icon?: string, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?: boolean, selected?: boolean }>, selectionMode?: "none"|"single"|"multiple", caption?: string }. ' +
-    'Cell values can be plain strings or rich objects with icon (SF Symbol name) and iconColor. ' +
-    'Column width is in points — use it for narrow columns (e.g. counts, short labels) so flexible columns get more space. Omit width for columns that should expand.\n' +
-    '- form: Input form with typed fields. ' +
+    "Cell values can be plain strings or rich objects with icon (SF Symbol name) and iconColor. " +
+    "Column width is in points — use it for narrow columns (e.g. counts, short labels) so flexible columns get more space. Omit width for columns that should expand.\n" +
+    "- form: Input form with typed fields. " +
     'data shape: { description?: string, fields: Array<{ id: string, type: "text"|"textarea"|"select"|"toggle"|"number"|"password", label: string, placeholder?: string, required?: boolean, defaultValue?: string|number|boolean, options?: Array<{ label: string, value: string }> }>, submitLabel?: string }. ' +
-    'For multi-page forms, use pages array instead of top-level fields: { pages: [{ id: string, title: string, description?: string, fields: [...] }], pageLabels?: { next?: string, back?: string, submit?: string }, submitLabel?: string }\n' +
-    '- list: Selectable list of items. ' +
+    "For multi-page forms, use pages array instead of top-level fields: { pages: [{ id: string, title: string, description?: string, fields: [...] }], pageLabels?: { next?: string, back?: string, submit?: string }, submitLabel?: string }\n" +
+    "- list: Selectable list of items. " +
     'data shape: { items: Array<{ id: string, title: string, subtitle?: string, icon?: string, selected?: boolean }>, selectionMode: "single"|"multiple"|"none" }\n' +
-    '- confirmation: Yes/no confirmation dialog. ' +
-    'data shape: { message: string, detail?: string, confirmLabel?: string, confirmedLabel?: string, cancelLabel?: string, destructive?: boolean }\n' +
-    '- dynamic_page: Custom HTML page rendered in a sandboxed container. ' +
-    'data shape: { html: string, width?: number, height?: number, preview?: { title: string, subtitle?: string, description?: string, icon?: string (emoji), metrics?: Array<{ label: string, value: string }> } }. ' +
+    "- confirmation: Yes/no confirmation dialog. " +
+    "data shape: { message: string, detail?: string, confirmLabel?: string, confirmedLabel?: string, cancelLabel?: string, destructive?: boolean }\n" +
+    "- dynamic_page: Custom HTML page rendered in a sandboxed container. " +
+    "data shape: { html: string, width?: number, height?: number, preview?: { title: string, subtitle?: string, description?: string, icon?: string (emoji), metrics?: Array<{ label: string, value: string }> } }. " +
     'When preview is provided, a compact preview card is shown inline in chat with the title, subtitle, description, metric pills, and a "View Output" button that opens the full page.\n' +
-    '- file_upload: File upload dialog where the user can drag-and-drop or browse for files. ' +
-    'data shape: { prompt: string, acceptedTypes?: string[], maxFiles?: number }\n\n' +
-    'Action payload conventions:\n' +
-    '- Multi-select tables: use `window.vellum.sendAction(actionId, { selectedIds: [...] })` to send selected row IDs\n' +
-    '- Bulk actions: include `selectedRows` array with full row data for context\n\n' +
-    'Presenting choices: When the user needs to make a choice or provide structured input, prefer interactive surfaces over plain text. ' +
-    'Use list (2-8 options, single select), form (structured input with typed fields), confirmation (destructive/important actions), or table (data review with selectable rows).\n\n' +
-    'Tool chaining: After gathering data via tools (web search, browser, APIs), synthesize results into a visual output. ' +
-    'Exception: get_weather automatically renders its own surface with live API data — do NOT call ui_show, ui_update, app_create, or web_search after get_weather. Just respond with a brief summary.\n\n' +
+    "- file_upload: File upload dialog where the user can drag-and-drop or browse for files. " +
+    "data shape: { prompt: string, acceptedTypes?: string[], maxFiles?: number }\n\n" +
+    "Action payload conventions:\n" +
+    "- Multi-select tables: use `window.vellum.sendAction(actionId, { selectedIds: [...] })` to send selected row IDs\n" +
+    "- Bulk actions: include `selectedRows` array with full row data for context\n\n" +
+    "Presenting choices: When the user needs to make a choice or provide structured input, prefer interactive surfaces over plain text. " +
+    "Use list (2-8 options, single select), form (structured input with typed fields), confirmation (destructive/important actions), or table (data review with selectable rows).\n\n" +
+    "Tool chaining: After gathering data via tools (web search, browser, APIs), synthesize results into a visual output. " +
+    "Exception: get_weather automatically renders its own surface with live API data — do NOT call ui_show, ui_update, app_create, or web_search after get_weather. Just respond with a brief summary.\n\n" +
     'Task progress for multi-step workflows: Create a card with template "task_progress" and templateData containing steps. ' +
-    'As each step completes, call ui_update to patch data.templateData (not top-level fields). ' +
+    "As each step completes, call ui_update to patch data.templateData (not top-level fields). " +
     'Set templateData.status to "completed" or "failed" when done.',
-  category: 'ui-surface',
+  category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
-  executionMode: 'proxy',
+  executionMode: "proxy",
 
   getDefinition(): ToolDefinition {
     return {
       name: this.name,
       description: this.description,
       input_schema: {
-        type: 'object',
+        type: "object",
         properties: {
           surface_type: {
-            type: 'string',
-            enum: ['card', 'form', 'list', 'table', 'confirmation', 'dynamic_page', 'file_upload'],
-            description: 'The type of surface to display',
+            type: "string",
+            enum: [
+              "card",
+              "form",
+              "list",
+              "table",
+              "confirmation",
+              "dynamic_page",
+              "file_upload",
+            ],
+            description: "The type of surface to display",
           },
           title: {
-            type: 'string',
-            description: 'Optional title for the surface window',
+            type: "string",
+            description: "Optional title for the surface window",
           },
           data: {
-            type: 'object',
-            description: 'Surface data; structure depends on surface_type (see tool description)',
+            type: "object",
+            description:
+              "Surface data; structure depends on surface_type (see tool description)",
           },
           actions: {
-            type: 'array',
+            type: "array",
             items: {
-              type: 'object',
+              type: "object",
               properties: {
-                id: { type: 'string', description: 'Unique action identifier' },
-                label: { type: 'string', description: 'Button label text' },
+                id: { type: "string", description: "Unique action identifier" },
+                label: { type: "string", description: "Button label text" },
                 style: {
-                  type: 'string',
-                  enum: ['primary', 'secondary', 'destructive'],
-                  description: 'Visual style of the button',
+                  type: "string",
+                  enum: ["primary", "secondary", "destructive"],
+                  description: "Visual style of the button",
                 },
               },
-              required: ['id', 'label'],
+              required: ["id", "label"],
             },
-            description: 'Optional action buttons to display on the surface',
+            description: "Optional action buttons to display on the surface",
           },
           display: {
-            type: 'string',
-            enum: ['inline', 'panel'],
-            description: 'Where to render the surface. "inline" embeds it in the chat message. "panel" shows a floating window. Defaults to "inline".',
+            type: "string",
+            enum: ["inline", "panel"],
+            description:
+              'Where to render the surface. "inline" embeds it in the chat message. "panel" shows a floating window. Defaults to "inline".',
           },
           await_action: {
-            type: 'boolean',
-            description: 'Whether to block until the user interacts with an action. Defaults to true when actions are provided.',
+            type: "boolean",
+            description:
+              "Whether to block until the user interacts with an action. Defaults to true when actions are provided.",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are showing and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
           },
         },
-        required: ['surface_type', 'data'],
+        required: ["surface_type", "data"],
       },
     };
   },
@@ -128,31 +146,36 @@ export const uiShowTool: Tool = {
 // ---------------------------------------------------------------------------
 
 export const uiUpdateTool: Tool = {
-  name: 'ui_update',
+  name: "ui_update",
   description:
     "Update an existing surface's data. The provided data object is merged into the surface's current data.\n" +
-    'For card templates (for example `task_progress`), update nested fields under `data.templateData` rather than sending template fields at the top level.',
-  category: 'ui-surface',
+    "For card templates (for example `task_progress`), update nested fields under `data.templateData` rather than sending template fields at the top level.",
+  category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
-  executionMode: 'proxy',
+  executionMode: "proxy",
 
   getDefinition(): ToolDefinition {
     return {
       name: this.name,
       description: this.description,
       input_schema: {
-        type: 'object',
+        type: "object",
         properties: {
           surface_id: {
-            type: 'string',
-            description: 'The ID of the surface to update',
+            type: "string",
+            description: "The ID of the surface to update",
           },
           data: {
-            type: 'object',
-            description: 'Partial data to merge into the existing surface data',
+            type: "object",
+            description: "Partial data to merge into the existing surface data",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are updating and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
           },
         },
-        required: ['surface_id', 'data'],
+        required: ["surface_id", "data"],
       },
     };
   },
@@ -165,25 +188,30 @@ export const uiUpdateTool: Tool = {
 // ---------------------------------------------------------------------------
 
 export const uiDismissTool: Tool = {
-  name: 'ui_dismiss',
-  description: 'Dismiss a currently displayed surface.',
-  category: 'ui-surface',
+  name: "ui_dismiss",
+  description: "Dismiss a currently displayed surface.",
+  category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
-  executionMode: 'proxy',
+  executionMode: "proxy",
 
   getDefinition(): ToolDefinition {
     return {
       name: this.name,
       description: this.description,
       input_schema: {
-        type: 'object',
+        type: "object",
         properties: {
           surface_id: {
-            type: 'string',
-            description: 'The ID of the surface to dismiss',
+            type: "string",
+            description: "The ID of the surface to dismiss",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are dismissing and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
           },
         },
-        required: ['surface_id'],
+        required: ["surface_id"],
       },
     };
   },
@@ -196,37 +224,44 @@ export const uiDismissTool: Tool = {
 // ---------------------------------------------------------------------------
 
 export const requestFileTool: Tool = {
-  name: 'request_file',
+  name: "request_file",
   description:
-    'Request a file or image from the user. Shows a file upload dialog where the user can drag-and-drop or browse for files. ' +
-    'Use this when you need the user to share a file (image, document, PDF, etc.) to continue the conversation. ' +
-    'The result contains the uploaded file data including base64 content and MIME type.',
-  category: 'ui-surface',
+    "Request a file or image from the user. Shows a file upload dialog where the user can drag-and-drop or browse for files. " +
+    "Use this when you need the user to share a file (image, document, PDF, etc.) to continue the conversation. " +
+    "The result contains the uploaded file data including base64 content and MIME type.",
+  category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
-  executionMode: 'proxy',
+  executionMode: "proxy",
 
   getDefinition(): ToolDefinition {
     return {
       name: this.name,
       description: this.description,
       input_schema: {
-        type: 'object',
+        type: "object",
         properties: {
           prompt: {
-            type: 'string',
-            description: 'What to ask the user for, e.g. "Please share the design file you\'d like me to review"',
+            type: "string",
+            description:
+              'What to ask the user for, e.g. "Please share the design file you\'d like me to review"',
           },
           accepted_types: {
-            type: 'array',
-            items: { type: 'string' },
-            description: 'MIME type filters, e.g. ["image/*", "application/pdf"]. If omitted, all supported file types are accepted.',
+            type: "array",
+            items: { type: "string" },
+            description:
+              'MIME type filters, e.g. ["image/*", "application/pdf"]. If omitted, all supported file types are accepted.',
           },
           max_files: {
-            type: 'number',
-            description: 'Maximum number of files to accept. Defaults to 1.',
+            type: "number",
+            description: "Maximum number of files to accept. Defaults to 1.",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are requesting and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
           },
         },
-        required: ['prompt'],
+        required: ["prompt"],
       },
     };
   },

package/src/tools/ui-surface/registry.ts

@@ -4,8 +4,8 @@
  * Called once at daemon startup via initializeTools().
  */
 
-import { registerTool } from '../registry.js';
-import { allUiSurfaceTools } from './definitions.js';
+import { registerTool } from "../registry.js";
+import { allUiSurfaceTools } from "./definitions.js";
 
 export function registerUiSurfaceTools(): void {
   for (const tool of allUiSurfaceTools) {