@vellumai/assistant 0.8.12 → 0.9.0-staging.1

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

@@ -55,7 +55,7 @@ The `claude-agent-acp` adapter requires a Claude OAuth token. Store it once in t
 assistant credentials set --service acp --field claude_oauth_token <token>
 ```
 
-When the token is missing, do NOT ask the user to paste it into chat. Collect it via the secret-request flow instead: `credential_store` with action `prompt`, service `acp`, field `claude_oauth_token`. That prompts the user through a secure UI so the token never enters the conversation or the workspace config. Users generate the token by running `claude setup-token` on a machine where they are logged in to Claude.
+When the token is missing, do NOT ask the user to paste it into chat. Collect it via the secure prompt instead: `assistant credentials prompt --service acp --field claude_oauth_token --label "Claude OAuth Token"`. That prompts the user through a secure UI so the token never enters the conversation or the workspace config. Users generate the token by running `claude setup-token` on a machine where they are logged in to Claude.
 
 ## Codex setup
 
@@ -78,7 +78,7 @@ Gemini CLI speaks ACP natively (`gemini --acp`) - there is no separate adapter b
 assistant credentials set --service acp --field gemini_api_key <key>
 ```
 
-Or collect the key via the secret-request flow: `credential_store` with action `prompt`, service `acp`, field `gemini_api_key`. Either way the key never appears in chat or workspace config, and every spawn injects it as `GEMINI_API_KEY` automatically. The key is optional - a spawn proceeds without it when the vault has no entry.
+Or collect the key via the secure prompt: `assistant credentials prompt --service acp --field gemini_api_key --label "Gemini API Key"`. Either way the key never appears in chat or workspace config, and every spawn injects it as `GEMINI_API_KEY` automatically. The key is optional - a spawn proceeds without it when the vault has no entry.
 
 The alternative is browser OAuth: run `gemini` once interactively and complete the sign-in flow. This is impractical on hosted assistants (no browser), so prefer the credential store there.
 

package/src/config/bundled-skills/image-studio/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: image-studio
-description: Generate and edit images using AI
+description: Create images from a text description, or edit photos and graphics the user provides (remove backgrounds or watermarks, retouch, restyle, in-paint). Can produce multiple variants when the user wants options to choose from.
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "🎨"
@@ -9,36 +9,83 @@ metadata:
     category: "content"
     activation-hints:
       - "User asks to generate, draw, or create an image from a text prompt"
-      - "User wants to edit an existing image — background removal, in-painting, style change, retouching"
+      - "User wants to edit an existing image: background removal, watermark removal, in-painting, style change, retouching"
       - "User wants multiple variations of a visual (logo concepts, mood boards, illustration options)"
 ---
 
-You are an image generation assistant. When the user asks you to create or edit images, use the `media_generate_image` tool.
-
-## Usage
-
-- **Text-to-image**: "Generate an image of a sunset over the ocean"
-- **Image editing**: "Remove the background from this image" (requires providing source image file paths)
-- **Multiple variants**: "Generate 3 variations of a logo for a coffee shop"
+Use the `media_generate_image` tool via `skill_execute` to create or edit images.
 
 ## Modes
 
 - **generate** (default): Create a new image from a text prompt.
-- **edit**: Modify an existing image based on a text prompt. Requires one or more source images via `source_paths` (file paths on disk).
+- **edit**: Modify an existing image. Requires one or more source images via `source_paths`.
 
 ## Models
 
-- `gemini-3.1-flash-image-preview` (default) - Nano Banana 2, fast, good quality
-- `gemini-3-pro-image-preview` - Nano Banana Pro, higher quality, slower
-- `gpt-image-2` - OpenAI GPT Image 2, high fidelity, slower
+Do not pass the `model` parameter unless you need a specific tier. Omitting it uses the configured default, which is correct for most requests.
+
+When you do need to choose, use an alias, not a concrete model ID. Aliases always resolve to the current model for that tier:
+
+- `fast`: quickest, good quality (default tier)
+- `quality`: higher fidelity, slower
+- `openai`: OpenAI's model; most permissive on photo edits
+
+Pass a concrete model ID only if the user names one explicitly. If the tool rejects an unknown model ID, the error lists the currently available models and aliases.
+
+## Example calls
+
+Generate (no model parameter, default is correct):
+
+```json
+{ "tool": "media_generate_image", "input": { "prompt": "A sunset over the ocean, golden hour, soft haze, 35mm photo style", "variants": 2 } }
+```
+
+Edit:
+
+```json
+{ "tool": "media_generate_image", "input": { "prompt": "Remove the watermark text from the background. Keep the subject, framing, lighting, and colors exactly identical. Change nothing else.", "mode": "edit", "source_paths": ["conversations/<conv-id>/attachments/photo.jpeg"], "model": "openai" } }
+```
+
+`source_paths` is a flat array of file path strings. Do NOT pass objects:
+
+- Wrong: `"source_paths": [{ "path": "img.jpeg" }]` → schema validation error
+- Right: `"source_paths": ["img.jpeg"]`
 
-## Tips
+## Source images for edit mode
 
-- Be descriptive in your prompts for better results. Include details about style, composition, lighting, and mood.
-- When editing images, clearly describe what changes you want made to the source image.
-- Use the `variants` parameter (1-4) to generate multiple options and pick the best one.
-- If no API key is configured for the selected model's provider (Gemini or OpenAI), the tool will return an error - ask the user to set one up.
+- Paths resolve inside the workspace. Conversation attachments live under `conversations/<conversation-id>/attachments/`; prefer that path for images the user attached.
+- Host paths (e.g. `~/Desktop/photo.jpg`) only work if the file arrived as an attachment; the tool falls back to the stored workspace copy. If the user references a host file that was never attached, pull it into the workspace first, then pass the workspace path.
+
+## Prompting
+
+- Generate: describe style, composition, lighting, and mood, not just the subject.
+- Edit: name the change AND what must stay the same. Models re-render the whole image, so without preservation language ("keep subject, framing, and lighting identical; only change X") they drift on crop and color.
+- Aspect ratio and size have no parameter today. State them in the prompt ("16:9 widescreen banner") and verify the output.
+- Use `variants` (1 to 4) when the user wants options. In **edit mode always use `variants: 1`**: edits run 60-90 seconds per variant, and two variants can exceed the tool execution timeout (`timeouts.toolExecutionTimeoutSec`, default 120s). If the user wants multiple edit options, make separate sequential calls.
+
+## Timing
+
+Edits on large photos are slow (1 to 2 minutes). If the tool reports a timeout ("timed out after Ns"), the result is lost; do not wait for it to appear. Retry with `variants: 1`, or if it already was 1, fall back to the CLI which writes files to disk: `assistant image-generation generate --prompt "..." --mode edit --source <path> --model openai --output-dir <dir>`.
+
+## Output handling
+
+Images return as inline content blocks in the tool result; they are not written to disk automatically.
+
+- If the user just wants to see the image, the inline result is enough.
+- If the user wants a file or you need to iterate on the result, save it to disk and deliver it through the conversation's attachment mechanism.
 
 ## Error handling
 
-When image generation fails, report the error to the user as-is. **Do not** attempt to fix the error by changing service configuration (e.g. switching between "managed" and "your-own" mode, or changing the provider/model). Service configuration changes should only be made at the user's explicit request via Settings.
+Two kinds of failure. Treat them differently:
+
+1. **Configuration errors** (missing API key, provider not set up): report the error to the user as-is. Do NOT change service configuration (managed vs your-own mode, default provider, or default model in Settings). Configuration changes happen only at the user's explicit request.
+2. **Generation failures** (any other error: "invalid", content policy, safety rejection, provider error). Do not diagnose the cause; switch providers. The error message names the model that failed:
+   - If the error names a `gemini-*` model (or no model) → retry ONCE with `model: "openai"`.
+   - If the error names `gpt-image-2` or another `gpt-*` model → retry ONCE with `model: "quality"`.
+   - If the retry also fails → stop and report both errors to the user.
+
+Do NOT rephrase the prompt and retry on the same model, even if the error suggests checking the prompt. One provider switch, then stop.
+
+## Complete when
+
+The tool has returned at least one image and the user can see it: either the inline result in chat or an attached saved file. An error report counts as complete only after the retry path in Error handling has been exhausted.

package/src/config/bundled-skills/image-studio/TOOLS.json

@@ -27,12 +27,7 @@
           },
           "model": {
             "type": "string",
-            "enum": [
-              "gemini-3.1-flash-image-preview",
-              "gemini-3-pro-image-preview",
-              "gpt-image-2"
-            ],
-            "description": "Which model to use for generation. If omitted, uses the user's configured preference."
+            "description": "Model tier alias (fast | quality | openai) or a concrete model ID. If omitted, uses the user's configured preference. Unknown values return an error listing currently available models."
           },
           "variants": {
             "type": "number",

package/src/config/bundled-skills/image-studio/tools/media-generate-image.ts

@@ -1,5 +1,9 @@
 import { getConfig } from "../../../../config/loader.js";
 import { resolveImageGenCredentials } from "../../../../media/image-credentials.js";
+import {
+  describeImageModels,
+  resolveImageModel,
+} from "../../../../media/image-models.js";
 import {
   generateImage,
   mapImageGenError,
@@ -19,7 +23,20 @@ export async function run(
 ): Promise<ToolExecutionResult> {
   const config = getConfig();
   const svc = config.services["image-generation"];
-  const modelOverride = input.model;
+  let modelOverride = input.model;
+  // Resolve tier aliases (fast, quality, openai) to concrete model IDs via
+  // the registry. Unknown values get an error listing the current catalog so
+  // callers can self-correct without a stale schema enum.
+  if (typeof modelOverride === "string" && modelOverride) {
+    const entry = resolveImageModel(modelOverride);
+    if (!entry) {
+      return {
+        content: `Unknown model "${modelOverride}". Available models and aliases:\n${describeImageModels()}\n\nRetry with one of the aliases above, or omit the model parameter to use the configured default.`,
+        isError: true,
+      };
+    }
+    modelOverride = entry.id;
+  }
   // Derive provider from the explicit model when supplied so that requesting
   // e.g. `gpt-image-2` while config.provider === "gemini" routes to OpenAI
   // instead of silently falling back to the Gemini default model.
@@ -30,7 +47,7 @@ export async function run(
   });
   if (!credentials) {
     return {
-      content: `${errorHint ?? "Image generation is not configured."}\n\nReport this error to the user. Do not change service configuration (mode, provider, or model) to try to fix it.`,
+      content: `${errorHint ?? "Image generation is not configured."}\n\nReport this error to the user as-is. Do not change service configuration (managed/your-own mode or default provider/model settings) to try to fix it.`,
       isError: true,
     };
   }
@@ -130,8 +147,10 @@ export async function run(
       contentBlocks,
     };
   } catch (error) {
+    // Echo the model that failed so callers (including the skill's retry
+    // branch) can key off the error text instead of remembering their input.
     return {
-      content: `${mapImageGenError(provider, error)}\n\nReport this error to the user. Do not change service configuration (mode, provider, or model) to try to fix it.`,
+      content: `${mapImageGenError(provider, error)}\n\nFailed model: ${model}\n\nDo not change service configuration (managed/your-own mode or default provider/model settings) to try to fix it. Retrying this call once with a different model parameter is allowed; follow the skill's error handling instructions.`,
       isError: true,
     };
   }

package/src/config/bundled-skills/personal-page/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: personal-page
+description: Build or update the user's personal page — a cinematic landing page about THE USER themselves (their bio, work, life areas). Use whenever the user asks for a personal page, a page about them, or to update what's on their page. NOT for general landing pages or other apps (that's app-builder). The page already exists in the workspace; this skill is how to fill it.
+metadata:
+  emoji: "✨"
+  vellum:
+    display-name: "Personal Page"
+    category: "content"
+    activation-hints:
+      - "User asks for a personal page, profile page, or landing page about themselves"
+      - "User asks to change, refresh, or add something to their personal page"
+      - "Onboarding asks you to turn research about the user into a page"
+    avoid-when:
+      - "User wants a landing page for a product, company, or someone else — use app-builder"
+---
+
+You fill in the user's personal page — a finished, cinematic dark landing page
+that already lives in the workspace as the app `personal-page`. Your job is
+**content, not construction**: the design is done.
+
+If `/workspace/data/apps/personal-page/` does not exist, this skill does not
+apply (the preseeded page is rolled out gradually) — build whatever the user
+asked for with app-builder instead.
+
+**Present it as yours.** To the user this is "the page you filled in for
+them" — fine to acknowledge the page shell exists, but never narrate the
+mechanics below (file paths, refresh calls, contracts) or your progress in
+chat. Do the work, then one short line.
+
+## How to populate it
+
+1. Read `/workspace/data/apps/personal-page/src/profile-data.ts`. The contract
+   comment at the top explains every field and shows a worked example.
+2. Overwrite the `profile` export with what you know or learned about the
+   user. Set `status: "ready"`. Touch ONLY this file — never the layout,
+   styles, animations, or media. Do NOT use `app_create`; the app exists.
+3. Call `app_refresh` (app_id: `personal-page`). If it reports compile errors,
+   fix your profile-data.ts edit and refresh again. **`app_refresh` is the
+   only build step — never compile manually (no esbuild, bundlers, or build
+   commands in the terminal); the platform's compiler has the correct JSX
+   setup and a manual build will produce a broken page.**
+4. As soon as the refresh is clean, call `app_open` (app_id: `personal-page`)
+   so the finished page is up and waiting — don't wait to be asked.
+
+## Writing the content
+
+- Facts beat adjectives: names, numbers, places. One fact per bullet.
+- Only what you actually verified; write around gaps rather than inventing.
+- Third person, warm but grounded. The page should feel like a profile in a
+  design magazine, not a résumé.
+
+## Later edits
+
+- Content tweaks ("add my marathon PR", "fix my title") → same flow: edit
+  `profile-data.ts`, `app_refresh`.
+- Only if the user explicitly asks to change the **design or layout** may you
+  edit the other source files, following app-builder conventions.

package/src/config/bundled-skills/personal-page/TOOLS.json

@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "app_refresh",
+      "description": "Trigger recompilation and surface refresh for an app after making file changes. Call this once after you finish editing app files with generic file tools.",
+      "category": "apps",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "app_id": {
+            "type": "string",
+            "description": "The ID of the app to refresh"
+          },
+          "change_summary": {
+            "type": "string",
+            "description": "Short summary of what changed, using git conventional commit format (e.g. 'feat: add dark mode toggle', 'fix: form validation'). Used as the version history entry."
+          }
+        },
+        "required": ["app_id"]
+      },
+      "executor": "tools/app-refresh.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/personal-page/tools/app-refresh.ts

@@ -0,0 +1,17 @@
+import { setAppCommitMessage } from "../../../../memory/app-git-service.js";
+import * as appStore from "../../../../memory/app-store.js";
+import { executeAppRefresh } from "../../../../tools/apps/executors.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  if (typeof input.change_summary === "string" && input.change_summary.trim()) {
+    setAppCommitMessage(context.conversationId, input.change_summary.trim());
+  }
+  return executeAppRefresh({ app_id: input.app_id as string }, appStore);
+}

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

@@ -17,7 +17,7 @@ metadata:
       - "User wants to act immediately or run a quick command that completes within the conversation — schedule is only for deferred or recurring execution"
 ---
 
-Manage scheduled automations. Schedules can be **recurring** (cron or RRULE expression) or **one-shot** (a single `fire_at` timestamp). Schedules support three modes: **execute** (run a message through the assistant), **notify** (send a notification to the user), and **script** (run a shell command directly without LLM involvement).
+Manage scheduled automations. Schedules can be **recurring** (cron or RRULE expression) or **one-shot** (a single `fire_at` timestamp). Schedules support four modes: **execute** (run a message through the assistant), **notify** (send a notification to the user), **script** (run a shell command directly without LLM involvement), and **workflow** (run a saved multi-agent workflow by name).
 
 ## Schedule Syntax
 
@@ -96,8 +96,13 @@ The `mode` parameter controls what happens when a schedule fires:
 - **execute** (default) - sends the schedule's message to a background assistant conversation for autonomous handling. The assistant processes the message as if the user sent it.
 - **notify** - sends a notification to the user via the notification pipeline. No assistant processing occurs.
 - **script** - runs the `script` field as a shell command directly. No LLM invoked, no conversation created. stdout/stderr are captured in the schedule run record. Exit code 0 = success, non-zero = error. Commands run in the workspace directory with a 60-second timeout by default. Override the timeout per schedule with `timeout_ms` (range 1000–1800000 ms) when a script needs more or less time; pass `timeout_ms: null` on update to revert to the default. The guardian can also adjust this from the /assistant/settings/schedules page.
+- **workflow** - runs a saved workflow (by `workflow_name`) at trigger time, optionally with `workflow_args`. Requires the `workflows` feature flag; `workflow_name` is required. Use this to run a previously saved multi-agent workflow on a schedule (e.g. "run my inbox-triage workflow every morning at 8am"). Optionally pass `capabilities` (the run's single consent point) to grant the scheduled run's leaves side-effecting tools or host functions beyond the read-only baseline; declaring any prompts the guardian for approval once at creation.
 
-Use `notify` for simple reminders ("remind me to take medicine at 9am"), `execute` for tasks that need assistant action ("check my calendar at 8am and send me a digest"), and `script` for lightweight shell automations that don't need LLM involvement ("refresh a cache", "poll an API", "rotate logs").
+Use `notify` for simple reminders ("remind me to take medicine at 9am"), `execute` for tasks that need assistant action ("check my calendar at 8am and send me a digest"), `script` for lightweight shell automations that don't need LLM involvement ("refresh a cache", "poll an API", "rotate logs"), and `workflow` to run a saved workflow on a schedule.
+
+## Inference Profile
+
+Execute-mode runs use the default `mainAgent` model selection unless the schedule pins an `inference_profile` (a key from `llm.profiles`). Pin a profile when a recurring task should run on a specific model — e.g. a cost-optimized profile for a high-frequency digest. Pass `inference_profile: null` on update to revert to the default. The pinned profile is shown on the schedule's details page in settings.
 
 ## Conversation Reuse
 

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

@@ -48,8 +48,36 @@
           },
           "mode": {
             "type": "string",
-            "enum": ["notify", "execute", "script"],
-            "description": "Whether to notify the user, execute autonomously via LLM, or run a shell command directly. Defaults to \"execute\"."
+            "enum": ["notify", "execute", "script", "workflow"],
+            "description": "Whether to notify the user, execute autonomously via LLM, run a shell command directly (script), or run a saved workflow (workflow). Defaults to \"execute\"."
+          },
+          "workflow_name": {
+            "type": "string",
+            "description": "Name of a saved workflow to run when the schedule triggers. Required for workflow mode."
+          },
+          "workflow_args": {
+            "type": "object",
+            "description": "Arguments object passed to the saved workflow as `args`. Optional; only used in workflow mode."
+          },
+          "capabilities": {
+            "type": "object",
+            "description": "Workflow mode only. Per-run capability grant (the single consent point) persisted with the schedule and applied to each triggered run. Leaves get a read-only baseline by default. Declaring any side-effecting tool or host function requires a fresh approval at creation.",
+            "properties": {
+              "tools": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Side-effecting tool names granted to leaves on top of the read-only baseline."
+              },
+              "hostFunctions": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Host-function names the run may invoke."
+              },
+              "persona": {
+                "type": "boolean",
+                "description": "Grant leaves access to persona (identity + memory) context."
+              }
+            }
           },
           "routing_intent": {
             "type": "string",
@@ -79,6 +107,10 @@
           "timeout_ms": {
             "type": "integer",
             "description": "For script mode: maximum time in milliseconds the shell command may run before it is killed. Defaults to 60000 (60s). Allowed range: 1000 to 1800000."
+          },
+          "inference_profile": {
+            "type": "string",
+            "description": "Inference profile (a key from llm.profiles) the schedule's LLM-executed runs should use, e.g. to run a heavy task on a cheaper model. When omitted, runs use the default mainAgent model selection. Must name a configured profile."
           }
         },
         "required": ["name", "description"]
@@ -155,8 +187,16 @@
           },
           "mode": {
             "type": "string",
-            "enum": ["notify", "execute", "script"],
-            "description": "Whether to notify the user, execute autonomously via LLM, or run a shell command directly"
+            "enum": ["notify", "execute", "script", "workflow"],
+            "description": "Whether to notify the user, execute autonomously via LLM, run a shell command directly (script), or run a saved workflow (workflow)"
+          },
+          "workflow_name": {
+            "type": "string",
+            "description": "Name of a saved workflow to run when the schedule triggers. Required when the schedule's resulting mode is workflow."
+          },
+          "workflow_args": {
+            "type": "object",
+            "description": "Arguments object passed to the saved workflow as `args`. Only used in workflow mode."
           },
           "routing_intent": {
             "type": "string",
@@ -186,6 +226,10 @@
           "timeout_ms": {
             "type": ["integer", "null"],
             "description": "For script mode: maximum time in milliseconds the shell command may run before it is killed (default 60000, range 1000 to 1800000). Pass null to clear a custom timeout and revert to the default."
+          },
+          "inference_profile": {
+            "type": ["string", "null"],
+            "description": "Inference profile (a key from llm.profiles) the schedule's LLM-executed runs should use. Pass null to clear the override and revert to the default mainAgent model selection. Must name a configured profile."
           }
         },
         "required": ["job_id"]

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

@@ -0,0 +1,214 @@
+---
+name: workflows
+description: Author and run autonomous multi-agent workflows that fan work across parallel leaf agents
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "⚙️"
+  vellum:
+    display-name: "Workflows"
+    category: "system"
+    feature-flag: "workflows"
+    activation-hints:
+      - "A task decomposes into many similar sub-tasks that can run concurrently (score every item, extract a field from each of many documents, draft-then-verify a batch)"
+      - "You want fan-out orchestrated deterministically and the result reported back when the whole run finishes"
+    avoid-when:
+      - "The task is a single tool call or a quick lookup — do it inline"
+      - "The work needs interactive, conversational back-and-forth rather than unattended fan-out"
+---
+
+A workflow is a short JS/TS script you author that runs in a sandbox and fans work
+out across many short-lived **leaf agents**, orchestrated deterministically. Launch
+one with `run_workflow` (inline `script` OR saved `name`, exactly one). It returns a
+`runId` immediately; the run is asynchronous and you are notified in this
+conversation when it completes — **do NOT poll**.
+
+Reach for one when a task decomposes into many similar small sub-tasks that can run
+concurrently. For a single task or a quick lookup, do it inline.
+
+## The script model
+
+These are the load-bearing invariants. Get them wrong and the run misbehaves silently.
+
+### Scripts are SYNCHRONOUS — never `await`
+
+Host functions block and return their result directly. Write straight-line code.
+
+```js
+const r = agent("Summarize this thread."); // r is the result, right here
+```
+
+Do **not** write `await agent(...)`, and do **not** make the script `async`. An
+`async` script deadlocks on its second host call — the sandbox can suspend the main
+evaluation stack but not a promise continuation.
+
+### Every script begins with a literal `meta`
+
+The first statement must be a pure-literal export — no computed values, template
+strings, or concatenation:
+
+```js
+export const meta = {
+  name: "triage-inbox",
+  description: "Triage and label inbox messages",
+};
+```
+
+`meta` is extracted **statically**, without executing the script, so it must be a
+plain object literal with string `name` and `description`. The `name` is how a saved
+workflow is referenced by `workflow(name)` and the scheduler.
+
+### You must `return` the result
+
+The script body runs as a function. Its result is whatever it `return`s at the top
+level — a bare trailing expression (e.g. `result;`) is **discarded** and the run
+finishes with no result. Always `return` the value you want surfaced.
+
+```js
+const result = agent(`Write the final summary: ${JSON.stringify(parts)}`);
+return result;
+```
+
+### Determinism (this is what makes runs resumable)
+
+Every leaf call is journaled by sequence number and input hash, so a resumed run can
+replay the unchanged prefix instead of re-spawning agents. That only holds if the
+script is deterministic, so `Date.now()`, `Math.random()`, and argless `new Date()`
+**throw**. Pass any timestamps or random seeds in through `args`.
+
+## Host API
+
+All functions are synchronous from the script's perspective.
+
+| Function                     | Returns                                        | Notes                                                                                                       |
+| ---------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `agent(prompt, opts?)`       | the leaf's result                              | Runs ONE leaf. **Throws** on leaf failure (fails the whole run).                                            |
+| `leaf(prompt, opts?)`        | a leaf descriptor                              | Runs nothing on its own; used inside `parallel`/`map`/`pipeline`.                                           |
+| `parallel(specs)`            | `results[]`                                    | Runs an array of `leaf(...)` descriptors concurrently, results in input order. A failed leaf becomes `null` (never throws). |
+| `map(items, build)`          | `results[]`                                    | `build(item, i)` returns a `leaf(...)` descriptor per item; runs them like `parallel`.                     |
+| `pipeline(items, ...stages)` | `results[]`                                    | Each `stage(prev, i)` returns a `leaf(...)` descriptor (run an agent) OR a plain value (pass through unchanged — filter/transform locally, no agent spent). Per-stage barrier: stage N+1 starts only after all of stage N finishes. |
+| `phase(title)`               | —                                              | Marks a named phase for progress reporting.                                                                |
+| `log(msg)`                   | —                                              | Emits a progress log line.                                                                                  |
+| `usage()`                    | `{ agentsSpawned, inputTokens, outputTokens }` | Live snapshot so a script can self-moderate.                                                               |
+| `workflow(name, args?)`      | the child's result                             | Runs a SAVED workflow inline, depth 1 only (a child may not call `workflow()`).                            |
+| `args`                       | the run input                                  | The `args` object passed to `run_workflow`.                                                                |
+
+Use `agent` for a single sequential leaf (throws on failure). Use `parallel`/`map`/
+`pipeline` for fan-out (a failed leaf is `null`, so a batch survives a few bad items).
+
+## Leaf options (`opts` for `agent` / `leaf`)
+
+| Option    | Type                       | Effect                                                                                  |
+| --------- | -------------------------- | --------------------------------------------------------------------------------------- |
+| `schema`  | JSON Schema object literal | Forces structured output via a tool. A schema leaf runs with **no tools** (pure judge/extractor). Use a plain JSON Schema literal, not Zod. |
+| `label`   | string                     | Short display/diagnostic label for the leaf.                                            |
+| `profile` | string                     | Overrides the model profile. Must exist in `llm.profiles` or the leaf throws. See [Listing profiles](#listing-available-profiles). |
+| `persona` | boolean                    | `true` makes the leaf speak AS the assistant (identity + memory) — use for output meant to be in the assistant's voice. Default is anonymous — use for impartial judging/extraction. |
+
+`persona: true` is the costly path (it runs the full memory-injection pipeline). Use
+it only for the few leaves whose output must be in the assistant's voice; keep bulk
+judging/extraction anonymous.
+
+## Capabilities — the single consent point
+
+The `capabilities` argument to `run_workflow` declares **once**, up front, what the
+run's leaves may do. There are **no per-call permission prompts inside a running
+workflow**.
+
+```jsonc
+{
+  "tools": ["file_write", "gmail_send"], // side-effecting tools granted to leaves
+  "hostFunctions": [],                    // host-function names the run may invoke
+  "persona": true                         // grant leaves persona (identity + memory)
+}
+```
+
+- **Read-only baseline** (always available, no declaration, no launch prompt):
+  `file_read`, `file_list`, `recall`, `web_search`.
+- **`web_fetch` is NOT in the baseline** — an outbound fetch is side-effecting (its
+  URL can exfiltrate read data), so a leaf that must fetch a URL has to declare
+  `"web_fetch"` in `capabilities.tools`.
+- **Declaring ANY side-effecting tool** (writes, sends, shell, `web_fetch`, …) or
+  host function makes the LAUNCH prompt the user for approval **once** — that single
+  approval covers the whole run. A read-only run (no declared tools) launches with no
+  prompt. Declare the minimum you need.
+
+Runs are autonomous but BOUNDED by a per-run agent cap — spend is structurally
+capped and you cannot exceed it.
+
+## Listing available profiles
+
+Before choosing a `profile` for a leaf, look up the valid values rather than guessing
+— an unknown profile throws.
+
+- **Preferred (model-accessible):** call `manage_workflows` with action
+  `list_profiles`. It returns the profile names defined in `llm.profiles` plus the
+  workspace-wide active profile.
+- The same data is served by the daemon route `GET config/llm/profiles` (operationId
+  `llm_profiles_list`), which clients use to populate profile dropdowns.
+
+Omit `profile` to use the default: a persona leaf mirrors the main agent (the active
+profile floats above the call-site default); an anonymous leaf uses the cost-optimized
+`workflowLeaf` default.
+
+## Run management
+
+Use `manage_workflows` to inspect and control runs:
+
+| Action          | Requires   | Purpose                                                          |
+| --------------- | ---------- | ---------------------------------------------------------------- |
+| `status`        | `run_id`   | Status + agent/token counts for one run (NOT the result).       |
+| `get_result`    | `run_id`   | The full result of a finished run.                              |
+| `list_runs`     | —          | Recent runs, newest first.                                      |
+| `abort`         | `run_id`   | Signal an in-flight run to abort.                               |
+| `resume`        | `run_id`   | Resume an `interrupted` run (see below).                        |
+| `list_profiles` | —          | List defined profiles + the active profile (for leaf `profile`).|
+
+The completion notification injected when a run finishes carries a **truncated**
+preview of the result (large results are cut off). To read the complete result,
+call `manage_workflows` with action `get_result` and the `run_id` — `status`
+deliberately omits the result to stay lightweight.
+
+### Crash recovery / resume
+
+Resume is **not automatic**. If the assistant restarts mid-run, the run is reconciled
+to status `interrupted` (the agent/token accounting is preserved so the agent cap
+still carries across the restart). It sits there until you explicitly resume it by
+`run_id` via `manage_workflows` action `resume`. Resuming re-invokes the engine with
+the same `runId`: the journal **replays the completed prefix** without re-spawning (or
+re-paying for) finished leaves, then continues from the first unfinished leaf under the
+run's originally-declared capabilities. Only `interrupted` runs are resumable; a
+`completed` / `failed` / `aborted` run is terminal.
+
+## Worked example
+
+Score each inbox item in parallel (anonymous schema leaves), then write one summary in
+the assistant's voice (a single persona leaf). The item list comes in via `args` —
+never fetched inside the script.
+
+```js
+export const meta = {
+  name: "triage-inbox",
+  description: "Score and summarize inbox items",
+};
+
+phase("score");
+const scored = map(args.items, (item) =>
+  leaf(`Rate this message's urgency 0-10 with a one-line reason:\n${item.subject}\n${item.body}`, {
+    label: `score:${item.id}`,
+    schema: {
+      type: "object",
+      properties: { urgency: { type: "number" }, reason: { type: "string" } },
+      required: ["urgency", "reason"],
+    },
+  }),
+);
+
+phase("summarize");
+const summary = agent(
+  `Here are scored inbox items. Write a short triage summary, highlighting anything urgent:\n${JSON.stringify(scored)}`,
+  { persona: true },
+);
+return summary;
+```
+
+A failed scoring leaf shows up as `null` in `scored`; the run continues.