@nodetool-ai/execution 0.8.1

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @nodetool-ai/execution – Public API
+ */
+export { ExecutionSession } from "./session.js";
+export { DurableGenerationLifecycle, createDurableGenerationLifecycle, createFalGenerationLifecycleHooks } from "./generation-lifecycle.js";
+export { DurableGenerationRecoveryWorker } from "./generation-recovery-worker.js";
+export { decodeFalOutputs, deterministicFalStorageKey, type FalOutputDescriptor } from "./fal-output-decoder.js";
+export type { DurableGenerationRecoveryOptions, DurableRecoveryProvider, DurableRecoveryRunResult, DurableRecoverySubmission } from "./generation-recovery-worker.js";
+export type { DurableGenerationAcceptance, GenerationLeaseWindow, FalGenerationLifecycleHooksOptions } from "./generation-lifecycle.js";
+export { normalizeGraph, toRawGraphInput } from "./normalize-graph.js";
+export { assertPreflight, collectPreflightIssues, ExecutionPreflightError, formatPreflightDetail, isExecutionPreflightError, modelSelectionErrors, providerConfigurationChecker, unconfiguredProviderErrors, RUNTIME_CATALOGS } from "./preflight.js";
+export type { CredentialResolver, ExecutionPreflightIssue, PreflightIssueKind, PreflightOptions, ProviderConfigurationChecker, RunModelCatalogs } from "./preflight.js";
+export { DEFAULT_MESSAGE_BUFFER_LIMIT } from "./message-stream.js";
+export { attachRunCostLedger, isUnitBilledCapability, nodeTypeLookup, priceGeneration, recordFromMessage, recordGenerationSpend, recordNodeProviderCost } from "./cost-ledger.js";
+export type { CostLedgerSource, RunCostLedgerHandle, GenerationSpend, NodeCostSpend, PricedGeneration, RunCostLedgerOptions } from "./cost-ledger.js";
+export { createTrackerState, drainReconcileQueue, generationsForNode, linkGenerationAssets, reconcileGeneration, reconcileRow, resetGenerationTrackerState, startGenerationReconcileWorker, sweepInterruptedGenerations, trackPredictionMessage } from "./generation-tracker.js";
+export type { GenerationTrackerState, ReconcileOutcome, ReconcileSecretResolver } from "./generation-tracker.js";
+export { INTERVENTION_MARK, formatInterventionLine, formatSupervisedSummary, summarizeInterventions } from "./supervisor.js";
+export type { SupervisedRunSummary } from "./supervisor.js";
+export type { BridgeFactory, Edge, ExecutionLimits, ExecutionSessionOptions, JobPersistenceHook, NodeDescriptor, ProcessingMessage, RawGraphInput, RunResult, SupervisorHandle } from "./types.js";
+export type { NodeTypeResolver, ResolvedNodeType } from "@nodetool-ai/kernel";
+export { collectExecutionSummary, previewValue } from "./debug/collector.js";
+export { buildRunVerdict, collectInterventionWarnings, collectRunIssues, describeErrors } from "./debug/verdict.js";
+export type { DebugError, DebugGraph, DebugTargetInfo, DebugVerdict, EdgeDebug, ExecutionSummary, LlmCallDebug, LogEntry, NodeDebug, NodeOutput, RunVerdict, ServerRunReport, TraceSummary } from "./debug/types.js";
+export { simulateApp, defaultInteractions } from "./app-debug/index.js";
+export type { AppServerRunInput, AppServerRunOutcome, AppSimulationDeps } from "./app-debug/simulate.js";
+export type * from "./app-debug/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,0BAA0B,EAC1B,gCAAgC,EAChC,iCAAiC,EAClC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,+BAA+B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gCAAgC,EAChC,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,2BAA2B,EAC3B,qBAAqB,EACrB,kCAAkC,EACnC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACpB,4BAA4B,EAC5B,0BAA0B,EAC1B,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,4BAA4B,EAC5B,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,2BAA2B,EAC3B,8BAA8B,EAC9B,2BAA2B,EAC3B,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EACV,aAAa,EACb,IAAI,EACJ,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAI9E,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,gBAAgB,EAChB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,UAAU,EACV,UAAU,EACV,eAAe,EACf,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,UAAU,EACV,UAAU,EACV,eAAe,EACf,YAAY,EACb,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACxE,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AACjC,mBAAmB,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @nodetool-ai/execution – Public API
+ */
+export { ExecutionSession } from "./session.js";
+export { DurableGenerationLifecycle, createDurableGenerationLifecycle, createFalGenerationLifecycleHooks } from "./generation-lifecycle.js";
+export { DurableGenerationRecoveryWorker } from "./generation-recovery-worker.js";
+export { decodeFalOutputs, deterministicFalStorageKey } from "./fal-output-decoder.js";
+export { normalizeGraph, toRawGraphInput } from "./normalize-graph.js";
+export { assertPreflight, collectPreflightIssues, ExecutionPreflightError, formatPreflightDetail, isExecutionPreflightError, modelSelectionErrors, providerConfigurationChecker, unconfiguredProviderErrors, RUNTIME_CATALOGS } from "./preflight.js";
+export { DEFAULT_MESSAGE_BUFFER_LIMIT } from "./message-stream.js";
+export { attachRunCostLedger, isUnitBilledCapability, nodeTypeLookup, priceGeneration, recordFromMessage, recordGenerationSpend, recordNodeProviderCost } from "./cost-ledger.js";
+export { createTrackerState, drainReconcileQueue, generationsForNode, linkGenerationAssets, reconcileGeneration, reconcileRow, resetGenerationTrackerState, startGenerationReconcileWorker, sweepInterruptedGenerations, trackPredictionMessage } from "./generation-tracker.js";
+export { INTERVENTION_MARK, formatInterventionLine, formatSupervisedSummary, summarizeInterventions } from "./supervisor.js";
+// Debug surface: one execution-summary vocabulary + triage for every host that
+// reports on a run (CLI harness, HTTP debug endpoint, agent tools).
+export { collectExecutionSummary, previewValue } from "./debug/collector.js";
+export { buildRunVerdict, collectInterventionWarnings, collectRunIssues, describeErrors } from "./debug/verdict.js";
+// App-debug surface: one headless simulation of a mini app for every host that
+// reports on one (CLI `app debug`, the agent build loop, the server).
+export { simulateApp, defaultInteractions } from "./app-debug/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,0BAA0B,EAC1B,gCAAgC,EAChC,iCAAiC,EAClC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,+BAA+B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAE3B,MAAM,yBAAyB,CAAC;AAYjC,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACpB,4BAA4B,EAC5B,0BAA0B,EAC1B,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AASxB,OAAO,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,2BAA2B,EAC3B,8BAA8B,EAC9B,2BAA2B,EAC3B,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,iBAAiB,CAAC;AAgBzB,+EAA+E;AAC/E,oEAAoE;AACpE,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,gBAAgB,EAChB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAiB5B,+EAA+E;AAC/E,sEAAsE;AACtE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/js-script-debug/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@nodetool-ai/execution/js-script-debug` — JS script validation + debug
+ * report.
+ *
+ * Pure core: no DB, no sandbox, no browser. Hosts (the CLI `jsscript` command,
+ * the `validate_js_script` capability) resolve the target and write the bundle.
+ */
+export type { JsScriptDebugIssue, JsScriptValidation, JsScriptInteractionRecord, JsScriptDebugTarget, JsScriptDocumentMeta, JsScriptDebugReport } from "./types.js";
+export { validateJsScriptDoc, type JsScriptValidationOptions } from "./validate.js";
+export { missingDeclaredJsScriptOutputs, emptyDeclaredJsScriptOutputsError } from "./outputs.js";
+export { buildJsScriptDebugReport, type JsScriptDebugReportInput } from "./report.js";
+export { renderJsScriptReportMarkdown } from "./markdown.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/js-script-debug/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/js-script-debug/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,mBAAmB,EACnB,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,8BAA8B,EAC9B,iCAAiC,EAClC,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,wBAAwB,EACxB,KAAK,wBAAwB,EAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC"}

package/dist/js-script-debug/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@nodetool-ai/execution/js-script-debug` — JS script validation + debug
+ * report.
+ *
+ * Pure core: no DB, no sandbox, no browser. Hosts (the CLI `jsscript` command,
+ * the `validate_js_script` capability) resolve the target and write the bundle.
+ */
+export { validateJsScriptDoc } from "./validate.js";
+export { missingDeclaredJsScriptOutputs, emptyDeclaredJsScriptOutputsError } from "./outputs.js";
+export { buildJsScriptDebugReport } from "./report.js";
+export { renderJsScriptReportMarkdown } from "./markdown.js";
+//# sourceMappingURL=index.js.map

package/dist/js-script-debug/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/js-script-debug/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,OAAO,EACL,mBAAmB,EAEpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,8BAA8B,EAC9B,iCAAiC,EAClC,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,wBAAwB,EAEzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC"}

package/dist/js-script-debug/markdown.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Renders a `JsScriptDebugReport` as human-readable Markdown for the bundle.
+ */
+import type { JsScriptDebugReport } from "./types.js";
+export declare function renderJsScriptReportMarkdown(report: JsScriptDebugReport): string;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/js-script-debug/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/js-script-debug/markdown.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAsB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA+B1E,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,mBAAmB,GAC1B,MAAM,CAsDR"}

package/dist/js-script-debug/markdown.js

@@ -0,0 +1,62 @@
+import { isString } from "../predicates.js";
+const short = (value, max = 120) => {
+    if (value === undefined)
+        return "—";
+    let s;
+    try {
+        s = isString(value) ? value : JSON.stringify(value);
+    }
+    catch {
+        s = String(value);
+    }
+    s = (s ?? "null").replace(/\s+/g, " ");
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+};
+function issueTable(title, issues, lines) {
+    if (issues.length === 0)
+        return;
+    lines.push("", `## ${title}`, "");
+    lines.push("| Severity | Code | Where | Message |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const issue of issues) {
+        lines.push(`| ${issue.severity} | \`${issue.code}\` | ${issue.path ? `\`${issue.path}\`` : "—"} | ${short(issue.message, 300)} |`);
+    }
+}
+export function renderJsScriptReportMarkdown(report) {
+    const lines = [];
+    const title = report.target.name ?? report.target.ref;
+    lines.push(`# JS script debug: ${title}`);
+    lines.push("");
+    lines.push(`${report.verdict.ok ? "✅" : "❌"} ${report.verdict.headline}`);
+    lines.push("");
+    lines.push(`Target: \`${report.target.ref}\` (${report.target.kind})`);
+    lines.push(`Document: ${report.meta.inputCount} input(s), ${report.meta.outputCount} output(s), ` +
+        `${report.meta.packageCount} package(s), ${report.meta.secretCount} secret(s), ` +
+        `${report.meta.testCount} test(s) · timeout ${report.meta.timeoutSeconds}s · ` +
+        `${report.meta.codeLength} chars of code`);
+    if (report.verdict.issues.length > 0) {
+        lines.push("", "## Issues", "");
+        for (const issue of report.verdict.issues)
+            lines.push(`- ${issue}`);
+    }
+    issueTable("Validation", [...report.validation.errors, ...report.validation.warnings], lines);
+    if (report.interactions.length > 0) {
+        lines.push("", "## Interactions", "");
+        lines.push("| Tool | OK | Input | Error |");
+        lines.push("| --- | --- | --- | --- |");
+        for (const step of report.interactions) {
+            lines.push(`| \`${step.tool}\` | ${step.ok ? "✅" : "❌"} | ${short(step.input)} | ${step.error ? short(step.error, 200) : "—"} |`);
+        }
+    }
+    if (report.finalValidation) {
+        issueTable("Validation after edits", [...report.finalValidation.errors, ...report.finalValidation.warnings], lines);
+    }
+    if (report.notSimulated.length > 0) {
+        lines.push("", "## Not simulated", "");
+        for (const entry of report.notSimulated)
+            lines.push(`- ${entry}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=markdown.js.map

package/dist/js-script-debug/markdown.js.map

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

package/dist/js-script-debug/outputs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Runtime contract for a JS-script run: a document that declares output
+ * ports cannot succeed with an empty output bag.
+ *
+ * Shared by the HTTP run route and the eval headless bridge so both
+ * surfaces fail the same `{ok: true, outputs: {}}` hole.
+ */
+/**
+ * Declared output names that a successful run left out of the bag.
+ *
+ * Returns every declared name only when none of them appear — the empty-bag
+ * false success. If any declared name is present, returns [] and leaves a
+ * partial bag to other checks. No declared ports is never a miss.
+ */
+export declare function missingDeclaredJsScriptOutputs(declared: readonly {
+    name: string;
+}[], outputs: Record<string, unknown> | undefined): string[];
+/** Error text when {@link missingDeclaredJsScriptOutputs} is non-empty. */
+export declare function emptyDeclaredJsScriptOutputsError(missing: readonly string[]): string;
+//# sourceMappingURL=outputs.d.ts.map

package/dist/js-script-debug/outputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputs.d.ts","sourceRoot":"","sources":["../../src/js-script-debug/outputs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,EACrC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,MAAM,EAAE,CAMV;AAED,2EAA2E;AAC3E,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CAMR"}

package/dist/js-script-debug/outputs.js

@@ -0,0 +1,30 @@
+/**
+ * Runtime contract for a JS-script run: a document that declares output
+ * ports cannot succeed with an empty output bag.
+ *
+ * Shared by the HTTP run route and the eval headless bridge so both
+ * surfaces fail the same `{ok: true, outputs: {}}` hole.
+ */
+/**
+ * Declared output names that a successful run left out of the bag.
+ *
+ * Returns every declared name only when none of them appear — the empty-bag
+ * false success. If any declared name is present, returns [] and leaves a
+ * partial bag to other checks. No declared ports is never a miss.
+ */
+export function missingDeclaredJsScriptOutputs(declared, outputs) {
+    if (declared.length === 0)
+        return [];
+    const bag = outputs ?? {};
+    const missing = declared.map((port) => port.name).filter((name) => !(name in bag));
+    if (missing.length !== declared.length)
+        return [];
+    return missing;
+}
+/** Error text when {@link missingDeclaredJsScriptOutputs} is non-empty. */
+export function emptyDeclaredJsScriptOutputsError(missing) {
+    return (`The run produced none of the declared outputs: ${missing.join(", ")}. ` +
+        "Leave values with `await output(name, value)` or `await emit(name, value)` — " +
+        "an empty output bag is not success.");
+}
+//# sourceMappingURL=outputs.js.map

package/dist/js-script-debug/outputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputs.js","sourceRoot":"","sources":["../../src/js-script-debug/outputs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAqC,EACrC,OAA4C;IAE5C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC;IAC1B,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC;IACnF,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAClD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,iCAAiC,CAC/C,OAA0B;IAE1B,OAAO,CACL,kDAAkD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACxE,+EAA+E;QAC/E,qCAAqC,CACtC,CAAC;AACJ,CAAC"}

package/dist/js-script-debug/report.d.ts

@@ -0,0 +1,15 @@
+import type { JsScriptDebugReport, JsScriptDebugTarget, JsScriptInteractionRecord } from "./types.js";
+import { type JsScriptValidationOptions } from "./validate.js";
+export interface JsScriptDebugReportInput {
+    target: JsScriptDebugTarget;
+    /** The document as loaded — untrusted, validated here. */
+    document: unknown;
+    options?: JsScriptValidationOptions;
+    interactions?: JsScriptInteractionRecord[];
+    /** Bridge snapshot after the scripted session. */
+    finalState?: unknown;
+    /** The document the session left behind, validated as a second pass. */
+    finalDocument?: unknown;
+}
+export declare function buildJsScriptDebugReport(input: JsScriptDebugReportInput): Promise<JsScriptDebugReport>;
+//# sourceMappingURL=report.d.ts.map

package/dist/js-script-debug/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/js-script-debug/report.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAEV,mBAAmB,EACnB,mBAAmB,EAEnB,yBAAyB,EAE1B,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AAwFvB,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,yBAAyB,CAAC;IACpC,YAAY,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAC3C,kDAAkD;IAClD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CA2B9B"}

package/dist/js-script-debug/report.js

@@ -0,0 +1,90 @@
+/**
+ * Assembles a `JsScriptDebugReport` from a document, an optional scripted edit
+ * session, and the document that session left behind.
+ *
+ * Pure: the host resolves the target (file, id) and writes the bundle; this
+ * decides what the run means.
+ */
+import { JS_SCRIPT_DEFAULT_TIMEOUT_SECONDS } from "@nodetool-ai/protocol/api-schemas/js-scripts.js";
+import { validateJsScriptDoc } from "./validate.js";
+import { isFiniteNumber, isString } from "../predicates.js";
+/**
+ * What a headless JS-script run cannot answer. Fixed, because the boundary is
+ * a property of the harness, not of the document it was pointed at.
+ */
+const NOT_SIMULATED = [
+    "The editor — Monaco, the assistant panel, the ports/packages/secrets controls, and the run console render nothing headlessly.",
+    "Version history — a debug session never snapshots or restores; use `jsscript versions` for that.",
+    "Persistence — a scripted session edits an in-memory document and is never saved back onto the row.",
+    "Secret values — a run reads only the secrets the document declares, and the store is per-install."
+];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const count = (value) => Array.isArray(value) ? value.length : 0;
+function describeDocument(document) {
+    const record = isRecord(document) ? document : {};
+    const timeout = record.timeoutSeconds;
+    return {
+        inputCount: count(record.inputs),
+        outputCount: count(record.outputs),
+        packageCount: count(record.packages),
+        secretCount: count(record.secrets),
+        testCount: count(record.tests),
+        timeoutSeconds: isFiniteNumber(timeout)
+            ? timeout
+            : JS_SCRIPT_DEFAULT_TIMEOUT_SECONDS,
+        codeLength: isString(record.code) ? record.code.length : 0
+    };
+}
+const describe = (issue) => issue.path
+    ? `[${issue.code}] ${issue.path}: ${issue.message}`
+    : `[${issue.code}] ${issue.message}`;
+function buildVerdict(validation, interactions, finalValidation) {
+    const failedSteps = interactions.filter((step) => !step.ok);
+    const issues = [
+        ...validation.errors.map(describe),
+        ...failedSteps.map((step) => `Interaction \`${step.tool}\` failed${step.error ? `: ${step.error}` : ""}`),
+        ...(finalValidation?.errors ?? []).map((issue) => `After edits — ${describe(issue)}`)
+    ];
+    const warnings = [
+        ...validation.warnings.map(describe),
+        ...(finalValidation?.warnings ?? []).map((issue) => `After edits — ${describe(issue)}`)
+    ];
+    const ok = issues.length === 0;
+    const headline = ok
+        ? `Script is sound — ${interactions.length} interaction(s) ran clean` +
+            (warnings.length > 0 ? `, ${warnings.length} warning(s)` : "") +
+            "."
+        : `Script has ${issues.length} problem(s)` +
+            (failedSteps.length > 0
+                ? `, ${failedSteps.length} failed interaction(s)`
+                : "") +
+            (warnings.length > 0 ? `, ${warnings.length} warning(s)` : "") +
+            ` — ${issues[0]}`;
+    return warnings.length > 0
+        ? { ok, headline, issues, warnings }
+        : { ok, headline, issues };
+}
+export async function buildJsScriptDebugReport(input) {
+    const options = input.options ?? {};
+    const validation = await validateJsScriptDoc(input.document, options);
+    const finalValidation = input.finalDocument === undefined
+        ? undefined
+        : await validateJsScriptDoc(input.finalDocument, options);
+    const interactions = input.interactions ?? [];
+    const report = {
+        target: input.target,
+        meta: describeDocument(input.finalDocument ?? input.document),
+        validation,
+        interactions,
+        notSimulated: [...NOT_SIMULATED],
+        verdict: buildVerdict(validation, interactions, finalValidation)
+    };
+    if (input.finalState !== undefined) {
+        report.finalState = input.finalState;
+    }
+    if (finalValidation) {
+        report.finalValidation = finalValidation;
+    }
+    return report;
+}
+//# sourceMappingURL=report.js.map

package/dist/js-script-debug/report.js.map

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

package/dist/js-script-debug/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * JS script debug vocabulary.
+ *
+ * One report shape for "is this script document sound, and what did a scripted
+ * edit session leave behind" — shared by the CLI `jsscript validate` /
+ * `jsscript debug` commands and the `validate_js_script` capability, the same
+ * way `../sketch-debug/types.ts` is shared by the sketch surfaces.
+ */
+import type { DebugVerdict } from "../debug/types.js";
+/** One finding against a JS script document. */
+export interface JsScriptDebugIssue {
+    severity: "error" | "warning";
+    /** Stable machine code, e.g. `js_script_duplicate_port`, `code_syntax`. */
+    code: string;
+    message: string;
+    /** JSON path of the offending field, for schema findings. */
+    path?: string;
+}
+export interface JsScriptValidation {
+    /** True when there are no errors. Warnings do not clear `ok`. */
+    ok: boolean;
+    errors: JsScriptDebugIssue[];
+    warnings: JsScriptDebugIssue[];
+}
+/** One executed step of a `--interact` script. */
+export interface JsScriptInteractionRecord {
+    /** Tool name as invoked (canonical `ui_jsscript_*` form). */
+    tool: string;
+    input: unknown;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+export interface JsScriptDebugTarget {
+    kind: "file" | "id";
+    ref: string;
+    name?: string;
+}
+export interface JsScriptDocumentMeta {
+    inputCount: number;
+    outputCount: number;
+    packageCount: number;
+    secretCount: number;
+    testCount: number;
+    timeoutSeconds: number;
+    codeLength: number;
+}
+export interface JsScriptDebugReport {
+    target: JsScriptDebugTarget;
+    meta: JsScriptDocumentMeta;
+    /** Static validation of the input document. */
+    validation: JsScriptValidation;
+    /** Scripted edit session, when one ran. */
+    interactions: JsScriptInteractionRecord[];
+    /** Bridge snapshot after the script. */
+    finalState?: unknown;
+    /** Validation of the document the session left behind. */
+    finalValidation?: JsScriptValidation;
+    /** What a headless run cannot answer. */
+    notSimulated: string[];
+    verdict: DebugVerdict;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/js-script-debug/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/js-script-debug/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED,kDAAkD;AAClD,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,+CAA+C;IAC/C,UAAU,EAAE,kBAAkB,CAAC;IAC/B,2CAA2C;IAC3C,YAAY,EAAE,yBAAyB,EAAE,CAAC;IAC1C,wCAAwC;IACxC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,kBAAkB,CAAC;IACrC,yCAAyC;IACzC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,YAAY,CAAC;CACvB"}

package/dist/js-script-debug/types.js

@@ -0,0 +1,10 @@
+/**
+ * JS script debug vocabulary.
+ *
+ * One report shape for "is this script document sound, and what did a scripted
+ * edit session leave behind" — shared by the CLI `jsscript validate` /
+ * `jsscript debug` commands and the `validate_js_script` capability, the same
+ * way `../sketch-debug/types.ts` is shared by the sketch surfaces.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/js-script-debug/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/js-script-debug/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/js-script-debug/validate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The static check behind `nodetool jsscript validate` and the
+ * `validate_js_script` capability.
+ *
+ * Two layers, neither forked:
+ *
+ * - the document's shape and internal consistency come from
+ *   `validateJsScriptDocument` in `@nodetool-ai/protocol` — the same function
+ *   the model's `beforeSave` and the tRPC router run;
+ * - the body analysis comes from `validateCodeNodeBody` in
+ *   `@nodetool-ai/node-sdk` — the same function `validateGraph` runs over a
+ *   Code node, given the document's declared ports. A script has no packages
+ *   setting: every installed pack and every platform module resolves by import.
+ *
+ * On top of both, two rules only a script has: outputs that leave through
+ * `return` instead of `emit`/`output` are an error (a script is a new surface,
+ * so there is no legacy contract to support), and a declared secret the
+ * install does not carry is a warning. Secrets are passed in rather than read
+ * here, so a file target stays database-free.
+ */
+import type { SandboxModuleCatalog } from "@nodetool-ai/runtime";
+import type { JsScriptValidation } from "./types.js";
+export interface JsScriptValidationOptions {
+    /**
+     * Secret names this install carries. A declared secret missing from the list
+     * is a warning. Omit to skip the check — the store is per-install, and a file
+     * target has no database to read it from.
+     */
+    knownSecrets?: readonly string[];
+    /** The installed sandbox catalog, when the caller has one. */
+    sandboxModuleCatalog?: SandboxModuleCatalog | null;
+}
+/**
+ * Check a JS script document without running it. Returns findings rather than
+ * throwing: every caller renders them.
+ */
+export declare function validateJsScriptDoc(document: unknown, options?: JsScriptValidationOptions): Promise<JsScriptValidation>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/js-script-debug/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/js-script-debug/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAsB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEzE,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,8DAA8D;IAC9D,oBAAoB,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACpD;AAsED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,OAAO,EACjB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,kBAAkB,CAAC,CAgE7B"}

package/dist/js-script-debug/validate.js

@@ -0,0 +1,137 @@
+/**
+ * The static check behind `nodetool jsscript validate` and the
+ * `validate_js_script` capability.
+ *
+ * Two layers, neither forked:
+ *
+ * - the document's shape and internal consistency come from
+ *   `validateJsScriptDocument` in `@nodetool-ai/protocol` — the same function
+ *   the model's `beforeSave` and the tRPC router run;
+ * - the body analysis comes from `validateCodeNodeBody` in
+ *   `@nodetool-ai/node-sdk` — the same function `validateGraph` runs over a
+ *   Code node, given the document's declared ports. A script has no packages
+ *   setting: every installed pack and every platform module resolves by import.
+ *
+ * On top of both, two rules only a script has: outputs that leave through
+ * `return` instead of `emit`/`output` are an error (a script is a new surface,
+ * so there is no legacy contract to support), and a declared secret the
+ * install does not carry is a warning. Secrets are passed in rather than read
+ * here, so a file target stays database-free.
+ */
+import { jsScriptDocument, validateJsScriptDocument } from "@nodetool-ai/protocol/api-schemas/js-scripts.js";
+function split(issues) {
+    const errors = issues.filter((issue) => issue.severity === "error");
+    const warnings = issues.filter((issue) => issue.severity === "warning");
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * A body still on the return contract: it declares outputs and calls neither
+ * `emit` nor `output`, so nothing ever reaches a handle.
+ */
+function legacyContractIssue(doc, usesEmitOutputContract) {
+    const code = doc.code.trim();
+    if (code === "" || doc.outputs.length === 0)
+        return null;
+    if (usesEmitOutputContract(doc.code))
+        return null;
+    return {
+        severity: "error",
+        code: "js_script_legacy_contract",
+        message: "The body declares outputs but calls neither emit() nor output(). A " +
+            "script has no return contract: stream a value with " +
+            "`await emit(name, value)` and set a final one with " +
+            "`await output(name, value)`."
+    };
+}
+/**
+ * Where the saved cases and the body disagree about how inputs arrive.
+ *
+ * A case stages items for a body that never calls `stream`: nothing pulls them,
+ * so the case tests less than it looks like it does. A streaming body whose
+ * cases stage nothing: every `stream` completes immediately, so the case proves
+ * only that the body survives an empty inbox.
+ */
+function testStreamIssues(doc, streaming) {
+    const staged = doc.tests.filter((testCase) => Object.keys(testCase.inputStreams ?? {}).length > 0);
+    if (!streaming) {
+        return staged.map((testCase) => ({
+            severity: "warning",
+            code: "js_script_test_streams_unused",
+            message: `test "${testCase.name}" stages input streams, but the body never ` +
+                "calls stream() — the staged items are never read. Read them with " +
+                "`for await (const item of stream(name))`, or move them to `inputs`."
+        }));
+    }
+    if (doc.tests.length > 0 && staged.length === 0) {
+        return [
+            {
+                severity: "warning",
+                code: "js_script_tests_no_streams",
+                message: "The body reads its inputs with stream(), but no saved test stages " +
+                    "any items — every stream ends immediately. Give a case " +
+                    "`inputStreams` so the cases exercise what the body does."
+            }
+        ];
+    }
+    return [];
+}
+/**
+ * Check a JS script document without running it. Returns findings rather than
+ * throwing: every caller renders them.
+ */
+export async function validateJsScriptDoc(document, options = {}) {
+    const shapeIssues = validateJsScriptDocument(document).map((issue) => ({
+        severity: issue.severity,
+        code: issue.code,
+        message: issue.message
+    }));
+    const parsed = jsScriptDocument.safeParse(document);
+    if (!parsed.success) {
+        // The document does not even parse, so there is nothing to analyze; the
+        // schema findings are the whole answer.
+        return split(shapeIssues);
+    }
+    const doc = parsed.data;
+    const { validateCodeNodeBody, usesEmitOutputContract, usesStreamInputContract } = await import("@nodetool-ai/node-sdk");
+    // A script has no node-configured property values: every declared input is
+    // fed by the caller, which is what the graph calls a connected handle. Saying
+    // so is what makes the streaming rules right here — `stream("x")` on a
+    // declared input never warns "nothing feeds it", and reading a declared input
+    // through `inputs.x` in a streaming body is the error it is in a graph.
+    const inputNames = doc.inputs.map((port) => port.name);
+    const bodyIssues = validateCodeNodeBody({
+        code: doc.code,
+        availableInputs: inputNames,
+        connectedInputs: inputNames,
+        declaredOutputs: doc.outputs.map((port) => port.name),
+        sandboxModuleCatalog: options.sandboxModuleCatalog ?? null
+    }).map((issue) => ({
+        severity: issue.severity,
+        code: issue.code,
+        message: issue.message
+    }));
+    const issues = [...shapeIssues, ...bodyIssues];
+    const streaming = usesStreamInputContract(doc.code);
+    // A streaming body on the return contract is already an error from the body
+    // check (`code_stream_return_contract`), which says the same thing.
+    const legacy = streaming
+        ? null
+        : legacyContractIssue(doc, usesEmitOutputContract);
+    if (legacy)
+        issues.push(legacy);
+    issues.push(...testStreamIssues(doc, streaming));
+    if (options.knownSecrets !== undefined) {
+        const known = new Set(options.knownSecrets);
+        for (const name of doc.secrets) {
+            if (name.trim() !== "" && !known.has(name)) {
+                issues.push({
+                    severity: "warning",
+                    code: "js_script_secret_missing",
+                    message: `Declared secret "${name}" is not in this install's secret store.`
+                });
+            }
+        }
+    }
+    return split(issues);
+}
+//# sourceMappingURL=validate.js.map