@nodetool-ai/execution 0.8.1

package/README.md

@@ -0,0 +1,129 @@
+# @nodetool-ai/execution
+
+`ExecutionSession` — the one place that constructs `WorkflowRunner`. Sits
+between `@nodetool-ai/kernel` and its consumers (CLI, debug harness, headless
+job runner, HTTP API, MCP server, the WebSocket runner). Task A3 migrated the CLI, debug
+harness, and headless job runner onto this facade; A5 migrated the WS runner
+(then `unified-websocket-runner.ts`, since renamed to
+`packages/websocket/src/websocket-client-session.ts`) last, once the reliability
+harness could watch it for drift. The wiring-inventory table below is a
+historical snapshot from before those migrations, and still uses the old file
+name and its line numbers — each migrated row is annotated with what actually
+changed; unmigrated sites (HTTP API, MCP server, the DSL, the agent runner,
+`RunInnerGraph`, the browser workflow runner) are unchanged and still
+construct `WorkflowRunner` directly, per `scripts/check-execution-boundary.mjs`'s
+allowlist.
+
+## Wiring inventory (Task A1)
+
+Every non-test `new WorkflowRunner(...)` site in the repo, and what each one
+does around `runner.run()`. "Decision" says where that behavior now lives:
+**facade-owned** (moved into `ExecutionSession`, available to every surface
+that migrates onto it), **adapter-owned** (stays specific to one surface —
+transport/queueing/UI concerns the facade should not generalize), or
+**out of scope** (a nested/child-runner construction, not a top-level
+execution surface — not part of this facade's contract).
+
+| Site | Graph hydration | Executor resolution | Param/stream seeding | Cancellation | Timeout | Persistence | Output-name rewriting | Decision |
+|---|---|---|---|---|---|---|---|---|
+| `packages/cli/src/nodetool.ts:751` (`workflows run`) | `hydrateGraphNodeFlags` (registry) | 3-branch: registry → `resolvePythonNodeExecutor` → throw (copy-pasted) | params only | none (`process.exit` on completion) | none | none (stdout only) | none | **facade-owned** (hydration, executor resolution); timeout/cancel are new capabilities A3 can adopt |
+| `packages/cli/src/debug/server-runner.ts:101` (`nodetool debug`) | `hydrateGraphNodeFlags` (registry) | 3-branch (copy-pasted, identical to above) | params only | **none** — `withTimeout` races the promise and *abandons* the still-running kernel on timeout (a real leak) | `withTimeout` wraps the whole run in a `setTimeout`/`Promise.race`, synthesizing a `failed` result; kernel run keeps executing | none | none | **facade-owned**: hydration, executor resolution, and — critically — the timeout becomes `session.cancel("timeout")` instead of abandonment (A3's stated fix) |
+| `packages/websocket/src/headless-job-runner.ts:225` (`startHeadlessJob`) | `hydrateGraphNodeFlags` (registry), preceded by its own `normalizeRunnableGraph` (editor-only pruning, `data`→`properties`, edge_type normalization) | 3-branch (copy-pasted, identical) | params + optional `trigger_event` | none exposed (no cancel handle returned to caller) | none | `Job` row created before run, terminal status persisted after (`persistTerminalStatus`, DB-cancel-aware) | none | **facade-owned**: hydration + the `normalizeRunnableGraph` pre-step (folded into this package's `normalizeGraph`), executor resolution, trigger_event passthrough. Persistence stays **adapter-owned** (Job-model specifics) but is expressible via `JobPersistenceHook` |
+| `packages/websocket/src/unified-websocket-runner.ts:2797` (`startJobInner`, `run_job`) | `this.hydrateGraph` — `Graph.loadFromDict({resolver: this.resolveNodeType})` when a node-type resolver is configured, else `withExplicitNodeFlags` (a *different* hydration path than `hydrateGraphNodeFlags`, richer: supports async Python-metadata-backed resolution) | `resolveExecutor` **injected at construction** (`UnifiedWebSocketRunnerOptions.resolveExecutor`) — not the copy-pasted 3-branch; the WS server wires it once at bootstrap | params, **plus** live `stream_input`/`end_input_stream` commands mapped straight onto `runner.pushInputValue`/`finishInputStream` (the *only* surface with streaming seeding before this package) | `cancelJob`: `runner.cancel()` + immediate DB `markCancelled()` + `job_update` (ahead of the runner's own `.finally()` persistence, to avoid a UI race) | none built in (host process only) | `Job.create` before run, queueing (`MAX_CONCURRENT_JOBS`, per-workflow caps), slot accounting (`startingJobs`→`activeJobs`) | **yes** — `unified-websocket-runner.ts:2733`: when `require_terminal_result`, every `nodetool.output.*` node's kernel-facing `name` is rewritten to `properties.name` before the run, so `output_update` and the terminal snapshot address the same key | **Migrated (A5).** `startJobInner` now calls `ExecutionSession.create(...)` instead of `new WorkflowRunner(...)` + a later `runner.run(...)`; `active.runner: WorkflowRunner` is `active.session: ExecutionSession`. What moved and what didn't: **hydration** stays exactly as it was — `this.hydrateGraph(rawGraph)` (unchanged, including the output-name rewrite right after it) still runs first, so `ExecutionSession` receives an *already-hydrated* graph; it re-hydrates internally via `withExplicitNodeFlags` (no `registry` passed — this class has never held a `NodeRegistry` instance, only the bootstrap-injected `resolveExecutor`/`resolveNodeType` closures), which is a no-op on fields already resolved (`...node` passes `propertyTypes`, flags, and the rewritten output name straight through). **Executor resolution** is the bootstrap-injected `this.resolveExecutor` passed via the facade's new `resolveExecutor` override (added in A5 specifically for this: it bypasses `ExecutionSession`'s own registry+bridge construction, since this class has no registry to hand it) — not rebuilt, not duplicated. **`pushInputValue`/`finishInputStream`** passthrough is now `session.pushInput`/`session.finishInputStream`; the new `session.updateNodeProperties` passthrough (added in A5) covers the `update_node_properties` command, which the pre-migration inventory above didn't list. **Still adapter-owned, unchanged**: queueing, slot accounting, per-client concurrency caps, the DB-ahead-of-runner cancel ordering, the `Job.create`/existing-row persistence block, output-name rewriting (still the manual pre-existing rewrite loop, not the facade's `requireTerminalResult` option — no reason to swap a working adapter-owned rewrite for a facade one mid-migration). One real (accepted) behavior shift: `ExecutionSession.create()` couples "construct" and "start the kernel run" into one call, where the pre-migration code constructed the runner (registering it in `activeJobs`, cancellable) *before* the `Job.create` persistence block and only called `runner.run()` *after* it — the migrated code creates the session (which starts the run) at the former construction point, so the run can begin a few milliseconds before its DB row exists. The reliability harness's differential suite (C2/C4) shows this produces no observable wire-protocol difference. |
+| `packages/websocket/src/unified-websocket-runner.ts:4147` (`handleChatMessage`) | same `this.hydrateGraph` | injected `resolveExecutor` (same pattern) | params built from chat history/legacy fields | none exposed here directly (goes through the same `activeJobs`/`cancelJob` machinery) | none | `Job.create` (best-effort) | n/a | **out of scope for A2**: this is chat-turn orchestration built on the same runner-construction pattern as the row above, not a distinct wiring divergence |
+| `packages/websocket/src/unified-websocket-runner.ts:6283` (single-node tool-call harness) | `this.hydrateGraph` on a synthetic one-node graph | injected `resolveExecutor` | `params: {}`, values fed via `data` on the synthetic node | none | none | none | n/a | **out of scope for A2**: an internal single-node execution helper (tool call → node run), not a top-level surface |
+| `packages/websocket/src/http-api.ts:771` (async HTTP run) | — | — | params only | — | — | — | — | **Migrated.** The route calls `runWorkflow` from `@nodetool-ai/execution/service`, so hydration, executor resolution, cancellation, timeout and `Job` persistence are all the facade's now. The one thing it still owns is the environment: `environment: () => getWorkflowRuntimeEnvironment(options)`, passed lazily so a nonexistent workflow 404s before the runtime bootstraps. That bootstrap stays **out of scope** (it also builds the registry and connects the Python bridge — infra construction, not execution semantics) |
+| `packages/websocket/src/mcp-server.ts` (MCP tool: run workflow) | — | — | — | — | — | — | — | **Gone.** The mount no longer runs workflows; `registerAgentMcpTools` exposes the agents package's capability tools instead, and the file imports nothing from `@nodetool-ai/kernel` |
+| `packages/core-nodes/src/nodes/run-inner-graph.ts:131` (`RunInnerGraph` / `WorkflowNode`) | `Graph.loadFromDict` via `context.resolveNodeType` when set, else `withExplicitNodeFlags` | injected `resolveExecutor` from the *parent* run's `context.resolveExecutor` | params from node properties | none (bounded by the parent run's lifetime) | none | none (child of an already-persisted parent run) | maps runner output keys back to the sub-graph's declared output names (`outputKeyMap`) | **out of scope**: a node's own implementation spawning a *child* runner inside an already-running parent node — not a top-level surface entry point. Revisit only if a future task generalizes nested execution |
+| `packages/agents/src/execute-agent-graph.ts:122` (`executeAgentGraph`) | — | — | — | — | — | — | — | **Gone.** The retired `Agent` graph branch was its only caller, so it was deleted with it; `applyRunPolicy`, a graph transform rather than execution wiring, survives in `packages/agents/src/run-policy.ts` for the `graph-e2e` eval |
+| `packages/dsl/src/core.ts:399` (`run()`, the TS DSL entry point) | none — DSL nodes carry flags from generated metadata; wrapped in `withExplicitNodeFlags` directly | 4-branch: `opts.registry` → `NodeRegistry.global` → `builtinRegistry` → Python bridge → throw (a superset of the 3-branch pattern — DSL graphs can mix three TS registries) | params only | none | none | none | none | **out of scope for A2, revisit for A3+**: the DSL's multi-registry resolver is a genuinely different shape (3 TS registries, not 1) that this package's single-`registry` option doesn't yet cover. Noted as a gap, not silently generalized |
+| `packages/workflow-runner/src/run.ts:118` (`runWorkflow`, browser + `nodetool run` shared core) | `hydrateGraphNodeFlags` | `opts.registry.resolve(node)` only (no Python-bridge branch — this path targets the browser, which has no Python bridge) | params only, **but** already an `AsyncGenerator<ProcessingMessage, RunResult>` with `AbortSignal`-based `cancelRun()` — this file is the closest existing prior art to `ExecutionSession`'s streaming/cancel shape | `AbortSignal` → `runner.cancel()`, mirrors this package's `cancel()` | none built in (caller's `AbortSignal` can carry one) | none (caller's concern) | none | **not migrated in A2** — its generator-based public API predates this package and has its own consumers (browser workflow runner, `nodetool run`). Cataloged here as the pattern this package's `messages`/`cancel()` API generalizes; a follow-up task can make it a thin wrapper over `ExecutionSession` |
+| `packages/workflow-runner/e2e/src/browser-entry.ts:151` | same pattern as `run.ts` (it's the e2e harness's copy of the browser runner) | `opts.registry.resolve` | params only | `AbortSignal` | none | none | none | **out of scope**: test harness, not a product surface |
+
+### Notes on what didn't make the table
+
+- **The third executor-resolution copy is down to one caller.** `http-api.ts`
+  and `mcp-server.ts` used to share a `getRuntimeEnvironment`/
+  `getWorkflowRuntimeEnvironment` helper wrapping registry + Python-bridge
+  bootstrap — a third copy of "registry → Python bridge → throw", independent
+  of the one duplicated verbatim in `cli/nodetool.ts`, `debug/server-runner.ts`,
+  and `headless-job-runner.ts`. `mcp-server.ts` no longer runs workflows, and
+  `http-api.ts` now hands that helper to `runWorkflow` as an `environment`
+  callback rather than driving a runner with it. Folding what remains onto this
+  package's `createExecutorResolver` (`src/executor-resolver.ts`) is still open.
+- **Output-name rewriting** existed at exactly one site
+  (`unified-websocket-runner.ts:2733`, `require_terminal_result`). It is now
+  `ExecutionSession`'s `requireTerminalResult` option
+  (`src/output-names.ts`), available to every surface without being
+  reinvented per-site.
+- **`bufferLimit`** is a `WorkflowRunnerOptions` field, not a `run()`-time
+  argument; no existing call site sets it (all rely on the kernel default).
+  `ExecutionSession`'s `limits.bufferLimit` forwards it 1:1.
+- **`nodeTimeoutMs`** has no kernel-side hook today (only the run-level `AbortSignal` that
+  `cancel()` aborts). `ExecutionSession.create()` throws if it's set, rather
+  than accepting and silently ignoring it — inventing a no-op timeout would
+  be worse than refusing it.
+
+## API
+
+```ts
+import { ExecutionSession } from "@nodetool-ai/execution";
+
+const session = await ExecutionSession.create({
+  graph,                       // raw saved JSON — hydration happens HERE, once
+  registry,                    // NodeRegistry from @nodetool-ai/node-sdk
+  bridgeFactory,                // optional; defaults to connectPythonBridgeForGraph
+  params,                       // and/or pushInput/finishInputStream below
+  persistence: { onAccepted, onTerminal } | null,
+  limits: { runTimeoutMs, bufferLimit },  // nodeTimeoutMs: not yet supported, see above
+  requireTerminalResult: true,  // optional — output-name rewriting
+  captureMessages: true,        // optional — required to read `messages` below
+  catalogs, providerConfiguration,  // optional — preflight, see below
+});
+
+// Only with `captureMessages: true`, and only if you actually drain it:
+// capture queues each message until a consumer pulls it, so a host that just
+// awaits `result` would hold the whole run's messages (audio chunks included)
+// for nothing. Reading `messages` without the flag throws; a consumer that
+// falls behind `limits.messageBufferLimit` makes the iterator throw.
+for await (const message of session.messages) { /* ProcessingMessage */ }
+
+await session.pushInput("input_name", value);
+session.finishInputStream("input_name");
+
+session.cancel("reason");     // the ONLY cancel; limits.runTimeoutMs = cancel("timeout")
+
+const result = await session.result;  // RunResult — never rejects
+```
+
+`create()` refuses before it spends anything. After normalization — and ahead
+of the Python bridge, `persistence.onAccepted`, and the kernel — it checks the
+graph's model selections against the provider catalogs and each selected
+provider's credentials against `context.getSecret`, and throws
+`ExecutionPreflightError` (`.issues` is the machine-readable list, `.message`
+the text a host prints). Without it a missing key failed at the node that
+needed it, after the upstream half of the graph had already run and billed.
+`catalogs` and `providerConfiguration` default to the process-wide provider
+registry; a host whose providers are not in that registry must pass both.
+
+Inside the facade: `hydrateGraphNodeFlags` (plus the graph normalization
+`headless-job-runner.ts` used to do inline — editor-only pruning, `data` →
+`properties`, `edge_type` defaulting), the three-branch executor resolver,
+param/stream seeding via the kernel's own `pushInputValue`/
+`finishInputStream`, cancellation, and run-timeout-as-cancel.
+
+## Subpaths
+
+- `@nodetool-ai/execution/debug` — the execution-summary reducer, the run
+  verdict, and the target/run-report types every surface reports a run with.
+- `@nodetool-ai/execution/app-debug` — the headless mini-app simulator:
+  `simulateApp` takes a resolved app target and an injected workflow runner and
+  returns an `AppDebugReport`. It reads no database and writes no files, so the
+  CLI (`nodetool app debug`), the agent build loop, and the server all simulate
+  an app the same way. Target resolution and bundle writing belong to the host.
+
+## What this package does not do
+
+- **Does not validate the message stream against a schema.** `messages` is a
+  live `AsyncIterable<ProcessingMessage>`; runtime protocol validation is
+  Track B (`packages/protocol`'s Zod-first `messages.ts`).

package/dist/.nodetool-build-stamp

@@ -0,0 +1 @@
+2026-09-28T09:19:14.123Z

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

@@ -0,0 +1,94 @@
+/**
+ * Pure app-spec layer: parse a workflow's app document into a flat widget
+ * list, extract the graph's bindable surface, and statically validate the
+ * wiring between the two.
+ *
+ * The semantics — widget catalog, document parsing, binding resolution — come
+ * from `@nodetool-ai/app-runtime`, so this harness checks the same rules the
+ * web runtime enforces instead of a copy that drifts away from it.
+ */
+import { type ApplicationDocument, type BindingScope, type OperationBinding, type VariableDeclaration } from "@nodetool-ai/app-runtime";
+import type { DebugGraph } from "../debug/types.js";
+import type { AppIO, AppOperationSpec, AppSpec, AppValidation, AppWidgetSpec } from "./types.js";
+/**
+ * The app's operations resolved against real graphs, plus the declared
+ * variables and resources. Built by the harness (resolving an operation's
+ * workflow may need a database read) and handed to the pure layer here.
+ */
+export interface AppContext {
+    defaultOperationId: string;
+    operations: AppOperationSpec[];
+    variables: VariableDeclaration[];
+    resources: Array<{
+        id: string;
+        name: string;
+        kind: string;
+    }>;
+}
+/**
+ * The binding scope an app resolves against: every declared operation with the
+ * surface of the workflow it runs, plus the declared variables. Without a
+ * context this is the single-operation shape a legacy `app_doc` has.
+ */
+export declare function bindingScopeFor(io: AppIO, context?: AppContext): BindingScope;
+/**
+ * The operations a parsed document declares, as report specs. A document with
+ * none gets the implicit single operation a legacy `app_doc` runs.
+ */
+export declare function documentOperations(document: ApplicationDocument): OperationBinding[];
+/** Parse an app document (object or JSON string), or explain why it will not. */
+export declare function parseAppDocument(appDoc: unknown): {
+    document: null;
+    issue: string;
+} | {
+    document: ApplicationDocument;
+    issue: null;
+};
+/**
+ * Parse an app document (object or JSON string) into an {@link AppSpec},
+ * resolving every widget binding to a node-ID reference against the live
+ * graph. Slot children are discovered from the widget catalog, falling back to
+ * a structural scan so a new layout widget keeps working before the catalog
+ * knows about it.
+ */
+export declare function parseAppSpec(appDoc: unknown, io: AppIO, context?: AppContext, 
+/**
+ * The document the target loader already parsed. Passed in so an application
+ * or bundle target is not re-parsed as if it were a `workflow.app_doc` —
+ * `appDoc` stays the raw stored value, which is what the persist-downgrade
+ * check needs to see.
+ */
+preparsed?: {
+    document: ApplicationDocument | null;
+    issue: string | null;
+}): {
+    spec: null;
+    issues: string[];
+    warnings: never[];
+} | {
+    spec: {
+        version: number;
+        title: string | null;
+        widgets: AppWidgetSpec[];
+        operations: AppOperationSpec[];
+        variables: VariableDeclaration[];
+        resources: {
+            id: string;
+            name: string;
+            kind: import("@nodetool-ai/app-runtime").ResourceKind;
+        }[];
+    };
+    issues: string[];
+    warnings: string[];
+};
+/** An operation binding plus the surface it resolved against, for the report. */
+export declare function operationSpec(binding: OperationBinding, io: AppIO | null, unavailable: string | null): AppOperationSpec;
+/**
+ * Extract the app-bindable surface from a kernel-shape graph: input nodes,
+ * output/Preview nodes, and SetVariable channel names — the same surface the
+ * web builder offers in its binding pickers.
+ */
+export declare function extractAppIO(graph: DebugGraph): AppIO;
+/** Statically check the app's wiring against the workflow's bindable surface. */
+export declare function validateApp(spec: AppSpec, io: AppIO, context?: AppContext): AppValidation;
+//# sourceMappingURL=app-spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"app-spec.d.ts","sourceRoot":"","sources":["../../src/app-debug/app-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAYL,KAAK,mBAAmB,EAGxB,KAAK,YAAY,EAEjB,KAAK,gBAAgB,EAErB,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAGV,KAAK,EACL,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,aAAa,EACd,MAAM,YAAY,CAAC;AAwBpB;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,SAAS,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D;AA2CD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,YAAY,CAoB7E;AA+DD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,mBAAmB,GAC5B,gBAAgB,EAAE,CAYpB;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO;;;;;;EAyB/C;AAmCD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,EACf,EAAE,EAAE,KAAK,EACT,OAAO,CAAC,EAAE,UAAU;AACpB;;;;;GAKG;AACH,SAAS,CAAC,EAAE;IAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;;;;;;;;;;;;;;;;;;;EAsH3E;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAC3B,OAAO,EAAE,gBAAgB,EACzB,EAAE,EAAE,KAAK,GAAG,IAAI,EAChB,WAAW,EAAE,MAAM,GAAG,IAAI,GACzB,gBAAgB,CAalB;AAeD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,CAwBrD;AAsBD,iFAAiF;AACjF,wBAAgB,WAAW,CACzB,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,KAAK,EACT,OAAO,CAAC,EAAE,UAAU,GACnB,aAAa,CAyTf"}