@smithers-orchestrator/graph 0.20.4 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/graph",
-  "version": "0.20.4",
+  "version": "0.22.0",
   "description": "Framework-neutral Smithers workflow graph model and extraction helpers",
   "type": "module",
   "sideEffects": false,
@@ -22,7 +22,7 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/errors": "0.20.4"
+    "@smithers-orchestrator/errors": "0.22.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/dom/extract.js

@@ -398,7 +398,8 @@ export function extractFromHost(root, opts) {
                 : undefined;
             const parallelGroup = nextParallelStack[nextParallelStack.length - 1];
             const topWorktree = nextWorktreeStack[nextWorktreeStack.length - 1];
-            const runtime = raw.__smithersSandboxRuntime ?? raw.runtime ?? "bubblewrap";
+            const runtime = raw.__smithersSandboxRuntime ?? raw.runtime;
+            const provider = raw.__smithersSandboxProvider ?? raw.provider;
             const workflowDef = raw.__smithersSandboxWorkflow ??
                 raw.workflow;
             const descriptor = {
@@ -431,23 +432,27 @@ export function extractFromHost(root, opts) {
                     const [
                         { executeSandbox },
                         { executeChildWorkflow },
+                        { applyDiffBundle },
                     ] = await Promise.all([
                         loadRuntimeModule("@smithers-orchestrator/sandbox/execute"),
                         loadRuntimeModule("@smithers-orchestrator/engine/child-workflow"),
+                        loadRuntimeModule("@smithers-orchestrator/engine/effect/diff-bundle"),
                     ]);
                     if (!workflowDef) {
                         throw new SmithersError("INVALID_INPUT", `Sandbox ${nodeId} is missing workflow definition.`, { nodeId });
                     }
                     return executeSandbox({
-                        parentWorkflow: workflowDef && typeof workflowDef === "object" && "build" in workflowDef
-                            ? workflowDef
-                            : undefined,
+                        parentWorkflow: undefined,
                         sandboxId: nodeId,
-                        runtime: runtime === "docker" || runtime === "codeplane" || runtime === "bubblewrap"
+                        provider,
+                        runtime: runtime === undefined || runtime === "docker" || runtime === "codeplane" || runtime === "bubblewrap"
                             ? runtime
-                            : "bubblewrap",
+                            : (() => {
+                                throw new SmithersError("INVALID_INPUT", `Unsupported sandbox runtime: ${String(runtime)}`, { runtime });
+                            })(),
                         workflow: workflowDef,
                         executeChildWorkflow,
+                        applyDiffBundle,
                         input: raw.__smithersSandboxInput ?? raw.input,
                         rootDir: topWorktree?.path ?? process.cwd(),
                         allowNetwork: Boolean(raw.allowNetwork),
@@ -455,6 +460,7 @@ export function extractFromHost(root, opts) {
                         toolTimeoutMs: 60_000,
                         reviewDiffs: raw.reviewDiffs,
                         autoAcceptDiffs: raw.autoAcceptDiffs,
+                        allowNested: Boolean(raw.__smithersSandboxAllowNested ?? raw.allowNested),
                         config: {
                             image: raw.image,
                             env: raw.env,
@@ -472,7 +478,23 @@ export function extractFromHost(root, opts) {
                     ...raw.meta,
                     __sandbox: true,
                     __sandboxRuntime: runtime,
+                    __sandboxProvider: provider,
+                    __sandboxWorkflow: workflowDef,
                     __sandboxInput: raw.__smithersSandboxInput ?? raw.input,
+                    __sandboxAllowNetwork: Boolean(raw.allowNetwork),
+                    __sandboxReviewDiffs: raw.reviewDiffs,
+                    __sandboxAutoAcceptDiffs: raw.autoAcceptDiffs,
+                    __sandboxAllowNested: raw.__smithersSandboxAllowNested ?? raw.allowNested,
+                    __sandboxConfig: {
+                        image: raw.image,
+                        env: raw.env,
+                        ports: raw.ports,
+                        volumes: raw.volumes,
+                        memoryLimit: raw.memoryLimit,
+                        cpuLimit: raw.cpuLimit,
+                        command: raw.command,
+                        workspace: raw.workspace,
+                    },
                 },
                 parallelGroupId: parallelGroup?.id,
                 parallelMaxConcurrency: parallelGroup?.max,

package/src/extract.js

@@ -1,5 +1,7 @@
 import { isAbsolute, resolve as resolvePath } from "node:path";
+import { getTableName } from "drizzle-orm";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { validateForkSources } from "./validateForkSources.js";
 /** @typedef {import("./TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
 /** @typedef {import("./XmlNode.ts").XmlNode} XmlNode */
 /** @typedef {import("./ExtractOptions.ts").ExtractOptions} ExtractOptions */
@@ -58,23 +60,18 @@ function isZodObject(value) {
 }
 /**
  * @param {unknown} value
- * @returns {string | undefined}
+ * @returns {boolean}
  */
-function maybeTableName(value) {
+function isDrizzleTable(value) {
     if (!value || typeof value !== "object")
-        return undefined;
-    const symbols = Object.getOwnPropertySymbols(value);
-    for (const symbol of symbols) {
-        const key = String(symbol);
-        if (key.includes("drizzle") || key.includes("Name")) {
-            const symbolValue = value[symbol];
-            if (typeof symbolValue === "string" && symbolValue.length > 0) {
-                return symbolValue;
-            }
-        }
+        return false;
+    try {
+        const name = getTableName(value);
+        return typeof name === "string" && name.length > 0;
+    }
+    catch {
+        return false;
     }
-    const named = value.name;
-    return typeof named === "string" && named.length > 0 ? named : undefined;
 }
 /**
  * @param {Record<string, unknown>} raw
@@ -90,13 +87,17 @@ function resolveOutput(raw) {
             outputSchema: undefined,
         };
     }
-    const outputRef = isZodObject(outputRaw) ? outputRaw : undefined;
-    const tableName = typeof outputRaw === "string" ? outputRaw : maybeTableName(outputRaw) ?? "";
-    const outputTable = outputRef ? null : typeof outputRaw === "string" ? null : outputRaw;
+    const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
+    const outputTableName = outputTable
+        ? getTableName(outputTable)
+        : typeof outputRaw === "string"
+            ? outputRaw
+            : "";
+    const outputRef = !outputTable && isZodObject(outputRaw) ? outputRaw : undefined;
     const outputSchema = isZodObject(raw.outputSchema) ? raw.outputSchema : outputRef;
     return {
         outputTable,
-        outputTableName: tableName,
+        outputTableName,
         outputRef,
         outputSchema,
     };
@@ -308,13 +309,13 @@ export function extractGraph(root, opts) {
     const seenTcf = new Set();
     let ordinal = 0;
     /**
-   * @param {Record<string, unknown>} raw
    * @param {string} nodeId
+   * @param {string} kind
    * @param {Omit<TaskDescriptor, "ordinal" | "nodeId">} descriptor
    */
-    function addDescriptor(raw, nodeId, descriptor) {
+    function addDescriptor(nodeId, kind, descriptor) {
         if (seen.has(nodeId)) {
-            throw new SmithersError("DUPLICATE_ID", `Duplicate ${String(raw.__smithersKind ?? "Task")} id detected: ${nodeId}`, { id: nodeId });
+            throw new SmithersError("DUPLICATE_ID", `Duplicate ${kind} id detected: ${nodeId}`, { id: nodeId });
         }
         seen.add(nodeId);
         tasks.push({ nodeId, ordinal: ordinal++, ...descriptor });
@@ -399,7 +400,7 @@ export function extractGraph(root, opts) {
                 requireOutput(raw, nodeId, "Subflow");
                 const { retries, retryPolicy } = resolveRetryConfig(raw);
                 const output = resolveOutput(raw);
-                addDescriptor(raw, nodeId, {
+                addDescriptor(nodeId, "Subflow", {
                     ...common,
                     ...output,
                     needsApproval: false,
@@ -431,8 +432,8 @@ export function extractGraph(root, opts) {
             requireOutput(raw, nodeId, "Sandbox");
             const { retries, retryPolicy } = resolveRetryConfig(raw);
             const output = resolveOutput(raw);
-            const runtime = raw.__smithersSandboxRuntime ?? raw.runtime ?? "bubblewrap";
-            addDescriptor(raw, nodeId, {
+            const runtime = raw.__smithersSandboxRuntime ?? raw.runtime;
+            addDescriptor(nodeId, "Sandbox", {
                 ...common,
                 ...output,
                 needsApproval: false,
@@ -452,7 +453,23 @@ export function extractGraph(root, opts) {
                         : {}),
                     __sandbox: true,
                     __sandboxRuntime: runtime,
+                    __sandboxProvider: raw.__smithersSandboxProvider ?? raw.provider,
+                    __sandboxWorkflow: raw.__smithersSandboxWorkflow ?? raw.workflow,
                     __sandboxInput: raw.__smithersSandboxInput ?? raw.input,
+                    __sandboxAllowNetwork: Boolean(raw.allowNetwork),
+                    __sandboxReviewDiffs: raw.reviewDiffs,
+                    __sandboxAutoAcceptDiffs: raw.autoAcceptDiffs,
+                    __sandboxAllowNested: raw.__smithersSandboxAllowNested ?? raw.allowNested,
+                    __sandboxConfig: {
+                        image: raw.image,
+                        env: raw.env,
+                        ports: raw.ports,
+                        volumes: raw.volumes,
+                        memoryLimit: raw.memoryLimit,
+                        cpuLimit: raw.cpuLimit,
+                        command: raw.command,
+                        workspace: raw.workspace,
+                    },
                 },
             });
             return;
@@ -463,7 +480,7 @@ export function extractGraph(root, opts) {
             requireOutput(raw, nodeId, "WaitForEvent");
             const output = resolveOutput(raw);
             const onTimeout = raw.__smithersOnTimeout ?? raw.onTimeout ?? "fail";
-            addDescriptor(raw, nodeId, {
+            addDescriptor(nodeId, "WaitForEvent", {
                 ...common,
                 ...output,
                 needsApproval: false,
@@ -508,7 +525,7 @@ export function extractGraph(root, opts) {
             if (raw.every !== undefined) {
                 throw new SmithersError("INVALID_INPUT", `Timer ${nodeId} uses every=, but recurring timers are not supported yet.`, { nodeId, every: raw.every });
             }
-            addDescriptor(raw, nodeId, {
+            addDescriptor(nodeId, "Timer", {
                 ...common,
                 outputTable: null,
                 outputTableName: "",
@@ -572,9 +589,10 @@ export function extractGraph(root, opts) {
             if (prompt === "[object Object]") {
                 throw new SmithersError("MDX_PRELOAD_INACTIVE", `Task "${logicalNodeId}" prompt resolved to [object Object].`);
             }
-            addDescriptor(raw, nodeId, {
+            addDescriptor(nodeId, "Task", {
                 ...common,
                 ...output,
+                forkSource: typeof raw.fork === "string" && raw.fork ? raw.fork : undefined,
                 needsApproval: Boolean(raw.needsApproval),
                 waitAsync: Boolean(raw.waitAsync),
                 approvalMode,
@@ -636,6 +654,7 @@ export function extractGraph(root, opts) {
         worktreeStack: [],
         loopStack: [],
     });
+    validateForkSources(tasks);
     return { xml: toXmlNode(root), tasks, mountedTaskIds };
 }
 export const extractFromHost = extractGraph;

package/src/types.ts

@@ -133,6 +133,8 @@ export type TaskDescriptor = {
   ralphId?: string;
   dependsOn?: string[];
   needs?: Record<string, string>;
+  /** Logical id of the task whose final agent session this task forks. Gates execution and seeds the session. */
+  forkSource?: string;
   worktreeId?: string;
   worktreePath?: string;
   worktreeBranch?: string;

package/src/validateForkSources.js

@@ -0,0 +1,107 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+
+/** @typedef {import("./TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
+
+/**
+ * Strip the loop-scope suffix (`@@ralph=0,...`) from a node id to recover the
+ * logical task id authored in JSX. `fork` and `dependsOn` reference logical ids.
+ * @param {string} nodeId
+ * @returns {string}
+ */
+function logicalId(nodeId) {
+    const atIdx = nodeId.indexOf("@@");
+    return atIdx === -1 ? nodeId : nodeId.slice(0, atIdx);
+}
+
+/**
+ * Validate `<Task fork>` references across the extracted task list. Throws a
+ * typed SmithersError for fork sources that can never resolve to a usable
+ * session snapshot, so authoring mistakes fail fast at graph-build time rather
+ * than deadlocking the scheduler.
+ *
+ * Detects:
+ *   - TASK_FORK_SOURCE_NOT_FOUND — fork id absent from the graph (covers a
+ *     source that only exists in an unselected branch).
+ *   - TASK_FORK_SESSION_UNAVAILABLE — the forking task is not an agent task and
+ *     therefore has no session to seed.
+ *   - TASK_FORK_CYCLE — the fork edge closes a dependency cycle, directly or
+ *     indirectly (via `dependsOn` and/or other fork edges).
+ *
+ * Loop semantics are intentionally not validated here: `fork` resolves to the
+ * latest completed snapshot for a task id at execution time, so a source inside
+ * a loop is valid as long as its logical id appears in the graph.
+ *
+ * @param {readonly TaskDescriptor[]} tasks
+ * @returns {void}
+ */
+export function validateForkSources(tasks) {
+    const forks = tasks.filter((task) => typeof task.forkSource === "string" && task.forkSource);
+    if (forks.length === 0) {
+        return;
+    }
+    const presentLogicalIds = new Set(tasks.map((task) => logicalId(task.nodeId)));
+    // Union of dependency edges keyed by logical id: dependsOn entries plus the
+    // fork edge. Used only for cycle detection.
+    /** @type {Map<string, Set<string>>} */
+    const adjacency = new Map();
+    const addEdge = (from, to) => {
+        const cleanedFrom = logicalId(from);
+        const cleanedTo = logicalId(to);
+        let set = adjacency.get(cleanedFrom);
+        if (!set) {
+            set = new Set();
+            adjacency.set(cleanedFrom, set);
+        }
+        set.add(cleanedTo);
+    };
+    for (const task of tasks) {
+        const from = logicalId(task.nodeId);
+        for (const dep of task.dependsOn ?? []) {
+            addEdge(from, dep);
+        }
+        if (typeof task.forkSource === "string" && task.forkSource) {
+            addEdge(from, task.forkSource);
+        }
+    }
+    /**
+     * @param {string} from
+     * @param {string} target
+     * @returns {boolean}
+     */
+    const canReach = (from, target) => {
+        const stack = [from];
+        const visited = new Set();
+        while (stack.length > 0) {
+            const current = /** @type {string} */ (stack.pop());
+            if (current === target) {
+                return true;
+            }
+            if (visited.has(current)) {
+                continue;
+            }
+            visited.add(current);
+            const neighbors = adjacency.get(current);
+            if (neighbors) {
+                for (const next of neighbors) {
+                    stack.push(next);
+                }
+            }
+        }
+        return false;
+    };
+    for (const task of forks) {
+        const forkSource = /** @type {string} */ (task.forkSource);
+        const nodeLogicalId = logicalId(task.nodeId);
+        if (!presentLogicalIds.has(forkSource)) {
+            throw new SmithersError("TASK_FORK_SOURCE_NOT_FOUND", `Task "${task.nodeId}" forks "${forkSource}", which is not present in the workflow graph.`, { nodeId: task.nodeId, forkSource });
+        }
+        if (!task.agent) {
+            throw new SmithersError("TASK_FORK_SESSION_UNAVAILABLE", `Task "${task.nodeId}" uses fork but is not an agent task. Only agent tasks can fork a session.`, { nodeId: task.nodeId, forkSource });
+        }
+        // The fork edge is nodeLogicalId -> forkSource. A cycle exists iff
+        // forkSource can already reach nodeLogicalId through the dependency graph.
+        if (canReach(forkSource, nodeLogicalId)) {
+            throw new SmithersError("TASK_FORK_CYCLE", `Task "${task.nodeId}" forks "${forkSource}", which creates a dependency cycle.`, { nodeId: task.nodeId, forkSource });
+        }
+    }
+}