@smithers-orchestrator/graph 0.16.9 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/graph",
-  "version": "0.16.9",
+  "version": "0.17.0",
   "description": "Framework-neutral Smithers workflow graph model and extraction helpers",
   "type": "module",
   "sideEffects": false,
@@ -20,8 +20,10 @@
     "src/"
   ],
   "dependencies": {
-    "@smithers-orchestrator/agents": "0.16.9",
-    "@smithers-orchestrator/errors": "0.16.9"
+    "drizzle-orm": "^0.45.2",
+    "zod": "^4.3.6",
+    "@smithers-orchestrator/agents": "0.17.0",
+    "@smithers-orchestrator/errors": "0.17.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/dom/extract.js

@@ -24,11 +24,28 @@ import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 //   differ, so replacing this implementation would not produce identical output
 //   for all inputs.
 const loadRuntimeModule = new Function("specifier", "return import(specifier)");
-// CLI agents (Claude Code, Codex, etc.) can spend minutes reading files and
-// thinking without producing stdout.  60s was too aggressive and caused
-// spurious aborts on complex spec/research/plan generation tasks.
-const DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS = 300_000;
-const DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS = 300_000;
+// CLI agents (Claude Code, Codex, Gemini, Kimi) can spend many minutes reading
+// files and thinking without producing stdout. 5 min was still too aggressive:
+// reviewer agents on substantive diffs were getting killed mid-review and
+// breaking ValidationLoop. 10 min matches the explicit per-task overrides used
+// by implement/validate tasks.
+//
+// The default can be overridden at runtime via the SMITHERS_TASK_HEARTBEAT_MS
+// environment variable.
+const HEARTBEAT_DEFAULT_MS = 600_000;
+function envHeartbeatTimeoutMs() {
+    const raw = typeof process !== "undefined" && process?.env
+        ? process.env.SMITHERS_TASK_HEARTBEAT_MS
+        : undefined;
+    if (typeof raw !== "string" || raw.length === 0)
+        return HEARTBEAT_DEFAULT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return HEARTBEAT_DEFAULT_MS;
+    return Math.floor(parsed);
+}
+const DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS = envHeartbeatTimeoutMs();
+const DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS = envHeartbeatTimeoutMs();
 /**
  * @param {unknown} value
  * @returns {boolean}
@@ -101,17 +118,24 @@ function getRalphIteration(opts, id) {
 /**
  * @param {Record<string, unknown>} raw
  */
-function resolveRetryConfig(raw) {
+function resolveRetryConfig(raw, isAgent = false) {
     const noRetry = Boolean(raw.noRetry);
     const continueOnFail = Boolean(raw.continueOnFail);
     const hasExplicitRetries = typeof raw.retries === "number" && !Number.isNaN(raw.retries);
     const hasExplicitRetryPolicy = Boolean(raw.retryPolicy && typeof raw.retryPolicy === "object");
     const defaultNoRetryForContinueOnFail = continueOnFail && !hasExplicitRetries && !hasExplicitRetryPolicy;
-    const retries = noRetry || defaultNoRetryForContinueOnFail
+    // Agent tasks (CLI agents like Codex/Claude) can hit transient upstream
+    // failures (e.g. "thread <uuid> not found"). Give them at least one free
+    // retry by default — even when the user opted into continueOnFail —
+    // unless they explicitly requested noRetry.
+    const baseRetries = noRetry
         ? 0
-        : hasExplicitRetries
-            ? /** @type {number} */ (raw.retries)
-            : Infinity;
+        : defaultNoRetryForContinueOnFail
+            ? (isAgent ? 1 : 0)
+            : hasExplicitRetries
+                ? /** @type {number} */ (raw.retries)
+                : Infinity;
+    const retries = baseRetries;
     const retryPolicy = hasExplicitRetryPolicy
         ? /** @type {import("../RetryPolicy.ts").RetryPolicy} */ (raw.retryPolicy)
         : retries > 0
@@ -404,7 +428,13 @@ export function extractFromHost(root, opts) {
                 prompt: undefined,
                 staticPayload: undefined,
                 computeFn: async () => {
-                    const { executeSandbox } = await loadRuntimeModule("@smithers-orchestrator/sandbox/execute");
+                    const [
+                        { executeSandbox },
+                        { executeChildWorkflow },
+                    ] = await Promise.all([
+                        loadRuntimeModule("@smithers-orchestrator/sandbox/execute"),
+                        loadRuntimeModule("@smithers-orchestrator/engine/child-workflow"),
+                    ]);
                     if (!workflowDef) {
                         throw new SmithersError("INVALID_INPUT", `Sandbox ${nodeId} is missing workflow definition.`, { nodeId });
                     }
@@ -417,6 +447,7 @@ export function extractFromHost(root, opts) {
                             ? runtime
                             : "bubblewrap",
                         workflow: workflowDef,
+                        executeChildWorkflow,
                         input: raw.__smithersSandboxInput ?? raw.input,
                         rootDir: topWorktree?.path ?? process.cwd(),
                         allowNetwork: Boolean(raw.allowNetwork),
@@ -703,14 +734,14 @@ export function extractFromHost(root, opts) {
                 }
                 : undefined;
             const skipIf = Boolean(raw.skipIf);
-            const { retries, retryPolicy } = resolveRetryConfig(raw);
+            const agent = raw.agent;
+            const kind = raw.__smithersKind;
+            const isAgent = kind === "agent" || Boolean(agent);
+            const { retries, retryPolicy } = resolveRetryConfig(raw, isAgent);
             const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : null;
             const parsedHeartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
             const continueOnFail = Boolean(raw.continueOnFail);
             const cachePolicy = raw.cache && typeof raw.cache === "object" ? raw.cache : undefined;
-            const agent = raw.agent;
-            const kind = raw.__smithersKind;
-            const isAgent = kind === "agent" || Boolean(agent);
             const heartbeatTimeoutMs = parsedHeartbeatTimeoutMs ??
                 (isAgent ? DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS : null);
             const prompt = isAgent ? String(raw.children ?? "") : undefined;
@@ -761,6 +792,8 @@ export function extractFromHost(root, opts) {
                 heartbeatTimeoutMs,
                 continueOnFail,
                 cachePolicy,
+                hijack: Boolean(raw.hijack),
+                onHijackExit: raw.onHijackExit === "reopen" ? "reopen" : "complete",
                 agent,
                 prompt,
                 staticPayload,

package/src/extract.js

@@ -8,8 +8,25 @@ import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 
 const DEFAULT_MERGE_QUEUE_CONCURRENCY = 1;
 const WORKTREE_EMPTY_PATH_ERROR = "<Worktree> requires a non-empty path prop";
-const DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS = 300_000;
-const DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS = 300_000;
+// Default per-task heartbeat timeout. 10 min is the floor for agent-backed
+// tasks: LLM CLIs (claude, codex, gemini, kimi) can sit silent for several
+// minutes during long deliberation or large-context reads. The previous
+// 5-minute default killed reviewer agents mid-review and broke ValidationLoop.
+// Overridable at runtime via SMITHERS_TASK_HEARTBEAT_MS.
+const HEARTBEAT_DEFAULT_MS = 600_000;
+function envHeartbeatTimeoutMs() {
+    const raw = typeof process !== "undefined" && process?.env
+        ? process.env.SMITHERS_TASK_HEARTBEAT_MS
+        : undefined;
+    if (typeof raw !== "string" || raw.length === 0)
+        return HEARTBEAT_DEFAULT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return HEARTBEAT_DEFAULT_MS;
+    return Math.floor(parsed);
+}
+const DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS = envHeartbeatTimeoutMs();
+const DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS = envHeartbeatTimeoutMs();
 /**
  * @param {string} prefix
  * @param {readonly number[]} path
@@ -102,17 +119,23 @@ function parseHeartbeatTimeoutMs(raw) {
 /**
  * @param {Record<string, unknown>} raw
  */
-function resolveRetryConfig(raw) {
+function resolveRetryConfig(raw, isAgent = false) {
     const noRetry = Boolean(raw.noRetry);
     const continueOnFail = Boolean(raw.continueOnFail);
     const hasExplicitRetries = typeof raw.retries === "number" && !Number.isNaN(raw.retries);
     const hasExplicitRetryPolicy = Boolean(raw.retryPolicy && typeof raw.retryPolicy === "object");
     const defaultNoRetryForContinueOnFail = continueOnFail && !hasExplicitRetries && !hasExplicitRetryPolicy;
-    const retries = noRetry || defaultNoRetryForContinueOnFail
+    // Agent tasks (CLI agents like Codex/Claude) can hit transient upstream
+    // failures (e.g. "thread <uuid> not found"). Give them at least one free
+    // retry by default — even when the user opted into continueOnFail —
+    // unless they explicitly requested noRetry.
+    const retries = noRetry
         ? 0
-        : hasExplicitRetries
-            ? raw.retries
-            : Infinity;
+        : defaultNoRetryForContinueOnFail
+            ? (isAgent ? 1 : 0)
+            : hasExplicitRetries
+                ? raw.retries
+                : Infinity;
     const retryPolicy = hasExplicitRetryPolicy
         ? raw.retryPolicy
         : retries > 0
@@ -538,9 +561,9 @@ export function extractGraph(root, opts) {
                 raw.approvalOnDeny === "fail"
                 ? raw.approvalOnDeny
                 : undefined;
-            const { retries, retryPolicy } = resolveRetryConfig(raw);
             const kind = raw.__smithersKind;
             const isAgent = kind === "agent" || Boolean(raw.agent);
+            const { retries, retryPolicy } = resolveRetryConfig(raw, isAgent);
             const isCompute = kind === "compute" && typeof raw.__smithersComputeFn === "function";
             const parsedHeartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
             const heartbeatTimeoutMs = parsedHeartbeatTimeoutMs ??
@@ -569,6 +592,8 @@ export function extractGraph(root, opts) {
                 cachePolicy: raw.cache && typeof raw.cache === "object"
                     ? raw.cache
                     : undefined,
+                hijack: Boolean(raw.hijack),
+                onHijackExit: raw.onHijackExit === "reopen" ? "reopen" : "complete",
                 agent: raw.agent,
                 prompt,
                 staticPayload: isAgent || isCompute

package/src/index.d.ts

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import { AgentCapabilityRegistry } from '@smithers-orchestrator/agents/capability-registry';
 
 type XmlNode$1 = XmlElement$1 | XmlText$1;
 type XmlElement$1 = {
@@ -42,7 +41,18 @@ type CachePolicy$1<Ctx = unknown> = {
 type AgentLike$1 = {
     id?: string;
     tools?: Record<string, unknown>;
-    capabilities?: AgentCapabilityRegistry;
+    capabilities?: {
+        version: 1;
+        engine: string;
+        runtimeTools: Record<string, {
+            description?: string;
+            source?: string;
+        }>;
+        mcp: Record<string, unknown>;
+        skills: Record<string, unknown>;
+        humanInteraction: Record<string, unknown>;
+        builtIns: string[];
+    };
     generate: (args: unknown) => Promise<unknown>;
 };
 type ScoreResult$1 = {
@@ -138,6 +148,8 @@ type TaskDescriptor$1 = {
     heartbeatTimeoutMs: number | null;
     continueOnFail: boolean;
     cachePolicy?: CachePolicy$1;
+    hijack?: boolean;
+    onHijackExit?: "complete" | "reopen";
     agent?: AgentLike$1 | AgentLike$1[];
     prompt?: string;
     staticPayload?: unknown;

package/src/types.ts

@@ -1,5 +1,4 @@
 import type { z } from "zod";
-import type { AgentCapabilityRegistry } from "@smithers-orchestrator/agents/capability-registry";
 
 export type XmlNode = XmlElement | XmlText;
 
@@ -51,7 +50,15 @@ export type CachePolicy<Ctx = unknown> = {
 export type AgentLike = {
   id?: string;
   tools?: Record<string, unknown>;
-  capabilities?: AgentCapabilityRegistry;
+  capabilities?: {
+    version: 1;
+    engine: string;
+    runtimeTools: Record<string, { description?: string; source?: string }>;
+    mcp: Record<string, unknown>;
+    skills: Record<string, unknown>;
+    humanInteraction: Record<string, unknown>;
+    builtIns: string[];
+  };
   generate: (args: unknown) => Promise<unknown>;
 };
 
@@ -155,6 +162,8 @@ export type TaskDescriptor = {
   heartbeatTimeoutMs: number | null;
   continueOnFail: boolean;
   cachePolicy?: CachePolicy;
+  hijack?: boolean;
+  onHijackExit?: "complete" | "reopen";
   agent?: AgentLike | AgentLike[];
   prompt?: string;
   staticPayload?: unknown;