@agentproto/workflow-runtime 0.13.0 → 0.14.0

package/README.md

@@ -301,9 +301,13 @@ try {
 
 This is a manual retry, not a resumable run object — `runWorkflow` has no
 notion of "the run that failed"; the cacheKey is just a namespace the caller
-re-supplies. A first-class `run.retry`/`run.replay` verb that resumes a named
-run without the caller re-threading `workflow`/`input`/`cacheKey` by hand is
-AIP-58 P5, not implemented here.
+re-supplies. A first-class `run.retry` verb that resumes a named run without
+the caller re-threading `workflow`/`input`/`cacheKey` by hand — AIP-58 P5 —
+is a HOST concern, not something this transport-agnostic package implements
+itself: see `@agentproto/runtime`'s `WorkflowRunner.retry()` / the
+`workflow_retry` MCP tool, which owns runId allocation and an always-on
+internal journal (so it works even when the original run never passed a
+`cacheKey` at all — every step it runs is journaled internally either way).
 
 ### Run workspace (AIP-58 §4)
 
@@ -347,12 +351,18 @@ steps:
 
 `path` is read relative to `$run.workspace` (absolute paths, and any path
 that would resolve OUTSIDE the workspace, throw). The step hashes
-(`sha256`) and sizes the file, copies it to `artifactsDir/<sanitized key>`,
-and binds/report an `ArtifactEntry` — `{ key, path: "artifacts/<key>", sha256,
-size, stepId, contentType? }` (`path` here is relative to the RUN WORKSPACE
-ROOT, the parent of `$run.workspace` itself — not the source location).
-Pass `onArtifact` to `runWorkflow` to observe every one recorded, cache hit
-or fresh.
+(`sha256`) and sizes the file, copies it to `artifactsDir/<basename of path,
+sanitized>` — `path: "briefs/latest.md"` above lands at
+`artifacts/latest.md`, keeping the extension, NOT the bare key
+(`artifacts/brief`) — and binds/reports an `ArtifactEntry` — `{ key, path:
+"artifacts/<basename>", sha256, size, stepId, contentType? }` (`path` here is
+relative to the RUN WORKSPACE ROOT, the parent of `$run.workspace` itself —
+not the source location; always read it back rather than assuming a name).
+If two keys' files share a basename, the second one claimed is prefixed with
+its own sanitized key (`artifacts/<key>-<basename>`) instead of silently
+overwriting the first — deterministic, same result run to run. Pass
+`onArtifact` to `runWorkflow` to observe every one recorded, cache hit or
+fresh.
 
 A declarative WORKFLOW.md manifest may instead declare **`outputsFiles`**
 (AIP-16, amended by AIP-58 §4 with `required`) at the top level — checked
@@ -400,11 +410,38 @@ relocates (copies) the file from the ORIGINAL run's `artifactsDir` into the
 CURRENT run's own before returning — the two runs' workspaces stay fully
 disjoint on disk; only the *bytes* are reused, exactly the same way
 `run.replay`'s journal-sourced step reuse is specified to work (AIP-58 §6).
-This is a deliberate, narrower scope than "any cacheable step's output might
-reference a workspace file" — a plain cacheable `tool`/`agent` step whose
-output happens to name a path is NOT relocated automatically; route a
-step's file-shaped output through `kind: "artifact"` (or `outputsFiles`) to
-get cache/replay continuity for it.
+
+A plain cacheable `tool`/`agent` step gets the same treatment, not a narrower
+one (this used to be a documented gap — see "Cache key vs. the run
+workspace" below for why it had to stop being one):
+
+- **Hashing ignores the workspace's identity.** `hashResolvedInputs`
+  replaces every occurrence of `ctx.workspace` inside the serialized
+  resolved input/prompt (including trailing subpaths, e.g.
+  `<workspace>/cleaned/out.txt`) with a stable placeholder before hashing.
+  Two runs of the same logical step under the same `cacheKey` hash
+  identically even though AIP-58 §4 gives each one a fresh, disjoint
+  workspace directory — without this, ANY step whose input/prompt names
+  `$run.workspace` / `{{run.workspace}}` / `_workflowFsRoot` could never hit
+  the journal at all.
+- **A hit relocates forward.** On a hit, every workspace-relative file/
+  directory the entry recorded (`StepCacheEntry.workspaceFiles` — collected,
+  best-effort, from every string in the step's output that resolved to a
+  real path under the ORIGINAL run's workspace) is copied into the matching
+  path under the CURRENT run's own; the recorded output's path strings are
+  then rewritten from the original workspace onto the current one. A
+  downstream step whose input reads one of those paths (`$steps.<id>.path`)
+  finds the bytes there, not just the (by-then-gone) original run's.
+  Best-effort, same posture as the `artifact` step's own relocation: a
+  source already swept by a host's `scratch/` retention policy is not this
+  run's problem to recover.
+- **Still no cross-step content hashing.** This closes the *workspace-path*
+  gap only — the journal still hashes each step's own resolved inputs, not
+  a transitive hash of everything upstream. A step whose resolved input is
+  an opaque reference that stays textually identical across runs (a fixed
+  relative filename, an id) replays from cache on that basis alone,
+  regardless of whether the value behind that reference changed upstream —
+  same limitation any resolved-input-hash cache has, workspace or not.
 
 ### Step lifecycle callbacks
 

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;
 };
 /**
@@ -431,7 +433,11 @@ interface AgentStep {
 interface ArtifactStep {
     kind: "artifact";
     id: string;
-    /** Artifact key — also becomes its filename under `artifactsDir` (sanitized). */
+    /** Artifact key — identifies this artifact for `workflow_artifact_get`/
+     *  `workflow_publish`. Its on-disk filename under `artifactsDir` is
+     *  `path`'s own basename (sanitized), not the key — see {@link
+     *  ArtifactEntry.path} — unless another key's file shares the same
+     *  basename, in which case the key disambiguates it (F42). */
     key: Selector<string> | string;
     /** Path to the source file. Relative to `$run.workspace`; MUST resolve
      *  inside it (an absolute path or a `..`-escaping relative one throws). */
@@ -440,10 +446,15 @@ interface ArtifactStep {
 }
 /**
  * AIP-58 §4/§1 `ArtifactEntry` — one run-scoped copy of a declared output
- * file. `path` is always `"artifacts/<sanitized key>"`, relative to the RUN
- * WORKSPACE ROOT (`<runsRoot>/<runId>/`, the parent of `$run.workspace`
- * itself) — never the original in-workspace location the file was read
- * from.
+ * file. `path` is `"artifacts/<basename>"` (F42: the declared source file's
+ * OWN basename, sanitized — e.g. `outputsFiles.pdf: {path: transcript.pdf}`
+ * ⇒ `artifacts/transcript.pdf` — keeping the extension, unlike the bare key),
+ * relative to the RUN WORKSPACE ROOT (`<runsRoot>/<runId>/`, the parent of
+ * `$run.workspace` itself) — never the original in-workspace location the
+ * file was read from. Two keys whose files share a basename get the SECOND
+ * one's name prefixed with its own sanitized key instead (deterministic,
+ * never a silent overwrite) — always read `path` back rather than assuming
+ * `artifacts/<key>` or `artifacts/<basename(path)>`.
  */
 interface ArtifactEntry {
     key: string;
@@ -516,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. */
@@ -691,6 +708,20 @@ interface StepCacheEntry {
      *  §4 forbids two runs sharing a workspace) copies the file forward from
      *  here into the new run's own `artifactsDir` instead of re-declaring it. */
     artifactsDirAtCache?: string;
+    /** Set only for a cacheable `tool`/`agent` step (see `hashResolvedInputs`/
+     *  `buildCacheEntry` in `run-workflow.ts`) whenever the host wires a run
+     *  workspace: the absolute `$run.workspace` / `_workflowFsRoot` path this
+     *  entry was cached under. A hit in a LATER run (a different workspace —
+     *  AIP-58 §4 forbids two runs sharing one) rewrites `output`'s path
+     *  strings from here onto the new run's own, and relocates
+     *  {@link workspaceFiles} the same way. */
+    workspaceAtCache?: string;
+    /** Workspace-relative files/directories (under {@link workspaceAtCache})
+     *  this entry's `output` pointed at and that existed on disk when the
+     *  entry was written — copied forward into a later cache-hit run's own
+     *  workspace so a downstream step reading one of these paths finds the
+     *  bytes there too, not just in the original (by-then-gone) run's. */
+    workspaceFiles?: readonly string[];
 }
 /** Opt-in journal for cacheable steps. Host-injected; file-backed in the runtime. */
 interface StepCache {
@@ -710,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. */
@@ -875,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>;
 
 /**
@@ -1157,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

@@ -1,7 +1,7 @@
 import { runTool } from '@agentproto/driver';
 import { createHash } from 'crypto';
 import { execFile } from 'child_process';
-import { stat, readFile, mkdir, writeFile, appendFile, readdir, copyFile } from 'fs/promises';
+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';
 import { assertKnownStepRefs } from '@agentproto/workflow';
@@ -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 });
     }
   }
 }
@@ -1131,8 +1139,74 @@ function spentUsd(state) {
   for (const c of state.costBySession.values()) total += c;
   return total;
 }
-function hashResolvedInputs(kind, resolved) {
-  return createHash("sha256").update(`${kind}\0${JSON.stringify(resolved) ?? "undefined"}`).digest("hex");
+var WORKSPACE_HASH_PLACEHOLDER = "\0$run.workspace\0";
+function hashResolvedInputs(kind, resolved, workspace) {
+  const serialized = `${kind}\0${JSON.stringify(resolved) ?? "undefined"}`;
+  const normalized = workspace ? serialized.split(workspace).join(WORKSPACE_HASH_PLACEHOLDER) : serialized;
+  return createHash("sha256").update(normalized).digest("hex");
+}
+function rewriteWorkspacePaths(value, from, to) {
+  if (typeof value === "string") return value.split(from).join(to);
+  if (Array.isArray(value)) return value.map((v) => rewriteWorkspacePaths(v, from, to));
+  if (value !== null && typeof value === "object" && value.constructor === Object) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = rewriteWorkspacePaths(v, from, to);
+    return out;
+  }
+  return value;
+}
+function collectWorkspaceCandidates(value, workspace, out) {
+  if (typeof value === "string") {
+    if (value === workspace || value.startsWith(`${workspace}/`)) {
+      const rel = relative(workspace, value);
+      if (rel !== "" && !rel.startsWith("..") && !isAbsolute(rel)) out.add(rel);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const v of value) collectWorkspaceCandidates(v, workspace, out);
+    return;
+  }
+  if (value !== null && typeof value === "object" && value.constructor === Object) {
+    for (const v of Object.values(value)) collectWorkspaceCandidates(v, workspace, out);
+  }
+}
+async function collectWorkspaceFiles(out, workspace) {
+  const candidates = /* @__PURE__ */ new Set();
+  collectWorkspaceCandidates(out, workspace, candidates);
+  const files = [];
+  for (const rel of candidates) {
+    try {
+      await stat(join(workspace, rel));
+      files.push(rel);
+    } catch {
+    }
+  }
+  return files;
+}
+async function buildCacheEntry(ctx, out, hash) {
+  if (ctx.workspace === void 0) return { output: out, resolvedInputHash: hash };
+  const workspaceFiles = await collectWorkspaceFiles(out, ctx.workspace);
+  return {
+    output: out,
+    resolvedInputHash: hash,
+    workspaceAtCache: ctx.workspace,
+    ...workspaceFiles.length > 0 ? { workspaceFiles } : {}
+  };
+}
+async function relocateCachedOutput(ctx, entry) {
+  const from = entry.workspaceAtCache;
+  const to = ctx.workspace;
+  if (from === void 0 || to === void 0 || from === to) return entry.output;
+  for (const rel of entry.workspaceFiles ?? []) {
+    const dest = join(to, rel);
+    try {
+      await mkdir(dirname(dest), { recursive: true });
+      await cp(join(from, rel), dest, { recursive: true });
+    } catch {
+    }
+  }
+  return rewriteWorkspacePaths(entry.output, from, to);
 }
 function stepJournalKey(ctx, step) {
   return `${ctx.cacheKey}\0${step.id}\0${step.kind}${ctx.cacheKeySuffix ?? ""}`;
@@ -1149,10 +1223,10 @@ function completeStep(ctx, stepId, out) {
 }
 async function readStepCache(ctx, step, resolvedInputs) {
   const key = stepJournalKey(ctx, step);
-  const hash = hashResolvedInputs(step.kind, resolvedInputs);
+  const hash = hashResolvedInputs(step.kind, resolvedInputs, ctx.workspace);
   const entry = await ctx.cache.get(key);
   if (entry !== void 0 && entry.resolvedInputHash === hash) {
-    return { hit: true, output: entry.output };
+    return { hit: true, output: await relocateCachedOutput(ctx, entry) };
   }
   return { hit: false, key, hash };
 }
@@ -1267,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,
@@ -1379,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 });
@@ -1419,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`);
@@ -1450,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 };
@@ -1485,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);
@@ -1509,7 +1587,7 @@ async function execStepBody(step, ctx, item, index) {
       if (c.hit) return cacheHit(ctx, step, c.output);
       ctx.onStepStart?.(step.id);
       const out = await runIt();
-      await ctx.cache.set(c.key, { output: out, resolvedInputHash: c.hash });
+      await ctx.cache.set(c.key, await buildCacheEntry(ctx, out, c.hash));
       return out;
     }
     case "transform":
@@ -1544,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);
     }
@@ -1587,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(
@@ -1601,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
         );
@@ -1681,7 +1779,8 @@ async function execStepBody(step, ctx, item, index) {
         cacheKey: ctx.cacheKey,
         runGateCommand: ctx.runGateCommand,
         onGateReport: ctx.onGateReport,
-        spawned: ctx.spawned
+        spawned: ctx.spawned,
+        usedArtifactNames: ctx.usedArtifactNames
       });
       return child.output;
     }
@@ -1697,7 +1796,7 @@ async function execStepBody(step, ctx, item, index) {
       const c = await readStepCache(ctx, step, resolved);
       if (c.hit) return cacheHit(ctx, step, c.output);
       const out = await execAgentStep(step, ctx, b);
-      await ctx.cache.set(c.key, { output: out, resolvedInputHash: c.hash });
+      await ctx.cache.set(c.key, await buildCacheEntry(ctx, out, c.hash));
       return out;
     }
     case "gate":
@@ -1706,11 +1805,24 @@ async function execStepBody(step, ctx, item, index) {
       return execArtifactStep(step, ctx, b);
   }
 }
-function sanitizeArtifactKey(key) {
-  const cleaned = key.replace(/[^a-zA-Z0-9._-]/g, "_");
+function sanitizeArtifactFilename(name) {
+  const cleaned = name.replace(/[^a-zA-Z0-9._-]/g, "_");
   return cleaned.length > 0 ? cleaned : "artifact";
 }
-async function copyIntoArtifacts(stepId, key, rawPath, workspace, artifactsDir, contentType) {
+function reserveArtifactDestName(rawPath, key, usedNames) {
+  const base = sanitizeArtifactFilename(basename(rawPath));
+  let candidate = base;
+  if (usedNames.has(candidate)) {
+    const keyPart = sanitizeArtifactFilename(key);
+    candidate = `${keyPart}-${base}`;
+    for (let n = 2; usedNames.has(candidate); n++) {
+      candidate = `${keyPart}-${n}-${base}`;
+    }
+  }
+  usedNames.add(candidate);
+  return candidate;
+}
+async function copyIntoArtifacts(stepId, key, rawPath, workspace, artifactsDir, contentType, usedNames) {
   const abs = isAbsolute(rawPath) ? resolve(rawPath) : resolve(workspace, rawPath);
   const rel = relative(workspace, abs);
   if (rel.startsWith("..") || isAbsolute(rel)) {
@@ -1718,7 +1830,7 @@ async function copyIntoArtifacts(stepId, key, rawPath, workspace, artifactsDir,
   }
   const buf = await readFile(abs);
   const sha256 = createHash("sha256").update(buf).digest("hex");
-  const destName = sanitizeArtifactKey(key);
+  const destName = reserveArtifactDestName(rawPath, key, usedNames);
   await mkdir(artifactsDir, { recursive: true });
   await writeFile(join(artifactsDir, destName), buf);
   return {
@@ -1742,12 +1854,13 @@ async function execArtifactStep(step, ctx, b) {
   const resolvedInputs = { key, path: rawPath };
   const cacheOn = ctx.cache !== void 0 && ctx.cacheKey !== void 0;
   const journalKey = cacheOn ? stepJournalKey(ctx, step) : void 0;
-  const hash = cacheOn ? hashResolvedInputs(step.kind, resolvedInputs) : void 0;
+  const hash = cacheOn ? hashResolvedInputs(step.kind, resolvedInputs, ctx.workspace) : void 0;
   if (cacheOn) {
     const entry = await ctx.cache.get(journalKey);
     if (entry !== void 0 && entry.resolvedInputHash === hash) {
       const out2 = entry.output;
-      const destName = sanitizeArtifactKey(key);
+      const destName = out2.path.slice("artifacts/".length);
+      ctx.usedArtifactNames?.add(destName);
       const destAbs = join(artifactsDir, destName);
       const srcAbs = join(entry.artifactsDirAtCache ?? artifactsDir, destName);
       if (srcAbs !== destAbs) {
@@ -1762,7 +1875,7 @@ async function execArtifactStep(step, ctx, b) {
     }
   }
   ctx.onStepStart?.(step.id);
-  const out = await copyIntoArtifacts(step.id, key, rawPath, workspace, artifactsDir, contentType);
+  const out = await copyIntoArtifacts(step.id, key, rawPath, workspace, artifactsDir, contentType, ctx.usedArtifactNames);
   if (cacheOn) {
     await ctx.cache.set(journalKey, { output: out, resolvedInputHash: hash, artifactsDirAtCache: artifactsDir });
   }
@@ -1780,7 +1893,7 @@ async function checkOutputsFiles(outputsFiles, ctx, workflowId, lastStepId) {
     const abs = isAbsolute(rawPath) ? rawPath : resolve(ctx.workspace, rawPath);
     let out;
     try {
-      out = await copyIntoArtifacts(lastStepId ?? workflowId, key, abs, ctx.workspace, ctx.artifactsDir, contract.contentType);
+      out = await copyIntoArtifacts(lastStepId ?? workflowId, key, abs, ctx.workspace, ctx.artifactsDir, contract.contentType, ctx.usedArtifactNames);
     } catch {
       if (contract.required === true) {
         throw new MissingArtifactError(key, lastStepId);
@@ -1811,7 +1924,11 @@ async function runFinally(steps, ctx, bodyFailed) {
 async function runWorkflowInner(workflow, input, hooks, maxTotalCostUsd) {
   const state = { input, steps: {}, costBySession: /* @__PURE__ */ new Map(), maxTotalCostUsd, cachedHits: /* @__PURE__ */ new Set() };
   const ownsScope = hooks.spawned === void 0;
-  const ctx = { state, ...hooks, ...ownsScope ? { spawned: [] } : {} };
+  const ctx = {
+    state,
+    ...hooks,
+    ...ownsScope ? { spawned: [], usedArtifactNames: /* @__PURE__ */ new Set() } : {}
+  };
   let lastId;
   let bodyFailed = false;
   try {
@@ -1865,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