Workflows

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.

{
  "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 (available to tool leaves, no declaration, no launch prompt): file_read, file_list, recall, web_search. A schema leaf gets none of these (it runs as a single forced-tool-choice call) — pass it inline content, never tell it to read.
• 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:

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.

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.