@nodetool-ai/execution 0.8.1

package/dist/service/workflow-run.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Running a saved workflow, as a service every host can call in-process.
+ *
+ * This is what `POST /api/workflows/:id/run|debug` does minus Request/Response
+ * parsing: find the workflow, refuse a graph whose model selections cannot be
+ * honoured, create the job row, run it, finalize the row, and shape the payload
+ * — plain `/run` or the debug report. The interactive path parks escalations in
+ * the {@link debugSessions} registry and hands back the session event.
+ *
+ * The websocket package keeps the Fastify routes and calls this; the agent
+ * tools call it directly, so `run_workflow` no longer needs a server listening
+ * on localhost to run a workflow.
+ */
+import { WorkflowRunner } from "@nodetool-ai/kernel";
+import { type NodeRegistry } from "@nodetool-ai/node-sdk";
+import type { NodeExecutor, ProcessingContext, StorageAdapter, Workspace } from "@nodetool-ai/runtime";
+import type { RawGraphInput } from "../types.js";
+import { type RunModelCatalogs } from "../preflight.js";
+import type { ExecutionSummary } from "../debug/types.js";
+import { DebugSession, type DebugSessionEvent } from "./debug-sessions.js";
+export { modelSelectionErrors, unconfiguredProviderErrors, formatPreflightDetail, ExecutionPreflightError } from "../preflight.js";
+export type { CredentialResolver, ExecutionPreflightIssue, RunModelCatalogs } from "../preflight.js";
+type WorkflowRunResult = Awaited<ReturnType<WorkflowRunner["run"]>>;
+/**
+ * What the host brings to a run: the node registry, and — for a host that also
+ * owns a Python worker — how to resolve a Python node and how to wake the
+ * bridge. A host with neither (the agent tools, a test) supplies just the
+ * registry and gets registry-only resolution.
+ */
+export interface WorkflowRunEnvironment {
+    registry: NodeRegistry;
+    resolveExecutor?: (node: {
+        id: string;
+        type: string;
+        [key: string]: unknown;
+    }) => NodeExecutor;
+    ensurePythonBridge?: () => Promise<void>;
+    /**
+     * Attach host-provided model interfaces (asset persistence, message
+     * storage, …) to the run's ProcessingContext before execution. Without it
+     * nodes that persist artifacts — every image Output — fail their run.
+     */
+    configureContext?: (context: ProcessingContext) => void;
+    /**
+     * The store `asset://<id>` inputs resolve through, and the temp store for
+     * runtime-materialized refs. A host that brings neither runs with a context
+     * that can write assets but not read them.
+     */
+    assetStorage?: StorageAdapter | null;
+    storage?: StorageAdapter | null;
+}
+export interface RunWorkflowOptions {
+    /**
+     * The saved workflow to run. With {@link RunWorkflowOptions.graph} nothing
+     * is looked up and this is only the label the job row and the cost ledger
+     * carry, so a run that belongs to no workflow passes `""`.
+     */
+    workflowId: string;
+    userId: string;
+    /**
+     * Run this graph instead of the one stored on `workflowId`.
+     *
+     * A caller that assembles a graph on the fly — `render_timeline` builds a
+     * `nodetool.timeline.RenderTimeline` graph (D12,
+     * docs/plans/motion-graphics.md) — gets the job row, the logs, the progress
+     * messages and cancel without first saving a workflow nobody asked for.
+     */
+    graph?: RawGraphInput;
+    /**
+     * Name for the job row. A graph run has no workflow to name it, so without
+     * this the job lists as an unlabelled row.
+     */
+    jobName?: string;
+    /**
+     * The run environment, or a lazy resolver for it. Pass the resolver form
+     * when constructing the environment is expensive (registry bootstrap,
+     * Python bridge): it is awaited only after the cheap not-found and
+     * model-selection checks have passed.
+     */
+    environment: WorkflowRunEnvironment | (() => Promise<WorkflowRunEnvironment>);
+    params?: Record<string, unknown>;
+    /** Return the full debug report (summary + verdict) instead of the run row. */
+    debug?: boolean;
+    /**
+     * Detach the run: the call returns as soon as the job row exists, and the
+     * run finishes on its own, writing its status and outputs onto the job.
+     * The caller polls `get_job` (or `nodetool.jobs.wait`) for the result.
+     */
+    background?: boolean;
+    /**
+     * Bubble node failures up to the caller instead of resolving them here: the
+     * call returns as soon as a node invocation escalates and the run stays
+     * parked until a verdict arrives via {@link submitEscalationVerdict}.
+     */
+    interactive?: boolean;
+    maxDecisions?: number;
+    maxRetriesPerNode?: number;
+    decisionTimeoutMs?: number;
+    /**
+     * Injected so a host that mocks workspace resolution (the websocket tests
+     * do) keeps controlling it. Defaults to the workspace stored on the workflow.
+     */
+    resolveWorkspace?: (workflowId: string | null, userId: string) => Promise<Workspace | null>;
+    catalogs?: RunModelCatalogs;
+    /**
+     * The project this run belongs to, when the caller knows one. Neither a
+     * workflow row nor a job row carries a project today, so nothing here can
+     * derive it — a caller that has the context (a project's agent thread, a
+     * document's run) passes it, and every other caller leaves the ledger rows
+     * with a null project rather than defaulting them into the loose bucket.
+     */
+    projectId?: string | null;
+    /** The project document this run is producing, when the caller names one. */
+    documentId?: string | null;
+}
+/**
+ * A run's answer. `error` is a refusal the caller turns into its own transport
+ * error (an HTTP status, a tool error object); anything genuinely exceptional
+ * still throws.
+ */
+export type RunWorkflowOutcome = {
+    kind: "payload";
+    payload: Record<string, unknown>;
+} | {
+    kind: "error";
+    status: number;
+    detail: string;
+};
+/**
+ * Server-side ceilings for the interactive bounds a caller may ask for. A
+ * number nobody would type by hand — a decision timeout of a day, ten thousand
+ * decisions — is clamped rather than honored.
+ */
+export declare const MAX_INTERACTIVE_DECISIONS = 100;
+export declare const MAX_INTERACTIVE_RETRIES_PER_NODE = 20;
+export declare const MAX_INTERACTIVE_DECISION_TIMEOUT_MS: number;
+/**
+ * An interactive-run bound: an integer in `[min, max]`, or undefined.
+ * Out-of-range highs clamp to `max`; anything that is not a sane integer (NaN,
+ * Infinity, negatives, fractions) is undefined so the caller gets the default
+ * instead of a bound that fails every decision instantly.
+ */
+export declare function boundedRunOption(value: number | undefined, min: number, max: number): number | undefined;
+/**
+ * How much serialized output a job row will carry. Outputs are normally
+ * asset refs and short strings; a run that emits a megabyte of text should
+ * not turn every `get_job` into that megabyte, so past this the row records
+ * the handle names instead and the caller reads the values from the assets.
+ */
+export declare const MAX_PERSISTED_OUTPUT_BYTES = 256000;
+/**
+ * Drop inline bytes from an asset ref that already says where its bytes live.
+ *
+ * A media output travels as `{type, data: "<base64>", asset_id, uri}` — the
+ * bytes and the handle, both. The job row wants only the handle: it is read
+ * back by `get_job`, which hands it to an agent. Carrying the base64 pushed
+ * every real media run past {@link MAX_PERSISTED_OUTPUT_BYTES}, so the row
+ * recorded the omission marker instead of the asset the run produced, and a
+ * caller that ran a render in the background could not find its video.
+ *
+ * A ref with no `asset_id` and no `uri` keeps its `data`: dropping that loses
+ * the only copy.
+ */
+export declare function withoutInlineAssetBytes(outputs: Record<string, unknown>): Record<string, unknown>;
+/** What the row holds instead of an outputs bag it cannot carry. */
+export interface OmittedOutputs {
+    omitted: true;
+    reason: string;
+    handles: string[];
+}
+/**
+ * The outputs to store on the job row, or a marker naming the handles when
+ * they are too big to keep. Pure so the size rule is pinned by a test.
+ */
+export declare function persistableOutputs(outputs: Record<string, unknown>): Record<string, unknown> | OmittedOutputs;
+/** How many log entries a job row keeps — the tail, which explains a failure. */
+export declare const MAX_PERSISTED_LOG_ENTRIES = 200;
+/** One persisted log line, in the shape `get_job_logs` hands back. */
+export interface PersistedJobLog extends Record<string, unknown> {
+    severity: string;
+    node_id: string | null;
+    node_name: string | null;
+    content: string;
+}
+/**
+ * The run's log tail plus one line per node that failed.
+ *
+ * `job.logs` had no writer at all: every `get_job_logs` call answered
+ * `total_logs: 0`, and `debug_workflow` reported an empty `logs` array, so the
+ * one tool an agent reaches for after a background run went wrong could not
+ * tell it anything. The messages are already folded for the debug payload;
+ * this keeps the part that survives the run.
+ */
+export declare function persistableLogs(summary: ExecutionSummary): PersistedJobLog[];
+export declare function buildWorkflowRunPayload(jobId: string, workflowId: string, result: WorkflowRunResult, debug: boolean, extras: {
+    background: boolean;
+}): {
+    job_id: string;
+    workflow_id: string;
+    status: "cancelled" | "completed" | "failed";
+    outputs: Record<string, unknown[]>;
+    error: string | null;
+    summary: ExecutionSummary;
+    verdict: import("../debug/types.js").RunVerdict | {
+        ok: boolean;
+        issues: string[];
+        headline: string;
+        warnings: string[];
+    };
+    message_count?: undefined;
+    background?: undefined;
+} | {
+    summary?: undefined;
+    verdict?: undefined;
+    job_id: string;
+    workflow_id: string;
+    status: "cancelled" | "completed" | "failed";
+    outputs: Record<string, unknown[]>;
+    error: string | null;
+    message_count: number;
+    background: boolean;
+};
+/** One escalated/running/done payload shape for every interactive response. */
+export declare function debugSessionEventPayload(session: DebugSession, event: DebugSessionEvent): {
+    session_id: string;
+    escalation_id?: undefined;
+    escalation?: undefined;
+    resolve?: undefined;
+    status?: undefined;
+    job_id?: undefined;
+    workflow_id?: undefined;
+} | {
+    status: string;
+    session_id: string;
+    job_id: string;
+    workflow_id: string | null;
+    escalation_id: string;
+    escalation: {
+        nodeId: string;
+        nodeType: string;
+        correlationLineage: string[];
+        invocationKey: string;
+        allowedActions: ("end_stream" | "fail" | "retry" | "skip" | "substitute")[];
+        detail: string;
+        failureSignature?: string | undefined;
+        candidateOutput?: unknown;
+        inputs: Record<string, unknown>;
+        declaredOutputs: Record<string, string>;
+        attempt: number;
+        spentCostUsd: number;
+        createdAssets: boolean;
+        retrySafe: boolean;
+        emitted: boolean;
+    };
+    resolve: string;
+} | {
+    escalation_id?: undefined;
+    escalation?: undefined;
+    resolve?: undefined;
+    status: string;
+    session_id: string;
+    job_id: string;
+    workflow_id: string | null;
+};
+/**
+ * Run a saved workflow end to end. Everything the HTTP route did except read
+ * the request and write the response.
+ */
+export declare function runWorkflow(options: RunWorkflowOptions): Promise<RunWorkflowOutcome>;
+/** Read a session's current state without waiting. */
+export declare function peekDebugSession(sessionId: string, userId: string): RunWorkflowOutcome;
+/**
+ * Answer the escalation a run is parked on, then wait for whatever comes next
+ * — the following escalation, or the run's final report.
+ */
+export declare function submitEscalationVerdict(sessionId: string, userId: string, escalationId: string, verdict: Parameters<DebugSession["submitVerdict"]>[1]): Promise<RunWorkflowOutcome>;
+/** Cancel a session's run and return its final report. */
+export declare function cancelDebugSession(sessionId: string, userId: string): Promise<RunWorkflowOutcome>;
+//# sourceMappingURL=workflow-run.d.ts.map

package/dist/service/workflow-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-run.d.ts","sourceRoot":"","sources":["../../src/service/workflow-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAiB,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,SAAS,EACV,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAM1D,OAAO,EAEL,YAAY,EAIZ,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAe7B,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAIzB,KAAK,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAsCpE;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE;QACvB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,KAAK,YAAY,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACxD;;;;OAIG;IACH,YAAY,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACrC,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,WAAW,EAAE,sBAAsB,GAAG,CAAC,MAAM,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CACjB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,eAAO,MAAM,gCAAgC,KAAK,CAAC;AACnD,eAAO,MAAM,mCAAmC,QAAc,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAKpB;AAeD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAuBD,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAmB1C;AAED,iFAAiF;AACjF,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAK7C,sEAAsE;AACtE,MAAM,WAAW,eAAgB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,EAAE,CAoB5E;AAwBD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;EA4ChC;AAED,+EAA+E;AAC/E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BzB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAgT7B;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,kBAAkB,CASpB;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,UAAU,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,GACpD,OAAO,CAAC,kBAAkB,CAAC,CAc7B;AAED,0DAA0D;AAC1D,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,CAO7B"}