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

package/dist/app-build/judge.js

@@ -0,0 +1,318 @@
+/**
+ * The Judge stage: does the app the build produced actually do what was asked?
+ *
+ * Check and Run answer structural questions — the wiring resolves, the run
+ * completed, the widget received a value. None of them can tell a real German
+ * translation from the English echoed back, so a Check+Run-green app gets one
+ * structured-output call per interaction, following the `goal-judge` pattern
+ * the `graph-e2e` suite uses: the spec's plain-language intent, the steps the
+ * user performed, and the widget states those steps left behind, in, and
+ * `{ achieved, confidence, reasons }` out.
+ *
+ * Fail closed (docs/mini-app-build-harness-design.md §7): a judge that times
+ * out, errors, or answers with something unparseable scores the interaction as
+ * *not achieved*, so a broken judge never green-lights an app. The reasons
+ * carry the failure so the report says why.
+ *
+ * The judge is configured independently of the builder — `--judge-model`,
+ * `NODETOOL_APP_JUDGE_MODEL`, and a default that prefers a model the builder
+ * did not use — because a model grading its own work is the weakest reviewer
+ * available. {@link JudgeRecord.model} records which one actually ran.
+ */
+import { previewValue } from "@nodetool-ai/execution/debug";
+import { isBoolean, isNumber, isObjectLike, isString } from "../utils/type-guards.js";
+/** Ceiling on one judgement's answer. Two sentences of reasoning, no essays. */
+const JUDGE_MAX_TOKENS = 600;
+/** Wall clock for one judgement. Exhausted ⇒ not achieved. */
+export const DEFAULT_JUDGE_TIMEOUT_MS = 60_000;
+/**
+ * Judge models tried in order when nothing is configured, best first. Whichever
+ * is available and is not what the builder used wins; see
+ * {@link resolveJudgeModelSpec}.
+ */
+export const JUDGE_MODEL_CANDIDATES = [
+    "anthropic/claude-sonnet-4-6",
+    "openai/gpt-5.4-mini",
+    "gemini/gemini-2.5-flash"
+];
+const SYSTEM_PROMPT = `You grade a mini app that an automated builder just produced.
+
+You are given what the app was asked to do, one interaction a user performed
+with it, and the state every widget was left in afterwards.
+
+Judge ONLY whether that interaction achieved what was asked. Ignore how the app
+was built, which widgets it uses, and how you would have worded the result.
+Formatting, length and phrasing may vary freely — content is what counts. A
+widget that is empty, shows an error, shows an unfilled placeholder, or echoes
+the input where new content was required does NOT achieve the intent.
+
+Answer with a single JSON object and nothing else:
+{"achieved": true|false, "confidence": 0.0-1.0, "reasons": ["…"]}
+
+"achieved" is your verdict. "confidence" is how sure you are of it. "reasons"
+is one to three short strings quoting the widget state that decided it; when
+the verdict is false they must say what is wrong, because the builder repairs
+the app from them.`;
+/** Split `provider/model`, deciding the cut with the caller's provider list. */
+function splitSpec(spec, isProvider) {
+    const cut = spec.indexOf("/");
+    if (cut === -1)
+        return null;
+    const head = spec.slice(0, cut).toLowerCase();
+    return isProvider(head)
+        ? { providerId: head, model: spec.slice(cut + 1) }
+        : null;
+}
+/**
+ * Which model judges this build.
+ *
+ * An explicit `--judge-model` wins, then `NODETOOL_APP_JUDGE_MODEL`, then the
+ * first {@link JUDGE_MODEL_CANDIDATES} entry that is available and differs from
+ * the builder. When nothing else can be reached the builder judges its own work
+ * — reported as such rather than skipped, since a weak reviewer still catches
+ * an empty output.
+ */
+export function resolveJudgeModelSpec(opts) {
+    const builder = {
+        spec: `${opts.builderProviderId}/${opts.builderModel}`,
+        providerId: opts.builderProviderId,
+        model: opts.builderModel,
+        sameAsBuilder: true
+    };
+    const isAvailable = opts.isAvailable ?? ((id) => id === opts.builderProviderId);
+    const isProvider = (id) => isAvailable(id) || id === opts.builderProviderId;
+    const configured = opts.explicit ?? (opts.env ?? process.env)["NODETOOL_APP_JUDGE_MODEL"];
+    if (configured) {
+        const parts = splitSpec(configured, isProvider);
+        if (parts) {
+            return {
+                spec: configured,
+                ...parts,
+                sameAsBuilder: parts.providerId === opts.builderProviderId &&
+                    parts.model === opts.builderModel
+            };
+        }
+        // A bare model id names a model on the builder's own provider.
+        return {
+            spec: `${opts.builderProviderId}/${configured}`,
+            providerId: opts.builderProviderId,
+            model: configured,
+            sameAsBuilder: configured === opts.builderModel
+        };
+    }
+    for (const candidate of JUDGE_MODEL_CANDIDATES) {
+        const parts = splitSpec(candidate, isProvider);
+        if (!parts || !isAvailable(parts.providerId))
+            continue;
+        if (parts.providerId === opts.builderProviderId &&
+            parts.model === opts.builderModel) {
+            continue;
+        }
+        return { spec: candidate, ...parts, sameAsBuilder: false };
+    }
+    return builder;
+}
+/** Render one interaction step for the judge. */
+const stepText = (step) => JSON.stringify(step);
+const widgetText = (widget) => {
+    const label = widget.label ? ` "${widget.label}"` : "";
+    const value = JSON.stringify(previewValue(widget.value)) ?? "null";
+    return `- ${widget.widget} (${widget.type}${label}): ${value}`;
+};
+/** Everything the judge is told about one interaction. */
+export function renderJudgePrompt(spec, input, prompt) {
+    const objectives = spec.operations
+        .map((operation) => `- ${operation.id}: ${operation.objective || "(bound to an existing workflow)"}`)
+        .join("\n");
+    return [
+        `APP: ${spec.title}`,
+        prompt ? `WHAT THE USER ASKED FOR:\n${prompt}` : "",
+        `WHAT EACH OPERATION IS FOR:\n${objectives || "(none declared)"}`,
+        `INTERACTION: ${input.interaction.name}`,
+        `STEPS THE USER PERFORMED:\n${input.interaction.steps.map(stepText).join("\n") || "(none)"}`,
+        `WIDGET STATE AFTERWARDS:\n${input.widgets.map(widgetText).join("\n") || "(no widgets)"}`
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+}
+/**
+ * Parse the judge's answer. Accepts a bare JSON object or one wrapped in prose
+ * or a fenced block; anything else returns null so the caller fails closed
+ * instead of guessing a verdict.
+ */
+export function parseJudgeAnswer(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+    if (!isObjectLike(parsed))
+        return null;
+    const obj = parsed;
+    if (!isBoolean(obj.achieved))
+        return null;
+    const raw = isNumber(obj.confidence) ? obj.confidence : NaN;
+    const confidence = Number.isFinite(raw) ? Math.min(1, Math.max(0, raw)) : 0;
+    const reasons = Array.isArray(obj.reasons)
+        ? obj.reasons
+            .map((reason) => String(reason))
+            .filter((reason) => reason.length > 0)
+        : isString(obj.reasons)
+            ? [obj.reasons]
+            : [];
+    return {
+        achieved: obj.achieved,
+        confidence,
+        reasons: reasons.length > 0 ? reasons : ["(no reason given)"]
+    };
+}
+function extractText(content) {
+    if (isString(content))
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => isObjectLike(part) && "text" in part
+        ? String(part.text ?? "")
+        : "")
+        .join("");
+}
+/** A judgement that failed closed, carrying why. */
+const notAchieved = (interaction, reason) => ({
+    interaction,
+    achieved: false,
+    confidence: 0,
+    reasons: [reason]
+});
+/**
+ * Judge one interaction. Never throws: a provider failure, a timeout, or an
+ * unparseable answer resolves as not achieved with the failure as its reason.
+ */
+export async function judgeInteraction(opts) {
+    const name = opts.input.interaction.name;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_JUDGE_TIMEOUT_MS;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    opts.signal?.addEventListener("abort", abort);
+    let timedOut = false;
+    /**
+     * The deadline is a race, not just an abort: a provider that ignores the
+     * signal would otherwise never resolve, and the fail-closed verdict this
+     * function promises would never be produced.
+     */
+    const expired = Symbol("judge-timeout");
+    let expire = () => { };
+    const deadline = new Promise((resolve) => {
+        expire = resolve;
+    });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+        expire(expired);
+    }, timeoutMs);
+    try {
+        const reply = await Promise.race([
+            opts.provider.generateMessageTraced({
+                messages: [
+                    { role: "system", content: SYSTEM_PROMPT },
+                    {
+                        role: "user",
+                        content: renderJudgePrompt(opts.spec, opts.input, opts.prompt)
+                    }
+                ],
+                model: opts.model,
+                tools: [],
+                maxTokens: JUDGE_MAX_TOKENS,
+                temperature: 0,
+                signal: controller.signal
+            }),
+            deadline
+        ]);
+        if (reply === expired) {
+            return notAchieved(name, `the judge did not answer within ${timeoutMs}ms, so the interaction counts as not achieved`);
+        }
+        const answer = parseJudgeAnswer(extractText(reply.content));
+        if (!answer) {
+            return notAchieved(name, "the judge's answer was not parseable JSON, so the interaction counts as not achieved");
+        }
+        return { interaction: name, ...answer };
+    }
+    catch (error) {
+        if (timedOut) {
+            return notAchieved(name, `the judge did not answer within ${timeoutMs}ms, so the interaction counts as not achieved`);
+        }
+        return notAchieved(name, `the judge call failed (${error instanceof Error ? error.message : String(error)}), so the interaction counts as not achieved`);
+    }
+    finally {
+        clearTimeout(timer);
+        opts.signal?.removeEventListener("abort", abort);
+    }
+}
+/**
+ * Judge every interaction of a Check+Run-green app. The stage record carries
+ * the spend and a one-line summary; the {@link JudgeRecord} carries the
+ * verdicts the orchestrator turns into complaints.
+ */
+export async function runJudgeStage(opts) {
+    const startedAt = Date.now();
+    const costBefore = opts.provider.getTotalCost();
+    const verdicts = [];
+    for (const input of opts.interactions) {
+        if (opts.signal?.aborted) {
+            verdicts.push(notAchieved(input.interaction.name, "the build was cancelled before this interaction was judged"));
+            continue;
+        }
+        const judgeArgs = {
+            spec: opts.spec,
+            provider: opts.provider,
+            model: opts.model,
+            input
+        };
+        if (opts.prompt !== undefined)
+            judgeArgs.prompt = opts.prompt;
+        if (opts.timeoutMs !== undefined)
+            judgeArgs.timeoutMs = opts.timeoutMs;
+        if (opts.signal)
+            judgeArgs.signal = opts.signal;
+        const verdict = await judgeInteraction(judgeArgs);
+        verdicts.push(verdict);
+        opts.onLog?.(`judge: ${verdict.interaction} — ${verdict.achieved ? "achieved" : "not achieved"}`);
+    }
+    // A not-achieved verdict is the round's complaint: the reasons are what the
+    // Author is given to repair from, so they travel as the issue's message.
+    const issues = verdicts
+        .filter((verdict) => !verdict.achieved)
+        .map((verdict) => ({
+        stage: "judge",
+        code: "goal_not_achieved",
+        severity: "error",
+        message: `interaction "${verdict.interaction}": ${verdict.reasons.join("; ")}`
+    }));
+    return {
+        judge: {
+            model: `${opts.provider.provider}/${opts.model}`,
+            interactions: verdicts
+        },
+        record: {
+            stage: "judge",
+            round: opts.round,
+            // The judge defaults away from the builder, so its spend bills to the
+            // model that actually ran.
+            provider: opts.provider.provider,
+            model: opts.model,
+            startedAt: new Date(startedAt).toISOString(),
+            durationMs: Date.now() - startedAt,
+            issues,
+            costUsd: opts.provider.getTotalCost() - costBefore,
+            status: issues.length > 0 ? "failed" : "ok",
+            detail: `${verdicts.length} interaction(s), ${issues.length} not achieved`
+        }
+    };
+}
+//# sourceMappingURL=judge.js.map

package/dist/app-build/judge.js.map

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

package/dist/app-build/markdown.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The human half of a build report.
+ *
+ * `report.json` is what an agent reads; this is what a person opens first, so
+ * it leads with the verdict and the issues that produced it and leaves the
+ * evidence to the JSON.
+ */
+import type { BuildReport } from "./types.js";
+export declare function renderBuildReportMarkdown(report: BuildReport): string;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/app-build/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/app-build/markdown.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAoFrE"}

package/dist/app-build/markdown.js

@@ -0,0 +1,65 @@
+/**
+ * The human half of a build report.
+ *
+ * `report.json` is what an agent reads; this is what a person opens first, so
+ * it leads with the verdict and the issues that produced it and leaves the
+ * evidence to the JSON.
+ */
+import { formatSupervisedSummary } from "@nodetool-ai/execution/debug";
+const money = (usd) => `$${usd.toFixed(4)}`;
+export function renderBuildReportMarkdown(report) {
+    const lines = [];
+    const title = report.spec.title || "app build";
+    lines.push(`# ${title}`, "");
+    lines.push(`**${report.verdict.ok ? "OK" : "FAILED"}** — ${report.verdict.reason}`, "");
+    lines.push(`- target: ${report.target.specPath ?? (report.target.prompt || "(none)")}`, `- operations: ${report.spec.operations.length}`, `- widgets: ${report.spec.widgets.length}`, `- interactions: ${report.interactions.length}`, `- repair rounds: ${report.repairs.length}`, `- cost: ${money(report.cost.usd)}`, "");
+    lines.push("## Stages", "");
+    lines.push("| stage | round | status | ms | cost | detail |");
+    lines.push("| --- | --- | --- | --- | --- | --- |");
+    for (const stage of report.stages) {
+        lines.push(`| ${stage.stage} | ${stage.round} | ${stage.status} | ${stage.durationMs} | ${money(stage.costUsd)} | ${stage.detail ?? ""} |`);
+    }
+    lines.push("");
+    if (report.repairs.length > 0) {
+        lines.push("## Repairs", "");
+        for (const complaint of report.repairs) {
+            lines.push(`### Round ${complaint.round}`, "");
+            for (const issue of complaint.issues) {
+                lines.push(`- \`${issue.stage}/${issue.code}\` ${issue.message}`);
+            }
+            lines.push("");
+        }
+    }
+    lines.push("## Interactions", "");
+    for (const interaction of report.interactions) {
+        lines.push(`- **${interaction.name}**${interaction.derived ? " (derived)" : ""} — ${interaction.steps.length} step(s), ${interaction.expect.length} expectation(s)`);
+        for (const added of interaction.addedSteps) {
+            lines.push(`  - seeded: ${added}`);
+        }
+    }
+    lines.push("");
+    if (report.judge) {
+        lines.push("## Judge", "", `Model: ${report.judge.model}`, "");
+        for (const verdict of report.judge.interactions) {
+            lines.push(`- ${verdict.interaction}: ${verdict.achieved ? "achieved" : "not achieved"} — ${verdict.reasons.join("; ")}`);
+        }
+        lines.push("");
+    }
+    if (report.supervision) {
+        lines.push("## Supervision", "", formatSupervisedSummary(report.supervision.summary), "");
+        for (const entry of report.supervision.byInteraction) {
+            for (const item of entry.interventions) {
+                lines.push(`- **${entry.interaction}** — ${item.verdict.action} on \`${item.escalation.nodeId}\` (${item.decidedBy}): ${item.escalation.detail}`);
+            }
+        }
+        lines.push("");
+    }
+    if (report.verdict.notSimulated.length > 0) {
+        lines.push("## Not simulated", "");
+        for (const entry of report.verdict.notSimulated)
+            lines.push(`- ${entry}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=markdown.js.map

package/dist/app-build/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/app-build/markdown.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,MAAM,KAAK,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AAE5D,MAAM,UAAU,yBAAyB,CAAC,MAAmB;IAC3D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,WAAW,CAAC;IAC/C,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7B,KAAK,CAAC,IAAI,CACR,KAAK,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,QAAQ,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EACvE,EAAE,CACH,CAAC;IACF,KAAK,CAAC,IAAI,CACR,aAAa,MAAM,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC,EAAE,EAC3E,iBAAiB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAChD,cAAc,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAC1C,mBAAmB,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,EAC/C,oBAAoB,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAC3C,WAAW,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EACnC,EAAE,CACH,CAAC;IAEF,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC5B,KAAK,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;IAC9D,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IACpD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CACR,KAAK,KAAK,CAAC,KAAK,MAAM,KAAK,CAAC,KAAK,MAAM,KAAK,CAAC,MAAM,MAAM,KAAK,CAAC,UAAU,MAAM,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,MAAM,IAAI,EAAE,IAAI,CAChI,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAC7B,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,aAAa,SAAS,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;YAC/C,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;gBACrC,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACpE,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAClC,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9C,KAAK,CAAC,IAAI,CACR,OAAO,WAAW,CAAC,IAAI,KAAK,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,WAAW,CAAC,KAAK,CAAC,MAAM,aAAa,WAAW,CAAC,MAAM,CAAC,MAAM,iBAAiB,CACzJ,CAAC;QACF,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,UAAU,EAAE,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,eAAe,KAAK,EAAE,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,EAAE,UAAU,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QAC/D,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;YAChD,KAAK,CAAC,IAAI,CACR,KAAK,OAAO,CAAC,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC9G,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CACR,gBAAgB,EAChB,EAAE,EACF,uBAAuB,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,EACnD,EAAE,CACH,CAAC;QACF,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC;YACrD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;gBACvC,KAAK,CAAC,IAAI,CACR,OAAO,KAAK,CAAC,WAAW,QAAQ,IAAI,CAAC,OAAO,CAAC,MAAM,SAAS,IAAI,CAAC,UAAU,CAAC,MAAM,OAAO,IAAI,CAAC,SAAS,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CACtI,CAAC;YACJ,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;QACnC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;QAC1E,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/app-build/spec.d.ts

@@ -0,0 +1,228 @@
+/**
+ * The Spec stage: a prompt becomes a {@link BuildSpec}, or the build refuses.
+ *
+ * One `StepExecutor` call with the spec as `outputSchema`. The schema pins the
+ * shape; everything the schema cannot express — a widget type the catalog does
+ * not have, a binding that names an input no operation declares, an interaction
+ * that clicks a widget nobody placed — is checked here, before a single
+ * planning token is spent, and bounced back into the still-open conversation
+ * through the executor's acceptance callback. After
+ * {@link MAX_REPAIR_ROUNDS} bounces the build fails with the validation record
+ * as its reason: refuse rather than guess.
+ *
+ * `specFromFile` is the same validation with no model attached, so a
+ * hand-written `spec.json` enters the build through exactly one gate.
+ */
+import type { BaseProvider, ProcessingContext } from "@nodetool-ai/runtime";
+import type { TurnBudget } from "@nodetool-ai/runtime";
+import type { BuildIssue, BuildSpec, BuildSpecInteraction, StageRecord } from "./types.js";
+/** The JSON schema the model answers with. */
+export declare const BUILD_SPEC_SCHEMA: {
+    type: string;
+    required: string[];
+    properties: {
+        title: {
+            type: string;
+            minLength: number;
+        };
+        operations: {
+            type: string;
+            minItems: number;
+            items: {
+                type: string;
+                required: string[];
+                properties: {
+                    id: {
+                        type: string;
+                        minLength: number;
+                    };
+                    objective: {
+                        type: string;
+                    };
+                    workflowId: {
+                        type: string;
+                    };
+                    inputs: {
+                        type: string;
+                        items: {
+                            type: string;
+                            required: string[];
+                            properties: {
+                                name: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                                type: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                                example: {};
+                            };
+                        };
+                    };
+                    outputs: {
+                        type: string;
+                        items: {
+                            type: string;
+                            required: string[];
+                            properties: {
+                                name: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                                type: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                            };
+                        };
+                    };
+                    streaming: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        variables: {
+            type: string;
+            items: {
+                type: string;
+                required: string[];
+                properties: {
+                    id: {
+                        type: string;
+                        minLength: number;
+                    };
+                    scope: {
+                        type: string;
+                        enum: string[];
+                    };
+                    persist: {
+                        type: string;
+                    };
+                    writtenBy: {
+                        type: string;
+                        minLength: number;
+                    };
+                    readBy: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+        widgets: {
+            type: string;
+            minItems: number;
+            items: {
+                type: string;
+                required: string[];
+                properties: {
+                    role: {
+                        type: string;
+                        minLength: number;
+                    };
+                    type: {
+                        type: string;
+                        minLength: number;
+                    };
+                    binding: {
+                        type: string;
+                    };
+                    label: {
+                        type: string;
+                    };
+                    container: {
+                        type: string;
+                    };
+                    visibleWhen: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        interactions: {
+            type: string;
+            items: {
+                type: string;
+                required: string[];
+                properties: {
+                    name: {
+                        type: string;
+                        minLength: number;
+                    };
+                    steps: {
+                        type: string;
+                        items: {
+                            anyOf: Record<string, unknown>[];
+                        };
+                    };
+                    expect: {
+                        type: string;
+                        items: {
+                            type: string;
+                            required: string[];
+                            properties: {
+                                widget: {
+                                    type: string;
+                                    minLength: number;
+                                };
+                                check: {
+                                    type: string;
+                                    enum: string[];
+                                };
+                                value: {};
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+/**
+ * Resolve a widget reference the way the simulator does: component id (here the
+ * spec's `role`), then label, then a unique type.
+ */
+export declare function resolveSpecWidget(spec: BuildSpec, ref: string): BuildSpec["widgets"][number] | null;
+/**
+ * Which operations an interaction touches. The spec has no widget events yet —
+ * authoring assigns those — so this reads the vocabulary the spec does have:
+ * explicit `run`/`cancel`, a `set` that names an operation, and the operation
+ * any referenced widget's binding points at.
+ */
+export declare function operationsExercised(spec: BuildSpec, interaction: BuildSpecInteraction): Set<string>;
+/**
+ * Everything the schema cannot express. Returns every problem found, so one
+ * bounce can fix them all.
+ */
+export declare function validateBuildSpec(spec: BuildSpec): BuildIssue[];
+/** Schema check then catalog check. The one gate every spec passes through. */
+export declare function parseBuildSpec(raw: unknown): {
+    spec: BuildSpec | null;
+    issues: BuildIssue[];
+};
+export interface SpecStageOptions {
+    /** What the user asked for. */
+    prompt: string;
+    provider: BaseProvider;
+    model: string;
+    context: ProcessingContext;
+    /** Spend admission, shared with the rest of the build. */
+    turnBudget?: TurnBudget;
+    maxTokens?: number;
+    signal?: AbortSignal;
+}
+export interface SpecStageResult {
+    /** Null when the prompt could not be pinned — see the record. */
+    spec: BuildSpec | null;
+    record: StageRecord;
+}
+/** Load a hand-written `spec.json`: same validation, no model. */
+export declare function specFromFile(path: string): Promise<SpecStageResult>;
+/** Pin a prompt to a validated {@link BuildSpec}, or refuse. */
+export declare function runSpecStage(opts: SpecStageOptions): Promise<SpecStageResult>;
+export declare function buildSpecPrompt(prompt: string): string;
+//# sourceMappingURL=spec.d.ts.map

package/dist/app-build/spec.d.ts.map

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