Workflow Authoring

Workflow authoring

Use this guide when a task benefits from deterministic fan-out across many focused agents, direct MCP data calls, or durable child sessions. Do not use a workflow for one small sequential task that the current session can do directly.

Start with current capabilities

Call mcp__opensession-workflows__workflow_capabilities when model choice or run size matters. It returns the live model ids, default model, concurrency, lifetime, timeout, and child-session limits. Do not guess model ids or copy an old model list into a script.

Script shape

Pass plain JavaScript, not TypeScript, to run_workflow. Do not use imports. Export meta, then write the async body with top-level await and return:

export const meta = {
  name: "route-audit",
  description: "Audit routes for missing auth checks",
  phases: [{ title: "List" }, { title: "Audit" }, { title: "Rank" }],
};

phase("List");
const files = await agent("List the route files. Return only a JSON array.", {
  schema: { type: "array", items: { type: "string" } },
});
if (!files) return "Listing failed";

phase("Audit");
const findings = await parallel(
  files.map(
    (file) => () =>
      agent(`Read ${file} and report missing auth or validation checks.`, {
        label: file,
      }),
  ),
);

phase("Rank");
return findings.filter(Boolean);

meta.name is required and should be a short slug. description and phases are optional. Predeclared phases make progress understandable before work reaches them.

Injected globals

agent(prompt, opts?)

Run one focused model turn. Agents begin with no conversation context, so every prompt must include the paths, constraints, and output contract it needs.

Options:

{
  label,   // short progress label
  phase,   // phase override for this call
  schema,  // JSON Schema; returns parsed validated data
  model,   // current model id from workflow_capabilities
  effort,  // low, medium, high, xhigh, or max when supported
  write,   // opt into a branch-producing write agent
}

A successful unstructured call resolves to final text. A schema call resolves to the parsed value. An errored call resolves to null, so filter nulls before synthesis. Unsupported effort levels are ignored rather than failing the call.

Agents are read-only by default. Use write only when a lightweight branch-producing agent is sufficient. A successful write call returns an object containing text, structured, seq, branch, worktreeDir, changed, files, insertions, and deletions. Use a durable child session when work needs an inspectable transcript, steering, a worktree, or a pull request.

merge(writeResults)

Land selected write-agent branches back onto the session branch, sequentially. Pass one write result, an array of results, or bare { seq, branch } items. Null, unchanged, and branchless values are ignored.

const edits = await parallel(
  files.map(
    (file) => () =>
      agent(`Fix the issue in ${file} and commit the change.`, {
        label: file,
        write: true,
      }),
  ),
);
const merged = await merge(edits);
return merged;

The result is { merged, conflicts, skipped, error }. A conflicted branch is reported instead of rejecting the whole batch, and the remaining branches continue. Inspect the result rather than assuming every write landed.

parallel([...thunks])

Run zero-argument functions concurrently and wait for all results:

const reports = await parallel(
  files.map(
    (file) => () => agent(`Audit ${file}`, { label: file, phase: "Audit" }),
  ),
);

Pass thunks, not already-started promises. A thrown thunk becomes null and does not reject the batch.

pipeline(items, ...stages)

Run a per-item stage chain without a global barrier. Item B may start stage 2 while item A is still in stage 1. Each stage receives (previousResult, originalItem, index). A throwing stage drops that item to null and skips its remaining stages.

const findings = await pipeline(
  files,
  (file) => agent(`Inspect ${file}`, { label: file }),
  (report, file) => (report && report !== "none" ? `${file}: ${report}` : null),
);

Use parallel for one independent pass. Use pipeline when each item has a sequence of dependent transformations and early filtering should free capacity for other items.

Direct MCP calls

Call tools from the script without spending a model turn:

const alerts = await mcp.grafana.list_alert_groups({ state: "new" });
const issues = await mcp.linear.list_issues({ team: "ENG" });

Available forms:

• mcp.<server>.<tool>(args)
• mcp.call(server, tool, args) for dynamic names
• mcp.servers() to list the script's allowed servers
• mcp.tools(server) to return tool names, descriptions, and input schemas

A direct call returns the structured result, or parses text as JSON when possible. It rejects on failure. Catch failures explicitly or run calls inside parallel, where a throw degrades to null.

The script receives the current run's policy-scoped MCP surface. Per-user restrictions still apply, and confirmation-gated tools are unavailable.

Progress and inputs

• phase(title) sets the progress group for subsequent calls.
• log(message) appends a short narrator line to the live progress feed.
• args is the parsed args_json value passed to run_workflow.
• budget exposes { total, spent(), remaining() } for the optional advisory output-token budget.

Pass timestamps, seeds, file lists, and other varying inputs through args so a resumed run receives the same values.

Agent or tool?

Use direct mcp.* for retrieval and mutation that a connected tool already performs. Use agent() only when the step needs judgement, such as reading code, reconciling evidence, classifying, ranking, or synthesizing.

Filter and join data in JavaScript before sending it to agents. Every row removed in the script is context and model work not spent.

export const meta = { name: "alert-triage" };

const alerts = await mcp.grafana.list_alert_groups({ state: "new" });
const issues = await mcp.linear.list_issues({ team: "ENG", state: "started" });
const unclaimed = alerts.filter(
  (alert) => !issues.some((issue) => issue.title.includes(alert.title)),
);

log(`${unclaimed.length} unclaimed of ${alerts.length}`);
return await parallel(
  unclaimed.map(
    (alert) => () =>
      agent(
        `Assess this alert and suggest an owner: ${JSON.stringify(alert)}`,
        {
          label: alert.id,
        },
      ),
  ),
);