@vellumai/assistant 0.8.5 → 0.8.7

package/src/tools/types.ts

@@ -3,13 +3,14 @@ import type {
   DiffInfo,
   ExecutionTarget,
   ProxyApprovalCallback,
-  RiskLevel,
   SensitiveOutputBinding,
   ToolExecutionErrorEvent,
   ToolExecutionStartEvent,
   ToolPermissionDeniedEvent,
   ToolPermissionPromptEvent,
 } from "@vellumai/skill-host-contracts";
+import { RiskLevel } from "@vellumai/skill-host-contracts";
+import { z } from "zod";
 
 import type { InterfaceId } from "../channels/types.js";
 import type { CesClient } from "../credential-execution/client.js";
@@ -317,43 +318,95 @@ export interface ToolContext {
 }
 
 /**
- * Author-facing tool spec — re-exported from `@vellumai/plugin-api`.
- * Loaders fill documented defaults for omitted fields via `finalizeTool`
- * in `tool-defaults.ts`.
+ * Schema describing the shape of a {@link ToolDefinition}. All fields are
+ * optional — loaders fill documented defaults for omitted fields via
+ * `finalizeTool` in `tool-defaults.ts`. The IPC layer parses incoming
+ * skill tools against this same schema and re-finalizes them locally,
+ * so author shape and wire shape are one schema.
+ *
+ * `input_schema` is `z.custom<object>(...)` rather than
+ * `z.record(z.string(), z.unknown())` so that authors can assign a typed
+ * JSON-schema literal (`{ type: "object", properties: { ... } }`)
+ * without `as Record<...>` gymnastics. The custom check still rejects
+ * `null`, primitives, and arrays at runtime.
+ *
+ * `execute` is `z.custom<(input, context) => Promise<ToolExecutionResult>>()`
+ * for the same reason — the wire path drops closures (they can't cross
+ * IPC) and `finalizeTool` synthesizes a no-op error closure on arrival.
+ * The custom shape gives `ToolDefinition.execute` a fully-typed
+ * signature via `z.infer` without an overlay type.
+ *
+ * Result: `ToolDefinition = z.infer<typeof ToolDefinitionSchema>` —
+ * one declaration, both `input_schema` and `execute` typed correctly.
  */
-export interface ToolDefinition {
+export const ToolDefinitionSchema = z.object({
+  /**
+   * Name the model sees when calling this tool. Loaders default to the
+   * source file basename (e.g. `tools/read.ts` → `read`) when omitted,
+   * so the literal only needs to set this when overriding the
+   * file-derived name.
+   */
+  name: z.string().min(1).optional(),
   /** Human-readable description shown to the model in the tool catalog. */
-  description?: string;
-  /** Author-asserted risk band — low / medium / high. Drives default permission gating. */
-  defaultRiskLevel?: RiskLevel;
+  description: z.string().optional(),
   /** JSON schema describing the tool's input arguments. */
-  input_schema?: object;
+  input_schema: z
+    .custom<object>(
+      (val) => val !== null && typeof val === "object" && !Array.isArray(val),
+      { message: "input_schema must be a plain object" },
+    )
+    .optional(),
+  /** Author-asserted risk band — low / medium / high. Drives default permission gating. */
+  defaultRiskLevel: z.enum(RiskLevel).optional(),
+  /** Tool category used for Slack channel `allowedToolCategories` enforcement. */
+  category: z.string().min(1).optional(),
   /** Where the tool runs — sandbox (assistant container) or host (guardian device via proxy). Resolved by `resolveExecutionTarget` if omitted. */
-  executionTarget?: ExecutionTarget;
-  /** Implementation invoked when the model calls the tool. */
-  execute?: (
-    input: Record<string, unknown>,
-    context: ToolContext,
-  ) => Promise<ToolExecutionResult>;
-}
+  executionTarget: z.enum(["sandbox", "host"]).optional(),
+  /**
+   * Implementation invoked when the model calls the tool. Optional
+   * because some `ToolDefinition` instances are schema-only (e.g.
+   * {@link ../memory/graph/tools.graphRememberDefinition},
+   * {@link ../messaging/style-analyzer.storeStyleAnalysisTool},
+   * {@link ../memory/v2/sweep-job.SWEEP_TOOL}) — handed to providers as
+   * a function-calling schema without ever being registered for
+   * execution. Closures can't cross IPC, so the wire path drops this
+   * and `finalizeTool` synthesizes a no-op error closure on arrival.
+   * Tool sources use `satisfies ToolDefinition` (not `: ToolDefinition`)
+   * so the inferred export type preserves `execute` as required at
+   * call sites that statically import the literal.
+   */
+  execute: z
+    .custom<
+      (
+        input: Record<string, unknown>,
+        context: ToolContext,
+      ) => Promise<ToolExecutionResult>
+    >()
+    .optional(),
+});
+
+/**
+ * Author-facing tool spec — re-exported from `@vellumai/plugin-api`.
+ * Loaders fill documented defaults for omitted fields via `finalizeTool`
+ * in `tool-defaults.ts`. The type is a direct `z.infer` of
+ * {@link ToolDefinitionSchema} — both `input_schema` and `execute` are
+ * typed correctly by the schema itself, no overlay needed.
+ */
+export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
 
 /** Tool after the loader has derived its name and filled defaults. */
-export type LoadedTool = Required<ToolDefinition> & { name: string };
+export type Tool = Required<ToolDefinition>;
+
+/** The kind of extension that owns a tool. Core tools have no owner. */
+export type OwnerKind = "skill" | "mcp" | "plugin";
 
-export interface Tool extends LoadedTool {
-  category: string;
-  /** When set to 'proxy', the tool is forwarded to a connected client rather than executed locally. */
-  executionMode?: "local" | "proxy";
-  /** Whether this tool is a core built-in, provided by a skill, contributed by a plugin, or from an MCP server. */
-  origin?: "core" | "skill" | "mcp" | "plugin";
-  /** If origin is 'skill', the ID of the owning skill. */
-  ownerSkillId?: string;
-  /** If origin is 'mcp', the ID of the owning MCP server. */
-  ownerMcpServerId?: string;
-  /** If origin is 'plugin', the name of the owning plugin. */
-  ownerPluginId?: string;
-  /** Content-hash of the owning skill's source at registration time. */
-  ownerSkillVersionHash?: string;
-  /** Whether the owning skill is bundled with the daemon (trusted first-party). */
-  ownerSkillBundled?: boolean;
+/**
+ * Identifies which extension owns a tool (skill / plugin / MCP server).
+ * Tracked by the tool registry keyed by tool name, not stored on the `Tool`
+ * object itself — query via {@link ../tools/registry.getToolOwner}.
+ */
+export interface OwnerInfo {
+  kind: OwnerKind;
+  /** ID of the owning extension (skill id / plugin name / MCP server id). */
+  id: string;
 }

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

@@ -8,26 +8,101 @@
  */
 
 import { RiskLevel } from "../../permissions/types.js";
-import type { Tool, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-function proxyExecute(): Promise<ToolExecutionResult> {
-  throw new Error(
-    "Proxy tool: execution must be forwarded to the connected client",
-  );
+const APP_BUILDER_ARTIFACT_RE =
+  /\b(app|apps|application|applications|website|websites|site|sites|dashboard|dashboards|game|games|calculator|calculators|tracker|trackers|visualization|visualizations|visualisation|visualisations|tool|tools|utility|utilities|counter|counters)\b/i;
+const APP_BUILDER_BUILD_RE =
+  /\b(build|building|built|create|creating|created|make|making|made|generate|generating|generated)\b/i;
+
+/**
+ * Forward execution to the connected macOS client via the request-bound
+ * `proxyToolResolver`. Returns a structured error when no resolver is
+ * configured (e.g. no client connected) so callers see a normal tool
+ * failure rather than an unhandled throw.
+ */
+function proxyExecute(toolName: string) {
+  return async (
+    input: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    if (toolName === "ui_show" && isDynamicPageAppSubstitute(input)) {
+      return {
+        content:
+          'Error: ui_show dynamic_page is for transient UI surfaces only. This request is building an app-like experience, so load the app-builder skill first with `skill_load` using `skill: "app-builder"`, then create a persistent Library app with the app-builder workflow.',
+        isError: true,
+      };
+    }
+
+    if (!context.proxyToolResolver) {
+      return {
+        content: `No proxy resolver configured for proxy tool "${toolName}". This tool requires an external resolver (e.g. a connected macOS client).`,
+        isError: true,
+      };
+    }
+    return context.proxyToolResolver(toolName, input);
+  };
+}
+
+function isDynamicPageAppSubstitute(input: Record<string, unknown>): boolean {
+  if (input.surface_type !== "dynamic_page") {
+    return false;
+  }
+
+  const text = collectRoutingText(input).join(" ");
+  if (!APP_BUILDER_ARTIFACT_RE.test(text)) {
+    return false;
+  }
+
+  return APP_BUILDER_BUILD_RE.test(text) || /\b(app|application)\b/i.test(text);
+}
+
+function collectRoutingText(input: Record<string, unknown>): string[] {
+  const values: string[] = [];
+  addString(values, input.title);
+  addString(values, input.activity);
+
+  const data = asRecord(input.data);
+  if (data) {
+    const preview = asRecord(data.preview);
+    if (preview) {
+      addString(values, preview.title);
+      addString(values, preview.subtitle);
+      addString(values, preview.description);
+    }
+  }
+
+  return values;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function addString(values: string[], value: unknown): void {
+  if (typeof value === "string") {
+    values.push(value);
+  }
 }
 
 // ---------------------------------------------------------------------------
 // ui_show
 // ---------------------------------------------------------------------------
 
-export const uiShowTool: Tool = {
+export const uiShowTool = {
   name: "ui_show",
   description:
-    "Surface structured data or UI in the conversation. For long-form writing use the document skill; for interactive apps use the app-builder skill.\n\n" +
+    'Surface structured data or UI in the conversation. For long-form writing use the document skill. For interactive apps, dashboards, games, calculators, or durable tools, call `skill_load` with `skill: "app-builder"` and use the app-builder workflow; do not use `dynamic_page` as a substitute for a persistent app. App-like `dynamic_page` calls are rejected.\n\n' +
     "Surface types (data shapes):\n" +
     '- card: { title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Templates: "weather_forecast" (native weather widget), "task_progress" (live step tracker - update via ui_update on data.templateData; shape: { title, status: "in_progress"|"completed"|"failed", steps: [{ label, status: "pending"|"in_progress"|"completed"|"failed", detail? }] })\n' +
     '- table: { columns: [{ id, label }], rows: [{ id, cells: Record<id, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }\n' +
@@ -40,134 +115,131 @@ export const uiShowTool: Tool = {
     "Proactively show a task_progress card before multi-step or long-running work (web searches, file operations, research). Show it before your first tool call, then update steps as work progresses.",
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
-  executionMode: "proxy",
   executionTarget: "host",
 
   input_schema: {
+    type: "object",
+    properties: {
+      surface_type: {
+        type: "string",
+        enum: [
+          "card",
+          "form",
+          "list",
+          "table",
+          "confirmation",
+          "dynamic_page",
+          "file_upload",
+          "task_preferences",
+        ],
+        description: "The type of surface to display",
+      },
+      title: {
+        type: "string",
+        description: "Optional title for the surface window",
+      },
+      data: {
         type: "object",
-        properties: {
-          surface_type: {
-            type: "string",
-            enum: [
-              "card",
-              "form",
-              "list",
-              "table",
-              "confirmation",
-              "dynamic_page",
-              "file_upload",
-              "task_preferences",
-            ],
-            description: "The type of surface to display",
-          },
-          title: {
-            type: "string",
-            description: "Optional title for the surface window",
-          },
-          data: {
-            type: "object",
-            description:
-              "Surface data; structure depends on surface_type (see tool description)",
-          },
-          actions: {
-            type: "array",
-            items: {
-              type: "object",
-              properties: {
-                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",
-                },
-              },
-              required: ["id", "label"],
+        description:
+          "Surface data; structure depends on surface_type (see tool description)",
+      },
+      actions: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            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",
             },
-            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". Prefer inline — only use panel when a separate window is explicitly requested.',
-          },
-          await_action: {
-            type: "boolean",
-            description:
-              "Whether to block until an action is selected. Defaults to true when actions are provided.",
-          },
-          persistent: {
-            type: "boolean",
-            description:
-              "When true, clicking an action does not dismiss the surface — the card stays visible and only the clicked action is marked as spent. Use for launcher or menu-style cards where multiple buttons may be clicked. Defaults to false.",
           },
+          required: ["id", "label"],
         },
-        required: ["surface_type", "data"],
+        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". Prefer inline — only use panel when a separate window is explicitly requested.',
+      },
+      await_action: {
+        type: "boolean",
+        description:
+          "Whether to block until an action is selected. Defaults to true when actions are provided.",
       },
+      persistent: {
+        type: "boolean",
+        description:
+          "When true, clicking an action does not dismiss the surface — the card stays visible and only the clicked action is marked as spent. Use for launcher or menu-style cards where multiple buttons may be clicked. Defaults to false.",
+      },
+    },
+    required: ["surface_type", "data"],
+  },
 
-  execute: proxyExecute,
-};
+  execute: proxyExecute("ui_show"),
+} satisfies ToolDefinition;
 
 // ---------------------------------------------------------------------------
 // ui_update
 // ---------------------------------------------------------------------------
 
-const uiUpdateTool: Tool = {
+const uiUpdateTool = {
   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",
   defaultRiskLevel: RiskLevel.Low,
-  executionMode: "proxy",
   executionTarget: "host",
 
   input_schema: {
+    type: "object",
+    properties: {
+      surface_id: {
+        type: "string",
+        description: "The ID of the surface to update",
+      },
+      data: {
         type: "object",
-        properties: {
-          surface_id: {
-            type: "string",
-            description: "The ID of the surface to update",
-          },
-          data: {
-            type: "object",
-            description: "Partial data to merge into the existing surface data",
-          },
-        },
-        required: ["surface_id", "data"],
+        description: "Partial data to merge into the existing surface data",
       },
+    },
+    required: ["surface_id", "data"],
+  },
 
-  execute: proxyExecute,
-};
+  execute: proxyExecute("ui_update"),
+} satisfies ToolDefinition;
 
 // ---------------------------------------------------------------------------
 // ui_dismiss
 // ---------------------------------------------------------------------------
 
-const uiDismissTool: Tool = {
+const uiDismissTool = {
   name: "ui_dismiss",
   description: "Dismiss a currently displayed surface.",
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
-  executionMode: "proxy",
   executionTarget: "host",
 
   input_schema: {
-        type: "object",
-        properties: {
-          surface_id: {
-            type: "string",
-            description: "The ID of the surface to dismiss",
-          },
-        },
-        required: ["surface_id"],
+    type: "object",
+    properties: {
+      surface_id: {
+        type: "string",
+        description: "The ID of the surface to dismiss",
       },
+    },
+    required: ["surface_id"],
+  },
 
-  execute: proxyExecute,
-};
+  execute: proxyExecute("ui_dismiss"),
+} satisfies ToolDefinition;
 
-export const allUiSurfaceTools: Tool[] = [
+export const allUiSurfaceTools: ToolDefinition[] = [
   uiShowTool,
   uiUpdateTool,
   uiDismissTool,

package/src/types/onboarding-context.ts

@@ -10,4 +10,10 @@ export interface OnboardingContext {
   cohort?: string;
   websiteUrl?: string;
   contentSourceUrl?: string;
+  /** Filename of the bootstrap template to use (e.g. "BOOTSTRAP-CONTENT-AUTOMATION.md"). When set, replaces generic BOOTSTRAP.md if still pristine. */
+  bootstrapTemplate?: string;
+  /** Override the first user message content. When set during a wake-up greeting, this replaces the canned greeting. */
+  initialMessage?: string;
+  /** Skills to eagerly load on first turn (e.g. ["geo-writing", "document-editor"]). Informational — the bootstrap template drives actual loading. */
+  skills?: string[];
 }

package/src/usage/attribution.ts

@@ -15,6 +15,14 @@ export type UsageAttributionProfileSource =
 export interface UsageAttributionInput {
   callSite: LLMCallSite | null;
   overrideProfile?: string | null;
+  /**
+   * Per-conversation seed for `mix`-profile expansion (the conversation id).
+   * When the applied profile is a mix, threading the same seed the dispatch
+   * path uses ensures `resolvedModel`/`resolvedMixArm` reflect the arm the
+   * request actually ran on. Omitted by one-shot callers (the snapshot's
+   * `resolvedMixArm` is then null even if a mix was involved).
+   */
+  selectionSeed?: string;
 }
 
 export interface UsageAttributionSnapshot {
@@ -26,6 +34,12 @@ export interface UsageAttributionSnapshot {
   profileSource: UsageAttributionProfileSource;
   resolvedProvider: string;
   resolvedModel: string;
+  /**
+   * When `appliedProfile` is a mix profile, the constituent arm chosen for
+   * this request; null otherwise. Lets A/B analysis attribute usage to the
+   * specific arm (mix name lives in `appliedProfile`).
+   */
+  resolvedMixArm: string | null;
 }
 
 /**
@@ -51,7 +65,11 @@ export function resolveUsageAttribution(
   const overrideProfile = normalizeProfileId(input.overrideProfile);
 
   if (callSite == null) {
-    const resolvedMainAgent = resolveCallSiteConfig("mainAgent", llm);
+    const resolvedMainAgent = resolveCallSiteConfig("mainAgent", llm, {
+      ...(input.selectionSeed != null
+        ? { selectionSeed: input.selectionSeed }
+        : {}),
+    });
     return {
       callSite: null,
       activeProfile: normalizeProfileId(llm.activeProfile),
@@ -61,11 +79,20 @@ export function resolveUsageAttribution(
       profileSource: "unknown",
       resolvedProvider: resolvedMainAgent.provider,
       resolvedModel: resolvedMainAgent.model,
+      resolvedMixArm: null,
     };
   }
 
+  // Capture which arm each expanded mix resolved to so we can attribute usage
+  // to the arm behind the applied (mix) profile below.
+  const mixSelections = new Map<string, string>();
   const resolved = resolveCallSiteConfig(callSite, llm, {
     ...(overrideProfile != null ? { overrideProfile } : {}),
+    ...(input.selectionSeed != null
+      ? { selectionSeed: input.selectionSeed }
+      : {}),
+    onMixSelected: ({ mixProfile, chosenProfile }) =>
+      mixSelections.set(mixProfile, chosenProfile),
   });
   const activeProfile = normalizeProfileId(llm.activeProfile);
   const callSiteProfile = normalizeProfileId(
@@ -88,6 +115,10 @@ export function resolveUsageAttribution(
     profileSource: profile.profileSource,
     resolvedProvider: resolved.provider,
     resolvedModel: resolved.model,
+    resolvedMixArm:
+      profile.appliedProfile != null
+        ? (mixSelections.get(profile.appliedProfile) ?? null)
+        : null,
   };
 }
 

package/src/usage/types.ts

@@ -85,4 +85,14 @@ export interface UsageEvent extends UsageEventInput {
   inferenceProfileSource: UsageAttributionProfileSource | null;
   estimatedCostUsd: number | null;
   pricingStatus: "priced" | "unpriced";
+  /**
+   * Version of the assistant binary at the moment this event was
+   * RECORDED, captured by `recordUsageEvent` and persisted with the
+   * row. Not provided by callers; computed at record time. Surfaces
+   * onto the telemetry wire as `assistant_version` so analytics
+   * stays truthful even when a batch flushes days after the events
+   * fired. `null` only for rows persisted before migration 267 ran.
+   * See `migrations/267-llm-usage-events-add-assistant-version.ts`.
+   */
+  assistantVersion: string | null;
 }

package/src/util/browser.ts

@@ -10,8 +10,13 @@ const log = getLogger("browser");
  * Open a URL on the user's host machine.
  *
  * Writes an `open_url` event to the `signals/emit-event` file so that the
- * daemon's ConfigWatcher picks it up and publishes it to connected clients
- * (e.g. the Swift macOS app) via the assistant event hub.
+ * assistant's ConfigWatcher picks it up and publishes it to connected
+ * clients (e.g. the Swift macOS app) via the assistant event hub.
+ *
+ * CLI-initiated emit — no conversation context available, so the inner
+ * message has no `conversationId`. That's fine: `OpenUrlEventSchema`
+ * declares `conversationId` as optional, so this payload parses
+ * cleanly on the web side as well as in the Swift macOS app.
  */
 export async function openInHostBrowser(url: string): Promise<void> {
   try {

package/src/util/errors.ts

@@ -153,14 +153,14 @@ export class ConfigError extends AssistantError {
 export class ProviderNotConfiguredError extends ConfigError {
   /**
    * Optional name of the `provider_connections` row whose credential was
-   * missing. Surfaced through `ConversationErrorMessage.connectionName` so
+   * missing. Surfaced through `ConversationErrorEvent.connectionName` so
    * the macOS chat banner can render "API key required for connection
    * <name>" instead of a generic message.
    */
   public readonly connectionName?: string;
   /**
    * Optional name of the resolved profile in play when this error was
-   * thrown. Forwarded to the wire `ConversationErrorMessage.profileName`
+   * thrown. Forwarded to the wire `ConversationErrorEvent.profileName`
    * for the same banner-attribution purpose as `connectionName`.
    */
   public readonly profileName?: string;

package/src/util/map-limit.ts

@@ -0,0 +1,27 @@
+/**
+ * Map `fn` over `items` with bounded concurrency, preserving input order in the
+ * result array. At most `limit` invocations of `fn` are in flight at once.
+ *
+ * Each of the `min(limit, items.length)` workers pulls the next index off a
+ * shared cursor and processes it, so faster items don't block on slower ones.
+ * Results are written back to their original positions, so `out[i]` always
+ * corresponds to `items[i]` regardless of completion order.
+ */
+export async function mapLimit<T, R>(
+  items: T[],
+  limit: number,
+  fn: (t: T) => Promise<R>,
+): Promise<R[]> {
+  const out: R[] = new Array(items.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, async () => {
+      while (true) {
+        const i = next++;
+        if (i >= items.length) return;
+        out[i] = await fn(items[i]!);
+      }
+    }),
+  );
+  return out;
+}