@agentproto/workflow-runtime 0.14.0 → 0.15.0

package/README.md

@@ -76,6 +76,38 @@ whenever the host wires `RunWorkflowArgs.workspace` — see **Run workspace
 | `group` | Run a list of steps as one unit; output is the last step's. |
 | `subworkflow` | Run a nested workflow with its own isolated bindings. |
 
+### Step timeouts (`tool` / `gate`)
+
+A `tool` or `gate` step's dispatch is bounded by `timeout_ms` (`timeoutMs` on
+the compiled `ToolStep`/`GateStep`) — default `DEFAULT_STEP_TIMEOUT_MS` (10
+minutes) when the step declares none. On expiry the step fails with `step
+'<id>': timed out after <n>ms`; the underlying subprocess (a `kind: cli`
+driver's spawn, or a `gate` step's command) is killed by its WHOLE process
+group, not just the direct child, so a subprocess that spawned its own
+children (e.g. headless Chrome) can't leave orphans running past the step.
+
+This exists because completion for both used to depend on the child's stdio
+pipes closing (`close`), not the direct child's own `exit` — a grandchild
+that inherited an fd (inherited/piped stdout or stderr) and outlived its
+parent (e.g. reparented to pid 1) could hold that pipe open forever even
+after the tool's actual work was done, hanging the step indefinitely with no
+timeout to bound it. Both the CLI driver's `runSubprocess` and this
+package's `defaultRunGateCommand` now settle on `exit` (with a short drain
+window for any already-in-flight stdio) instead.
+
+```yaml
+steps:
+  - id: pdf-render
+    kind: tool
+    tool: pdf.render
+    timeout_ms: 120000          # override the 10-minute default
+  - id: lint
+    kind: gate
+    command: pnpm
+    args: ["lint"]
+    timeout_ms: 60000
+```
+
 ### WORKFLOW.md `kind: branch` — exclusive arms + join
 
 `compileWorkflow` compiles a declarative AIP-15 `kind: branch` step (goto-style

package/dist/index.d.ts

@@ -51,6 +51,12 @@ interface ToolStep<TInput = unknown, TOutput = unknown, TContext extends ToolCon
     /** Cache this step's output under the run's cacheKey; only its `input` is hashed
      *  (not `context`/secrets). Default false. */
     cacheable?: boolean;
+    /** Hard wall-clock cap for this step's dispatch (driver resolve + execute),
+     *  in ms. Bounds a driver that never settles its own promise (e.g. a `kind:
+     *  cli` subprocess whose stdio pipe is held open by an orphaned grandchild
+     *  process — F45) rather than relying on the driver to self-timeout.
+     *  Default {@link DEFAULT_STEP_TIMEOUT_MS} when unset. */
+    timeoutMs?: number;
 }
 /** A pure in-run computation (combine / filter / shape) — no tool dispatch. */
 interface TransformStep {
@@ -104,6 +110,10 @@ interface TolerantFanOutResult<T = unknown> {
 /** Default for {@link MapStep.maxConsecutiveSpawnFailures} /
  *  {@link PipelineStep.maxConsecutiveSpawnFailures}. */
 declare const DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES = 3;
+/** Default for {@link ToolStep.timeoutMs} / {@link GateStep.timeoutMs} when
+ *  the step declares none — 10 minutes. Bounds an otherwise-unbounded `tool`
+ *  or `gate` step dispatch (F45). */
+declare const DEFAULT_STEP_TIMEOUT_MS: number;
 /**
  * Run a sub-step once per element of an array, optionally with bounded
  * concurrency. The element + index are exposed to the body via `bindings.item`
@@ -494,7 +504,9 @@ interface GateStep {
     /** Path (relative to `cwd`), of a JSON report file, consulted when stdout
      *  doesn't itself parse as JSON. */
     reportPath?: string;
-    /** Hard wall-clock cap for a single command invocation, in ms. */
+    /** Hard wall-clock cap for a single command invocation, in ms. Default
+     *  {@link DEFAULT_STEP_TIMEOUT_MS} when unset — a gate's subprocess is
+     *  never left to run unbounded (F45). */
     timeoutMs?: number;
     /** Re-run on a failing exit code, up to `maxAttempts` (default 1 = no
      *  retry — a single attempt, fail immediately on a non-zero exit). */
@@ -1203,4 +1215,4 @@ declare class NodeFsPort implements FsPort {
     lock(): Promise<FsLockHandle>;
 }
 
-export { type AgentHarness, AgentInputRequiredError, type AgentRefResolution, type AgentSandboxRef, type AgentSessionHost, AgentSpawnError, type AgentStep, type AgentStepFields, type ApprovalDecision, type ApprovalRequest, type ApprovalStep, type ArtifactEntry, type ArtifactStep, type Bindings, type BranchStep, type CompileWorkflowOptions, DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES, type FanOutOutcome, type GateCommandResult, type GateCommandRunner, type GateReportEvent, type GateStep, type GroupStep, type HarnessKnowledgeSelector, type InputRequiredRequest, type KnowledgeAppliedRecord, type LoopStep, type MapStep, type MaterializedKnowledge, MissingArtifactError, NodeFsPort, type OutputSchemaLike, type OutputsFileContract, type ParallelStep, type PipelineStep, type ResumeRequest, type RunStep, type RunWorkflowArgs, type RuntimeWorkflow, type SchemaValidationIssue, type Selector, type StepCache, type StepCacheEntry, type StepFailedInfo, type StepHookInfo, StepOutcomeError, type StepSkippedInfo, type SubworkflowStep, type SuspendStep, type TolerantFanOutResult, type ToolStep, type TransformStep, WorkflowCancelledError, WorkflowCompileError, type WorkflowInputValidation, type WorkflowRunResult, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, isCompilableJsonSchema, materializeKnowledge, normalizeWorkflowInputsSchema, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow, validateAgainstJsonSchema, validateWorkflowInput };
+export { type AgentHarness, AgentInputRequiredError, type AgentRefResolution, type AgentSandboxRef, type AgentSessionHost, AgentSpawnError, type AgentStep, type AgentStepFields, type ApprovalDecision, type ApprovalRequest, type ApprovalStep, type ArtifactEntry, type ArtifactStep, type Bindings, type BranchStep, type CompileWorkflowOptions, DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES, DEFAULT_STEP_TIMEOUT_MS, type FanOutOutcome, type GateCommandResult, type GateCommandRunner, type GateReportEvent, type GateStep, type GroupStep, type HarnessKnowledgeSelector, type InputRequiredRequest, type KnowledgeAppliedRecord, type LoopStep, type MapStep, type MaterializedKnowledge, MissingArtifactError, NodeFsPort, type OutputSchemaLike, type OutputsFileContract, type ParallelStep, type PipelineStep, type ResumeRequest, type RunStep, type RunWorkflowArgs, type RuntimeWorkflow, type SchemaValidationIssue, type Selector, type StepCache, type StepCacheEntry, type StepFailedInfo, type StepHookInfo, StepOutcomeError, type StepSkippedInfo, type SubworkflowStep, type SuspendStep, type TolerantFanOutResult, type ToolStep, type TransformStep, WorkflowCancelledError, WorkflowCompileError, type WorkflowInputValidation, type WorkflowRunResult, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, isCompilableJsonSchema, materializeKnowledge, normalizeWorkflowInputsSchema, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow, validateAgainstJsonSchema, validateWorkflowInput };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { runTool } from '@agentproto/driver';
 import { createHash } from 'crypto';
-import { execFile } from 'child_process';
+import { spawn } from 'child_process';
 import { stat, readFile, mkdir, writeFile, appendFile, readdir, copyFile, cp } from 'fs/promises';
 import { join, dirname, isAbsolute, basename, resolve, relative } from 'path';
 import { z } from 'zod';
@@ -323,6 +323,15 @@ function normalizeToolId(ref) {
   return slash === -1 ? s : s.slice(slash + 1);
 }
 var f = (step, key) => step[key];
+function assertStepTimeoutMs(id, kind, value) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    throw new WorkflowCompileError(
+      `${kind} step '${id}' has an invalid 'timeout_ms' (${JSON.stringify(value)}) \u2014 must be a number >= 1`
+    );
+  }
+  return value;
+}
 function assertLinear(steps) {
   steps.forEach((s, i) => {
     const next = s.next;
@@ -563,7 +572,7 @@ function compileGateStep(step, id) {
   const args = f(step, "args");
   const cwd = f(step, "cwd");
   const reportPath = f(step, "report");
-  const timeoutMs = f(step, "timeout_ms");
+  const timeoutMs = assertStepTimeoutMs(id, "gate", step.timeout_ms);
   const retry = f(step, "retry");
   const onFail = f(
     step,
@@ -601,6 +610,7 @@ function compileStep(step, ctx) {
       assertKnownStepRefs(inputs, ctx.knownStepIds, `tool step '${id}' inputs`, {
         makeError: (message) => new WorkflowCompileError(message)
       });
+      const timeoutMs = assertStepTimeoutMs(id, "tool", step.timeout_ms);
       return {
         kind: "tool",
         id,
@@ -608,7 +618,8 @@ function compileStep(step, ctx) {
         candidates: opts.candidates,
         input: (b) => resolveValue(inputs, b),
         context: opts.contextFor ? (b) => opts.contextFor(toolId, b) : void 0,
-        ...step.cacheable ? { cacheable: true } : {}
+        ...step.cacheable ? { cacheable: true } : {},
+        ...timeoutMs !== void 0 ? { timeoutMs } : {}
       };
     }
     case "map": {
@@ -773,6 +784,7 @@ function resolveRefString(stepId, field, value, b, onUnmatched = "passthrough")
 
 // src/types.ts
 var DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES = 3;
+var DEFAULT_STEP_TIMEOUT_MS = 10 * 60 * 1e3;
 var NodeFsPort = class {
   root;
   constructor(root) {
@@ -1448,23 +1460,83 @@ function tryParseJson(text) {
     return void 0;
   }
 }
+var GATE_STDIO_DRAIN_MS = 2e3;
+var GATE_KILL_GRACE_MS = 2e3;
 function defaultRunGateCommand(spec) {
+  const timeoutMs = spec.timeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
   return new Promise((resolve2) => {
-    execFile(
-      spec.command,
-      [...spec.args],
-      { cwd: spec.cwd, timeout: spec.timeoutMs, maxBuffer: 10 * 1024 * 1024, signal: spec.signal },
-      (err, stdout, stderr) => {
-        if (!err) {
-          resolve2({ exitCode: 0, stdout, stderr });
-          return;
-        }
-        const nodeErr = err;
-        const timedOut = nodeErr.killed === true && nodeErr.signal !== void 0 && spec.timeoutMs !== void 0;
-        const exitCode = typeof nodeErr.code === "number" ? nodeErr.code : 1;
-        resolve2({ exitCode, stdout, stderr, ...timedOut ? { timedOut: true } : {} });
+    const child = spawn(spec.command, [...spec.args], {
+      cwd: spec.cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: process.platform !== "win32"
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    let stdoutEnded = !child.stdout;
+    let stderrEnded = !child.stderr;
+    let exitCode;
+    let drainTimer;
+    const killGroup = (sig) => {
+      if (typeof child.pid !== "number") return;
+      try {
+        if (process.platform !== "win32") process.kill(-child.pid, sig);
+        else child.kill(sig);
+      } catch {
       }
-    );
+    };
+    let killTimer;
+    const kill = () => {
+      killGroup("SIGTERM");
+      killTimer = setTimeout(() => killGroup("SIGKILL"), GATE_KILL_GRACE_MS).unref();
+    };
+    const onAbort = () => kill();
+    if (spec.signal?.aborted) kill();
+    else spec.signal?.addEventListener("abort", onAbort, { once: true });
+    const timeoutTimer = setTimeout(() => {
+      timedOut = true;
+      kill();
+    }, timeoutMs).unref();
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(killTimer);
+      clearTimeout(timeoutTimer);
+      clearTimeout(drainTimer);
+      spec.signal?.removeEventListener("abort", onAbort);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      resolve2({ exitCode: code, stdout, stderr, ...timedOut ? { timedOut: true } : {} });
+    };
+    const maybeFinish = () => {
+      if (exitCode !== void 0 && stdoutEnded && stderrEnded) finish(exitCode);
+    };
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stdout?.on("end", () => {
+      stdoutEnded = true;
+      maybeFinish();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.stderr?.on("end", () => {
+      stderrEnded = true;
+      maybeFinish();
+    });
+    child.on("error", () => {
+      clearTimeout(timeoutTimer);
+      exitCode = 1;
+      drainTimer = setTimeout(() => finish(1), GATE_STDIO_DRAIN_MS).unref();
+      maybeFinish();
+    });
+    child.on("exit", (code, signal) => {
+      exitCode = code ?? (signal ? 1 : 0);
+      drainTimer = setTimeout(() => finish(exitCode), GATE_STDIO_DRAIN_MS).unref();
+      maybeFinish();
+    });
   });
 }
 async function resolveGateReport(cmd, cwd, reportPath) {
@@ -1545,6 +1617,27 @@ Please address the findings above, then reply when done.`
   }
   return last;
 }
+async function withStepTimeout(stepId, timeoutMs, parentSignal, fn) {
+  const controller = new AbortController();
+  const onParentAbort = (sig) => controller.abort(sig.reason);
+  const onParentAbortEvent = () => onParentAbort(parentSignal);
+  if (parentSignal?.aborted) onParentAbort(parentSignal);
+  else parentSignal?.addEventListener("abort", onParentAbortEvent, { once: true });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort(new Error(`step '${stepId}': timed out after ${timeoutMs}ms`));
+  }, timeoutMs);
+  try {
+    return await fn(controller.signal);
+  } catch (err) {
+    if (timedOut) throw new Error(`step '${stepId}': timed out after ${timeoutMs}ms`);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+    parentSignal?.removeEventListener("abort", onParentAbortEvent);
+  }
+}
 function cacheHit(ctx, step, output) {
   ctx.state.cachedHits.add(cachedHitKey(ctx, step.id));
   ctx.onStepStart?.(step.id, { cached: true });
@@ -1570,15 +1663,20 @@ async function execStepBody(step, ctx, item, index) {
   switch (step.kind) {
     case "tool": {
       const input = step.input(b);
-      const runIt = () => runTool({
-        tool: step.tool,
-        candidates: step.candidates,
-        input,
-        context: step.context ? step.context(b) : void 0,
-        resolverContext: step.resolverContext,
-        secrets: step.secrets,
-        signal
-      });
+      const runIt = () => withStepTimeout(
+        step.id,
+        step.timeoutMs ?? DEFAULT_STEP_TIMEOUT_MS,
+        signal,
+        (sig) => runTool({
+          tool: step.tool,
+          candidates: step.candidates,
+          input,
+          context: step.context ? step.context(b) : void 0,
+          resolverContext: step.resolverContext,
+          secrets: step.secrets,
+          signal: sig
+        })
+      );
       if (!isCacheEnabled(ctx, step)) {
         ctx.onStepStart?.(step.id);
         return runIt();
@@ -1982,6 +2080,6 @@ function compileWorkflowManifest(source, opts) {
   return compileWorkflow(handle, opts);
 }
 
-export { AgentInputRequiredError, AgentSpawnError, DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES, MissingArtifactError, NodeFsPort, StepOutcomeError, WorkflowCancelledError, WorkflowCompileError, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, isCompilableJsonSchema, materializeKnowledge, normalizeWorkflowInputsSchema, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow, validateAgainstJsonSchema, validateWorkflowInput };
+export { AgentInputRequiredError, AgentSpawnError, DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES, DEFAULT_STEP_TIMEOUT_MS, MissingArtifactError, NodeFsPort, StepOutcomeError, WorkflowCancelledError, WorkflowCompileError, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, isCompilableJsonSchema, materializeKnowledge, normalizeWorkflowInputsSchema, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow, validateAgainstJsonSchema, validateWorkflowInput };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map