@vellumai/assistant 0.8.1 → 0.8.3

package/src/config/bundled-skills/app-builder/TOOLS.json

@@ -64,6 +64,13 @@
             },
             "required": ["title"]
           },
+          "source_files": {
+            "type": "object",
+            "description": "Map of file paths to file contents to write under the app directory. Supply the real app source here instead of making separate file_write calls. Paths are relative to the app directory (e.g. 'src/main.tsx', 'src/components/App.tsx', 'src/styles.css'). When src/main.tsx is included, no scaffold placeholder is created and the app compiles immediately with real content.",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
           "change_summary": {
             "type": "string",
             "description": "Short summary of what changed, using git conventional commit format (e.g. 'feat: add coin flip app', 'fix: correct button alignment'). Used as the version history entry."

package/src/config/bundled-skills/computer-use/TOOLS.json

@@ -24,11 +24,7 @@
         "properties": {
           "click_type": {
             "type": "string",
-            "enum": [
-              "single",
-              "double",
-              "right"
-            ],
+            "enum": ["single", "double", "right"],
             "description": "Type of click to perform (default: \"single\")"
           },
           "element_id": {
@@ -52,9 +48,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "reasoning"
-        ]
+        "required": ["reasoning"]
       },
       "executor": "tools/computer-use-click.ts",
       "execution_target": "host"
@@ -80,10 +74,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "text",
-          "reasoning"
-        ]
+        "required": ["text", "reasoning"]
       },
       "executor": "tools/computer-use-type-text.ts",
       "execution_target": "host"
@@ -109,10 +100,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "key",
-          "reasoning"
-        ]
+        "required": ["key", "reasoning"]
       },
       "executor": "tools/computer-use-key.ts",
       "execution_target": "host"
@@ -139,12 +127,7 @@
           },
           "direction": {
             "type": "string",
-            "enum": [
-              "up",
-              "down",
-              "left",
-              "right"
-            ],
+            "enum": ["up", "down", "left", "right"],
             "description": "Scroll direction"
           },
           "amount": {
@@ -160,11 +143,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "direction",
-          "amount",
-          "reasoning"
-        ]
+        "required": ["direction", "amount", "reasoning"]
       },
       "executor": "tools/computer-use-scroll.ts",
       "execution_target": "host"
@@ -210,9 +189,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "reasoning"
-        ]
+        "required": ["reasoning"]
       },
       "executor": "tools/computer-use-drag.ts",
       "execution_target": "host"
@@ -238,10 +215,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "duration_ms",
-          "reasoning"
-        ]
+        "required": ["duration_ms", "reasoning"]
       },
       "executor": "tools/computer-use-wait.ts",
       "execution_target": "host"
@@ -267,17 +241,14 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "app_name",
-          "reasoning"
-        ]
+        "required": ["app_name", "reasoning"]
       },
       "executor": "tools/computer-use-open-app.ts",
       "execution_target": "host"
     },
     {
       "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 the user. Never use 'do shell script' inside AppleScript (blocked for security).",
+      "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).",
       "category": "computer-use",
       "risk": "medium",
       "input_schema": {
@@ -296,10 +267,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "script",
-          "reasoning"
-        ]
+        "required": ["script", "reasoning"]
       },
       "executor": "tools/computer-use-run-applescript.ts",
       "execution_target": "host"
@@ -317,16 +285,14 @@
             "description": "Human-readable summary of what was accomplished"
           }
         },
-        "required": [
-          "summary"
-        ]
+        "required": ["summary"]
       },
       "executor": "tools/computer-use-done.ts",
       "execution_target": "host"
     },
     {
       "name": "computer_use_respond",
-      "description": "Respond to the user with a text answer instead of performing computer actions. Use this when you can answer directly without interacting with the screen.",
+      "description": "Reply with a text answer instead of performing computer actions. Use this when you can answer directly without interacting with the screen.",
       "category": "computer-use",
       "risk": "low",
       "input_schema": {
@@ -334,17 +300,14 @@
         "properties": {
           "answer": {
             "type": "string",
-            "description": "The text answer to display to the user"
+            "description": "The text answer to display"
           },
           "reasoning": {
             "type": "string",
             "description": "Explanation of how you determined the answer"
           }
         },
-        "required": [
-          "answer",
-          "reasoning"
-        ]
+        "required": ["answer", "reasoning"]
       },
       "executor": "tools/computer-use-respond.ts",
       "execution_target": "host"

package/src/config/bundled-skills/document/SKILL.md

@@ -18,13 +18,33 @@ Create and edit long-form documents using the built-in rich text editor. Documen
 
 - **document_create** - Opens a new document editor with an optional title and initial Markdown content. Returns a `surface_id` for subsequent updates.
 - **document_update** - Updates content in an open document editor by `surface_id`. Supports `replace` (overwrite) and `append` (add to end) modes.
+- **document_read** - Reads the current content of a document by `surface_id` when it belongs to the current conversation, or when the current actor is the guardian/local user. Use to verify content before editing.
+- **document_list** - Lists documents. Without `query`, lists the current conversation's documents. With `query`, searches by title; guardian/local users can search across conversations, while other actors are scoped to the current conversation.
+- **document_delete** - Deletes a document by `surface_id`. Use to clean up unwanted documents.
 
-## Workflow
+## Retrieving existing documents
+
+When the user asks to see, open, or pull up a document:
+
+1. Check the `<active_documents>` block in your context — it lists all documents in this conversation with their `surface_id` and title. If the document is there, call `document_read` with its `surface_id`. Done in one call.
+2. If the document is NOT in `<active_documents>`, call `document_list` with a `query` matching the document title. For guardian/local users, this searches across previous conversations and sessions.
+3. Once you have the `surface_id`, call `document_read` to retrieve the content.
+
+**Never** search the filesystem, conversation history, or archives to find a document. Always use `document_list` with a `query`.
+
+## Creating a new document
 
 1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
-2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, *italic*, code blocks, tables, lists, blockquotes as appropriate.
+2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, _italic_, code blocks, tables, lists, blockquotes as appropriate.
 3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. The user experiences real-time content appearing as you write.
-4. **Respond to edits**: When the user requests changes via the docked chat, use `document_update` with `replace` for full rewrites or `append` for additions.
+
+## Editing an existing document
+
+When the user requests changes to a document:
+
+1. Find the `surface_id` from the `<active_documents>` context block.
+2. Use `document_update` with the existing `surface_id` — do NOT call `document_create` again.
+3. Use `mode: "replace"` for full rewrites or `mode: "append"` for additions.
 
 ## Usage Notes
 

package/src/config/bundled-skills/document/TOOLS.json

@@ -48,6 +48,59 @@
       },
       "executor": "tools/document-update.ts",
       "execution_target": "host"
+    },
+    {
+      "name": "document_read",
+      "description": "Read the current content of a document by its surface_id when it belongs to the current conversation, or when the current actor is the guardian/local user. Use this to verify document state before making edits.",
+      "category": "document",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The ID of the document to read"
+          }
+        },
+        "required": ["surface_id"]
+      },
+      "executor": "tools/document-read.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "document_list",
+      "description": "List documents. Without a query, lists documents in the current conversation. With a query, searches documents by title; guardian/local users can search across conversations, while other actors are scoped to the current conversation.",
+      "category": "document",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search documents by title. Omit to list only the current conversation's documents."
+          }
+        }
+      },
+      "executor": "tools/document-list.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "document_delete",
+      "description": "Delete a document by its surface_id.",
+      "category": "document",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "surface_id": {
+            "type": "string",
+            "description": "The ID of the document to delete"
+          }
+        },
+        "required": ["surface_id"]
+      },
+      "executor": "tools/document-delete.ts",
+      "execution_target": "host"
     }
   ]
 }

package/src/config/bundled-skills/document/tools/document-delete.ts

@@ -0,0 +1,12 @@
+import { executeDocumentDelete } from "../../../../tools/document/document-tool.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeDocumentDelete(input, context);
+}

package/src/config/bundled-skills/document/tools/document-list.ts

@@ -0,0 +1,12 @@
+import { executeDocumentList } from "../../../../tools/document/document-tool.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeDocumentList(input, context);
+}

package/src/config/bundled-skills/document/tools/document-read.ts

@@ -0,0 +1,12 @@
+import { executeDocumentRead } from "../../../../tools/document/document-tool.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeDocumentRead(input, context);
+}

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -33,7 +33,7 @@ Follow the steps below to ensure everything is prepared to make and receive phon
 
 ## Step 1: Twilio Setup
 
-Load the `twilio-setup` skill to determine whether Twilio has been fully configured and set it up if not. This is a prerequisite to all subsequent steps.
+Immediately load the `twilio-setup` skill to begin setup. That skill marks Twilio setup as started before its read-only checks, which gives managed deployments a chance to open the Velay tunnel WebSocket while the user finishes entering credentials and choosing a number. Twilio setup is a prerequisite to all subsequent steps.
 
 ## Step 2: Enable Calls
 

package/src/config/bundled-skills/skill-management/SKILL.md

@@ -18,6 +18,6 @@ Manage the lifecycle of custom managed skills in `{workspaceDir}/skills`.
 ## Capabilities
 
 - **Scaffold** a new managed skill with YAML frontmatter and markdown body
-- **Delete** an existing managed skill and remove it from the SKILLS.md index
+- **Delete** an existing managed skill directory
 
-Skills created via `scaffold_managed_skill` become available for `skill_load` immediately.
+Skills created via `scaffold_managed_skill` become available for `skill_load` when a valid top-level `SKILL.md` is written under the skill directory.

package/src/config/bundled-skills/skill-management/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "scaffold_managed_skill",
-      "description": "Create or update a managed skill in {workspaceDir}/skills. The skill becomes available for skill_load immediately. Never persist a skill without explicit user consent. Before persisting, test the snippet: write to a temp file with bash and run with `bun run /tmp/vellum-eval/snippet.ts`. Iterate up to 3 attempts, then ask the user. Clean up temp files after. Do not use file_write for temp files outside the working directory. After a skill is written, the next turn may run in a recreated conversation due to file-watcher eviction - continue normally.",
+      "description": "Create or update a managed skill in {workspaceDir}/skills. The skill becomes available for skill_load when a valid top-level SKILL.md is written under the skill directory. Never persist a skill without explicit user consent. Before persisting, test the snippet: write to a temp file with bash and run with `bun run /tmp/vellum-eval/snippet.ts`. Iterate up to 3 attempts, then ask the user. Clean up temp files after. Do not use file_write for temp files outside the working directory. After a skill is written, the next turn may run in a recreated conversation due to file-watcher eviction - continue normally.",
       "category": "skills",
       "risk": "high",
       "input_schema": {
@@ -33,14 +33,14 @@
             "type": "boolean",
             "description": "Whether to overwrite an existing skill with the same ID (default: false)."
           },
-          "add_to_index": {
-            "type": "boolean",
-            "description": "Whether to add the skill to SKILLS.md index (default: true)."
-          },
           "includes": {
             "type": "array",
             "items": { "type": "string" },
             "description": "Optional list of child skill IDs that this skill includes (metadata only, no auto-activation)."
+          },
+          "add_to_index": {
+            "type": "boolean",
+            "description": "Deprecated no-op compatibility field. Skills are discovered from top-level SKILL.md files."
           }
         },
         "required": ["skill_id", "name", "description", "body_markdown"]
@@ -50,7 +50,7 @@
     },
     {
       "name": "delete_managed_skill",
-      "description": "Delete a managed skill from {workspaceDir}/skills and remove it from the SKILLS.md index. Never delete a skill without explicit user confirmation. After deletion, the next turn may run in a recreated conversation due to file-watcher eviction - continue normally.",
+      "description": "Delete a managed skill directory from {workspaceDir}/skills. Never delete a skill without explicit user confirmation. After deletion, the next turn may run in a recreated conversation due to file-watcher eviction - continue normally.",
       "category": "skills",
       "risk": "high",
       "input_schema": {
@@ -62,7 +62,7 @@
           },
           "remove_from_index": {
             "type": "boolean",
-            "description": "Whether to remove the skill from SKILLS.md index (default: true)."
+            "description": "Deprecated no-op compatibility field. Skill deletion does not edit SKILLS.md."
           }
         },
         "required": ["skill_id"]

package/src/config/bundled-tool-registry.ts

@@ -52,6 +52,9 @@ import * as contactSearch from "./bundled-skills/contacts/tools/contact-search.j
 import * as googleContacts from "./bundled-skills/contacts/tools/google-contacts.js";
 // ── document ───────────────────────────────────────────────────────────────────
 import * as documentCreate from "./bundled-skills/document/tools/document-create.js";
+import * as documentDelete from "./bundled-skills/document/tools/document-delete.js";
+import * as documentList from "./bundled-skills/document/tools/document-list.js";
+import * as documentRead from "./bundled-skills/document/tools/document-read.js";
 import * as documentUpdate from "./bundled-skills/document/tools/document-update.js";
 // ── followups ──────────────────────────────────────────────────────────────────
 import * as followupCreate from "./bundled-skills/followups/tools/followup-create.js";
@@ -168,6 +171,9 @@ export const bundledToolRegistry = new Map<string, SkillToolScript>([
 
   // document
   ["document:tools/document-create.ts", documentCreate],
+  ["document:tools/document-delete.ts", documentDelete],
+  ["document:tools/document-list.ts", documentList],
+  ["document:tools/document-read.ts", documentRead],
   ["document:tools/document-update.ts", documentUpdate],
 
   // followups

package/src/config/call-site-defaults.ts

@@ -0,0 +1,105 @@
+import { type LLMCallSite } from "./schemas/llm.js";
+
+type CallSiteDefaultConfig = {
+  profile: string;
+  maxTokens?: number;
+  effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
+  temperature?: number | null;
+  thinking?: { enabled?: boolean; streamThinking?: boolean };
+  contextWindow?: { maxInputTokens?: number };
+};
+
+export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
+  mainAgent: { profile: "balanced" },
+  subagentSpawn: { profile: "balanced" },
+  compactionAgent: { profile: "balanced" },
+  analyzeConversation: { profile: "balanced" },
+  patternScan: { profile: "balanced" },
+  narrativeRefinement: { profile: "balanced" },
+  callAgent: { profile: "balanced" },
+  proactiveArtifactBuild: { profile: "balanced" },
+  memoryConsolidation: { profile: "balanced" },
+  identityIntro: { profile: "balanced" },
+  emptyStateGreeting: { profile: "balanced" },
+
+  memoryRouter: {
+    profile: "balanced",
+    contextWindow: { maxInputTokens: 1000000 },
+  },
+  recall: {
+    profile: "balanced",
+    maxTokens: 4096,
+    effort: "low",
+    thinking: { enabled: false, streamThinking: false },
+    temperature: 0,
+  },
+  conversationStarters: {
+    profile: "balanced",
+    effort: "low",
+    thinking: { enabled: false },
+  },
+
+  filingAgent: { profile: "cost-optimized" },
+  proactiveArtifactDecision: { profile: "cost-optimized" },
+  memoryExtraction: { profile: "cost-optimized" },
+  memoryRetrieval: { profile: "cost-optimized" },
+  memoryRetrospective: { profile: "cost-optimized" },
+  memoryV2Migration: { profile: "cost-optimized" },
+  memoryV2Sweep: { profile: "cost-optimized" },
+  memoryV2Consolidation: { profile: "balanced" },
+  conversationSummarization: { profile: "cost-optimized" },
+  conversationTitle: { profile: "cost-optimized" },
+  approvalCopy: { profile: "cost-optimized" },
+  approvalConversation: { profile: "cost-optimized" },
+  trustRuleSuggestion: { profile: "cost-optimized" },
+  styleAnalyzer: { profile: "cost-optimized" },
+  meetConsentMonitor: { profile: "cost-optimized" },
+  meetChatOpportunity: { profile: "cost-optimized" },
+  inference: { profile: "cost-optimized" },
+
+  heartbeatAgent: {
+    profile: "cost-optimized",
+  },
+  commitMessage: {
+    profile: "cost-optimized",
+    maxTokens: 120,
+    temperature: 0.2,
+    effort: "low",
+    thinking: { enabled: false },
+  },
+  replySuggestion: {
+    profile: "cost-optimized",
+    effort: "low",
+    thinking: { enabled: false },
+  },
+  guardianQuestionCopy: {
+    profile: "cost-optimized",
+    effort: "low",
+    thinking: { enabled: false },
+  },
+  notificationDecision: {
+    profile: "cost-optimized",
+    effort: "low",
+    thinking: { enabled: false },
+  },
+  preferenceExtraction: {
+    profile: "cost-optimized",
+    effort: "low",
+    thinking: { enabled: false },
+  },
+  interactionClassifier: {
+    profile: "cost-optimized",
+    effort: "low",
+    thinking: { enabled: false },
+  },
+  inviteInstructionGenerator: {
+    profile: "cost-optimized",
+    effort: "low",
+    thinking: { enabled: false },
+  },
+  skillCategoryInference: {
+    profile: "cost-optimized",
+    effort: "low",
+    thinking: { enabled: false },
+  },
+};

package/src/config/feature-flag-registry.json

@@ -9,14 +9,6 @@
       "description": "Automatically trigger conversation analysis on the same cadence as memory extraction (batch threshold, idle debounce, end-of-conversation). The analysis agent has full tool access and writes back to memory and skills without user approval.",
       "defaultEnabled": false
     },
-    {
-      "id": "memory-retrospective",
-      "scope": "assistant",
-      "key": "memory-retrospective",
-      "label": "Memory retrospective pass",
-      "description": "Run a focused, memory-only retrospective during active conversations and at conversation lifecycle. The retrospective agent re-reads the messages added since the last successful run, dedupes against memory/archive/, and calls `remember` for what wasn't captured in the moment. Enabling this also relaxes the in-conversation pressure to call `remember` (lighter PKB reminder + relaxed tool description) so the assistant can stay present and trust the retrospective as the backstop.",
-      "defaultEnabled": false
-    },
     {
       "id": "user-hosted-enabled",
       "scope": "client",
@@ -33,6 +25,14 @@
       "description": "When enabled, the Local hosting option uses Docker under the hood for sandboxed execution, hiding the separate Docker card",
       "defaultEnabled": false
     },
+    {
+      "id": "a2a-channel",
+      "scope": "assistant",
+      "key": "a2a-channel",
+      "label": "A2A Channel",
+      "description": "Enable the A2A (Agent-to-Agent) channel for inter-assistant communication via the open A2A protocol",
+      "defaultEnabled": false
+    },
     {
       "id": "email-channel",
       "scope": "assistant",
@@ -145,6 +145,14 @@
       "description": "Show a speaker button on assistant messages to generate and play the message as audio via Fish Audio TTS",
       "defaultEnabled": false
     },
+    {
+      "id": "openai-compatible-endpoints",
+      "scope": "assistant",
+      "key": "openai-compatible-endpoints",
+      "label": "OpenAI-Compatible Endpoints",
+      "description": "Enable user-configured OpenAI-compatible inference endpoints with custom base URLs and model identifiers",
+      "defaultEnabled": false
+    },
     {
       "id": "backward-releases",
       "scope": "assistant",
@@ -294,7 +302,31 @@
       "scope": "assistant",
       "key": "pro-plan-adjust",
       "label": "Pro Plan Adjust",
-      "description": "Show the rich Plan card (current plan, features, Manage/Upgrade CTA) at the top of the macOS Settings → Billing tab.",
+      "description": "Show the rich Plan card (current plan, features, Manage/Upgrade CTA) at the top of the macOS Settings \u2192 Billing tab.",
+      "defaultEnabled": false
+    },
+    {
+      "id": "external-plugins",
+      "scope": "assistant",
+      "key": "external-plugins",
+      "label": "External Plugins",
+      "description": "Enable the external-plugin install path: the `assistant plugins` CLI subcommand and the declarative external-plugin loader convention (`<workspaceDir>/plugins/<name>/` directories containing `package.json` plus interface dirs). Gates an unstable surface that may change shape before stabilizing.",
+      "defaultEnabled": false
+    },
+    {
+      "id": "provider-zai",
+      "scope": "assistant",
+      "key": "provider-zai",
+      "label": "z.ai Provider",
+      "description": "Enable the z.ai (Zhipu AI) provider and its GLM models in the provider picker and model selection UI",
+      "defaultEnabled": false
+    },
+    {
+      "id": "velvet-theme",
+      "scope": "client",
+      "key": "velvet-theme",
+      "label": "Velvet Theme",
+      "description": "Show the Velvet theme option in the macOS appearance settings. Velvet is a dark-mode variant with red/pink accent colors.",
       "defaultEnabled": false
     }
   ]