@agentproto/workflow-runtime 0.12.0 → 0.13.1

package/dist/index.mjs

@@ -1,9 +1,12 @@
 import { runTool } from '@agentproto/driver';
 import { createHash } from 'crypto';
 import { execFile } from 'child_process';
-import { stat, readFile, mkdir, writeFile, appendFile, readdir } from 'fs/promises';
-import { join, dirname, isAbsolute, basename, resolve } from 'path';
+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';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
 import { isRefinedKind, filterEntriesByAllOf, resolveKnowledge } from '@agentproto/corpus';
 import { parseWorkflowManifest, workflowFromManifest } from '@agentproto/workflow/manifest';
 
@@ -20,6 +23,7 @@ function buildAgentStep(id, fields) {
     kind: "agent",
     id,
     ...fields.adapter !== void 0 ? { adapter: fields.adapter } : {},
+    ...fields.cwd !== void 0 ? { cwd: fields.cwd } : {},
     ...fields.model !== void 0 ? { model: fields.model } : {},
     ...fields.sessionRef !== void 0 ? { sessionRef: fields.sessionRef } : {},
     ...fields.sandbox !== void 0 ? { sandbox: fields.sandbox } : {},
@@ -29,7 +33,85 @@ function buildAgentStep(id, fields) {
     policy: fields.policy ?? { awaiting: "fail" },
     ...fields.outputSchema !== void 0 ? { outputSchema: fields.outputSchema } : {},
     ...fields.maxRetries !== void 0 ? { maxRetries: fields.maxRetries } : {},
-    ...fields.harness !== void 0 ? { harness: fields.harness } : {}
+    ...fields.harness !== void 0 ? { harness: fields.harness } : {},
+    ...fields.agentTools !== void 0 ? { agentTools: fields.agentTools } : {}
+  };
+}
+var isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function isJsonSchemaObject(inputs) {
+  return inputs["type"] === "object" && isPlainObject(inputs["properties"]);
+}
+function normalizeWorkflowInputsSchema(inputs) {
+  if (!isPlainObject(inputs)) return { type: "object", properties: {} };
+  if (isJsonSchemaObject(inputs)) return inputs;
+  const properties = {};
+  const required = [];
+  for (const [key, rawSpec] of Object.entries(inputs)) {
+    const spec = isPlainObject(rawSpec) ? rawSpec : {};
+    const { required: isRequired, ...schemaFields } = spec;
+    properties[key] = schemaFields;
+    if (isRequired === true && spec["default"] === void 0) required.push(key);
+  }
+  return {
+    type: "object",
+    properties,
+    ...required.length > 0 ? { required } : {}
+  };
+}
+var _ajv = addFormats(new Ajv({ allErrors: true }));
+var _validatorCache = /* @__PURE__ */ new WeakMap();
+function compile(schema) {
+  let validate = _validatorCache.get(schema);
+  if (!validate) {
+    validate = _ajv.compile(schema);
+    _validatorCache.set(schema, validate);
+  }
+  return validate;
+}
+function fieldFor(err) {
+  if (err.keyword === "required") {
+    return String(err.params.missingProperty ?? "");
+  }
+  return err.instancePath.replace(/^\//, "") || "(root)";
+}
+function isCompilableJsonSchema(schema) {
+  if (!isPlainObject(schema)) return false;
+  try {
+    compile(schema);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function toIssue(err) {
+  const path = err.instancePath.replace(/^\//, "").split("/").filter((seg) => seg.length > 0);
+  if (err.keyword === "required") {
+    const missing = err.params.missingProperty;
+    if (missing) path.push(missing);
+  }
+  return { path, message: err.message ?? "invalid" };
+}
+function validateAgainstJsonSchema(schema, value) {
+  const validate = compile(schema);
+  if (validate(value)) return { valid: true };
+  const errors = validate.errors ?? [];
+  const issues = errors.map(toIssue);
+  const detail = errors.map((e) => `${e.instancePath || "/"} ${e.message}`).join("; ");
+  return { valid: false, message: `does not match schema: ${detail}`, issues };
+}
+function validateWorkflowInput(inputsField, input) {
+  const schema = normalizeWorkflowInputsSchema(inputsField);
+  const validate = compile(schema);
+  if (validate(input ?? {})) return { valid: true, schema };
+  const errors = validate.errors ?? [];
+  const fields = [...new Set(errors.map(fieldFor).filter((f2) => f2.length > 0))];
+  const detail = errors.map((e) => `${e.instancePath || "/"} ${e.message}`).join("; ");
+  return {
+    valid: false,
+    schema,
+    code: "invalid-input",
+    fields,
+    message: `invalid input${fields.length > 0 ? ` (${fields.join(", ")})` : ""}: ${detail}`
   };
 }
 
@@ -49,8 +131,8 @@ function dig(value, path) {
   }
   return v;
 }
-var REF_RE = /^\$(input|item|steps)((?:\.[^.]+)*)$/;
-var REF_PREFIX_RE = /^\$(?:input|item|steps|index)((?:\.[^.$/]+)*)/;
+var REF_RE = /^\$(input|item|steps|run)((?:\.[^.]+)*)$/;
+var REF_PREFIX_RE = /^\$(?:input|item|steps|run|index)((?:\.[^.$/]+)*)/;
 function resolveRef(ref, b) {
   if (ref === "$index") return b.index;
   const m = ref.match(REF_RE);
@@ -66,6 +148,10 @@ function resolveRef(ref, b) {
       if (!stepId) throw new WorkflowCompileError(`'$steps' needs a step id`);
       return dig(b.steps[stepId], rest);
     }
+    // AIP-58 §4 — `$run.workspace`, a convenience alias for the run
+    // workspace path (see `Bindings.run`).
+    case "run":
+      return dig(b.run, segs);
   }
 }
 function resolveRefPrefixed(value, b) {
@@ -87,6 +173,7 @@ function resolveTagName(name, b) {
   if (head === "steps" && segs.length > 1)
     return dig(b.steps[segs[1]], segs.slice(2));
   if (head === "index" && segs.length === 1) return b.index;
+  if (head === "run") return segs.length === 1 ? b.run : dig(b.run, segs.slice(1));
   return dig(b.input, segs);
 }
 function stringifyValue(v) {
@@ -121,7 +208,7 @@ function interpolateTemplate(template, b) {
         replacement = replacement.replace(/^\n/, "").replace(/\n[ \t]*$/, "");
       }
     }
-    out = before.slice(0, lineStart) + replacement + (standalone ? truthy ? nl === -1 ? after : after.slice(nl) : after.slice(nl + 1) : after);
+    out = (standalone ? before.slice(0, lineStart) : before) + replacement + (standalone ? truthy ? nl === -1 ? after : after.slice(nl) : after.slice(nl + 1) : after);
   }
   return out.replace(TAG_RE, (whole, name) => {
     const v = resolveTagName(name, b);
@@ -166,7 +253,7 @@ function refPathExists(ref, b) {
     segs.length = 0;
     segs.push(...rest);
   } else {
-    v = m[1] === "input" ? b.input : b.item;
+    v = m[1] === "input" ? b.input : m[1] === "run" ? b.run : b.item;
   }
   for (const seg of segs) {
     if (v === null || typeof v !== "object") return false;
@@ -269,11 +356,16 @@ function compileWorkflow(handle, opts) {
   const ctx = { opts, knownStepIds: collectStepIds(steps) };
   const result = handle.result;
   const output = result !== void 0 ? (b) => resolveValue(result, b) : void 0;
+  const finallySteps = handle.finally;
+  const finallyCtx = finallySteps?.length ? { opts, knownStepIds: /* @__PURE__ */ new Set([...ctx.knownStepIds, ...collectStepIds(finallySteps)]) } : ctx;
+  const outputsFiles = handle.outputsFiles;
   return {
     id: handle.id,
     description: handle.description,
     steps: compileSiblingsToSteps(steps, ctx),
-    ...output ? { output } : {}
+    ...finallySteps?.length ? { finally: compileSiblingsToSteps(finallySteps, finallyCtx) } : {},
+    ...output ? { output } : {},
+    ...outputsFiles ? { outputsFiles } : {}
   };
 }
 function compileSiblingsToSteps(steps, ctx) {
@@ -282,8 +374,14 @@ function compileSiblingsToSteps(steps, ctx) {
   for (let i = 0; i < steps.length; i++) {
     const s = steps[i];
     if (s.kind === "branch") {
-      out.push(compileBranchChain(steps, i, ctx));
-      return out;
+      if (s.fallthrough === true) {
+        out.push(compileBranchChain(steps, i, ctx));
+        return out;
+      }
+      const { node, joinIdx } = compileExclusiveBranch(steps, i, ctx);
+      out.push(node);
+      i = joinIdx - 1;
+      continue;
     }
     out.push(compileStep(s, ctx));
   }
@@ -294,19 +392,74 @@ function compileStepList(steps, id, ctx) {
   if (compiled.length === 1) return compiled[0];
   return { kind: "group", id, steps: compiled };
 }
-function compileBranchChain(steps, i, ctx) {
+function resolveBranchTarget(steps, i, targetId, label) {
+  const idx = steps.findIndex((s) => s.id === targetId);
+  if (idx === -1 || idx <= i) {
+    throw new WorkflowCompileError(
+      `branch '${steps[i].id}' ${label} targets '${targetId}', which is not a sibling later in this step list \u2014 the forward-only branch compiler only supports jumping to a later sibling in the SAME list (not backward, and not into a nested map/loop/parallel body). Hand-author a 'loop' step for retry-style control flow instead.`
+    );
+  }
+  return idx;
+}
+function compileExclusiveBranch(steps, i, ctx) {
   const branchStep = steps[i];
   const branches = f(branchStep, "branches");
   const defaultTarget = f(branchStep, "default");
-  const resolveTarget = (targetId, label) => {
-    const idx = steps.findIndex((s) => s.id === targetId);
-    if (idx === -1 || idx <= i) {
-      throw new WorkflowCompileError(
-        `branch '${branchStep.id}' ${label} targets '${targetId}', which is not a sibling later in this step list \u2014 the forward-only branch compiler only supports jumping to a later sibling in the SAME list (not backward, and not into a nested map/loop/parallel body). Hand-author a 'loop' step for retry-style control flow instead.`
-      );
+  const joinTarget = f(branchStep, "join");
+  const armIdx = branches.map((br, k) => resolveBranchTarget(steps, i, br.next, `branches[${k}].next`));
+  const defaultIdx = defaultTarget !== void 0 ? resolveBranchTarget(steps, i, defaultTarget, "default") : void 0;
+  const starts = [.../* @__PURE__ */ new Set([...armIdx, ...defaultIdx !== void 0 ? [defaultIdx] : []])].sort(
+    (a, b) => a - b
+  );
+  const lastStart = starts[starts.length - 1];
+  const joinIdx = joinTarget !== void 0 ? resolveBranchTarget(steps, i, joinTarget, "join") : lastStart + 1;
+  if (joinIdx <= lastStart) {
+    throw new WorkflowCompileError(
+      `branch '${branchStep.id}' join '${joinTarget}' must come after every arm target \u2014 '${steps[lastStart].id}' is an arm target at or after it`
+    );
+  }
+  if (defaultIdx !== void 0 && starts[0] > i + 1) {
+    throw new WorkflowCompileError(
+      `branch '${branchStep.id}': step '${steps[i + 1].id}' sits between the branch and its first arm target and belongs to no arm \u2014 with an explicit 'default' it can never run. Move it after the join, or make it an arm target.`
+    );
+  }
+  const bodies = /* @__PURE__ */ new Map();
+  const bodyAt = (start) => {
+    let body = bodies.get(start);
+    if (!body) {
+      const pos = starts.indexOf(start);
+      const end = pos + 1 < starts.length ? starts[pos + 1] : joinIdx;
+      body = compileSiblingsToSteps(steps.slice(start, end), ctx);
+      bodies.set(start, body);
     }
-    return idx;
+    return body;
   };
+  let otherwise = defaultIdx !== void 0 ? bodyAt(defaultIdx) : compileSiblingsToSteps(steps.slice(i + 1, starts[0]), ctx);
+  for (let k = branches.length - 1; k >= 0; k--) {
+    const condExpr = branches[k].when;
+    otherwise = [
+      {
+        kind: "branch",
+        id: k === 0 ? branchStep.id : `${branchStep.id}__branch${k}`,
+        ...k === 0 ? {} : { sourceId: branchStep.id },
+        cond: (b) => evalPredicate(condExpr, b),
+        then: bodyAt(armIdx[k]),
+        ...otherwise.length > 0 ? { otherwise } : {}
+      }
+    ];
+  }
+  return { node: otherwise[0], joinIdx };
+}
+function compileBranchChain(steps, i, ctx) {
+  const branchStep = steps[i];
+  const branches = f(branchStep, "branches");
+  const defaultTarget = f(branchStep, "default");
+  if (f(branchStep, "join") !== void 0) {
+    throw new WorkflowCompileError(
+      `branch '${branchStep.id}' declares both 'fallthrough: true' and 'join' \u2014 a fall-through branch runs every later sibling, so it has no join point`
+    );
+  }
+  const resolveTarget = (targetId, label) => resolveBranchTarget(steps, i, targetId, label);
   const defaultIdx = defaultTarget !== void 0 ? resolveTarget(defaultTarget, "default") : i + 1;
   let otherwise = compileSiblingsToSteps(steps.slice(defaultIdx), ctx);
   for (let k = branches.length - 1; k >= 0; k--) {
@@ -319,6 +472,7 @@ function compileBranchChain(steps, i, ctx) {
       {
         kind: "branch",
         id: nodeId,
+        ...k === 0 ? {} : { sourceId: branchStep.id },
         cond: (b) => evalPredicate(condExpr, b),
         then: thenSteps,
         ...otherwise.length > 0 ? { otherwise } : {}
@@ -327,6 +481,25 @@ function compileBranchChain(steps, i, ctx) {
   }
   return otherwise[0];
 }
+function hasSafeParse(value) {
+  return typeof value === "object" && value !== null && typeof value.safeParse === "function";
+}
+function compileOutputSchema(schema, stepId) {
+  if (!isCompilableJsonSchema(schema)) {
+    throw new WorkflowCompileError(
+      `agent step '${stepId}' has an invalid 'outputSchema' \u2014 not a compilable JSON Schema`
+    );
+  }
+  return {
+    safeParse: (value) => {
+      const result = validateAgainstJsonSchema(schema, value);
+      return result.valid ? { success: true, data: value } : { success: false, error: { issues: result.issues } };
+    },
+    // F27: lets `describeOutputSchemaForPrompt` (run-workflow.ts) render the
+    // EXACT WORKFLOW.md-authored schema into the agent's prompt.
+    jsonSchema: schema
+  };
+}
 function compileAgentStep(step, id, ctx) {
   const opts = ctx.opts;
   const prompt = f(step, "prompt");
@@ -335,6 +508,8 @@ function compileAgentStep(step, id, ctx) {
   }
   let adapter = typeof step.adapter === "string" ? step.adapter : void 0;
   let options = step.options !== void 0 ? step.options : void 0;
+  let model = step.model;
+  let agentTools;
   const agentRef = step.agent?.ref;
   if (agentRef !== void 0) {
     if (typeof agentRef !== "string" || agentRef.trim().length === 0) {
@@ -348,20 +523,36 @@ function compileAgentStep(step, id, ctx) {
       );
     }
     if (adapter === void 0) adapter = resolved.adapter;
-    if (options === void 0) options = resolved.options;
+    if (model === void 0) model = resolved.model;
+    if (options === void 0 && adapter === resolved.adapter) options = resolved.options;
+    agentTools = resolved.tools;
   }
+  let outputSchema;
+  if (step.outputSchema === void 0) {
+    console.warn(
+      `[workflow-runtime] agent step '${id}' declares no output contract; AIP-58 cannot detect a missing output`
+    );
+  } else if (hasSafeParse(step.outputSchema)) {
+    outputSchema = step.outputSchema;
+  } else {
+    outputSchema = compileOutputSchema(step.outputSchema, id);
+  }
+  const rawCwd = step.cwd;
+  const cwd = typeof rawCwd === "function" ? rawCwd : typeof rawCwd === "string" ? (b) => resolveRefString(id, "cwd", rawCwd, b, "error") : void 0;
   return buildAgentStep(id, {
     prompt: (b) => renderPrompt(prompt, b),
     ...adapter !== void 0 ? { adapter } : {},
+    ...cwd !== void 0 ? { cwd } : {},
     ...step.sessionRef !== void 0 ? { sessionRef: step.sessionRef } : {},
-    ...step.model !== void 0 ? { model: step.model } : {},
+    ...model !== void 0 ? { model } : {},
     ...step.sandbox !== void 0 ? { sandbox: step.sandbox } : {},
     ...step.cacheable ? { cacheable: true } : {},
     ...options !== void 0 ? { options } : {},
     policy: step.policy,
-    ...step.outputSchema !== void 0 ? { outputSchema: step.outputSchema } : {},
+    ...outputSchema !== void 0 ? { outputSchema } : {},
     ...step.maxRetries !== void 0 ? { maxRetries: step.maxRetries } : {},
-    ...step.harness !== void 0 ? { harness: step.harness } : {}
+    ...step.harness !== void 0 ? { harness: step.harness } : {},
+    ...agentTools !== void 0 ? { agentTools } : {}
   });
 }
 function compileGateStep(step, id) {
@@ -416,20 +607,23 @@ function compileStep(step, ctx) {
         tool,
         candidates: opts.candidates,
         input: (b) => resolveValue(inputs, b),
-        context: opts.contextFor ? (b) => opts.contextFor(toolId, b) : void 0
+        context: opts.contextFor ? (b) => opts.contextFor(toolId, b) : void 0,
+        ...step.cacheable ? { cacheable: true } : {}
       };
     }
     case "map": {
       const over = f(step, "over");
       const inner = compileStepList(f(step, "steps"), `${id}__body`, ctx);
       const onError = f(step, "onError");
+      const maxConsecutiveSpawnFailures = f(step, "maxConsecutiveSpawnFailures");
       return {
         kind: "map",
         id,
         parallelism: f(step, "parallelism"),
         over: (b) => resolveRef(over, b),
         body: () => inner,
-        ...onError !== void 0 ? { onError } : {}
+        ...onError !== void 0 ? { onError } : {},
+        ...maxConsecutiveSpawnFailures !== void 0 ? { maxConsecutiveSpawnFailures } : {}
       };
     }
     case "loop": {
@@ -512,6 +706,28 @@ function compileStep(step, ctx) {
     }
     case "gate":
       return compileGateStep(step, id);
+    case "artifact": {
+      if (typeof step.key === "function" || typeof step.path === "function") {
+        const passthrough = step;
+        return passthrough;
+      }
+      const key = f(step, "key");
+      const rawPath = f(step, "path");
+      if (typeof key !== "string" || key.trim().length === 0) {
+        throw new WorkflowCompileError(`artifact step '${id}' needs a non-empty 'key'`);
+      }
+      if (typeof rawPath !== "string" || rawPath.trim().length === 0) {
+        throw new WorkflowCompileError(`artifact step '${id}' needs a non-empty 'path'`);
+      }
+      const contentType = f(step, "contentType");
+      return {
+        kind: "artifact",
+        id,
+        key,
+        path: (b) => resolveRefString(id, "path", rawPath, b, "error"),
+        ...contentType !== void 0 ? { contentType } : {}
+      };
+    }
     case "transform": {
       const passthrough = step;
       return passthrough;
@@ -554,6 +770,9 @@ function resolveRefString(stepId, field, value, b, onUnmatched = "passthrough")
   }
   return String(hit.resolved) + hit.rest;
 }
+
+// src/types.ts
+var DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES = 3;
 var NodeFsPort = class {
   root;
   constructor(root) {
@@ -748,12 +967,150 @@ var WorkflowSuspendedError = class extends Error {
   stepId;
   on;
 };
-function view(state, item, index) {
-  return { input: state.input, steps: state.steps, item, index };
+var AgentInputRequiredError = class extends Error {
+  constructor(stepId, prompt, schema) {
+    super(
+      `step '${stepId}' requires input ("${prompt}") \u2014 no onInputRequired hook supplied`
+    );
+    this.stepId = stepId;
+    this.prompt = prompt;
+    this.schema = schema;
+    this.name = "AgentInputRequiredError";
+  }
+  stepId;
+  prompt;
+  schema;
+};
+var StepOutcomeError = class extends Error {
+  constructor(stepId, code, message, hint) {
+    super(message);
+    this.stepId = stepId;
+    this.code = code;
+    this.hint = hint;
+    this.name = "StepOutcomeError";
+  }
+  stepId;
+  code;
+  hint;
+};
+var MissingArtifactError = class extends Error {
+  constructor(key, stepId) {
+    super(`outputsFiles.${key} was required but is missing from the run workspace`);
+    this.key = key;
+    this.stepId = stepId;
+    this.name = "MissingArtifactError";
+  }
+  key;
+  stepId;
+  code = "missing-artifact";
+};
+var AgentSpawnError = class extends Error {
+  constructor(stepId, cause) {
+    super(`step '${stepId}': agent spawn failed \u2014 ${errorMessage(cause)}`);
+    this.stepId = stepId;
+    this.cause = cause;
+    this.name = "AgentSpawnError";
+  }
+  stepId;
+  cause;
+};
+function withReleaseScope(ctx) {
+  return { ...ctx, spawned: [] };
+}
+async function releaseScope(ctx) {
+  const release = ctx.agents?.releaseSession;
+  if (!release || !ctx.spawned || ctx.spawned.length === 0) return;
+  const ids = ctx.spawned.splice(0);
+  const agents = ctx.agents;
+  await Promise.all(ids.map((id) => Promise.resolve().then(() => release.call(agents, id)).catch(() => void 0)));
+}
+function view(ctx, item, index) {
+  return {
+    input: ctx.state.input,
+    steps: ctx.state.steps,
+    item,
+    index,
+    ...ctx.workspace !== void 0 ? { run: { workspace: ctx.workspace } } : {}
+  };
+}
+function withIndexedHooks(ctx, index) {
+  const cacheKeySuffix = `${ctx.cacheKeySuffix ?? ""}[${index}]`;
+  if (!ctx.onStepStart && !ctx.onStepComplete && !ctx.onStepSkipped && !ctx.onStepFailed) {
+    return { ...ctx, cacheKeySuffix };
+  }
+  return {
+    ...ctx,
+    cacheKeySuffix,
+    onStepStart: ctx.onStepStart ? (id, info) => ctx.onStepStart(`${id}[${index}]`, info) : void 0,
+    onStepComplete: ctx.onStepComplete ? (id, out, info) => ctx.onStepComplete(`${id}[${index}]`, out, info) : void 0,
+    onStepSkipped: ctx.onStepSkipped ? (id, info) => ctx.onStepSkipped(`${id}[${index}]`, info) : void 0,
+    onStepFailed: ctx.onStepFailed ? (id, info) => ctx.onStepFailed(`${id}[${index}]`, info) : void 0
+  };
+}
+var failureOrigin = /* @__PURE__ */ new WeakMap();
+function reportItemFailure(err, itemCtx, bodyId) {
+  const info = { error: errorMessage(err) };
+  const origin = typeof err === "object" && err !== null ? failureOrigin.get(err) : void 0;
+  if (origin) {
+    failureOrigin.delete(err);
+    origin(info);
+  } else {
+    itemCtx.onStepFailed?.(bodyId, info);
+  }
+}
+function spawnBreaker(threshold) {
+  let streak = 0;
+  let streakFirst;
+  let open;
+  return {
+    settle(err) {
+      if (open !== void 0) return;
+      if (!(err instanceof AgentSpawnError)) {
+        streak = 0;
+        streakFirst = void 0;
+        return;
+      }
+      if (streak === 0) streakFirst = err.message;
+      streak++;
+      if (threshold > 0 && streak >= threshold) open = streakFirst;
+    },
+    get open() {
+      return open;
+    }
+  };
+}
+function skipUnstartedItems(ctx, fanOutId, from, items, bodiesOf, reason, results) {
+  for (let idx = from; idx < items.length; idx++) {
+    results[idx] = { status: "skipped", index: idx, item: items[idx], reason: `circuit-open: ${reason}` };
+    const itemCtx = withIndexedHooks(ctx, idx);
+    if (!itemCtx.onStepSkipped) continue;
+    let bodies;
+    try {
+      bodies = bodiesOf(items[idx], idx);
+    } catch {
+      continue;
+    }
+    for (const id of new Set(skippableStepIds(bodies))) {
+      itemCtx.onStepSkipped(id, { reason: "circuit-open", branchId: fanOutId, message: reason });
+    }
+  }
+}
+function tolerantResult(results, circuitOpen) {
+  const outcomes = results;
+  return {
+    results: outcomes,
+    succeeded: outcomes.filter((r) => r.status === "fulfilled").length,
+    failed: outcomes.filter((r) => r.status === "rejected").length,
+    skipped: outcomes.filter((r) => r.status === "skipped").length,
+    ...circuitOpen !== void 0 ? { circuitOpen: { error: circuitOpen } } : {}
+  };
 }
 function resolveSel(sel, b) {
   return typeof sel === "function" ? sel(b) : sel;
 }
+function resolveSessionRef(ref, b) {
+  return b.index === void 0 ? ref : ref.replace(/\{\{\s*index\s*\}\}/g, String(b.index));
+}
 function extractJsonCandidate(raw) {
   const jsonFence = /```json\s*([\s\S]*?)```/g;
   const lastJson = lastMatch(jsonFence, raw);
@@ -774,40 +1131,166 @@ 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(cacheKey, step) {
-  return `${cacheKey}\0${step.id}\0${step.kind}`;
+function stepJournalKey(ctx, step) {
+  return `${ctx.cacheKey}\0${step.id}\0${step.kind}${ctx.cacheKeySuffix ?? ""}`;
 }
 function isCacheEnabled(ctx, step) {
   return step.cacheable === true && ctx.cache !== void 0 && ctx.cacheKey !== void 0;
 }
+function cachedHitKey(ctx, stepId) {
+  return `${stepId}${ctx.cacheKeySuffix ?? ""}`;
+}
+function completeStep(ctx, stepId, out) {
+  const cached = ctx.state.cachedHits.delete(cachedHitKey(ctx, stepId));
+  ctx.onStepComplete?.(stepId, out, cached ? { cached: true } : void 0);
+}
 async function readStepCache(ctx, step, resolvedInputs) {
-  const key = stepJournalKey(ctx.cacheKey, step);
-  const hash = hashResolvedInputs(step.kind, resolvedInputs);
+  const key = stepJournalKey(ctx, step);
+  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 };
 }
 function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
-function formatZodError(err) {
+function formatSchemaError(err) {
   return err.issues.map((i) => `${i.path.length > 0 ? i.path.join(".") + ": " : ""}${i.message}`).join(", ");
 }
+function describeOutputSchemaForPrompt(schema) {
+  if (schema.jsonSchema !== void 0) {
+    return `When done, reply with ONLY a JSON object matching this JSON Schema: ${JSON.stringify(schema.jsonSchema)}`;
+  }
+  try {
+    const jsonSchema = z.toJSONSchema(schema);
+    return `When done, reply with ONLY a JSON object matching this JSON Schema: ${JSON.stringify(jsonSchema)}`;
+  } catch {
+  }
+  const shape = schema.shape;
+  if (shape && typeof shape === "object") {
+    const fields = Object.keys(shape);
+    if (fields.length > 0) {
+      return `When done, reply with ONLY a JSON object with these fields: ${fields.join(", ")}`;
+    }
+  }
+  return void 0;
+}
+function skippableStepIds(steps, acc = []) {
+  for (const s of steps) {
+    switch (s.kind) {
+      case "group":
+        skippableStepIds(s.steps, acc);
+        break;
+      case "parallel":
+        for (const br of s.branches) skippableStepIds(br.steps, acc);
+        break;
+      case "branch":
+        skippableStepIds(s.then, acc);
+        if (s.otherwise) skippableStepIds(s.otherwise, acc);
+        break;
+      case "loop":
+        skippableStepIds(s.body, acc);
+        break;
+      default:
+        acc.push(s.id);
+    }
+  }
+  return acc;
+}
 async function runSequence(steps, ctx, item, index) {
   let last;
   for (const s of steps) {
     const out = await execStep(s, ctx, item, index);
     ctx.state.steps[s.id] = out;
-    ctx.onStepComplete?.(s.id, out);
+    completeStep(ctx, s.id, out);
     last = out;
   }
   return last;
 }
+async function sendPromptAndAwaitOutcome(ctx, step, sessionId, prompt) {
+  let next = prompt;
+  for (; ; ) {
+    await ctx.agents.sendPromptAndWait(sessionId, next);
+    const req = ctx.agents.takeInputRequest?.(sessionId);
+    if (!req) return;
+    if (!ctx.onInputRequired) {
+      throw new AgentInputRequiredError(step.id, req.prompt, req.schema);
+    }
+    const payload = await ctx.onInputRequired({ stepId: step.id, prompt: req.prompt, schema: req.schema });
+    next = JSON.stringify(payload);
+  }
+}
 async function execAgentStep(step, ctx, b) {
   ctx.onStepStart?.(step.id);
   if (step.adapter && ctx.state.maxTotalCostUsd !== void 0 && spentUsd(ctx.state) >= ctx.state.maxTotalCostUsd) {
@@ -815,7 +1298,8 @@ async function execAgentStep(step, ctx, b) {
       `step '${step.id}': budget_exceeded \u2014 run spend $${spentUsd(ctx.state).toFixed(4)} >= cap $${ctx.state.maxTotalCostUsd}`
     );
   }
-  const cwd = step.harness?.cwd ?? (step.cwd ? resolveSel(step.cwd, b) : ctx.cwd);
+  const stepCwd = step.cwd ? resolveSel(step.cwd, b) : void 0;
+  const cwd = step.harness?.cwd ?? (stepCwd !== void 0 ? ctx.cwd !== void 0 ? resolve(ctx.cwd, stepCwd) : stepCwd : ctx.cwd);
   let knowledgeOut;
   let knowledgeWarnings = [];
   if (step.harness?.knowledge && step.harness.knowledge.length > 0) {
@@ -847,15 +1331,28 @@ ${inner(b2)}` };
     ...step.harness ?? {},
     ...model !== void 0 && step.harness?.model === void 0 ? { model } : {}
   } : void 0;
-  const sessionId = step.adapter ? await ctx.agents.spawn(resolveSel(step.adapter, b), {
-    cwd,
-    workspaceSlug: ctx.workspaceSlug,
-    stepId: step.id,
-    ...sandbox !== void 0 ? { sandbox } : {},
-    ...step.options !== void 0 ? { options: step.options } : {},
-    ...harness !== void 0 ? { harness } : {}
-  }) : ctx.agents.resolveByLabel(step.sessionRef);
+  let sessionId;
+  if (step.adapter) {
+    if (ctx.signal?.aborted) throw new Error(`step '${step.id}': run cancelled \u2014 not spawning`);
+    try {
+      sessionId = await ctx.agents.spawn(resolveSel(step.adapter, b), {
+        cwd,
+        workspaceSlug: ctx.workspaceSlug,
+        stepId: step.id,
+        ...sandbox !== void 0 ? { sandbox } : {},
+        ...step.options !== void 0 ? { options: step.options } : {},
+        ...harness !== void 0 ? { harness } : {},
+        ...step.agentTools !== void 0 ? { agentTools: step.agentTools } : {},
+        ...b.index !== void 0 ? { stepKey: `${step.id}[${b.index}]` } : {}
+      });
+    } catch (err) {
+      throw new AgentSpawnError(step.id, err);
+    }
+  } else {
+    sessionId = ctx.agents.resolveByLabel(resolveSessionRef(step.sessionRef, b));
+  }
   if (!sessionId) throw new Error(`step '${step.id}': no session (adapter and sessionRef both unresolved)`);
+  if (step.adapter) ctx.spawned?.push(sessionId);
   if (knowledgeWarnings.length > 0 && ctx.agents.emitHarnessWarning) {
     ctx.agents.emitHarnessWarning({
       sessionId,
@@ -867,7 +1364,12 @@ ${inner(b2)}` };
     ...harness,
     ...harness.tools && harness.tools.length > 0 ? { toolsApplied: false } : {}
   } : void 0;
-  await ctx.agents.sendPromptAndWait(sessionId, step.prompt(b));
+  const inputRequestAffordance = ctx.agents.takeInputRequest ? "\n\nIf you need information you don't have, call the run_request_input tool instead of asking in your reply." : "";
+  const outputSchemaNote = step.outputSchema ? describeOutputSchemaForPrompt(step.outputSchema) : void 0;
+  const outputSchemaAffordance = outputSchemaNote ? `
+
+${outputSchemaNote}` : "";
+  await sendPromptAndAwaitOutcome(ctx, step, sessionId, step.prompt(b) + inputRequestAffordance + outputSchemaAffordance);
   if (step.policy && ctx.agents.onAwaitingInput) {
     await ctx.agents.onAwaitingInput(sessionId, step.policy);
   }
@@ -889,8 +1391,10 @@ ${inner(b2)}` };
   }
   const maxRetries = step.maxRetries ?? 2;
   let lastErr = "";
+  let lastRaw = "";
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     const raw = await ctx.agents.readFinalMessage(sessionId);
+    lastRaw = raw;
     const candidate = extractJsonCandidate(raw);
     let value;
     try {
@@ -898,24 +1402,34 @@ ${inner(b2)}` };
     } catch {
       lastErr = "not valid JSON";
       if (attempt < maxRetries) {
-        await ctx.agents.sendPromptAndWait(
+        await sendPromptAndAwaitOutcome(
+          ctx,
+          step,
           sessionId,
-          `Your previous reply did not match the required schema: ${lastErr}. Reply again with ONLY a JSON object that matches. No prose, no code fence needed.`
+          `Your previous reply did not match the required schema: ${lastErr}. Reply again with ONLY a JSON object that matches. No prose, no code fence needed.` + outputSchemaAffordance
         );
       }
       continue;
     }
     const res = step.outputSchema.safeParse(value);
     if (res.success) return { sessionId, output: res.data, ...harnessOut ? { harness: harnessOut } : {}, ...knowledgeOut ? { knowledgeApplied: knowledgeOut } : {} };
-    lastErr = formatZodError(res.error);
+    lastErr = formatSchemaError(res.error);
     if (attempt < maxRetries) {
-      await ctx.agents.sendPromptAndWait(
+      await sendPromptAndAwaitOutcome(
+        ctx,
+        step,
         sessionId,
-        `Your previous reply did not match the required schema: ${lastErr}. Reply again with ONLY a JSON object that matches. No prose, no code fence needed.`
+        `Your previous reply did not match the required schema: ${lastErr}. Reply again with ONLY a JSON object that matches. No prose, no code fence needed.` + outputSchemaAffordance
       );
     }
   }
-  throw new Error(`step '${step.id}': output_invalid \u2014 final message never matched outputSchema (${lastErr})`);
+  const hint = lastRaw.trim().endsWith("?") ? "possible-input-request" : void 0;
+  throw new StepOutcomeError(
+    step.id,
+    "missing-output",
+    `step '${step.id}': missing-output \u2014 final message never matched outputSchema (${lastErr})`,
+    hint
+  );
 }
 function tryParseJson(text) {
   const trimmed = text.trim();
@@ -1020,10 +1534,25 @@ Please address the findings above, then reply when done.`
   }
   return last;
 }
+function cacheHit(ctx, step, output) {
+  ctx.state.cachedHits.add(cachedHitKey(ctx, step.id));
+  ctx.onStepStart?.(step.id, { cached: true });
+  return output;
+}
 async function execStep(step, ctx, item, index) {
+  try {
+    return await execStepBody(step, ctx, item, index);
+  } catch (err) {
+    if (typeof err === "object" && err !== null && !failureOrigin.has(err)) {
+      failureOrigin.set(err, (info) => ctx.onStepFailed?.(step.id, info));
+    }
+    throw err;
+  }
+}
+async function execStepBody(step, ctx, item, index) {
   const { state, signal } = ctx;
-  const b = view(state, item, index);
-  if (step.kind !== "agent") {
+  const b = view(ctx, item, index);
+  if (step.kind !== "agent" && step.kind !== "tool" && step.kind !== "artifact") {
     ctx.onStepStart?.(step.id);
   }
   switch (step.kind) {
@@ -1038,11 +1567,15 @@ async function execStep(step, ctx, item, index) {
         secrets: step.secrets,
         signal
       });
-      if (!isCacheEnabled(ctx, step)) return runIt();
+      if (!isCacheEnabled(ctx, step)) {
+        ctx.onStepStart?.(step.id);
+        return runIt();
+      }
       const c = await readStepCache(ctx, step, input);
-      if (c.hit) return c.output;
+      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":
@@ -1052,81 +1585,110 @@ async function execStep(step, ctx, item, index) {
       const parallelism = Math.max(1, step.parallelism ?? 1);
       const tolerant = step.onError === "collect";
       const results = new Array(arr.length);
-      for (let i = 0; i < arr.length; i += parallelism) {
-        const chunk = arr.slice(i, i + parallelism);
-        if (!tolerant) {
-          const outs = await Promise.all(
-            chunk.map((el, j) => {
-              const idx = i + j;
-              const inner = step.body(el, idx, view(state, el, idx));
-              return execStep(inner, ctx, el, idx);
-            })
-          );
-          for (let j = 0; j < outs.length; j++) results[i + j] = outs[j];
-          continue;
+      let next = 0;
+      let failed = false;
+      const breaker = spawnBreaker(step.maxConsecutiveSpawnFailures ?? DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES);
+      const runItem = async (idx) => {
+        const el = arr[idx];
+        const inner = step.body(el, idx, view(ctx, el, idx));
+        const wrapped = withReleaseScope(withIndexedHooks(ctx, idx));
+        try {
+          const out = await execStep(inner, wrapped, el, idx);
+          completeStep(wrapped, inner.id, out);
+          results[idx] = tolerant ? { status: "fulfilled", index: idx, value: out } : out;
+          breaker.settle();
+        } catch (err) {
+          if (!tolerant) {
+            failed = true;
+            throw err;
+          }
+          results[idx] = { status: "rejected", index: idx, item: el, error: errorMessage(err) };
+          reportItemFailure(err, wrapped, inner.id);
+          breaker.settle(err);
+        } finally {
+          await releaseScope(wrapped);
         }
-        const settled = await Promise.allSettled(
-          chunk.map((el, j) => {
-            const idx = i + j;
-            const inner = step.body(el, idx, view(state, el, idx));
-            return execStep(inner, ctx, el, idx);
-          })
-        );
-        settled.forEach((s, j) => {
-          const idx = i + j;
-          results[idx] = s.status === "fulfilled" ? { status: "fulfilled", index: idx, value: s.value } : { status: "rejected", index: idx, item: chunk[j], error: errorMessage(s.reason) };
-        });
-      }
-      if (!tolerant) return results;
-      const outcomes = results;
-      return {
-        results: outcomes,
-        succeeded: outcomes.filter((r) => r.status === "fulfilled").length,
-        failed: outcomes.filter((r) => r.status === "rejected").length
       };
+      const worker = async () => {
+        while (!failed && breaker.open === void 0 && next < arr.length) {
+          const idx = next++;
+          await runItem(idx);
+        }
+      };
+      await Promise.all(Array.from({ length: Math.min(parallelism, arr.length) }, () => worker()));
+      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);
+      }
+      return tolerantResult(results, breaker.open);
     }
     case "pipeline": {
       const items = [...step.over(b)];
       const tolerant = step.onError === "collect";
-      if (items.length === 0) return tolerant ? { results: [], succeeded: 0, failed: 0 } : [];
+      if (items.length === 0) return tolerant ? tolerantResult([], void 0) : [];
       const cap = Math.max(1, step.concurrency ?? items.length);
       const results = new Array(items.length);
       let next = 0;
+      const breaker = spawnBreaker(step.maxConsecutiveSpawnFailures ?? DEFAULT_MAX_CONSECUTIVE_SPAWN_FAILURES);
       const runItem = async (idx) => {
         let prev = void 0;
+        let stageId = step.id;
+        const wrapped = withReleaseScope(withIndexedHooks(ctx, idx));
         try {
           for (const stage of step.stages) {
-            prev = await execStep(stage(items[idx], idx, prev, view(state, items[idx], idx)), ctx, items[idx], idx);
+            const inner = stage(items[idx], idx, prev, view(ctx, items[idx], idx));
+            stageId = inner.id;
+            prev = await execStep(inner, wrapped, items[idx], idx);
+            completeStep(wrapped, inner.id, prev);
           }
           results[idx] = tolerant ? { status: "fulfilled", index: idx, value: prev } : prev;
+          breaker.settle();
         } catch (err) {
           if (!tolerant) throw err;
           results[idx] = { status: "rejected", index: idx, item: items[idx], error: errorMessage(err) };
+          reportItemFailure(err, wrapped, stageId);
+          breaker.settle(err);
+        } finally {
+          await releaseScope(wrapped);
         }
       };
       const worker = async () => {
-        while (next < items.length) {
+        while ((!tolerant || breaker.open === void 0) && next < items.length) {
           const idx = next++;
           await runItem(idx);
         }
       };
       await Promise.all(Array.from({ length: Math.min(cap, items.length) }, () => worker()));
       if (!tolerant) return results;
-      const outcomes = results;
-      return {
-        results: outcomes,
-        succeeded: outcomes.filter((r) => r.status === "fulfilled").length,
-        failed: outcomes.filter((r) => r.status === "rejected").length
-      };
+      if (breaker.open !== void 0) {
+        skipUnstartedItems(
+          ctx,
+          step.id,
+          next,
+          items,
+          (el, idx) => step.stages.map((stage) => stage(el, idx, void 0, view(ctx, el, idx))),
+          breaker.open,
+          results
+        );
+      }
+      return tolerantResult(results, breaker.open);
     }
     case "branch": {
-      const chosen = step.cond(b) ? step.then : step.otherwise ?? [];
+      const taken = step.cond(b);
+      const chosen = taken ? step.then : step.otherwise ?? [];
+      if (ctx.onStepSkipped) {
+        const onChosenPath = new Set(skippableStepIds(chosen));
+        const untaken = taken ? step.otherwise ?? [] : step.then;
+        for (const id of new Set(skippableStepIds(untaken))) {
+          if (!onChosenPath.has(id)) ctx.onStepSkipped(id, { reason: "branch-not-taken", branchId: step.sourceId ?? step.id });
+        }
+      }
       return runSequence(chosen, ctx, item, index);
     }
     case "loop": {
       let iterations = 0;
       let last;
-      while (iterations < step.maxIterations && step.while(view(state, item, index))) {
+      while (iterations < step.maxIterations && step.while(view(ctx, item, index))) {
         last = await runSequence(step.body, ctx, item, index);
         iterations++;
       }
@@ -1172,14 +1734,21 @@ async function execStep(step, ctx, item, index) {
       const child = await runWorkflowInner(step.workflow, childInput, {
         approve: ctx.approve,
         resume: ctx.resume,
+        onInputRequired: ctx.onInputRequired,
         signal,
         agents: ctx.agents,
         cwd: ctx.cwd,
         workspaceSlug: ctx.workspaceSlug,
+        workspace: ctx.workspace,
+        artifactsDir: ctx.artifactsDir,
+        runId: ctx.runId,
+        onArtifact: ctx.onArtifact,
         cache: ctx.cache,
         cacheKey: ctx.cacheKey,
         runGateCommand: ctx.runGateCommand,
-        onGateReport: ctx.onGateReport
+        onGateReport: ctx.onGateReport,
+        spawned: ctx.spawned,
+        usedArtifactNames: ctx.usedArtifactNames
       });
       return child.output;
     }
@@ -1190,29 +1759,165 @@ async function execStep(step, ctx, item, index) {
         prompt: step.prompt(b),
         adapter: step.adapter ? resolveSel(step.adapter, b) : void 0,
         model: step.model ? resolveSel(step.model, b) : void 0,
-        sessionRef: step.sessionRef
+        sessionRef: step.sessionRef !== void 0 ? resolveSessionRef(step.sessionRef, b) : void 0
       };
       const c = await readStepCache(ctx, step, resolved);
-      if (c.hit) return c.output;
+      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":
       return execGateStep(step, ctx, b);
+    case "artifact":
+      return execArtifactStep(step, ctx, b);
   }
 }
+function sanitizeArtifactFilename(name) {
+  const cleaned = name.replace(/[^a-zA-Z0-9._-]/g, "_");
+  return cleaned.length > 0 ? cleaned : "artifact";
+}
+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)) {
+    throw new Error(`step '${stepId}': artifact path '${rawPath}' resolves outside the run workspace`);
+  }
+  const buf = await readFile(abs);
+  const sha256 = createHash("sha256").update(buf).digest("hex");
+  const destName = reserveArtifactDestName(rawPath, key, usedNames);
+  await mkdir(artifactsDir, { recursive: true });
+  await writeFile(join(artifactsDir, destName), buf);
+  return {
+    key,
+    path: `artifacts/${destName}`,
+    sha256,
+    size: buf.length,
+    stepId,
+    ...contentType !== void 0 ? { contentType } : {}
+  };
+}
+async function execArtifactStep(step, ctx, b) {
+  if (ctx.workspace === void 0 || ctx.artifactsDir === void 0) {
+    throw new Error(`step '${step.id}': kind:"artifact" requires a run workspace (no workspace/artifactsDir wired)`);
+  }
+  const workspace = ctx.workspace;
+  const artifactsDir = ctx.artifactsDir;
+  const key = resolveSel(step.key, b);
+  const rawPath = resolveSel(step.path, b);
+  const contentType = step.contentType ? resolveSel(step.contentType, b) : void 0;
+  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, 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 = out2.path.slice("artifacts/".length);
+      ctx.usedArtifactNames?.add(destName);
+      const destAbs = join(artifactsDir, destName);
+      const srcAbs = join(entry.artifactsDirAtCache ?? artifactsDir, destName);
+      if (srcAbs !== destAbs) {
+        await mkdir(dirname(destAbs), { recursive: true });
+        try {
+          await copyFile(srcAbs, destAbs);
+        } catch {
+        }
+      }
+      ctx.onArtifact?.(out2);
+      return cacheHit(ctx, step, out2);
+    }
+  }
+  ctx.onStepStart?.(step.id);
+  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 });
+  }
+  ctx.onArtifact?.(out);
+  return out;
+}
+function interpolateFileContractPath(path, workflowId, runId) {
+  return path.replace(/<runId>/g, runId ?? "").replace(/<workflowId>/g, workflowId).replace(/<isoDate>/g, (/* @__PURE__ */ new Date()).toISOString().slice(0, 10));
+}
+async function checkOutputsFiles(outputsFiles, ctx, workflowId, lastStepId) {
+  if (!outputsFiles) return;
+  if (ctx.workspace === void 0 || ctx.artifactsDir === void 0) return;
+  for (const [key, contract] of Object.entries(outputsFiles)) {
+    const rawPath = interpolateFileContractPath(contract.path, workflowId, ctx.runId);
+    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, ctx.usedArtifactNames);
+    } catch {
+      if (contract.required === true) {
+        throw new MissingArtifactError(key, lastStepId);
+      }
+      console.warn(
+        `[workflow-runtime] outputsFiles.${key} ('${contract.path}') is missing and not marked required \u2014 the run still succeeds (AIP-58 \xA74)`
+      );
+      continue;
+    }
+    ctx.onArtifact?.(out);
+  }
+}
+async function runFinally(steps, ctx, bodyFailed) {
+  const cleanupCtx = { ...ctx, signal: void 0 };
+  let firstError;
+  for (const step of steps) {
+    try {
+      const out = await execStep(step, cleanupCtx, void 0, void 0);
+      cleanupCtx.state.steps[step.id] = out;
+      completeStep(cleanupCtx, step.id, out);
+    } catch (err) {
+      cleanupCtx.onStepFailed?.(step.id, { error: errorMessage(err) });
+      if (firstError === void 0) firstError = err;
+    }
+  }
+  if (!bodyFailed && firstError !== void 0) throw firstError;
+}
 async function runWorkflowInner(workflow, input, hooks, maxTotalCostUsd) {
-  const state = { input, steps: {}, costBySession: /* @__PURE__ */ new Map(), maxTotalCostUsd };
-  const ctx = { state, ...hooks };
+  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: [], usedArtifactNames: /* @__PURE__ */ new Set() } : {}
+  };
   let lastId;
-  for (const step of workflow.steps) {
-    const out = await execStep(step, ctx, void 0, void 0);
-    state.steps[step.id] = out;
-    ctx.onStepComplete?.(step.id, out);
-    lastId = step.id;
+  let bodyFailed = false;
+  try {
+    for (const step of workflow.steps) {
+      const out = await execStep(step, ctx, void 0, void 0);
+      state.steps[step.id] = out;
+      completeStep(ctx, step.id, out);
+      lastId = step.id;
+    }
+    await checkOutputsFiles(workflow.outputsFiles, ctx, workflow.id, lastId);
+  } catch (err) {
+    bodyFailed = true;
+    throw err;
+  } finally {
+    try {
+      if (workflow.finally && workflow.finally.length > 0) await runFinally(workflow.finally, ctx, bodyFailed);
+    } finally {
+      if (ownsScope) await releaseScope(ctx);
+    }
   }
-  const bindings = view(state);
+  const bindings = view(ctx);
   const output = workflow.output ? workflow.output(bindings) : lastId !== void 0 ? state.steps[lastId] : void 0;
   return { output, bindings };
 }
@@ -1220,14 +1925,21 @@ async function runWorkflow(args) {
   return runWorkflowInner(args.workflow, args.input, {
     approve: args.approve,
     resume: args.resume,
+    onInputRequired: args.onInputRequired,
     signal: args.signal,
     agents: args.agents,
     cwd: args.cwd,
     workspaceSlug: args.workspaceSlug,
+    workspace: args.workspace,
+    artifactsDir: args.artifactsDir,
+    runId: args.runId,
+    onArtifact: args.onArtifact,
     cache: args.cache,
     cacheKey: args.cacheKey,
     onStepStart: args.onStepStart,
     onStepComplete: args.onStepComplete,
+    onStepSkipped: args.onStepSkipped,
+    onStepFailed: args.onStepFailed,
     runGateCommand: args.runGateCommand,
     onGateReport: args.onGateReport
   }, args.maxTotalCostUsd);
@@ -1238,6 +1950,6 @@ function compileWorkflowManifest(source, opts) {
   return compileWorkflow(handle, opts);
 }
 
-export { NodeFsPort, WorkflowCompileError, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, interpolateTemplate, materializeKnowledge, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow };
+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 };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map