@nodetool-ai/agents 0.7.0-rc.22 → 0.8.1

package/dist/supervisor/supervisor-agent.js

@@ -0,0 +1,185 @@
+/**
+ * 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 { CostCappedTurnBudget } from "@nodetool-ai/runtime";
+import { verdictSchema } from "@nodetool-ai/protocol";
+import { validateSubstituteOutputs } from "@nodetool-ai/kernel";
+import { createLogger } from "@nodetool-ai/config";
+import { StepExecutor } from "../step-executor.js";
+import { buildSupervisorPrompt } from "./prompt.js";
+import { buildVerdictSchema } from "./verdict-schema.js";
+import { createSupervisorTools } from "./tools.js";
+import { isObjectLike, isString } from "../utils/type-guards.js";
+const log = createLogger("nodetool.agents.supervisor");
+/** Run-level ceiling on what supervision may cost, in USD. */
+export 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 const DEFAULT_SUPERVISOR_MAX_OUTPUT_TOKENS = 2048;
+/** Tool-calling rounds allowed per decision. Diagnosis, then a verdict. */
+const DECISION_MAX_ITERATIONS = 6;
+const FAIL = { action: "fail" };
+export class SupervisorAgent {
+    _opts;
+    _budget;
+    _reader = null;
+    _decisions = 0;
+    constructor(opts) {
+        this._opts = opts;
+        this._budget = new CostCappedTurnBudget({
+            capUsd: opts.maxCostUsd ?? DEFAULT_MAX_SUPERVISOR_COST_USD,
+            maxOutputTokens: opts.maxOutputTokens ?? DEFAULT_SUPERVISOR_MAX_OUTPUT_TOKENS
+        });
+    }
+    attach(reader) {
+        this._reader = reader;
+    }
+    async decide(escalation, signal) {
+        const spentBefore = this._budget.spentUsd;
+        try {
+            const decision = await this._runDecision(escalation, signal);
+            const costUsd = this._budget.spentUsd - spentBefore;
+            if (decision === null) {
+                // The step never produced a verdict: refused turns, an exhausted
+                // iteration budget, an unparseable answer. Deterministic degradation.
+                return { verdict: FAIL, decidedBy: "bounds", costUsd };
+            }
+            this._remember(escalation, decision.verdict, decision.rationale);
+            return { verdict: decision.verdict, decidedBy: "agent", costUsd };
+        }
+        catch (error) {
+            log.warn("Supervisor decision failed", {
+                nodeId: escalation.nodeId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return {
+                verdict: FAIL,
+                decidedBy: "bounds",
+                costUsd: this._budget.spentUsd - spentBefore
+            };
+        }
+    }
+    close() {
+        this._reader = null;
+    }
+    async _runDecision(escalation, signal) {
+        const id = `supervisor_${++this._decisions}`;
+        const step = {
+            id,
+            instructions: buildSupervisorPrompt(escalation),
+            dependsOn: [],
+            completed: false,
+            logs: [],
+            outputSchema: JSON.stringify(buildVerdictSchema(escalation.allowedActions))
+        };
+        const task = {
+            id,
+            title: `Supervise ${escalation.nodeId}`,
+            steps: [step],
+            dependsOn: []
+        };
+        const executor = new StepExecutor({
+            task,
+            step,
+            context: this._opts.context,
+            provider: this._opts.provider,
+            model: this._opts.model,
+            tools: this._reader
+                ? createSupervisorTools(this._reader, escalation, this._opts.context)
+                : [],
+            maxIterations: DECISION_MAX_ITERATIONS,
+            maxTokens: this._opts.maxOutputTokens ?? DEFAULT_SUPERVISOR_MAX_OUTPUT_TOKENS,
+            turnBudget: this._budget,
+            acceptResult: (result) => this._accept(escalation, result),
+            signal
+        });
+        // The verdict is the result; the message stream belongs to the surfaces
+        // that wire this handle up (CLI, websocket), not to the decision itself.
+        for await (const _message of executor.execute()) {
+            if (signal.aborted)
+                break;
+        }
+        if (signal.aborted)
+            return null;
+        const result = executor.getResult();
+        const verdict = parseVerdict(result);
+        return verdict === null
+            ? null
+            : { verdict, rationale: readRationale(result) };
+    }
+    /**
+     * 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.
+     */
+    async _accept(escalation, result) {
+        const verdict = parseVerdict(result);
+        if (verdict === null) {
+            return {
+                accepted: false,
+                reason: "not a valid verdict for this escalation"
+            };
+        }
+        if (verdict.action !== "substitute")
+            return { accepted: true };
+        const checkOptions = {
+            declaredOutputs: escalation.declaredOutputs
+        };
+        if (this._opts.resolveRef) {
+            checkOptions.resolveRef = this._opts.resolveRef;
+        }
+        const validation = await validateSubstituteOutputs(verdict.outputs, checkOptions);
+        return validation.ok
+            ? { accepted: true }
+            : { accepted: false, reason: validation.issues.join("; ") };
+    }
+    /**
+     * Decisions and their rationales land in agent memory so a downstream
+     * compiler pass can reference them when it writes up the run.
+     */
+    _remember(escalation, verdict, rationale) {
+        const key = `supervisor:${escalation.nodeId}${escalation.invocationKey ? `:${escalation.invocationKey}` : ""}`;
+        this._opts.context.memory.set({
+            key,
+            kind: "shared",
+            value: { escalation, verdict, rationale },
+            source: escalation.nodeId,
+            title: `${verdict.action} — ${escalation.nodeId}: ${rationale}`
+        });
+    }
+}
+/**
+ * The model answers with a verdict plus a `rationale`; the kernel's verdict
+ * type has no such field and its schema is strict, so the rationale is split
+ * off here and kept in memory rather than dropped.
+ */
+function parseVerdict(result) {
+    if (!isObjectLike(result))
+        return null;
+    const { rationale: _rationale, ...rest } = result;
+    const parsed = verdictSchema.safeParse(rest);
+    return parsed.success ? parsed.data : null;
+}
+function readRationale(result) {
+    if (!isObjectLike(result))
+        return "";
+    const value = result["rationale"];
+    return isString(value) ? value : "";
+}
+//# sourceMappingURL=supervisor-agent.js.map

package/dist/supervisor/supervisor-agent.js.map

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

package/dist/supervisor/tools.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The supervisor's two read-only tools.
+ *
+ * Both pull from state the runner already holds, which is why there is no
+ * observation pipeline in this design: a clean run costs nothing, and the agent
+ * asks for what it needs when it needs it.
+ *
+ * `read_node_output` is scoped to the failing invocation's causal lineage. In a
+ * fan-out, "the last value this node emitted" usually belongs to some other
+ * item; handing that to the agent produces repairs built from the wrong data
+ * and quietly widens what the model sees beyond the item that failed.
+ *
+ * See docs/workflow-supervisor-design.md §6.
+ */
+import { type ZodType } from "zod";
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+import type { Escalation } from "@nodetool-ai/protocol";
+import { MAX_ESCALATION_VALUE_CHARS, redactRecord, type RunStateDigest, type RunStateReader } from "@nodetool-ai/kernel";
+import { Tool } from "../tools/base-tool.js";
+/**
+ * Secret values to mask in tool results. `read_node_output` is the one
+ * supervisor input that does not come from an already-redacted `Escalation`,
+ * so the same layer has to run here.
+ */
+type SecretSource = () => ReadonlySet<string>;
+export declare class GetRunStateTool extends Tool {
+    readonly name = "get_run_state";
+    readonly description: string;
+    private readonly _reader;
+    constructor(reader: RunStateReader);
+    get schema(): ZodType;
+    process(): Promise<RunStateDigest>;
+}
+/** What {@link ReadNodeOutputTool} answers: the branch's output, or why not. */
+export type NodeOutputReadResult = {
+    error: "not_available";
+    message: string;
+} | {
+    nodeId: string;
+    lineage: readonly string[];
+    outputs: ReturnType<typeof redactRecord>;
+};
+export declare class ReadNodeOutputTool extends Tool {
+    readonly name = "read_node_output";
+    readonly description: string;
+    private readonly _reader;
+    private readonly _escalation;
+    private readonly _secrets;
+    constructor(reader: RunStateReader, escalation: Escalation, secrets: SecretSource);
+    get schema(): ZodType;
+    process(_context: ProcessingContext, params: Record<string, unknown>): Promise<NodeOutputReadResult>;
+}
+/** The toolset for one decision, bound to the escalation being decided. */
+export declare function createSupervisorTools(reader: RunStateReader, escalation: Escalation, context: ProcessingContext): Tool[];
+export { MAX_ESCALATION_VALUE_CHARS };
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/supervisor/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAK,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,0BAA0B,EAC1B,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAE7C;;;;GAIG;AACH,KAAK,YAAY,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;AAM9C,qBAAa,eAAgB,SAAQ,IAAI;IACvC,QAAQ,CAAC,IAAI,mBAAmB;IAChC,QAAQ,CAAC,WAAW,SAG0B;IAE9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IAEzC,YAAY,MAAM,EAAE,cAAc,EAGjC;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAEK,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAEvC;CACF;AAED,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAC5B;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3C;IACE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;CAC1C,CAAC;AAEN,qBAAa,kBAAmB,SAAQ,IAAI;IAC1C,QAAQ,CAAC,IAAI,sBAAsB;IACnC,QAAQ,CAAC,WAAW,SAIP;IAEb,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IAExC,YACE,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,YAAY,EAMtB;IAED,IAAI,MAAM,IAAI,OAAO,CAIpB;IAEK,OAAO,CACX,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CAmB/B;CACF;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,iBAAiB,GACzB,IAAI,EAAE,CAKR;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/supervisor/tools.js

@@ -0,0 +1,83 @@
+/**
+ * The supervisor's two read-only tools.
+ *
+ * Both pull from state the runner already holds, which is why there is no
+ * observation pipeline in this design: a clean run costs nothing, and the agent
+ * asks for what it needs when it needs it.
+ *
+ * `read_node_output` is scoped to the failing invocation's causal lineage. In a
+ * fan-out, "the last value this node emitted" usually belongs to some other
+ * item; handing that to the agent produces repairs built from the wrong data
+ * and quietly widens what the model sees beyond the item that failed.
+ *
+ * See docs/workflow-supervisor-design.md §6.
+ */
+import { z } from "zod";
+import { MAX_ESCALATION_VALUE_CHARS, redactRecord } from "@nodetool-ai/kernel";
+import { Tool } from "../tools/base-tool.js";
+function resolveSecrets(context) {
+    return context.getResolvedSecretValues?.() ?? new Set();
+}
+export class GetRunStateTool extends Tool {
+    name = "get_run_state";
+    description = "Digest of the run in flight: every node's status, how many invocations " +
+        "it has emitted, how many times it has escalated, its error if it has " +
+        "one, and the run's provider spend so far.";
+    _reader;
+    constructor(reader) {
+        super();
+        this._reader = reader;
+    }
+    get schema() {
+        return z.object({});
+    }
+    async process() {
+        return this._reader.digest();
+    }
+}
+export class ReadNodeOutputTool extends Tool {
+    name = "read_node_output";
+    description = "The output a node produced for the failing invocation's own branch of " +
+        "the run. Reads outside that branch — another item of the same fan-out, " +
+        "an unrelated branch — are refused: that data is not evidence about this " +
+        "failure.";
+    _reader;
+    _escalation;
+    _secrets;
+    constructor(reader, escalation, secrets) {
+        super();
+        this._reader = reader;
+        this._escalation = escalation;
+        this._secrets = secrets;
+    }
+    get schema() {
+        return z.object({
+            node_id: z.string().describe("Id of the node whose output to read.")
+        });
+    }
+    async process(_context, params) {
+        const nodeId = String(params["node_id"] ?? "");
+        const read = this._reader.readOutput(nodeId, this._escalation.correlationLineage);
+        if (!read) {
+            return {
+                error: "not_available",
+                message: `No output from "${nodeId}" belongs to this invocation's branch ` +
+                    `(${this._escalation.correlationLineage.join(",") || "root"}).`
+            };
+        }
+        return {
+            nodeId: read.nodeId,
+            lineage: read.lineage,
+            outputs: redactRecord(read.outputs, this._secrets())
+        };
+    }
+}
+/** The toolset for one decision, bound to the escalation being decided. */
+export function createSupervisorTools(reader, escalation, context) {
+    return [
+        new GetRunStateTool(reader),
+        new ReadNodeOutputTool(reader, escalation, () => resolveSecrets(context))
+    ];
+}
+export { MAX_ESCALATION_VALUE_CHARS };
+//# sourceMappingURL=tools.js.map

package/dist/supervisor/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/supervisor/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAgB,MAAM,KAAK,CAAC;AAGtC,OAAO,EACL,0BAA0B,EAC1B,YAAY,EAGb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAS7C,SAAS,cAAc,CAAC,OAA0B;IAChD,OAAO,OAAO,CAAC,uBAAuB,EAAE,EAAE,IAAI,IAAI,GAAG,EAAU,CAAC;AAClE,CAAC;AAED,MAAM,OAAO,eAAgB,SAAQ,IAAI;IAC9B,IAAI,GAAG,eAAe,CAAC;IACvB,WAAW,GAClB,yEAAyE;QACzE,uEAAuE;QACvE,2CAA2C,CAAC;IAE7B,OAAO,CAAiB;IAEzC,YAAY,MAAsB;QAChC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;IAC/B,CAAC;CACF;AAWD,MAAM,OAAO,kBAAmB,SAAQ,IAAI;IACjC,IAAI,GAAG,kBAAkB,CAAC;IAC1B,WAAW,GAClB,wEAAwE;QACxE,yEAAyE;QACzE,0EAA0E;QAC1E,UAAU,CAAC;IAEI,OAAO,CAAiB;IACxB,WAAW,CAAa;IACxB,QAAQ,CAAe;IAExC,YACE,MAAsB,EACtB,UAAsB,EACtB,OAAqB;QAErB,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,CAAC,CAAC,MAAM,CAAC;YACd,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;SACrE,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,CACX,QAA2B,EAC3B,MAA+B;QAE/B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAClC,MAAM,EACN,IAAI,CAAC,WAAW,CAAC,kBAAkB,CACpC,CAAC;QACF,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO;gBACL,KAAK,EAAE,eAAe;gBACtB,OAAO,EACL,mBAAmB,MAAM,wCAAwC;oBACjE,IAAI,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,MAAM,IAAI;aAClE,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;SACrD,CAAC;IACJ,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,UAAU,qBAAqB,CACnC,MAAsB,EACtB,UAAsB,EACtB,OAA0B;IAE1B,OAAO;QACL,IAAI,eAAe,CAAC,MAAM,CAAC;QAC3B,IAAI,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/supervisor/verdict-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The verdict contract handed to the model, narrowed to what the kernel will
+ * actually accept for one escalation.
+ *
+ * The kernel computes `allowedActions` per escalation and rejects anything
+ * outside it. Offering the full verb list anyway would spend a decision to
+ * produce an answer that is thrown away, so the schema is built per decision
+ * from that set. Enforcement stays in the kernel — this only stops the model
+ * from wasting a round.
+ */
+import type { VerdictAction } from "@nodetool-ai/protocol";
+/** JSON schema for a verdict, restricted to `allowed`. */
+export declare function buildVerdictSchema(allowed: readonly VerdictAction[]): {
+    type: string;
+    description: string;
+    oneOf: Record<string, unknown>[];
+};
+//# sourceMappingURL=verdict-schema.d.ts.map

package/dist/supervisor/verdict-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-schema.d.ts","sourceRoot":"","sources":["../../src/supervisor/verdict-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAgD3D,0DAA0D;AAC1D,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,aAAa,EAAE;IAG/B,IAAI;IACJ,WAAW;IACX,KAAK;EAER"}

package/dist/supervisor/verdict-schema.js

@@ -0,0 +1,58 @@
+/**
+ * The verdict contract handed to the model, narrowed to what the kernel will
+ * actually accept for one escalation.
+ *
+ * The kernel computes `allowedActions` per escalation and rejects anything
+ * outside it. Offering the full verb list anyway would spend a decision to
+ * produce an answer that is thrown away, so the schema is built per decision
+ * from that set. Enforcement stays in the kernel — this only stops the model
+ * from wasting a round.
+ */
+const RATIONALE = {
+    type: "string",
+    description: "One line: why this verdict. Appears in the run report next to the node.",
+    minLength: 1
+};
+const APPLY_TO = {
+    type: "string",
+    enum: ["invocation", "signature"],
+    description: "`invocation` (default) decides this failure only. `signature` decides " +
+        "every later failure on this node with the same failure signature, with " +
+        "no further deliberation — use it when the cause is categorical, not " +
+        "specific to this item."
+};
+function branch(action) {
+    const base = {
+        type: "object",
+        properties: {
+            action: { type: "string", const: action },
+            rationale: RATIONALE
+        },
+        required: ["action", "rationale"],
+        additionalProperties: false
+    };
+    const properties = base["properties"];
+    const required = base["required"];
+    if (action === "substitute") {
+        properties["outputs"] = {
+            type: "object",
+            description: "Replacement value per output slot of the node. Type-checked against " +
+                "the node's declared outputs before it enters the graph.",
+            additionalProperties: true
+        };
+        required.push("outputs");
+    }
+    if (action === "skip" || action === "fail") {
+        properties["applyTo"] = APPLY_TO;
+    }
+    return base;
+}
+/** JSON schema for a verdict, restricted to `allowed`. */
+export function buildVerdictSchema(allowed) {
+    return {
+        type: "object",
+        description: "The verdict for this failed invocation.",
+        oneOf: allowed.map(branch)
+    };
+}
+//# sourceMappingURL=verdict-schema.js.map

package/dist/supervisor/verdict-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-schema.js","sourceRoot":"","sources":["../../src/supervisor/verdict-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,SAAS,GAAG;IAChB,IAAI,EAAE,QAAQ;IACd,WAAW,EACT,yEAAyE;IAC3E,SAAS,EAAE,CAAC;CACJ,CAAC;AAEX,MAAM,QAAQ,GAAG;IACf,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,CAAC,YAAY,EAAE,WAAW,CAAC;IACjC,WAAW,EACT,wEAAwE;QACxE,yEAAyE;QACzE,sEAAsE;QACtE,wBAAwB;CAClB,CAAC;AAEX,SAAS,MAAM,CAAC,MAAqB;IACnC,MAAM,IAAI,GAA4B;QACpC,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE;YACzC,SAAS,EAAE,SAAS;SACrB;QACD,QAAQ,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC;QACjC,oBAAoB,EAAE,KAAK;KAC5B,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAA4B,CAAC;IACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAa,CAAC;IAE9C,IAAI,MAAM,KAAK,YAAY,EAAE,CAAC;QAC5B,UAAU,CAAC,SAAS,CAAC,GAAG;YACtB,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,sEAAsE;gBACtE,yDAAyD;YAC3D,oBAAoB,EAAE,IAAI;SAC3B,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QAC3C,UAAU,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC;IACnC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,kBAAkB,CAChC,OAAiC;IAEjC,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,yCAAyC;QACtD,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;KAC3B,CAAC;AACJ,CAAC"}

package/dist/system-skills.d.ts

@@ -0,0 +1,68 @@
+/**
+ * System skills — the instruction documents that ship with NodeTool.
+ *
+ * A user skill is a row someone wrote and can rewrite. A system skill is a
+ * `SKILL.md` in the build: same shape in the prompt, but **immutable**, so a
+ * workflow the product depends on cannot be edited away by an agent that
+ * mis-read its own instructions, and every install has it on day one without a
+ * seeding migration that then drifts per machine.
+ *
+ * Nothing imports these files, so they are not a workspace and npm links
+ * nothing. Discovery mirrors the sandbox packs (`shippedPackSearchPaths`):
+ * `_skills/` beside the bundled `server.mjs`, else `packages/system-skills` on
+ * the way up from this module, else `NODETOOL_SYSTEM_SKILLS_DIR`.
+ *
+ * Their names are **reserved**: `create_skill` and `update_skill` refuse them,
+ * so a user row can never shadow one going forward.
+ */
+/** One shipped skill, as the catalog and `load_skill` both see it. */
+export interface SystemSkill {
+    readonly name: string;
+    readonly description: string;
+    readonly content: string;
+    /** Always true — the field exists so a merged list stays self-describing. */
+    readonly system: true;
+}
+/** The directory holding the shipped skills, or null when this build has none. */
+export declare function systemSkillsDir(): string | null;
+/**
+ * Split a `SKILL.md` into its frontmatter fields and body.
+ *
+ * Deliberately not a YAML parse: the frontmatter is two scalar fields, and
+ * pulling js-yaml into the host to read them would buy nothing. A file whose
+ * frontmatter is missing or malformed yields null and is skipped rather than
+ * failing the whole catalog — one bad shipped file must not cost a user every
+ * other skill.
+ */
+export declare function parseSkillMarkdown(text: string): {
+    name: string;
+    description: string;
+    content: string;
+} | null;
+/**
+ * Every shipped skill, read once per process.
+ *
+ * Cached because the files are part of the build and cannot change under a
+ * running server; `clearSystemSkillCache` exists for tests that stage a
+ * directory of their own.
+ */
+export declare function loadSystemSkills(): readonly SystemSkill[];
+/** Drop the cache. Tests only. */
+export declare function clearSystemSkillCache(): void;
+/** Whether `name` belongs to a shipped skill, and is therefore not writable. */
+export declare function isSystemSkillName(name: string): boolean;
+/** One shipped skill by name, or null. */
+export declare function findSystemSkill(name: string): SystemSkill | null;
+/**
+ * The catalog a prompt or `list_skills` should show: the user's rows, plus every
+ * shipped skill the user has not already taken the name of.
+ *
+ * A pre-existing user row wins on a collision. Reserving the names only stops
+ * *new* ones, so a row written before a skill shipped keeps working — and the
+ * person who wrote it gets what they wrote.
+ */
+export declare function mergeSystemSkills<T extends {
+    name: string;
+    description: string;
+}>(userSkills: readonly T[]): (T | SystemSkill)[];
+//# sourceMappingURL=system-skills.d.ts.map

package/dist/system-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-skills.d.ts","sourceRoot":"","sources":["../src/system-skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;CACvB;AAED,kFAAkF;AAClF,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAiB/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CAgCP;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,SAAS,WAAW,EAAE,CAIzD;AAED,kCAAkC;AAClC,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAkCD,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED,0CAA0C;AAC1C,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAGhE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAC/E,UAAU,EAAE,SAAS,CAAC,EAAE,GACvB,CAAC,CAAC,GAAG,WAAW,CAAC,EAAE,CAIrB"}