@esso0428/pi-subagents 0.17.6 → 0.17.7

package/dist/workflow/journal.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/** One settled agent call, as replayed. */
+export interface WorkflowJournalEntry {
+    /** Position in the run — the same counter that names `wf-agent-N`. */
+    index: number;
+    /** Hash of the call's payload; a mismatch ends the replayable prefix. */
+    key: string;
+    /** Whether the agent succeeded. A failure ends the prefix on replay. */
+    ok: boolean;
+    /** The agent's answer, when it had one. */
+    text?: string;
+    /**
+     * Whether the call continued an earlier child (`agent({ resume })`).
+     *
+     * A replayed agent leaves no session behind in the run that replays it — the
+     * conversation belongs to the run that actually spawned it, and the host's
+     * id map is per-run — so a later `resume` would have nothing to continue.
+     * Recording it lets the next run decline to replay at all rather than fail
+     * partway through, which is why the flag is on the journal and not derived.
+     */
+    resumed?: true;
+}
+/**
+ * The fields that decide what an agent does.
+ *
+ * Deliberately not the whole payload: `phaseIndex` and `phaseTitle` move the
+ * row around in the progress tree without changing a single token the agent
+ * sees, so re-grouping phases should not throw away an hour of results.
+ */
+export interface JournalKeyInput {
+    prompt: string;
+    label?: string;
+    model?: string;
+    agentType?: string;
+    effort?: string;
+    isolation?: string;
+    gate?: string;
+    resume?: string;
+    /** Serialized `agent({ schema })`, when the call asked for one. */
+    schema?: string;
+}
+/** Stable hash of a call's payload. Field order is fixed here, not by the caller. */
+export declare function journalKey(input: JournalKeyInput): string;
+/**
+ * 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 declare function readJournal(path: string): WorkflowJournalEntry[];
+/** Append one settled call. Failure to write is not failure to run. */
+export declare function appendJournal(path: string, entry: WorkflowJournalEntry): void;
+//# sourceMappingURL=journal.d.ts.map

package/dist/workflow/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/workflow/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAKH,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,EAAE,EAAE,OAAO,CAAC;IACZ,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAkBzD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAsBhE;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAM7E"}

package/dist/workflow/journal.js

@@ -0,0 +1,121 @@
+/**
+ * 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));
+}
+//# sourceMappingURL=journal.js.map

package/dist/workflow/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../src/workflow/journal.ts"],"names":[],"mappings":"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"}

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 and both
+ * are installed here. `@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, 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;
+//# sourceMappingURL=json-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/workflow/json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAUH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,4DAA4D;IAC5D,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC;CACtC;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,CA0CpE"}

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 and both
+ * are installed here. `@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, 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";
+}
+//# sourceMappingURL=json-schema.js.map

package/dist/workflow/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","sourceRoot":"","sources":["../../src/workflow/json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE9C,iDAAiD;AACjD,MAAM,gBAAgB,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnC,+DAA+D;AAC/D,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAa9B;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,mDAAmD,EAAE,CAAC;IACrF,CAAC;IACD,MAAM,IAAI,GAAG,MAAiC,CAAC;IAC/C,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,oGAAoG;kBAClG,sEAAsE;SAC3E,CAAC;IACJ,CAAC;IAED,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,gDAAgD,EAAE,CAAC;IAClF,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;QACzC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,qCAAqC,UAAU,CAAC,MAAM,wBAAwB,gBAAgB,IAAI;SAC5G,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,4EAA4E;IAC5E,iEAAiE;IACjE,IAAI,CAAC;QACH,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,kEACP,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACvD,EAAE;SACH,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;AAC7F,CAAC;AAED,SAAS,YAAY,CAAC,MAA+B,EAAE,KAAc;IACnE,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,qEAAqE;QACrE,qDAAqD;QACrD,OAAO,qCAAqC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IACvG,CAAC;IACD,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IAEvB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,CAAC;QACH,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;YAC1C,yEAAyE;YACzE,mDAAmD;YACnD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;YAC9C,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;YACjE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5C,IAAI,QAAQ,CAAC,MAAM,IAAI,mBAAmB;gBAAE,MAAM;QACpD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,iCAAiC;IACnC,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,8CAA8C,CAAC;AACpG,CAAC"}

package/dist/workflow/meta.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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;
+//# sourceMappingURL=meta.d.ts.map

package/dist/workflow/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/workflow/meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAc/C;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D;AAwID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CA6E1D;AAYD,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAmBtG"}