@ymy88/pi-subagents 0.0.0-stage → 0.24.0

package/dist/workflow/journal.js

@@ -0,0 +1,120 @@
+/**
+ * journal.ts — the record a workflow run leaves so a later run can skip work.
+ *
+ * ## What resume actually buys
+ *
+ * The documented iteration loop is "edit the persisted script and re-run it".
+ * Without a journal that re-pays every agent from scratch, which for a 40-agent
+ * audit is the entire cost of the run — to change one line of the last stage.
+ * With one, the unchanged prefix comes back from disk and only the edit runs.
+ *
+ * ## Why a *prefix*, and not a lookup table
+ *
+ * Each entry is keyed by both its position in the run and a hash of everything
+ * that decides what that agent does. A replay walks positions in order and
+ * stops reusing at the first entry that does not match — every call from there
+ * on runs live. Reusing later matches out of order would be reusing a result
+ * produced under different upstream conditions: the same prompt at position 12
+ * of a *different* run is not the same work, because what fed it changed.
+ *
+ * A failed agent is journaled as a failure and never replayed as one. Resuming
+ * a run that died at agent 5 exists to retry agent 5, so the prefix ends there
+ * and 5 onwards run live — the alternative would make a failure permanent.
+ *
+ * ## Runs that use `agent({ resume })`
+ *
+ * Those are not replayed at all. A replayed agent is text from a file, not a
+ * live child, so there is no conversation in this run for a later `resume` to
+ * continue — and the id map that would find one belongs to the run that did
+ * the spawning. Rather than replay a prefix that strands the first `resume`
+ * call, a journal carrying one declines the whole cache and the run pays in
+ * full. Coarse on purpose: the alternative is tracking which label each entry
+ * ran under and capping the prefix below the earliest one that gets resumed,
+ * which is a second key concept for a case that costs one run.
+ *
+ * ## Ordering under concurrency
+ *
+ * Positions are assigned as calls arrive, and with `pipeline` that order
+ * depends on which agent finished first. A replay usually reproduces it, since
+ * cached calls answer in journal order, but it is not guaranteed. That is why
+ * the key is checked as well as the position: a run that interleaves
+ * differently loses cache hits, it never returns another agent's answer.
+ *
+ * The file is JSON Lines, appended as each agent settles, so a run that is
+ * killed mid-flight still leaves everything it had finished.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, readFileSync } from "node:fs";
+/** Stable hash of a call's payload. Field order is fixed here, not by the caller. */
+export function journalKey(input) {
+    const canonical = JSON.stringify([
+        input.prompt,
+        input.label ?? null,
+        input.model ?? null,
+        input.agentType ?? null,
+        input.effort ?? null,
+        input.isolation ?? null,
+        input.gate ?? null,
+        input.resume ?? null,
+        // Appended only when present, which looks like a hack and is not: adding a
+        // ninth slot unconditionally would change the canonical form of every entry
+        // and invalidate every journal already on disk. Conditional, a schema-less
+        // call keys exactly as it always did, and adding or changing a schema still
+        // produces a different key.
+        ...(input.schema !== undefined ? [input.schema] : []),
+    ]);
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
+}
+/**
+ * Read a journal file into position order.
+ *
+ * Never throws: a missing, truncated or hand-mangled journal means "nothing to
+ * replay", which costs tokens. Refusing to run would cost the whole run.
+ * A partial last line is normal — the file is appended to while agents settle.
+ */
+export function readJournal(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (!isEntry(parsed))
+                continue;
+            entries.push(parsed);
+        }
+        catch {
+            // A half-written final line, or someone editing the file. Skipping it
+            // keeps what came before, and a shorter prefix is still a useful one.
+        }
+    }
+    entries.sort((a, b) => a.index - b.index);
+    return entries;
+}
+/** Append one settled call. Failure to write is not failure to run. */
+export function appendJournal(path, entry) {
+    try {
+        appendFileSync(path, `${JSON.stringify(entry)}\n`, "utf-8");
+    }
+    catch {
+        // A journal that cannot be written costs a future resume, nothing more.
+    }
+}
+function isEntry(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const entry = value;
+    return (Number.isInteger(entry.index) &&
+        entry.index >= 0 &&
+        typeof entry.key === "string" &&
+        typeof entry.ok === "boolean" &&
+        (entry.text === undefined || typeof entry.text === "string") &&
+        (entry.resumed === undefined || entry.resumed === true));
+}

package/dist/workflow/json-schema.d.ts

@@ -0,0 +1,52 @@
+/**
+ * json-schema.ts — validating a script-supplied JSON Schema.
+ *
+ * `agent(prompt, { schema })` hands us a raw JSON Schema written by a model, to
+ * be used two ways: as a tool's `parameters` (so the provider fills the fields)
+ * and as the check that decides whether what came back is usable.
+ *
+ * ## Which typebox
+ *
+ * **`typebox`, not `@sinclair/typebox`.** They are different packages.
+ * `@sinclair/typebox` (0.34) dispatches on a `Kind` symbol that a schema
+ * arriving over the wire does not carry, so `Value.Check` throws `Unknown type`
+ * on a plain JSON Schema — and `Type.Unsafe` does not help, it stamps a `Kind`
+ * that is not registered. `typebox` v1 is a standards JSON Schema validator and
+ * takes the schema as-is. It is also the package pi itself types
+ * `ToolDefinition.parameters` against and supplies to extensions at runtime
+ * (a peer dependency here), so the same schema object serves both roles with no
+ * conversion.
+ *
+ * ## Why we validate at all
+ *
+ * Nothing in pi checks a tool call's arguments against the tool's `parameters`.
+ * `validateToolCall`/`validateToolArguments` exist in `pi-ai` but are never
+ * called from either shipped package, so a schema on a tool is a *prompt to the
+ * provider*, not an enforcement point. Every guarantee the script gets about
+ * the shape of its result is made here.
+ *
+ * Pure and pi-free on purpose, so `runtime.ts` can import it without dragging
+ * sessions and models into the runtime's tests.
+ */
+export interface CompiledSchema {
+    /** The schema as given, for the tool's `parameters` and the journal key. */
+    readonly schema: Record<string, unknown>;
+    /** `true`, or a human-readable account of what is wrong. */
+    check(value: unknown): true | string;
+}
+export type SchemaCompilation = {
+    ok: true;
+    compiled: CompiledSchema;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Turn a script-supplied schema into something we can check against.
+ *
+ * Rejects up front rather than at the first tool call. A schema whose root is
+ * not an object cannot be a tool's input schema at all, so it would break every
+ * request the child makes rather than just the last one — and the author should
+ * hear about that before a model is paid to discover it.
+ */
+export declare function compileJsonSchema(schema: unknown): SchemaCompilation;

package/dist/workflow/json-schema.js

@@ -0,0 +1,112 @@
+/**
+ * json-schema.ts — validating a script-supplied JSON Schema.
+ *
+ * `agent(prompt, { schema })` hands us a raw JSON Schema written by a model, to
+ * be used two ways: as a tool's `parameters` (so the provider fills the fields)
+ * and as the check that decides whether what came back is usable.
+ *
+ * ## Which typebox
+ *
+ * **`typebox`, not `@sinclair/typebox`.** They are different packages.
+ * `@sinclair/typebox` (0.34) dispatches on a `Kind` symbol that a schema
+ * arriving over the wire does not carry, so `Value.Check` throws `Unknown type`
+ * on a plain JSON Schema — and `Type.Unsafe` does not help, it stamps a `Kind`
+ * that is not registered. `typebox` v1 is a standards JSON Schema validator and
+ * takes the schema as-is. It is also the package pi itself types
+ * `ToolDefinition.parameters` against and supplies to extensions at runtime
+ * (a peer dependency here), so the same schema object serves both roles with no
+ * conversion.
+ *
+ * ## Why we validate at all
+ *
+ * Nothing in pi checks a tool call's arguments against the tool's `parameters`.
+ * `validateToolCall`/`validateToolArguments` exist in `pi-ai` but are never
+ * called from either shipped package, so a schema on a tool is a *prompt to the
+ * provider*, not an enforcement point. Every guarantee the script gets about
+ * the shape of its result is made here.
+ *
+ * Pure and pi-free on purpose, so `runtime.ts` can import it without dragging
+ * sessions and models into the runtime's tests.
+ */
+import { Check, Errors } from "typebox/value";
+/** Largest schema we will accept, serialized. */
+const MAX_SCHEMA_BYTES = 64 * 1024;
+/** How many validation errors are quoted back to the model. */
+const MAX_REPORTED_ERRORS = 5;
+/**
+ * Turn a script-supplied schema into something we can check against.
+ *
+ * Rejects up front rather than at the first tool call. A schema whose root is
+ * not an object cannot be a tool's input schema at all, so it would break every
+ * request the child makes rather than just the last one — and the author should
+ * hear about that before a model is paid to discover it.
+ */
+export function compileJsonSchema(schema) {
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+        return { ok: false, message: "agent() opts.schema must be a JSON Schema object." };
+    }
+    const root = schema;
+    if (root.type !== "object") {
+        return {
+            ok: false,
+            message: 'agent() opts.schema must have `type: "object"` at its root — it becomes the tool\'s input schema, '
+                + "and a non-object root is not something a model can be asked to fill.",
+        };
+    }
+    let serialized;
+    try {
+        serialized = JSON.stringify(root);
+    }
+    catch {
+        return { ok: false, message: "agent() opts.schema must be JSON-serializable." };
+    }
+    if (serialized.length > MAX_SCHEMA_BYTES) {
+        return {
+            ok: false,
+            message: `agent() opts.schema is too large (${serialized.length} bytes; the limit is ${MAX_SCHEMA_BYTES}).`,
+        };
+    }
+    // Smoke-tested here so a schema the validator cannot walk fails at the call
+    // that wrote it, with the schema in hand, rather than inside a child's tool
+    // handler where the only symptom is an agent that never returns.
+    try {
+        Check(root, {});
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `agent() opts.schema is not a schema this runtime can validate: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return { ok: true, compiled: { schema: root, check: value => checkAgainst(root, value) } };
+}
+function checkAgainst(schema, value) {
+    let valid;
+    try {
+        valid = Check(schema, value);
+    }
+    catch (error) {
+        // Reported rather than thrown: a schema that compiled but trips on a
+        // particular value must fail that call, not the run.
+        return `the value could not be validated: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    if (valid)
+        return true;
+    const reported = [];
+    try {
+        for (const error of Errors(schema, value)) {
+            // `instancePath` is JSON Pointer (`/a/b`); the model wrote the schema in
+            // JavaScript, so it reads `$.a.b` far more easily.
+            const path = String(error.instancePath ?? "");
+            const where = path === "" ? "$" : `$${path.replace(/\//g, ".")}`;
+            reported.push(`${where}: ${error.message}`);
+            if (reported.length >= MAX_REPORTED_ERRORS)
+                break;
+        }
+    }
+    catch {
+        // Errors() can trip where Check() merely returned false. A vaguer message
+        // still names the right problem.
+    }
+    return reported.length > 0 ? reported.join("; ") : "the value does not match the required schema";
+}

package/dist/workflow/meta.d.ts

@@ -0,0 +1,67 @@
+/**
+ * meta.ts — extract and validate a workflow script's `meta` block.
+ *
+ * Workflow scripts open with `export const meta = { ... }`, but the script body
+ * runs through `node:vm`, which has no module loader — `export` is a syntax
+ * error there. The block also has to be readable *before* execution, because the
+ * declared phases seed the progress groups the UI renders from the first frame.
+ *
+ * Claude Code solves this by parsing with acorn and requiring `meta` to be a
+ * pure literal (no variables, calls, spreads, or template interpolation). We
+ * take the same contract without the dependency: scan to the matching brace,
+ * then evaluate *only* that fragment in an empty vm context. A pure literal has
+ * nothing to call, so evaluating it cannot reach anything — and anything that
+ * isn't a pure literal either throws (unbound identifier) or is rejected below.
+ *
+ * The scanner is string-, comment-, and regex-aware. That matters: a workflow's
+ * `detail` text routinely contains braces, and `phases: [{ title: "a}b" }]` must
+ * not terminate the scan early.
+ */
+/** A phase declared up front, so the UI can show it before any agent runs. */
+export interface WorkflowPhaseMeta {
+    title: string;
+    detail?: string;
+    /** Set when a phase pins a model; display-only, the runtime does not read it. */
+    model?: string;
+}
+export interface WorkflowMeta {
+    name: string;
+    description: string;
+    /** Shown in the saved-workflow listing. Not used by the runtime. */
+    whenToUse?: string;
+    phases?: WorkflowPhaseMeta[];
+}
+export interface MetaExtraction {
+    meta: WorkflowMeta;
+    /**
+     * The script with the leading `export ` stripped, so `const meta = {...}`
+     * compiles inside the vm. Byte offsets after the keyword are untouched, which
+     * keeps stack-trace line numbers aligned with what the author wrote.
+     */
+    body: string;
+}
+export declare class WorkflowMetaError extends Error {
+}
+/**
+ * Whether `source` even claims to be a workflow script.
+ *
+ * The cheap half of {@link extractMeta}, exported so a directory of `.js` files
+ * can be told apart from a directory of workflows without evaluating anything.
+ * A saved-workflow folder is a normal folder — it may hold a build artifact, a
+ * config, someone's scratch script — and those should neither be offered as
+ * workflows nor produce a parser error when named.
+ */
+export declare function hasMetaDeclaration(source: string): boolean;
+/**
+ * Pull `meta` off the front of a workflow script and hand back the runnable body.
+ *
+ * Throws {@link WorkflowMetaError} with author-facing guidance for every
+ * rejection — these messages are shown verbatim to whoever wrote the script.
+ */
+export declare function extractMeta(source: string): MetaExtraction;
+/** The label a `SubagentWorkflow` call renders under, from whichever field it carries. */
+export declare function workflowCallName(args: {
+    script?: string;
+    scriptPath?: string;
+    name?: string;
+}): string;

package/dist/workflow/meta.js

@@ -0,0 +1,317 @@
+/**
+ * meta.ts — extract and validate a workflow script's `meta` block.
+ *
+ * Workflow scripts open with `export const meta = { ... }`, but the script body
+ * runs through `node:vm`, which has no module loader — `export` is a syntax
+ * error there. The block also has to be readable *before* execution, because the
+ * declared phases seed the progress groups the UI renders from the first frame.
+ *
+ * Claude Code solves this by parsing with acorn and requiring `meta` to be a
+ * pure literal (no variables, calls, spreads, or template interpolation). We
+ * take the same contract without the dependency: scan to the matching brace,
+ * then evaluate *only* that fragment in an empty vm context. A pure literal has
+ * nothing to call, so evaluating it cannot reach anything — and anything that
+ * isn't a pure literal either throws (unbound identifier) or is rejected below.
+ *
+ * The scanner is string-, comment-, and regex-aware. That matters: a workflow's
+ * `detail` text routinely contains braces, and `phases: [{ title: "a}b" }]` must
+ * not terminate the scan early.
+ */
+import { createContext, Script } from "node:vm";
+export class WorkflowMetaError extends Error {
+}
+/**
+ * Wall-clock bound on evaluating the `meta` fragment. Generous for a literal —
+ * this exists only to stop a pathological one from hanging the host thread.
+ */
+const META_EVAL_TIMEOUT_MS = 100;
+const PURE_LITERAL_HINT = "The `meta` object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation.";
+/** Matches `export const meta =` allowing arbitrary inner whitespace. */
+const META_DECLARATION = /(^|[\r\n])[ \t]*export[ \t\r\n]+const[ \t\r\n]+meta[ \t\r\n]*=/;
+/**
+ * Whether `source` even claims to be a workflow script.
+ *
+ * The cheap half of {@link extractMeta}, exported so a directory of `.js` files
+ * can be told apart from a directory of workflows without evaluating anything.
+ * A saved-workflow folder is a normal folder — it may hold a build artifact, a
+ * config, someone's scratch script — and those should neither be offered as
+ * workflows nor produce a parser error when named.
+ */
+export function hasMetaDeclaration(source) {
+    return META_DECLARATION.test(source);
+}
+/**
+ * Find the index just past the object literal that starts at `open`.
+ *
+ * Tracks string, template, comment, and regex context so braces inside them do
+ * not move the depth counter.
+ */
+function scanObjectLiteral(source, open) {
+    let depth = 0;
+    let i = open;
+    let sawInterpolation = false;
+    // What we are currently inside of. "code" means brace counting is live.
+    let mode = "code";
+    // Template literals nest: `${ {a:1} }` re-enters code, and the closing brace
+    // of that substitution must not be read as the object's. One depth per level.
+    const templateStack = [];
+    while (i < source.length) {
+        const c = source[i];
+        const next = source[i + 1];
+        if (mode === "line-comment") {
+            if (c === "\n")
+                mode = "code";
+            i++;
+            continue;
+        }
+        if (mode === "block-comment") {
+            if (c === "*" && next === "/") {
+                mode = "code";
+                i += 2;
+                continue;
+            }
+            i++;
+            continue;
+        }
+        if (mode === "single" || mode === "double" || mode === "regex") {
+            if (c === "\\") {
+                i += 2;
+                continue;
+            }
+            if (mode === "single" && c === "'")
+                mode = "code";
+            else if (mode === "double" && c === '"')
+                mode = "code";
+            else if (mode === "regex" && c === "/")
+                mode = "code";
+            // An unterminated regex/string can't run past a newline; bail to code so a
+            // misdetected regex (see below) cannot swallow the rest of the literal.
+            else if (c === "\n" && mode !== "double")
+                mode = "code";
+            i++;
+            continue;
+        }
+        if (mode === "template") {
+            if (c === "\\") {
+                i += 2;
+                continue;
+            }
+            if (c === "`") {
+                mode = "code";
+                i++;
+                continue;
+            }
+            if (c === "$" && next === "{") {
+                sawInterpolation = true;
+                templateStack.push(depth);
+                depth++;
+                mode = "code";
+                i += 2;
+                continue;
+            }
+            i++;
+            continue;
+        }
+        // mode === "code"
+        if (c === "/" && next === "/") {
+            mode = "line-comment";
+            i += 2;
+            continue;
+        }
+        if (c === "/" && next === "*") {
+            mode = "block-comment";
+            i += 2;
+            continue;
+        }
+        if (c === "'") {
+            mode = "single";
+            i++;
+            continue;
+        }
+        if (c === '"') {
+            mode = "double";
+            i++;
+            continue;
+        }
+        if (c === "`") {
+            mode = "template";
+            i++;
+            continue;
+        }
+        if (c === "/" && isRegexPosition(source, i)) {
+            mode = "regex";
+            i++;
+            continue;
+        }
+        if (c === "{") {
+            depth++;
+            i++;
+            continue;
+        }
+        if (c === "}") {
+            depth--;
+            i++;
+            if (templateStack.length > 0 && depth === templateStack[templateStack.length - 1]) {
+                templateStack.pop();
+                mode = "template";
+                continue;
+            }
+            if (depth === 0)
+                return { end: i, sawInterpolation };
+            continue;
+        }
+        i++;
+    }
+    return { end: -1, sawInterpolation };
+}
+/**
+ * Decide whether the `/` at `i` opens a regex literal rather than a division.
+ *
+ * Walks back past whitespace and comments to the previous significant char: a
+ * regex can only follow an operator or opener, never a value. This is the usual
+ * heuristic and it is sufficient here, because the only thing riding on it is
+ * not miscounting braces inside a `meta` literal — and a `meta` literal
+ * containing division is already not a pure literal.
+ */
+function isRegexPosition(source, i) {
+    let j = i - 1;
+    while (j >= 0 && /\s/.test(source[j]))
+        j--;
+    if (j < 0)
+        return true;
+    const prev = source[j];
+    // Identifier/number/closer before `/` means division.
+    return !/[\w$)\]]/.test(prev);
+}
+function fail(message) {
+    throw new WorkflowMetaError(message);
+}
+function assertPhases(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        fail("`meta.phases` must be an array of { title, detail?, model? } objects.");
+    return value.map((entry, index) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            fail(`\`meta.phases[${index}]\` must be an object with a \`title\`.`);
+        }
+        const { title, detail, model } = entry;
+        if (typeof title !== "string" || title.trim() === "") {
+            fail(`\`meta.phases[${index}].title\` must be a non-empty string.`);
+        }
+        if (detail !== undefined && typeof detail !== "string") {
+            fail(`\`meta.phases[${index}].detail\` must be a string.`);
+        }
+        if (model !== undefined && typeof model !== "string") {
+            fail(`\`meta.phases[${index}].model\` must be a string.`);
+        }
+        return { title, ...(detail !== undefined ? { detail } : {}), ...(model !== undefined ? { model } : {}) };
+    });
+}
+/**
+ * Pull `meta` off the front of a workflow script and hand back the runnable body.
+ *
+ * Throws {@link WorkflowMetaError} with author-facing guidance for every
+ * rejection — these messages are shown verbatim to whoever wrote the script.
+ */
+export function extractMeta(source) {
+    const declaration = META_DECLARATION.exec(source);
+    if (!declaration) {
+        fail("A workflow script must begin with `export const meta = { name, description }`.\n" +
+            PURE_LITERAL_HINT);
+    }
+    const open = source.indexOf("{", declaration.index + declaration[0].length);
+    if (open === -1)
+        fail("`export const meta` must be assigned an object literal.\n" + PURE_LITERAL_HINT);
+    const { end: close, sawInterpolation } = scanObjectLiteral(source, open);
+    if (close === -1)
+        fail("`meta` object literal is never closed — check for an unbalanced `{`.");
+    // Caught here rather than by evaluation: a self-contained substitution such as
+    // `` `a${1 + 1}b` `` resolves without touching a single global, so it would
+    // sail through the empty-context check below and silently produce "a2b".
+    if (sawInterpolation) {
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: quoting the syntax being rejected
+        fail("`meta` must not use template interpolation (`${...}`).\n" + PURE_LITERAL_HINT);
+    }
+    const fragment = source.slice(open, close);
+    let value;
+    try {
+        // Empty context: a pure literal needs no globals, so anything reaching for
+        // one (a variable, a helper call) throws here and is reported as impure.
+        //
+        // The timeout is not belt-and-braces. An IIFE needs no globals either, so
+        // `name: (() => { while (true); })()` is evaluable — and this runs on the
+        // host thread, before the script ever reaches the worker. Without a bound it
+        // would wedge pi itself. `timeout` only governs synchronous execution, which
+        // is all a literal can contain.
+        value = new Script(`(${fragment})`, { filename: "workflow-meta.js" })
+            .runInContext(createContext({}), { timeout: META_EVAL_TIMEOUT_MS });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        if (/timed out|Script execution/i.test(detail)) {
+            fail(`\`meta\` did not finish evaluating within ${META_EVAL_TIMEOUT_MS}ms — it must be a literal, not a computation.\n` +
+                PURE_LITERAL_HINT);
+        }
+        fail(`\`meta\` could not be evaluated: ${detail}\n${PURE_LITERAL_HINT}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        fail("`meta` must be an object literal.\n" + PURE_LITERAL_HINT);
+    }
+    const raw = value;
+    if (typeof raw.name !== "string" || raw.name.trim() === "") {
+        fail("`meta.name` is required and must be a non-empty string.");
+    }
+    if (typeof raw.description !== "string" || raw.description.trim() === "") {
+        fail("`meta.description` is required and must be a non-empty string.");
+    }
+    if (raw.whenToUse !== undefined && typeof raw.whenToUse !== "string") {
+        fail("`meta.whenToUse` must be a string.");
+    }
+    const phases = assertPhases(raw.phases);
+    const meta = {
+        name: raw.name,
+        description: raw.description,
+        ...(raw.whenToUse !== undefined ? { whenToUse: raw.whenToUse } : {}),
+        ...(phases !== undefined ? { phases } : {}),
+    };
+    // Strip only the `export ` keyword. Replacing it with spaces rather than
+    // deleting it keeps every subsequent offset — and therefore every reported
+    // line and column — identical to the source the author wrote.
+    const exportAt = source.indexOf("export", declaration.index);
+    const body = `${source.slice(0, exportAt)}${" ".repeat(6)}${source.slice(exportAt + 6)}`;
+    return { meta, body };
+}
+/**
+ * `meta.name` for a call line, without re-parsing on every frame.
+ *
+ * `renderCall` runs on every repaint, and extraction evaluates a literal in a
+ * vm — cheap, but not free at that cadence. Keyed by the exact source, so an
+ * edit-and-rerun cycle re-reads it and a hit is always the answer a fresh parse
+ * would give.
+ */
+const workflowNames = new Map();
+/** The label a `SubagentWorkflow` call renders under, from whichever field it carries. */
+export function workflowCallName(args) {
+    const source = args.script;
+    if (source === undefined || source === "") {
+        // A path-only call would need a synchronous file read per repaint to do
+        // better than this, and the file name is what the author will recognize.
+        if (args.scriptPath !== undefined)
+            return args.scriptPath.split(/[/\\]/).pop() ?? "workflow";
+        // A saved workflow is already named by the caller; no read needed at all.
+        return args.name !== undefined && args.name !== "" ? args.name : "workflow";
+    }
+    const cached = workflowNames.get(source);
+    if (cached !== undefined)
+        return cached;
+    let name = "workflow";
+    try {
+        name = extractMeta(source).meta.name;
+    }
+    catch {
+        // An invalid script still gets a call line; `execute` reports why.
+    }
+    workflowNames.set(source, name);
+    return name;
+}