@nodetool-ai/execution 0.8.1

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

@@ -0,0 +1,89 @@
+import { Workspace as WorkspaceRow } from "@nodetool-ai/models";
+import { ProcessingContext, type StorageAdapter, type Workspace, type WorkspaceChange } from "@nodetool-ai/runtime";
+/**
+ * The host name the kernel's headless gate reports a denial under. Shared by
+ * the context built here and by `ExecutionSession.create`, which gates a
+ * caller's own context the same way when that caller set no gate.
+ */
+export declare const WORKFLOW_RUN_HOST = "kernel workflow run";
+/** Called once at startup by a host that serves cloud workspaces. */
+export declare function setWorkspaceCloudStorage(storage: StorageAdapter | null): void;
+/** What a host is told when a run writes in a workspace. */
+export interface WorkspaceFileChange extends WorkspaceChange {
+    workspaceId: string;
+    userId: string;
+}
+/** Called once at startup by a host that pushes workspace changes to clients. */
+export declare function setWorkspaceChangeNotifier(notify: ((change: WorkspaceFileChange) => void) | null): void;
+/** Build the {@link Workspace} a workspace row describes. */
+export declare function workspaceFromRow(row: WorkspaceRow): Workspace | null;
+/**
+ * Resolve the workspace a run reads and writes in.
+ *
+ * Selection is stored on the workflow (`workflow.workspace_id`); this maps it
+ * to a {@link Workspace}, gated on ownership and the workspace still being
+ * usable. When the workflow names none — or there is no workflow at all, which
+ * is every chat turn — the run falls back to the user's default workspace,
+ * created on first use.
+ *
+ * What comes back is an interface, not a directory: a local install gets one
+ * over a real folder and a cloud deployment one over its object storage, and
+ * nothing downstream can tell which. It answers null only when the database or
+ * the storage refused, and a caller that gets null must report that rather than
+ * writing somewhere else.
+ */
+export declare function resolveWorkflowWorkspace(workflowId: string | null, userId: string): Promise<Workspace | null>;
+/**
+ * The directory a run's workspace lives in, or null when it is virtual.
+ *
+ * Only for the few callers that still need a real path (host binaries). Prefer
+ * {@link resolveWorkflowWorkspace} and the {@link Workspace} interface, which
+ * work on both deployments.
+ */
+export declare function resolveWorkflowWorkspaceDir(workflowId: string | null, userId: string): Promise<string | null>;
+/** True when this deployment keeps workspaces in object storage. */
+export declare function usesCloudWorkspaces(): boolean;
+/**
+ * Build a minimal execution context carrying the resolved workspace, for run
+ * paths (REST / tRPC / MCP) that otherwise run without a ProcessingContext.
+ * The streaming WebSocket runner builds a richer context of its own; this keeps
+ * the workspace available everywhere else with the same resolution rules.
+ *
+ * The run's secrets come with it. Without a resolver `context.getSecret`
+ * answers `null` for every key and providers see only the process environment,
+ * so a key stored in the secret DB is invisible: an agent could generate an
+ * image in a chat turn and get a 401 from the same provider when it ran the
+ * workflow it had just built. The resolver is scoped to the run's own user,
+ * which is the only account whose secrets this run may read.
+ *
+ * So do the storage adapters. A context with none resolves no `asset://` ref
+ * at all — every uploaded image wired into a graph reached its node empty, and
+ * the node reported "The input image is empty". The host passes the same two
+ * adapters the streaming WebSocket runner uses; a host that passes neither
+ * keeps the old read-nothing behaviour rather than guessing at a backend.
+ *
+ * The context carries the headless permission gate, set here on purpose: a
+ * workflow run is consent — the user pressed Run on a graph whose nodes list
+ * their tools — so an agent loop inside it gates in `auto` with no human to
+ * ask, and every escalation the ladder raises is denied. Setting it
+ * explicitly is what lets `gateFromContext` in `@nodetool-ai/agents` treat a
+ * context with no gate as a bug and fail closed. A host that does have a
+ * user to ask — a chat turn — puts its own gate on the context it hands in
+ * and never comes through here.
+ */
+export declare function buildWorkspaceExecutionContext(opts: {
+    jobId: string;
+    workflowId?: string | null;
+    projectId?: string | null;
+    userId: string;
+    workspace: Workspace | null;
+    /** Overrides the per-user DB lookup (tests, a host with its own store). */
+    secretResolver?: (key: string, userId: string) => Promise<string | null | undefined> | string | null | undefined;
+    /** Temp store for runtime-materialized refs. */
+    storage?: StorageAdapter | null;
+    /** Asset store `asset://<id>` references resolve through. */
+    assetStorage?: StorageAdapter | null;
+    /** Enable the execution-owned FAL durable lifecycle for this host. */
+    durableFalGenerations?: boolean;
+}): ProcessingContext;
+//# sourceMappingURL=workflow-workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-workspace.d.ts","sourceRoot":"","sources":["../../src/service/workflow-workspace.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,SAAS,IAAI,YAAY,EAE1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,iBAAiB,EAKjB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAK9B;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAWvD,qEAAqE;AACrE,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAE7E;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAaD,iFAAiF;AACjF,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAC,GAAG,IAAI,GACrD,IAAI,CAEN;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAkBpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAsB3B;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExB;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,2EAA2E;IAC3E,cAAc,CAAC,EAAE,CACf,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpE,gDAAgD;IAChD,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACrC,sEAAsE;IACtE,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,GAAG,iBAAiB,CAwBpB"}

package/dist/service/workflow-workspace.js

@@ -0,0 +1,160 @@
+import { createLogger, workspaceStorageKind } from "@nodetool-ai/config";
+import { Workflow, Workspace as WorkspaceRow, getSecret } from "@nodetool-ai/models";
+import { PERMISSION_GATE_CONTEXT_KEY, ProcessingContext, createLocalWorkspace, createWorkspace, headlessGate, observeWorkspace } from "@nodetool-ai/runtime";
+import { createFalGenerationLifecycleHooks } from "../generation-lifecycle.js";
+const log = createLogger("nodetool.execution.workspace");
+/**
+ * The host name the kernel's headless gate reports a denial under. Shared by
+ * the context built here and by `ExecutionSession.create`, which gates a
+ * caller's own context the same way when that caller set no gate.
+ */
+export const WORKFLOW_RUN_HOST = "kernel workflow run";
+/**
+ * The object store a cloud deployment keeps workspaces in.
+ *
+ * Injected by the host rather than constructed here: `@nodetool-ai/execution`
+ * has no storage dependency, and the server already builds exactly one asset
+ * adapter it wants reused (connection pools, credentials).
+ */
+let cloudStorage = null;
+/** Called once at startup by a host that serves cloud workspaces. */
+export function setWorkspaceCloudStorage(storage) {
+    cloudStorage = storage;
+}
+/**
+ * Told about every file a run writes, so a host can push the change to a
+ * client watching that workspace.
+ *
+ * Injected the way {@link setWorkspaceCloudStorage} is: `@nodetool-ai/execution`
+ * has no websocket to broadcast on, and the workspace row id — which the
+ * {@link Workspace} interface deliberately does not carry — is known only here,
+ * where the row is read.
+ */
+let changeNotifier = null;
+/** Called once at startup by a host that pushes workspace changes to clients. */
+export function setWorkspaceChangeNotifier(notify) {
+    changeNotifier = notify;
+}
+/** Build the {@link Workspace} a workspace row describes. */
+export function workspaceFromRow(row) {
+    const workspace = !row.isVirtual()
+        ? createLocalWorkspace(row.path)
+        : cloudStorage
+            ? createWorkspace(cloudStorage, { prefix: row.path })
+            : null;
+    if (!workspace) {
+        log.warn("A virtual workspace was requested but no cloud storage is configured", { workspaceId: row.id });
+        return null;
+    }
+    const notify = changeNotifier;
+    if (!notify)
+        return workspace;
+    return observeWorkspace(workspace, (change) => notify({ ...change, workspaceId: row.id, userId: row.user_id }));
+}
+/**
+ * Resolve the workspace a run reads and writes in.
+ *
+ * Selection is stored on the workflow (`workflow.workspace_id`); this maps it
+ * to a {@link Workspace}, gated on ownership and the workspace still being
+ * usable. When the workflow names none — or there is no workflow at all, which
+ * is every chat turn — the run falls back to the user's default workspace,
+ * created on first use.
+ *
+ * What comes back is an interface, not a directory: a local install gets one
+ * over a real folder and a cloud deployment one over its object storage, and
+ * nothing downstream can tell which. It answers null only when the database or
+ * the storage refused, and a caller that gets null must report that rather than
+ * writing somewhere else.
+ */
+export async function resolveWorkflowWorkspace(workflowId, userId) {
+    try {
+        if (workflowId) {
+            const workflow = await Workflow.find(userId, workflowId);
+            if (workflow?.workspace_id) {
+                const row = await WorkspaceRow.find(userId, workflow.workspace_id);
+                if (row?.isAccessible() && row.project_id === workflow.project_id) {
+                    const workspace = workspaceFromRow(row);
+                    if (workspace)
+                        return workspace;
+                }
+            }
+        }
+        const fallback = await WorkspaceRow.ensureDefault(userId);
+        return fallback.isAccessible() ? workspaceFromRow(fallback) : null;
+    }
+    catch (err) {
+        log.warn("Failed to resolve run workspace", {
+            workflowId,
+            userId,
+            error: err instanceof Error ? err.message : String(err)
+        });
+        return null;
+    }
+}
+/**
+ * The directory a run's workspace lives in, or null when it is virtual.
+ *
+ * Only for the few callers that still need a real path (host binaries). Prefer
+ * {@link resolveWorkflowWorkspace} and the {@link Workspace} interface, which
+ * work on both deployments.
+ */
+export async function resolveWorkflowWorkspaceDir(workflowId, userId) {
+    return (await resolveWorkflowWorkspace(workflowId, userId))?.localDir ?? null;
+}
+/** True when this deployment keeps workspaces in object storage. */
+export function usesCloudWorkspaces() {
+    return workspaceStorageKind() === "cloud";
+}
+/**
+ * Build a minimal execution context carrying the resolved workspace, for run
+ * paths (REST / tRPC / MCP) that otherwise run without a ProcessingContext.
+ * The streaming WebSocket runner builds a richer context of its own; this keeps
+ * the workspace available everywhere else with the same resolution rules.
+ *
+ * The run's secrets come with it. Without a resolver `context.getSecret`
+ * answers `null` for every key and providers see only the process environment,
+ * so a key stored in the secret DB is invisible: an agent could generate an
+ * image in a chat turn and get a 401 from the same provider when it ran the
+ * workflow it had just built. The resolver is scoped to the run's own user,
+ * which is the only account whose secrets this run may read.
+ *
+ * So do the storage adapters. A context with none resolves no `asset://` ref
+ * at all — every uploaded image wired into a graph reached its node empty, and
+ * the node reported "The input image is empty". The host passes the same two
+ * adapters the streaming WebSocket runner uses; a host that passes neither
+ * keeps the old read-nothing behaviour rather than guessing at a backend.
+ *
+ * The context carries the headless permission gate, set here on purpose: a
+ * workflow run is consent — the user pressed Run on a graph whose nodes list
+ * their tools — so an agent loop inside it gates in `auto` with no human to
+ * ask, and every escalation the ladder raises is denied. Setting it
+ * explicitly is what lets `gateFromContext` in `@nodetool-ai/agents` treat a
+ * context with no gate as a bug and fail closed. A host that does have a
+ * user to ask — a chat turn — puts its own gate on the context it hands in
+ * and never comes through here.
+ */
+export function buildWorkspaceExecutionContext(opts) {
+    const generationLifecycle = opts.durableFalGenerations
+        ? createFalGenerationLifecycleHooks({
+            userId: opts.userId,
+            jobId: opts.jobId,
+            projectId: opts.projectId,
+            publicUrl: process.env["NODETOOL_PUBLIC_URL"] ?? null
+        })
+        : undefined;
+    const context = new ProcessingContext({
+        jobId: opts.jobId,
+        workflowId: opts.workflowId ?? null,
+        projectId: opts.projectId ?? null,
+        userId: opts.userId,
+        workspace: opts.workspace,
+        storage: opts.storage ?? null,
+        assetStorage: opts.assetStorage ?? null,
+        secretResolver: opts.secretResolver ??
+            ((key, userId) => getSecret(key, userId)),
+        generationLifecycle
+    });
+    context.set(PERMISSION_GATE_CONTEXT_KEY, headlessGate(WORKFLOW_RUN_HOST));
+    return context;
+}
+//# sourceMappingURL=workflow-workspace.js.map

package/dist/service/workflow-workspace.js.map

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

package/dist/session.d.ts

@@ -0,0 +1,62 @@
+import { type RunResult } from "@nodetool-ai/kernel";
+import type { HydratedGraphData, ProcessingMessage } from "@nodetool-ai/protocol";
+import type { ExecutionSessionOptions } from "./types.js";
+export declare class ExecutionSession {
+    readonly jobId: string;
+    readonly workflowId: string | null;
+    readonly graph: HydratedGraphData;
+    private readonly runner;
+    /** Null unless the caller opted into `captureMessages` (see options). */
+    private readonly stream;
+    private readonly persistence;
+    private readonly bridge;
+    private readonly resultPromise;
+    private runTimeoutHandle;
+    private _cancelReason;
+    private constructor();
+    /** Map a kernel run status onto the `job.end` reason. */
+    private endReason;
+    static create(options: ExecutionSessionOptions): Promise<ExecutionSession>;
+    /**
+     * Live message stream — closes once the run reaches a terminal state.
+     * Requires `captureMessages: true` at `create()`; without it nothing is
+     * queued (see that option) and reading this throws rather than handing back
+     * a stream that would silently yield nothing.
+     */
+    get messages(): AsyncIterable<ProcessingMessage>;
+    /** The run's terminal result. Never rejects — kernel failures resolve as `status: "failed"`. */
+    get result(): Promise<RunResult>;
+    /**
+     * Live resource counts, for leak accounting: after a terminal result every
+     * one of these must be back to zero. Measured, not inferred — the
+     * reliability harness's `cleanup-leaks` invariant asserts against these
+     * numbers and reports a violation when a driver can't produce them.
+     */
+    resourceCounters(): {
+        liveActors: number;
+        pendingControlResponses: number;
+        pendingTimers: number;
+        pythonBridgePendingRequests: number;
+    };
+    /** The reason passed to the most recent `cancel()` call, if any. */
+    get cancelReason(): string | null;
+    /** Stream one more value into a live input node (mirrors the WS `stream_input` command). */
+    pushInput(inputName: string, value: unknown, sourceHandle?: string): Promise<void>;
+    /** Signal end-of-stream for a live input node (mirrors `end_input_stream`). */
+    finishInputStream(inputName: string, sourceHandle?: string): void;
+    /**
+     * Push property updates into a running node's executor instance (live
+     * parameter changes, e.g. a synth knob while a patch plays — mirrors the
+     * WS runner's `update_node_properties` command). Returns `true` when the
+     * node's executor exists and supports live updates; `false` is not an
+     * error — the caller's own state already holds the new value for the next
+     * run.
+     */
+    updateNodeProperties(nodeId: string, properties: Record<string, unknown>): boolean;
+    /**
+     * The only cancel path. `runTimeoutMs` is implemented as
+     * `cancel("timeout")` — there is no separate timeout code path.
+     */
+    cancel(reason?: string): void;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAW/B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAI1D,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyC;IACrE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,gBAAgB,CAA8C;IACtE,OAAO,CAAC,aAAa,CAAuB;IAE5C,OAAO,eAiIN;IAED,yDAAyD;IACzD,OAAO,CAAC,SAAS;IAQjB,OAAa,MAAM,CACjB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAsK3B;IAED;;;;;OAKG;IACH,IAAI,QAAQ,IAAI,aAAa,CAAC,iBAAiB,CAAC,CAS/C;IAED,gGAAgG;IAChG,IAAI,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,CAE/B;IAED;;;;;OAKG;IACH,gBAAgB;;;;;MASf;IAED,oEAAoE;IACpE,IAAI,YAAY,IAAI,MAAM,GAAG,IAAI,CAEhC;IAED,4FAA4F;IAC5F,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAEf;IAED,+EAA+E;IAC/E,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAEhE;IAED;;;;;;;OAOG;IACH,oBAAoB,CAClB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAET;IAED;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAG5B;CACF"}