@agentproto/workflow-runtime 0.13.1 → 0.14.0

package/dist/index.d.ts

@@ -74,12 +74,14 @@ type FanOutOutcome<T = unknown> = {
     /** `err.message` if the throw was an `Error`, else `String(err)`. */
     readonly error: string;
 } | {
-    /** Never started: the fan-out's spawn circuit breaker opened first
-     *  (see {@link MapStep.maxConsecutiveSpawnFailures}). */
+    /** Never started: either the fan-out's spawn circuit breaker opened
+     *  first (see {@link MapStep.maxConsecutiveSpawnFailures}), or the run
+     *  was cancelled while earlier items were still in flight. */
     readonly status: "skipped";
     readonly index: number;
     readonly item: unknown;
-    /** `circuit-open: <first error of the failure streak>`. */
+    /** `circuit-open: <first error of the failure streak>`, or
+     *  `run-cancelled: run cancelled`. */
     readonly reason: string;
 };
 /**
@@ -525,6 +527,12 @@ type GateCommandRunner = (spec: {
     args: readonly string[];
     cwd: string;
     timeoutMs?: number;
+    /** The run's cancel signal — a cancelled run kills an in-flight gate
+     *  command's child process the same way it kills an agent step's session.
+     *  A host-injected runner should pass this through to its own subprocess
+     *  spawn (e.g. `child_process.execFile`'s `signal` option) so the process
+     *  is signalled, not merely orphaned. */
+    signal?: AbortSignal;
 }) => Promise<GateCommandResult>;
 /** One `kind: "gate"` command attempt's outcome, reported as it happens
  *  (every attempt, not just the last) — the `gate-report` lifecycle event. */
@@ -733,13 +741,16 @@ interface StepSkippedInfo {
     /** `"branch-not-taken"`: the step sits in an untaken `branch` arm.
      *  `"circuit-open"`: a `map`/`pipeline` item never started because the
      *  fan-out's spawn circuit breaker opened
-     *  ({@link MapStep.maxConsecutiveSpawnFailures}). */
-    reason: "branch-not-taken" | "circuit-open";
+     *  ({@link MapStep.maxConsecutiveSpawnFailures}). `"run-cancelled"`: a
+     *  `map`/`pipeline` item never started because the run was cancelled
+     *  (`RunWorkflowArgs.signal` aborted) while earlier items were still in
+     *  flight. */
+    reason: "branch-not-taken" | "circuit-open" | "run-cancelled";
     /** Id of the authored step whose decision skipped the step — the `branch`
-     *  step, or (circuit-open) the `map`/`pipeline` step. */
+     *  step, or (circuit-open/run-cancelled) the `map`/`pipeline` step. */
     branchId: string;
-    /** `"circuit-open"` only: the first error of the spawn-failure streak
-     *  that tripped the breaker. */
+    /** `"circuit-open"`: the first error of the spawn-failure streak that
+     *  tripped the breaker. `"run-cancelled"`: a fixed "run cancelled" message. */
     message?: string;
 }
 /** What `onStepFailed` reports. */
@@ -898,6 +909,18 @@ declare class AgentSpawnError extends Error {
     readonly cause: unknown;
     constructor(stepId: string, cause: unknown);
 }
+/**
+ * Thrown instead of dispatching a step whose run was cancelled
+ * (`ctx.signal.aborted`) — checked BEFORE any work for the step begins (see
+ * {@link execStepBody}'s entry guard), so a cancel stops the run from
+ * starting any further step, including a sibling within the SAME stage/
+ * fan-out, not just a later one. Never journaled: it's thrown before a
+ * cacheable step's `cache.set` call, so `workflow_retry` re-executes it.
+ */
+declare class WorkflowCancelledError extends Error {
+    readonly stepId: string;
+    constructor(stepId: string);
+}
 declare function runWorkflow(args: RunWorkflowArgs): Promise<WorkflowRunResult>;
 
 /**
@@ -1180,4 +1203,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, 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, 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

@@ -1014,6 +1014,14 @@ var AgentSpawnError = class extends Error {
   stepId;
   cause;
 };
+var WorkflowCancelledError = class extends Error {
+  constructor(stepId) {
+    super(`step '${stepId}': run cancelled \u2014 not started`);
+    this.stepId = stepId;
+    this.name = "WorkflowCancelledError";
+  }
+  stepId;
+};
 function withReleaseScope(ctx) {
   return { ...ctx, spawned: [] };
 }
@@ -1079,9 +1087,9 @@ function spawnBreaker(threshold) {
     }
   };
 }
-function skipUnstartedItems(ctx, fanOutId, from, items, bodiesOf, reason, results) {
+function skipUnstartedItems(ctx, fanOutId, from, items, bodiesOf, kind, reason, results) {
   for (let idx = from; idx < items.length; idx++) {
-    results[idx] = { status: "skipped", index: idx, item: items[idx], reason: `circuit-open: ${reason}` };
+    results[idx] = { status: "skipped", index: idx, item: items[idx], reason: `${kind}: ${reason}` };
     const itemCtx = withIndexedHooks(ctx, idx);
     if (!itemCtx.onStepSkipped) continue;
     let bodies;
@@ -1091,7 +1099,7 @@ function skipUnstartedItems(ctx, fanOutId, from, items, bodiesOf, reason, result
       continue;
     }
     for (const id of new Set(skippableStepIds(bodies))) {
-      itemCtx.onStepSkipped(id, { reason: "circuit-open", branchId: fanOutId, message: reason });
+      itemCtx.onStepSkipped(id, { reason: kind, branchId: fanOutId, message: reason });
     }
   }
 }
@@ -1333,7 +1341,7 @@ ${inner(b2)}` };
   } : void 0;
   let sessionId;
   if (step.adapter) {
-    if (ctx.signal?.aborted) throw new Error(`step '${step.id}': run cancelled \u2014 not spawning`);
+    if (ctx.signal?.aborted) throw new WorkflowCancelledError(step.id);
     try {
       sessionId = await ctx.agents.spawn(resolveSel(step.adapter, b), {
         cwd,
@@ -1445,7 +1453,7 @@ function defaultRunGateCommand(spec) {
     execFile(
       spec.command,
       [...spec.args],
-      { cwd: spec.cwd, timeout: spec.timeoutMs, maxBuffer: 10 * 1024 * 1024 },
+      { cwd: spec.cwd, timeout: spec.timeoutMs, maxBuffer: 10 * 1024 * 1024, signal: spec.signal },
       (err, stdout, stderr) => {
         if (!err) {
           resolve2({ exitCode: 0, stdout, stderr });
@@ -1485,6 +1493,7 @@ async function execGateStep(step, ctx, b) {
   const maxAttempts = Math.max(1, step.retry?.maxAttempts ?? 1);
   let last;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (ctx.signal?.aborted) throw new WorkflowCancelledError(step.id);
     if (attempt > 1 && step.onFail?.reprompt) {
       if (!ctx.agents) {
         throw new Error(`step '${step.id}': on_fail.reprompt requires a host agents implementation`);
@@ -1516,8 +1525,10 @@ Please address the findings above, then reply when done.`
       command: step.command,
       args,
       cwd,
-      timeoutMs: step.timeoutMs
+      timeoutMs: step.timeoutMs,
+      signal: ctx.signal
     });
+    if (ctx.signal?.aborted) throw new WorkflowCancelledError(step.id);
     const report = await resolveGateReport(cmdResult, cwd, step.reportPath);
     const ok = cmdResult.exitCode === 0;
     last = { ok, exitCode: cmdResult.exitCode, report };
@@ -1551,6 +1562,7 @@ async function execStep(step, ctx, item, index) {
 }
 async function execStepBody(step, ctx, item, index) {
   const { state, signal } = ctx;
+  if (signal?.aborted) throw new WorkflowCancelledError(step.id);
   const b = view(ctx, item, index);
   if (step.kind !== "agent" && step.kind !== "tool" && step.kind !== "artifact") {
     ctx.onStepStart?.(step.id);
@@ -1610,15 +1622,20 @@ async function execStepBody(step, ctx, item, index) {
         }
       };
       const worker = async () => {
-        while (!failed && breaker.open === void 0 && next < arr.length) {
+        while (!failed && breaker.open === void 0 && signal?.aborted !== true && next < arr.length) {
           const idx = next++;
           await runItem(idx);
         }
       };
       await Promise.all(Array.from({ length: Math.min(parallelism, arr.length) }, () => worker()));
+      if (signal?.aborted === true && next < arr.length) {
+        if (!tolerant) throw new WorkflowCancelledError(step.id);
+        skipUnstartedItems(ctx, step.id, next, arr, (el, idx) => [step.body(el, idx, view(ctx, el, idx))], "run-cancelled", "run cancelled", results);
+        return tolerantResult(results, breaker.open);
+      }
       if (!tolerant) return results;
       if (breaker.open !== void 0) {
-        skipUnstartedItems(ctx, step.id, next, arr, (el, idx) => [step.body(el, idx, view(ctx, el, idx))], breaker.open, results);
+        skipUnstartedItems(ctx, step.id, next, arr, (el, idx) => [step.body(el, idx, view(ctx, el, idx))], "circuit-open", breaker.open, results);
       }
       return tolerantResult(results, breaker.open);
     }
@@ -1653,12 +1670,26 @@ async function execStepBody(step, ctx, item, index) {
         }
       };
       const worker = async () => {
-        while ((!tolerant || breaker.open === void 0) && next < items.length) {
+        while ((!tolerant || breaker.open === void 0) && signal?.aborted !== true && next < items.length) {
           const idx = next++;
           await runItem(idx);
         }
       };
       await Promise.all(Array.from({ length: Math.min(cap, items.length) }, () => worker()));
+      if (signal?.aborted === true && next < items.length) {
+        if (!tolerant) throw new WorkflowCancelledError(step.id);
+        skipUnstartedItems(
+          ctx,
+          step.id,
+          next,
+          items,
+          (el, idx) => step.stages.map((stage) => stage(el, idx, void 0, view(ctx, el, idx))),
+          "run-cancelled",
+          "run cancelled",
+          results
+        );
+        return tolerantResult(results, breaker.open);
+      }
       if (!tolerant) return results;
       if (breaker.open !== void 0) {
         skipUnstartedItems(
@@ -1667,6 +1698,7 @@ async function execStepBody(step, ctx, item, index) {
           next,
           items,
           (el, idx) => step.stages.map((stage) => stage(el, idx, void 0, view(ctx, el, idx))),
+          "circuit-open",
           breaker.open,
           results
         );
@@ -1950,6 +1982,6 @@ function compileWorkflowManifest(source, opts) {
   return compileWorkflow(handle, opts);
 }
 
-export { AgentInputRequiredError, AgentSpawnError, DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES, MissingArtifactError, NodeFsPort, StepOutcomeError, 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, 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