@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/subagent.js

@@ -0,0 +1,444 @@
+/**
+ * Sub-agent core — the one place that knows how to spawn, stream, and settle
+ * a child agent.
+ *
+ * Before this module, every spawn site hand-rolled the same machinery:
+ * `run_subtask` and `run_search` each carried a depth guard, a context copy,
+ * a single-step Task, a `CodeActExecutor`, event tagging, forwarding, and
+ * result/error extraction. Copies of one concept meant every fix (the
+ * nested-`{error}` detection, the broken-forwarder guard) had to land in each
+ * of them — or didn't.
+ *
+ * The concept, stated once: a sub-agent is an async generator of
+ * `ProcessingMessage` events with a settled outcome as its return value.
+ * CodeAct is the default producer ({@link runSubAgent}), but any generator
+ * with that shape — an `authorGraph()` run, a future reviewer or researcher —
+ * streams through the same pipe ({@link forwardSubAgentStream}) and nests in
+ * the UI the same way (`parent_tool_call_id` + `subtask_depth`).
+ *
+ * Building blocks layered on the core:
+ *
+ * - {@link runSubAgent} — run one CodeAct child loop; yields its events,
+ *   returns a {@link SubAgentOutcome}. Structured results via `outputSchema`
+ *   (the child finalizes through `finish()`), prose otherwise (the final
+ *   assistant message is the result).
+ * - {@link forwardSubAgentStream} — drive any sub-agent generator: tag each
+ *   event for UI nesting, forward it without letting a broken forwarder kill
+ *   the child, honor an abort signal between events, hand back the outcome.
+ * - {@link enterSubAgentDepth} — the shared recursion gate over
+ *   {@link SUBTASK_DEPTH_KEY}.
+ * - {@link SubAgentTool} — base class for tools that expose a sub-agent to a
+ *   parent model. A concrete tool declares its schema, how params become
+ *   child instructions, and which parent tools the child inherits; the base
+ *   class owns everything else. `run_subtask` and `run_search` are ~40-line
+ *   subclasses; a new delegation tool should be too.
+ */
+import { randomUUID } from "node:crypto";
+import { budgetFromContext, createSemaphore, isRunBudget } from "@nodetool-ai/runtime";
+import { CodeActExecutor } from "./codeact/codeact-executor.js";
+import { Tool } from "./tools/base-tool.js";
+import { SUBTASK_DEPTH_KEY, TOOL_CALL_ID_FIELD } from "./tools/subtask-fields.js";
+import { isString } from "./utils/type-guards.js";
+/**
+ * Context variable holding the permit this branch runs on, as a one-permit
+ * pool its children draw from.
+ *
+ * The run's pool is a total, so a holder that blocks waiting for a *second*
+ * permit deadlocks the run: a step holding the last one while its child queues
+ * for another stops both until the deadline. The holder's own permit therefore
+ * counts as one for everything below it — a child takes it while the holder is
+ * idle in the tool call that spawned the child — and only a second concurrent
+ * child borrows from the run pool ({@link branchPool}). `ProcessingContext.copy()`
+ * gives every spawn its own variable bag, so the pool a child finds here is
+ * its parent's, and the one it sets is its own.
+ */
+const RUN_SLOT_KEY = "nodetool_run_slot";
+/**
+ * Take whichever of two pools frees first. The loser's permit, when it
+ * arrives, is handed straight back, so a wait on the pair never holds two.
+ */
+function acquireFirst(pools) {
+    return new Promise((resolve) => {
+        let won = false;
+        for (const pool of pools) {
+            void pool.acquire().then((release) => {
+                if (won) {
+                    release();
+                    return;
+                }
+                won = true;
+                resolve(release);
+            });
+        }
+    });
+}
+/**
+ * The pool a nested layer draws from: the permit its branch already holds,
+ * shared by its children one at a time, plus the run's pool beyond it. A
+ * branch holding nothing draws from the run pool alone.
+ */
+export function branchPool(budget, context) {
+    const held = context.get(RUN_SLOT_KEY);
+    if (!held)
+        return budget.concurrency;
+    const run = budget.concurrency;
+    return {
+        get permits() {
+            return held.permits + run.permits;
+        },
+        get available() {
+            return held.available + run.available;
+        },
+        get waiting() {
+            return held.waiting + run.waiting;
+        },
+        acquire() {
+            if (held.available > 0)
+                return held.acquire();
+            if (run.available > 0)
+                return run.acquire();
+            return acquireFirst([held, run]);
+        }
+    };
+}
+/**
+ * Record that this branch now runs on one permit, so the fan-outs beneath it
+ * share that permit and borrow beyond it. Called by a layer that holds a
+ * permit per running node (the step merge) on the node's own context, and by
+ * {@link acquireRunSlot} once a sub-agent has one. Hands back the undo.
+ */
+export function markRunSlotHeld(context) {
+    const previous = context.get(RUN_SLOT_KEY);
+    context.set(RUN_SLOT_KEY, createSemaphore(1));
+    let undone = false;
+    return () => {
+        if (undone)
+            return;
+        undone = true;
+        context.set(RUN_SLOT_KEY, previous);
+    };
+}
+/**
+ * Take a permit for this branch — its parent's when the parent is idle, else
+ * one of the run's — and mark the branch as holding it. Returns the release
+ * either way, so the caller has one `finally`. Unbudgeted runs take nothing.
+ */
+export async function acquireRunSlot(budget, context) {
+    if (!budget)
+        return () => { };
+    const release = await branchPool(budget, context).acquire();
+    const undo = markRunSlotHeld(context);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        undo();
+        release();
+    };
+}
+/**
+ * Settle a step's *value* into an outcome — the one place that knows what a
+ * failure looks like once it is a value rather than a protocol field.
+ *
+ * `null`/`undefined` is not a settlement at all (the step produced nothing
+ * yet), so it answers `null`. A plain object carrying a non-empty string
+ * `error` is the failure payload a step writes on its error path
+ * (`{ error: "Step failed: ..." }`). An **array is never that payload**: a
+ * fan-out step stores an array of per-item results, and whether that array
+ * failed is a question about its items, not about the array. With an output
+ * schema the object shape was explicitly requested, so it passes through.
+ */
+export function settleResultValue(result, opts = {}) {
+    if (result === null || result === undefined)
+        return null;
+    if (typeof result === "object" && !Array.isArray(result)) {
+        const error = result.error;
+        if (isString(error) && error.length > 0 && !opts.hasOutputSchema) {
+            return { ok: false, error };
+        }
+    }
+    return { ok: true, result };
+}
+/**
+ * Settle a `step_result` message into an outcome.
+ *
+ * The executor reports failures through the protocol-level `error` field;
+ * everything else is decided by {@link settleResultValue}.
+ */
+export function settleStepResult(sr, opts = {}) {
+    if (sr.error)
+        return { ok: false, error: sr.error };
+    return settleResultValue(sr.result, opts);
+}
+/**
+ * Run one CodeAct sub-agent: a fresh child loop over `tools`, driven by
+ * `instructions`, yielding every child event and returning how it settled.
+ *
+ * The generator never throws for run failures — provider errors, iteration
+ * caps, and failed steps all come back as `{ok: false, error}` so callers
+ * have one settlement path.
+ */
+export async function* runSubAgent(opts) {
+    const id = opts.id ?? randomUUID();
+    const step = {
+        id: `${id}`,
+        instructions: opts.instructions,
+        completed: false,
+        dependsOn: [],
+        logs: [],
+        outputSchema: opts.outputSchema
+            ? JSON.stringify(opts.outputSchema)
+            : undefined
+    };
+    const task = {
+        id: `task_${id}`,
+        title: opts.title ?? "subtask",
+        steps: [step]
+    };
+    // The run's budget, never a fresh one: a caller that passes none still gets
+    // the one the host put on the context, so a child spawned three levels down
+    // spends the same allowance as the turn that started it.
+    const turnBudget = opts.turnBudget ?? budgetFromContext(opts.context);
+    const runBudget = isRunBudget(turnBudget) ? turnBudget : undefined;
+    const executor = new CodeActExecutor({
+        task,
+        step,
+        context: opts.context,
+        provider: opts.provider,
+        model: opts.model,
+        tools: opts.tools,
+        systemPrompt: opts.systemPrompt,
+        maxIterations: opts.maxIterations,
+        maxTokens: opts.maxTokens,
+        turnBudget,
+        threadId: opts.threadId,
+        sandboxPackages: opts.sandboxPackages,
+        // Without the run's signal a cancelled parent leaves its children driving
+        // provider calls to completion in the background.
+        signal: opts.signal
+    });
+    let outcome = null;
+    // A permit for the whole child loop: the parent's own while the parent is
+    // idle in this call, else one of the run's. `start_subtask` detaches its
+    // children, so nothing else bounds a fan-out of them: the permit is what
+    // keeps the next from opening a provider conversation before one finishes.
+    const release = await acquireRunSlot(runBudget, opts.context);
+    try {
+        for await (const msg of executor.execute()) {
+            yield msg;
+            if (msg.type === "step_result") {
+                const settled = settleStepResult(msg, {
+                    hasOutputSchema: Boolean(opts.outputSchema)
+                });
+                if (settled)
+                    outcome = settled;
+            }
+        }
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+    finally {
+        release();
+    }
+    // A child that settled without a value is not a failure — callers decide
+    // whether a null result is an error (`run_subtask` reports it as
+    // `subtask_no_result`).
+    return outcome ?? { ok: true, result: null };
+}
+/**
+ * Shallow-clone a child event with the nesting tags the renderer reads.
+ * Returns the message unchanged when no tag applies — the original object is
+ * shared with whoever emitted it inside the child, so it is never mutated.
+ */
+export function tagSubAgentMessage(msg, tag) {
+    if (tag.parentToolCallId === undefined && tag.depth === undefined) {
+        return msg;
+    }
+    // The two tag keys ride on the copy as extra fields; every message type in
+    // the union transports them, and the copy keeps the emitter's object clean.
+    const tags = {};
+    if (tag.parentToolCallId !== undefined) {
+        tags.parent_tool_call_id = tag.parentToolCallId;
+    }
+    if (tag.depth !== undefined) {
+        tags.subtask_depth = tag.depth;
+    }
+    return { ...msg, ...tags };
+}
+async function nextSubAgentEvent(gen, signal) {
+    if (!signal) {
+        return { aborted: false, next: await gen.next() };
+    }
+    if (signal.aborted) {
+        return { aborted: true };
+    }
+    let onAbort;
+    const aborted = new Promise((resolve) => {
+        onAbort = () => resolve({ aborted: true });
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([
+            gen.next().then((next) => ({ aborted: false, next })),
+            aborted
+        ]);
+    }
+    finally {
+        if (onAbort) {
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
+}
+function closeSubAgentGenerator(gen) {
+    void gen.return(null).catch(() => {
+        // The caller has settled after cancellation; producer cleanup is best-effort.
+    });
+}
+/**
+ * Drive any sub-agent generator to completion: tag each event, forward it,
+ * and hand back the generator's return value.
+ *
+ * A broken forwarder must not kill the child — the parent model still gets
+ * the result via the tool return — so forward errors are logged and the
+ * stream continues.
+ */
+export async function forwardSubAgentStream(gen, opts) {
+    let read = await nextSubAgentEvent(gen, opts.signal);
+    if (read.aborted) {
+        closeSubAgentGenerator(gen);
+        return { aborted: true, value: null };
+    }
+    let next = read.next;
+    while (!next.done) {
+        if (opts.signal?.aborted) {
+            closeSubAgentGenerator(gen);
+            return { aborted: true, value: null };
+        }
+        const tagged = tagSubAgentMessage(next.value, opts);
+        if (opts.forward) {
+            try {
+                await opts.forward(tagged);
+            }
+            catch (forwardErr) {
+                // eslint-disable-next-line no-console
+                console.warn(`${opts.label ?? "subagent"}: failed to forward child event`, forwardErr);
+            }
+        }
+        read = await nextSubAgentEvent(gen, opts.signal);
+        if (read.aborted) {
+            closeSubAgentGenerator(gen);
+            return { aborted: true, value: null };
+        }
+        next = read.next;
+    }
+    if (opts.signal?.aborted) {
+        return { aborted: true, value: null };
+    }
+    return { aborted: false, value: next.value };
+}
+export const DEFAULT_SUBAGENT_MAX_DEPTH = 3;
+/**
+ * The shared recursion gate. Reads the current depth off the context, refuses
+ * past `maxDepth` with the standard error object, and otherwise returns a
+ * copied context with the depth bumped — the copy preserves `_onMessage`
+ * (telemetry listener) and clones variables so depth mutations stay local.
+ */
+export function enterSubAgentDepth(context, maxDepth, noun = "subtask") {
+    const currentDepth = context.get(SUBTASK_DEPTH_KEY) ?? 0;
+    if (currentDepth >= maxDepth) {
+        return {
+            ok: false,
+            refusal: {
+                error: "max_recursion_depth_reached",
+                depth: currentDepth,
+                max_depth: maxDepth,
+                message: `Cannot spawn another ${noun} — recursion depth limit reached. ` +
+                    "Answer directly using the tools already available at this level."
+            }
+        };
+    }
+    const childCtx = context.copy();
+    const depth = currentDepth + 1;
+    childCtx.set(SUBTASK_DEPTH_KEY, depth);
+    return { ok: true, childCtx, depth };
+}
+/**
+ * Base class for tools that expose a sub-agent as a building block the parent
+ * model can invoke. Subclasses declare the tool surface (name, description,
+ * schema), translate params into a {@link SubAgentToolRun}, and pick the
+ * child's toolset from the parent snapshot; the base class owns the depth
+ * gate, the child context, streaming, tagging, and settlement.
+ */
+export class SubAgentTool extends Tool {
+    needsToolCallId = true;
+    /** Noun used in the depth-refusal message ("subtask", "search", …). */
+    depthNoun = "subtask";
+    provider;
+    model;
+    parentToolsFn;
+    forward;
+    maxDepth;
+    maxIterations;
+    /** The run's budget, held once here for every subclass. */
+    budget;
+    constructor(runtime) {
+        super();
+        this.provider = runtime.provider;
+        this.model = runtime.model;
+        this.parentToolsFn = runtime.parentTools;
+        this.forward = runtime.forwardMessage;
+        this.maxDepth = runtime.maxDepth ?? DEFAULT_SUBAGENT_MAX_DEPTH;
+        this.maxIterations = runtime.maxIterations;
+        this.budget = runtime.budget;
+    }
+    async process(context, params) {
+        const gate = enterSubAgentDepth(context, this.maxDepth, this.depthNoun);
+        if (!gate.ok)
+            return gate.refusal;
+        const run = this.buildRun(params);
+        if ("error" in run)
+            return run;
+        const parentToolCallId = isString(params[TOOL_CALL_ID_FIELD])
+            ? params[TOOL_CALL_ID_FIELD]
+            : null;
+        const gen = runSubAgent({
+            context: gate.childCtx,
+            provider: this.provider,
+            model: this.model,
+            tools: this.buildChildToolset(this.parentToolsFn()),
+            instructions: run.instructions,
+            title: run.title,
+            outputSchema: run.outputSchema,
+            systemPrompt: run.systemPrompt,
+            maxIterations: run.maxIterations ?? this.maxIterations,
+            // The parent's budget, not a new one. Dropping it here was the hole:
+            // every child of a capped turn ran unbudgeted.
+            turnBudget: this.budget ?? budgetFromContext(context),
+            signal: context.signal
+        });
+        const { value: outcome } = await forwardSubAgentStream(gen, {
+            forward: this.forward,
+            parentToolCallId,
+            depth: gate.depth,
+            label: this.name
+        });
+        if (!outcome || !outcome.ok) {
+            return {
+                error: run.errorCode,
+                ...run.errorExtras,
+                message: outcome ? outcome.error : "Sub-agent stream ended early."
+            };
+        }
+        if (outcome.result === null || outcome.result === undefined) {
+            return {
+                error: run.noResultCode,
+                ...run.errorExtras,
+                message: run.noResultMessage
+            };
+        }
+        return outcome.result;
+    }
+}
+//# sourceMappingURL=subagent.js.map

package/dist/subagent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent.js","sourceRoot":"","sources":["../src/subagent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,WAAW,EACZ,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAEzC;;;GAGG;AACH,SAAS,YAAY,CAAC,KAA2B;IAC/C,OAAO,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;QACtC,IAAI,GAAG,GAAG,KAAK,CAAC;QAChB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;gBACnC,IAAI,GAAG,EAAE,CAAC;oBACR,OAAO,EAAE,CAAC;oBACV,OAAO;gBACT,CAAC;gBACD,GAAG,GAAG,IAAI,CAAC;gBACX,OAAO,CAAC,OAAO,CAAC,CAAC;YACnB,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,MAAiB,EACjB,OAA0B;IAE1B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAwB,YAAY,CAAC,CAAC;IAC9D,IAAI,CAAC,IAAI;QAAE,OAAO,MAAM,CAAC,WAAW,CAAC;IACrC,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC;IAC/B,OAAO;QACL,IAAI,OAAO;YACT,OAAO,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QACpC,CAAC;QACD,IAAI,SAAS;YACX,OAAO,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;QACxC,CAAC;QACD,IAAI,OAAO;YACT,OAAO,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QACpC,CAAC;QACD,OAAO;YACL,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;YAC9C,IAAI,GAAG,CAAC,SAAS,GAAG,CAAC;gBAAE,OAAO,GAAG,CAAC,OAAO,EAAE,CAAC;YAC5C,OAAO,YAAY,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAA0B;IACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAwB,YAAY,CAAC,CAAC;IAClE,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,OAAO,GAAG,EAAE;QACV,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,GAAG,IAAI,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAA6B,EAC7B,OAA0B;IAE1B,IAAI,CAAC,MAAM;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IAC5D,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,EAAE,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC;AAkDD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAe,EACf,IAAI,GAAkC,EAAE;IAExC,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACzD,MAAM,KAAK,GAAI,MAAkC,CAAC,KAAK,CAAC;QACxD,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,EAAc,EACd,IAAI,GAAkC,EAAE;IAExC,IAAI,EAAE,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC;IACpD,OAAO,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,CAChC,IAAwB;IAExB,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,IAAI,UAAU,EAAE,CAAC;IACnC,MAAM,IAAI,GAAS;QACjB,EAAE,EAAE,GAAG,EAAE,EAAE;QACX,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,SAAS,EAAE,KAAK;QAChB,SAAS,EAAE,EAAE;QACb,IAAI,EAAE,EAAE;QACR,YAAY,EAAE,IAAI,CAAC,YAAY;YAC7B,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC;YACnC,CAAC,CAAC,SAAS;KACd,CAAC;IACF,MAAM,IAAI,GAAS;QACjB,EAAE,EAAE,QAAQ,EAAE,EAAE;QAChB,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,SAAS;QAC9B,KAAK,EAAE,CAAC,IAAI,CAAC;KACd,CAAC;IAEF,4EAA4E;IAC5E,4EAA4E;IAC5E,yDAAyD;IACzD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnE,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC;QACnC,IAAI;QACJ,IAAI;QACJ,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,UAAU;QACV,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,0EAA0E;QAC1E,kDAAkD;QAClD,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IAEH,IAAI,OAAO,GAA2B,IAAI,CAAC;IAC3C,0EAA0E;IAC1E,yEAAyE;IACzE,yEAAyE;IACzE,2EAA2E;IAC3E,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YAC3C,MAAM,GAAG,CAAC;YACV,IAAI,GAAG,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBAC/B,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,EAAE;oBACpC,eAAe,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC;iBAC5C,CAAC,CAAC;gBACH,IAAI,OAAO;oBAAE,OAAO,GAAG,OAAO,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,CAAC;YAAS,CAAC;QACT,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,yEAAyE;IACzE,iEAAiE;IACjE,wBAAwB;IACxB,OAAO,OAAO,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC/C,CAAC;AAeD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAsB,EACtB,GAAsB;IAEtB,IAAI,GAAG,CAAC,gBAAgB,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAClE,OAAO,GAAG,CAAC;IACb,CAAC;IACD,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAM,IAAI,GAAwB,EAAE,CAAC;IACrC,IAAI,GAAG,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACvC,IAAI,CAAC,mBAAmB,GAAG,GAAG,CAAC,gBAAgB,CAAC;IAClD,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC;IACjC,CAAC;IACD,OAAO,EAAE,GAAG,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;AAC7B,CAAC;AAqBD,KAAK,UAAU,iBAAiB,CAC9B,GAAyC,EACzC,MAAoB;IAEpB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,IAAI,OAAiC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAoB,CAAC,OAAO,EAAE,EAAE;QACzD,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC;YACxB,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAc,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9D,OAAO;SACR,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB,CAC7B,GAAyC;IAEzC,KAAK,GAAG,CAAC,MAAM,CAAC,IAAa,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;QACxC,8EAA8E;IAChF,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,GAAyC,EACzC,IAAkC;IAElC,IAAI,IAAI,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACxC,CAAC;IAED,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACrB,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YACzB,sBAAsB,CAAC,GAAG,CAAC,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACxC,CAAC;QACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACpD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;YAAC,OAAO,UAAU,EAAE,CAAC;gBACpB,sCAAsC;gBACtC,OAAO,CAAC,IAAI,CACV,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,iCAAiC,EAC5D,UAAU,CACX,CAAC;YACJ,CAAC;QACH,CAAC;QACD,IAAI,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,sBAAsB,CAAC,GAAG,CAAC,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACxC,CAAC;QACD,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAM5C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA0B,EAC1B,QAAgB,EAChB,IAAI,GAAG,SAAS;IAEhB,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAS,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACjE,IAAI,YAAY,IAAI,QAAQ,EAAE,CAAC;QAC7B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE;gBACP,KAAK,EAAE,6BAA6B;gBACpC,KAAK,EAAE,YAAY;gBACnB,SAAS,EAAE,QAAQ;gBACnB,OAAO,EACL,wBAAwB,IAAI,oCAAoC;oBAChE,kEAAkE;aACrE;SACF,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,YAAY,GAAG,CAAC,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;IACvC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACvC,CAAC;AAoDD;;;;;;GAMG;AACH,MAAM,OAAgB,YAAa,SAAQ,IAAI;IACpC,eAAe,GAAG,IAAI,CAAC;IAEhC,uEAAuE;IACpD,SAAS,GAAW,SAAS,CAAC;IAE9B,QAAQ,CAAe;IACvB,KAAK,CAAS;IACd,aAAa,CAAe;IAC5B,OAAO,CAAiB;IACxB,QAAQ,CAAS;IACjB,aAAa,CAAU;IAC1C,2DAA2D;IACxC,MAAM,CAAa;IAEtC,YAAsB,OAA4B;QAChD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,0BAA0B,CAAC;QAC/D,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;IAaD,KAAK,CAAC,OAAO,CACX,OAA0B,EAC1B,MAA+B;QAE/B,MAAM,IAAI,GAAG,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACxE,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC;QAElC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,OAAO,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;QAE/B,MAAM,gBAAgB,GACpB,QAAQ,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;YAClC,CAAC,CAAC,MAAM,CAAC,kBAAkB,CAAC;YAC5B,CAAC,CAAC,IAAI,CAAC;QAEX,MAAM,GAAG,GAAG,WAAW,CAAC;YACtB,OAAO,EAAE,IAAI,CAAC,QAAQ;YACtB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACnD,YAAY,EAAE,GAAG,CAAC,YAAY;YAC9B,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,YAAY,EAAE,GAAG,CAAC,YAAY;YAC9B,YAAY,EAAE,GAAG,CAAC,YAAY;YAC9B,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa;YACtD,qEAAqE;YACrE,+CAA+C;YAC/C,UAAU,EAAE,IAAI,CAAC,MAAM,IAAI,iBAAiB,CAAC,OAAO,CAAC;YACrD,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QAEH,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,qBAAqB,CAAC,GAAG,EAAE;YAC1D,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,gBAAgB;YAChB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI,CAAC,IAAI;SACjB,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAC5B,OAAO;gBACL,KAAK,EAAE,GAAG,CAAC,SAAS;gBACpB,GAAG,GAAG,CAAC,WAAW;gBAClB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,+BAA+B;aACnE,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC5D,OAAO;gBACL,KAAK,EAAE,GAAG,CAAC,YAAY;gBACvB,GAAG,GAAG,CAAC,WAAW;gBAClB,OAAO,EAAE,GAAG,CAAC,eAAe;aAC7B,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC;CACF"}

package/dist/supervisor/prompt.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The supervisor's system prompt.
+ *
+ * A preamble over the standard execution contract, per the `StepExecutor`
+ * rule — it says what the verbs mean and what the job is, not how to finish a
+ * step.
+ */
+import type { Escalation } from "@nodetool-ai/protocol";
+export declare const SUPERVISOR_PROMPT_PREAMBLE = "# Role\nYou supervise a running workflow. A node invocation has failed. Decide what happens to it.\n\n# What you are deciding\nOne invocation, not the run. Everything else in the graph is still executing. Your verdict applies to this invocation alone.\n\n# Duties\n- Diagnose before you decide. `get_run_state` shows how the run is going; `read_node_output` shows what a node upstream of this failure produced. Read them when the error alone does not tell you what happened.\n- Give a one-line rationale with every verdict. It goes in the run report, and it is what a person reads later to understand why an item is missing.\n- Distrust `skip`. Skipping is data loss, and it is silent \u2014 the run reports success with a smaller result. Use it when an item is genuinely unprocessable, not when a failure is merely inconvenient. If you skip, name the item in your rationale.\n- `fail` is not a defeat. A guessed repair that passes validation and is wrong is worse than a failed run: the run reports success and the wrong answer flows downstream.\n\n# What the verbs mean";
+/** The prompt for one decision: verbs the escalation actually allows, then it. */
+export declare function buildSupervisorPrompt(escalation: Escalation): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/supervisor/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/supervisor/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,uBAAuB,CAAC;AAYvE,eAAO,MAAM,0BAA0B,ojCAYjB,CAAC;AAEvB,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CA+BpE"}

package/dist/supervisor/prompt.js

@@ -0,0 +1,51 @@
+/**
+ * The supervisor's system prompt.
+ *
+ * A preamble over the standard execution contract, per the `StepExecutor`
+ * rule — it says what the verbs mean and what the job is, not how to finish a
+ * step.
+ */
+const VERB_SEMANTICS = {
+    retry: "Run this invocation again, unchanged. Only useful when the failure was transient — a timeout, a rate limit, a 5xx. Offered only when the invocation spent nothing and wrote nothing, so it is never a way to pay twice.",
+    substitute: "Replace the node's output with a corrected value you supply. For a node that produced something almost right — malformed JSON, a near-miss shape. The value is type-checked against the node's declared outputs before it enters the graph; a repair that fails the check is not a repair.",
+    skip: "Retire this invocation. Downstream nodes see it as producing nothing — an item drops out of the batch. Correct when one item is genuinely unprocessable and the rest of the run is still worth having.",
+    end_stream: "End this streaming node's output where it stopped. What it already emitted stands; nothing more comes. The only recovery available once a node has emitted.",
+    fail: "Let the run fail, as it would without a supervisor. The right answer whenever recovery would be a guess."
+};
+export const SUPERVISOR_PROMPT_PREAMBLE = `# Role
+You supervise a running workflow. A node invocation has failed. Decide what happens to it.
+
+# What you are deciding
+One invocation, not the run. Everything else in the graph is still executing. Your verdict applies to this invocation alone.
+
+# Duties
+- Diagnose before you decide. \`get_run_state\` shows how the run is going; \`read_node_output\` shows what a node upstream of this failure produced. Read them when the error alone does not tell you what happened.
+- Give a one-line rationale with every verdict. It goes in the run report, and it is what a person reads later to understand why an item is missing.
+- Distrust \`skip\`. Skipping is data loss, and it is silent — the run reports success with a smaller result. Use it when an item is genuinely unprocessable, not when a failure is merely inconvenient. If you skip, name the item in your rationale.
+- \`fail\` is not a defeat. A guessed repair that passes validation and is wrong is worse than a failed run: the run reports success and the wrong answer flows downstream.
+
+# What the verbs mean`;
+/** The prompt for one decision: verbs the escalation actually allows, then it. */
+export function buildSupervisorPrompt(escalation) {
+    const verbs = escalation.allowedActions
+        .map((action) => `- \`${action}\` — ${VERB_SEMANTICS[action]}`)
+        .join("\n");
+    const omitted = Object.keys(VERB_SEMANTICS).filter((action) => !escalation.allowedActions.includes(action));
+    const unavailable = omitted.length > 0
+        ? `\n\nNot available for this failure: ${omitted.map((a) => `\`${a}\``).join(", ")}. The kernel computed that from what this node is and what this invocation already did; asking for one of them gets you \`fail\`.`
+        : "";
+    return `${SUPERVISOR_PROMPT_PREAMBLE}
+${verbs}${unavailable}
+
+# The failure
+Node \`${escalation.nodeId}\` (\`${escalation.nodeType}\`), attempt ${escalation.attempt}${escalation.invocationKey ? `, invocation \`${escalation.invocationKey}\`` : ""}.
+
+Error: ${escalation.detail}
+
+Inputs: ${JSON.stringify(escalation.inputs)}${escalation.candidateOutput === undefined
+        ? ""
+        : `\n\nThe node produced this, and it was rejected: ${JSON.stringify(escalation.candidateOutput)}`}${escalation.emitted
+        ? "\n\nThis node already emitted output downstream. Nothing can undo that."
+        : ""}`;
+}
+//# sourceMappingURL=prompt.js.map

package/dist/supervisor/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/supervisor/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,cAAc,GAAG;IACrB,KAAK,EAAE,yNAAyN;IAChO,UAAU,EACR,4RAA4R;IAC9R,IAAI,EAAE,wMAAwM;IAC9M,UAAU,EACR,6JAA6J;IAC/J,IAAI,EAAE,0GAA0G;CACzE,CAAC;AAE1C,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;;;;;;;;;;sBAYpB,CAAC;AAEvB,kFAAkF;AAClF,MAAM,UAAU,qBAAqB,CAAC,UAAsB;IAC1D,MAAM,KAAK,GAAG,UAAU,CAAC,cAAc;SACpC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,MAAM,QAAQ,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;SAC9D,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,OAAO,GAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAAqB,CAAC,MAAM,CACrE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,CACxD,CAAC;IACF,MAAM,WAAW,GACf,OAAO,CAAC,MAAM,GAAG,CAAC;QAChB,CAAC,CAAC,uCAAuC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,mIAAmI;QACrN,CAAC,CAAC,EAAE,CAAC;IAET,OAAO,GAAG,0BAA0B;EACpC,KAAK,GAAG,WAAW;;;SAGZ,UAAU,CAAC,MAAM,SAAS,UAAU,CAAC,QAAQ,gBAAgB,UAAU,CAAC,OAAO,GACpF,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,kBAAkB,UAAU,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC,EAC9E;;SAEO,UAAU,CAAC,MAAM;;UAEhB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,GACvC,UAAU,CAAC,eAAe,KAAK,SAAS;QACtC,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,oDAAoD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,eAAe,CAAC,EACpG,GACE,UAAU,CAAC,OAAO;QAChB,CAAC,CAAC,yEAAyE;QAC3E,CAAC,CAAC,EACN,EAAE,CAAC;AACL,CAAC"}

package/dist/supervisor/supervisor-agent.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The LLM-backed `SupervisorHandle`.
+ *
+ * One `StepExecutor` per decision: a fresh conversation, the verdict schema
+ * narrowed to what the kernel will accept, two read-only tools, and a hard
+ * dollar ceiling enforced turn by turn inside the provider. Everything that
+ * bounds *how many* decisions happen — counting, retries, timeouts, the sticky
+ * cache, serialization — lives in the kernel's `BoundedHandle`; this class
+ * bounds what one decision may cost and say.
+ *
+ * Every failure mode here resolves to `fail`. A supervisor that throws, times
+ * out, runs out of budget, or answers something unparseable must leave the run
+ * exactly where it would have been without a supervisor.
+ *
+ * See docs/workflow-supervisor-design.md §6.
+ */
+import type { BaseProvider, ProcessingContext } from "@nodetool-ai/runtime";
+import type { Escalation } from "@nodetool-ai/protocol";
+import { type DecisionOutcome, type RunStateReader, type SupervisorHandle } from "@nodetool-ai/kernel";
+/** Run-level ceiling on what supervision may cost, in USD. */
+export declare const DEFAULT_MAX_SUPERVISOR_COST_USD = 0.5;
+/**
+ * Output-token bound assumed for every supervisor turn. Reservation needs a
+ * known worst case, so this is never left unset — `StepExecutor.maxTokens`
+ * being optional is not good enough where a cap has to hold.
+ */
+export declare const DEFAULT_SUPERVISOR_MAX_OUTPUT_TOKENS = 2048;
+export interface SupervisorAgentOptions {
+    provider: BaseProvider;
+    model: string;
+    /**
+     * Context for tool execution and memory. The provider instance must not be
+     * shared with the run it supervises: per-turn spend is reconciled from the
+     * provider's own running cost, and a second caller on the same instance
+     * would corrupt that.
+     */
+    context: ProcessingContext;
+    /** Run-level dollar ceiling. Default {@link DEFAULT_MAX_SUPERVISOR_COST_USD}. */
+    maxCostUsd?: number;
+    /** Per-turn output bound. Default {@link DEFAULT_SUPERVISOR_MAX_OUTPUT_TOKENS}. */
+    maxOutputTokens?: number;
+    /**
+     * Resolves a reference uri against run storage, for accepting a `substitute`
+     * that carries reference-typed outputs. Omitted ⇒ such repairs are rejected,
+     * which is the safe direction: an unresolvable ref is the failure the check
+     * exists to catch.
+     */
+    resolveRef?: (uri: string) => Promise<boolean>;
+}
+export declare class SupervisorAgent implements SupervisorHandle {
+    private readonly _opts;
+    private readonly _budget;
+    private _reader;
+    private _decisions;
+    constructor(opts: SupervisorAgentOptions);
+    attach(reader: RunStateReader): void;
+    decide(escalation: Escalation, signal: AbortSignal): Promise<DecisionOutcome>;
+    close(): void;
+    private _runDecision;
+    /**
+     * A `substitute` is terminal only once its value would survive contact with
+     * the graph. Rejections go back into the still-open conversation, so the
+     * model repairs its repair instead of the kernel silently downgrading it.
+     */
+    private _accept;
+    /**
+     * Decisions and their rationales land in agent memory so a downstream
+     * compiler pass can reference them when it writes up the run.
+     */
+    private _remember;
+}
+//# sourceMappingURL=supervisor-agent.d.ts.map

package/dist/supervisor/supervisor-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-agent.d.ts","sourceRoot":"","sources":["../../src/supervisor/supervisor-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE5E,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAW7B,8DAA8D;AAC9D,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,OAAO,CAAC;AAKzD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,EAAE,iBAAiB,CAAC;IAC3B,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAID,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,UAAU,CAAK;IAEvB,YAAY,IAAI,EAAE,sBAAsB,EAOvC;IAED,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAEnC;IAEK,MAAM,CACV,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,eAAe,CAAC,CAuB1B;IAED,KAAK,IAAI,IAAI,CAEZ;YAEa,YAAY;IAoD1B;;;;OAIG;YACW,OAAO;IA4BrB;;;OAGG;IACH,OAAO,CAAC,SAAS;CAgBlB"}