@agentproto/workflow-runtime 0.9.0 → 0.11.0

package/dist/index.mjs

@@ -1,5 +1,10 @@
 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 { assertKnownStepRefs } from '@agentproto/workflow';
+import { isRefinedKind, filterEntriesByAllOf, resolveKnowledge } from '@agentproto/corpus';
 import { parseWorkflowManifest, workflowFromManifest } from '@agentproto/workflow/manifest';
 
 /**
@@ -7,702 +12,1160 @@ import { parseWorkflowManifest, workflowFromManifest } from '@agentproto/workflo
  * AIP-15 step-walker over @agentproto/driver runTool.
  */
 
-var WorkflowSuspendedError = class extends Error {
-  constructor(stepId, on) {
-    super(
-      `workflow suspended at step '${stepId}' awaiting [${on.join(", ")}] \u2014 no resume hook supplied`
-    );
-    this.stepId = stepId;
-    this.on = on;
-    this.name = "WorkflowSuspendedError";
+
+// src/build-agent-step.ts
+function buildAgentStep(id, fields) {
+  const prompt = fields.prompt;
+  return {
+    kind: "agent",
+    id,
+    ...fields.adapter !== void 0 ? { adapter: fields.adapter } : {},
+    ...fields.model !== void 0 ? { model: fields.model } : {},
+    ...fields.sessionRef !== void 0 ? { sessionRef: fields.sessionRef } : {},
+    ...fields.sandbox !== void 0 ? { sandbox: fields.sandbox } : {},
+    ...fields.cacheable ? { cacheable: true } : {},
+    ...fields.options !== void 0 ? { options: fields.options } : {},
+    prompt: typeof prompt === "function" ? prompt : ((_b) => prompt),
+    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 } : {}
+  };
+}
+
+// src/compile-workflow.ts
+var WorkflowCompileError = class extends Error {
+  constructor(message) {
+    super(`compileWorkflow: ${message}`);
+    this.name = "WorkflowCompileError";
   }
-  stepId;
-  on;
 };
-function view(state, item, index) {
-  return { input: state.input, steps: state.steps, item, index };
-}
-function resolveSel(sel, b) {
-  return typeof sel === "function" ? sel(b) : sel;
+var get = (m, key) => m instanceof Map ? m.get(key) : m[key];
+function dig(value, path) {
+  let v = value;
+  for (const seg of path) {
+    if (v == null) return void 0;
+    v = v[seg];
+  }
+  return v;
 }
-function extractJsonCandidate(raw) {
-  const jsonFence = /```json\s*([\s\S]*?)```/g;
-  const lastJson = lastMatch(jsonFence, raw);
-  if (lastJson !== void 0) return lastJson;
-  const anyFence = /```\s*([\s\S]*?)```/g;
-  const lastAny = lastMatch(anyFence, raw);
-  if (lastAny !== void 0) return lastAny;
-  return raw.trim();
+var REF_RE = /^\$(input|item|steps)((?:\.[^.]+)*)$/;
+var REF_PREFIX_RE = /^\$(?:input|item|steps|index)((?:\.[^.$/]+)*)/;
+function resolveRef(ref, b) {
+  if (ref === "$index") return b.index;
+  const m = ref.match(REF_RE);
+  if (!m) throw new WorkflowCompileError(`bad reference '${ref}'`);
+  const segs = m[2] ? m[2].slice(1).split(".") : [];
+  switch (m[1]) {
+    case "input":
+      return dig(b.input, segs);
+    case "item":
+      return dig(b.item, segs);
+    case "steps": {
+      const [stepId, ...rest] = segs;
+      if (!stepId) throw new WorkflowCompileError(`'$steps' needs a step id`);
+      return dig(b.steps[stepId], rest);
+    }
+  }
 }
-function lastMatch(re, s) {
-  let m;
-  let last = null;
-  while ((m = re.exec(s)) !== null) last = m;
-  return last ? last[1]?.trim() : void 0;
+function resolveRefPrefixed(value, b) {
+  const m = value.match(REF_PREFIX_RE);
+  if (!m) return void 0;
+  const token = value.slice(0, m[0].length);
+  return { resolved: resolveRef(token, b), rest: value.slice(m[0].length) };
 }
-function spentUsd(state) {
-  let total = 0;
-  for (const c of state.costBySession.values()) total += c;
-  return total;
+function resolveValue(node, b) {
+  if (typeof node === "string") {
+    if (node.startsWith("$$")) return node.slice(1);
+    if (node.startsWith("$")) return resolveRef(node, b);
+    return node;
+  }
+  if (Array.isArray(node)) return node.map((n) => resolveValue(n, b));
+  if (node && typeof node === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(node))
+      out[k] = resolveValue(v, b);
+    return out;
+  }
+  return node;
 }
-function hashResolvedInputs(kind, resolved) {
-  return createHash("sha256").update(`${kind}\0${JSON.stringify(resolved) ?? "undefined"}`).digest("hex");
+function refPathExists(ref, b) {
+  const m = ref.match(REF_RE);
+  if (!m) return false;
+  const segs = m[2] ? m[2].slice(1).split(".") : [];
+  let v;
+  if (m[1] === "steps") {
+    const [stepId, ...rest] = segs;
+    if (!stepId || !(stepId in b.steps)) return false;
+    v = b.steps[stepId];
+    segs.length = 0;
+    segs.push(...rest);
+  } else {
+    v = m[1] === "input" ? b.input : b.item;
+  }
+  for (const seg of segs) {
+    if (v === null || typeof v !== "object") return false;
+    const o = v;
+    if (!(seg in o)) return false;
+    v = o[seg];
+  }
+  return true;
 }
-function stepJournalKey(cacheKey, step) {
-  return `${cacheKey}\0${step.id}\0${step.kind}`;
+function resolveValueStrict(node, b, label) {
+  if (typeof node === "string") {
+    if (node.startsWith("$$")) return node.slice(1);
+    if (node.startsWith("$")) {
+      const v = resolveRef(node, b);
+      if (v === void 0 && !refPathExists(node, b)) {
+        throw new WorkflowCompileError(
+          `${label}: reference '${node}' resolves to nothing \u2014 the referenced field does not exist`
+        );
+      }
+      return v;
+    }
+    return node;
+  }
+  if (Array.isArray(node)) return node.map((n) => resolveValueStrict(n, b, label));
+  if (node && typeof node === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(node))
+      out[k] = resolveValueStrict(v, b, label);
+    return out;
+  }
+  return node;
 }
-function isCacheEnabled(ctx, step) {
-  return step.cacheable === true && ctx.cache !== void 0 && ctx.cacheKey !== void 0;
+var COMPARATORS = {
+  "<": (a, c) => a < c,
+  "<=": (a, c) => a <= c,
+  ">": (a, c) => a > c,
+  ">=": (a, c) => a >= c
+};
+function literal(token, b) {
+  if (token.startsWith("$")) return resolveRef(token, b);
+  if (token === "true") return true;
+  if (token === "false") return false;
+  if (token === "null") return null;
+  if (/^-?\d+(\.\d+)?$/.test(token)) return Number(token);
+  return token.replace(/^['"]|['"]$/g, "");
 }
-async function readStepCache(ctx, step, resolvedInputs) {
-  const key = stepJournalKey(ctx.cacheKey, step);
-  const hash = hashResolvedInputs(step.kind, resolvedInputs);
-  const entry = await ctx.cache.get(key);
-  if (entry !== void 0 && entry.resolvedInputHash === hash) {
-    return { hit: true, output: entry.output };
+function evalPredicate(expr, b) {
+  const m = expr.match(/^(.+?)\s*(==|!=|<=|>=|<|>)\s*(.+)$/);
+  if (!m) return Boolean(literal(expr.trim(), b));
+  const left = literal(m[1].trim(), b);
+  const right = literal(m[3].trim(), b);
+  switch (m[2]) {
+    case "==":
+      return left === right;
+    case "!=":
+      return left !== right;
+    default: {
+      const cmp = COMPARATORS[m[2]];
+      return cmp(Number(left), Number(right));
+    }
   }
-  return { hit: false, key, hash };
 }
-function errorMessage(err) {
-  return err instanceof Error ? err.message : String(err);
+function normalizeToolId(ref) {
+  let s = ref.trim();
+  if (s.endsWith("/TOOL.md")) s = s.slice(0, -"/TOOL.md".length);
+  const slash = s.lastIndexOf("/");
+  return slash === -1 ? s : s.slice(slash + 1);
 }
-function formatZodError(err) {
-  return err.issues.map((i) => `${i.path.length > 0 ? i.path.join(".") + ": " : ""}${i.message}`).join(", ");
+var f = (step, key) => step[key];
+function assertLinear(steps) {
+  steps.forEach((s, i) => {
+    const next = s.next;
+    const followingId = steps[i + 1]?.id;
+    if (next && next !== followingId) {
+      throw new WorkflowCompileError(
+        `step '${s.id}' has a non-linear next='${next}' \u2014 the structured-subset compiler only runs steps in document order. Hand-author a BranchStep or nest structurally.`
+      );
+    }
+  });
 }
-async function runSequence(steps, ctx, item, index) {
-  let last;
+function collectStepIds(steps, ids = /* @__PURE__ */ new Set()) {
   for (const s of steps) {
-    const out = await execStep(s, ctx, item, index);
-    ctx.state.steps[s.id] = out;
-    ctx.onStepComplete?.(s.id, out);
-    last = out;
+    if (typeof s?.id === "string") ids.add(s.id);
+    if (Array.isArray(s?.steps)) collectStepIds(s.steps, ids);
+    if (Array.isArray(s?.branches)) {
+      for (const br of s.branches) {
+        if (Array.isArray(br?.steps)) collectStepIds(br.steps, ids);
+      }
+    }
   }
-  return last;
+  return ids;
 }
-async function execAgentStep(step, ctx, b) {
-  ctx.onStepStart?.(step.id);
-  if (step.adapter && ctx.state.maxTotalCostUsd !== void 0 && spentUsd(ctx.state) >= ctx.state.maxTotalCostUsd) {
-    throw new Error(
-      `step '${step.id}': budget_exceeded \u2014 run spend $${spentUsd(ctx.state).toFixed(4)} >= cap $${ctx.state.maxTotalCostUsd}`
+function compileWorkflow(handle, opts) {
+  const steps = handle.steps;
+  if (handle.start && handle.start !== steps[0]?.id) {
+    throw new WorkflowCompileError(
+      `start='${handle.start}' is not the first step \u2014 structured-subset runs in order`
     );
   }
-  const cwd = step.cwd ? resolveSel(step.cwd, b) : ctx.cwd;
-  const sandbox = typeof step.sandbox === "function" ? step.sandbox(b) : step.sandbox;
-  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 } : {}
-  }) : ctx.agents.resolveByLabel(step.sessionRef);
-  if (!sessionId) throw new Error(`step '${step.id}': no session (adapter and sessionRef both unresolved)`);
-  await ctx.agents.sendPromptAndWait(sessionId, step.prompt(b));
-  if (step.policy && ctx.agents.onAwaitingInput) {
-    await ctx.agents.onAwaitingInput(sessionId, step.policy);
-  }
-  if (ctx.agents.readCostUsd) {
-    ctx.state.costBySession.set(sessionId, await ctx.agents.readCostUsd(sessionId));
+  const ctx = { opts, knownStepIds: collectStepIds(steps) };
+  const result = handle.result;
+  const output = result !== void 0 ? (b) => resolveValue(result, b) : void 0;
+  return {
+    id: handle.id,
+    description: handle.description,
+    steps: compileSiblingsToSteps(steps, ctx),
+    ...output ? { output } : {}
+  };
+}
+function compileSiblingsToSteps(steps, ctx) {
+  assertLinear(steps);
+  const out = [];
+  for (let i = 0; i < steps.length; i++) {
+    const s = steps[i];
+    if (s.kind === "branch") {
+      out.push(compileBranchChain(steps, i, ctx));
+      return out;
+    }
+    out.push(compileStep(s, ctx));
   }
-  if (!step.outputSchema) {
-    let text;
-    if (ctx.agents.readFinalMessage) {
-      try {
-        text = await ctx.agents.readFinalMessage(sessionId);
-      } catch {
-      }
+  return out;
+}
+function compileStepList(steps, id, ctx) {
+  const compiled = compileSiblingsToSteps(steps, ctx);
+  if (compiled.length === 1) return compiled[0];
+  return { kind: "group", id, steps: compiled };
+}
+function compileBranchChain(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.`
+      );
     }
-    return { sessionId, ...text !== void 0 ? { text } : {} };
+    return idx;
+  };
+  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--) {
+    const br = branches[k];
+    const targetIdx = resolveTarget(br.next, `branches[${k}].next`);
+    const thenSteps = compileSiblingsToSteps(steps.slice(targetIdx), ctx);
+    const condExpr = br.when;
+    const nodeId = k === 0 ? branchStep.id : `${branchStep.id}__branch${k}`;
+    otherwise = [
+      {
+        kind: "branch",
+        id: nodeId,
+        cond: (b) => evalPredicate(condExpr, b),
+        then: thenSteps,
+        ...otherwise.length > 0 ? { otherwise } : {}
+      }
+    ];
   }
-  if (!ctx.agents.readFinalMessage) {
-    throw new Error(`step '${step.id}': outputSchema requires a host with readFinalMessage`);
+  return otherwise[0];
+}
+function compileAgentStep(step, id, ctx) {
+  const opts = ctx.opts;
+  const prompt = f(step, "prompt");
+  if (typeof prompt !== "string" || prompt.length === 0) {
+    throw new WorkflowCompileError(`agent step '${id}' needs a non-empty 'prompt'`);
   }
-  const maxRetries = step.maxRetries ?? 2;
-  let lastErr = "";
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const raw = await ctx.agents.readFinalMessage(sessionId);
-    const candidate = extractJsonCandidate(raw);
-    let value;
-    try {
-      value = JSON.parse(candidate);
-    } catch {
-      lastErr = "not valid JSON";
-      if (attempt < maxRetries) {
-        await ctx.agents.sendPromptAndWait(
-          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.`
-        );
-      }
-      continue;
+  let adapter = typeof step.adapter === "string" ? step.adapter : void 0;
+  let options = step.options !== void 0 ? step.options : void 0;
+  const agentRef = step.agent?.ref;
+  if (agentRef !== void 0) {
+    if (typeof agentRef !== "string" || agentRef.trim().length === 0) {
+      throw new WorkflowCompileError(`agent step '${id}' has an empty 'agent.ref'`);
     }
-    const res = step.outputSchema.safeParse(value);
-    if (res.success) return { sessionId, output: res.data };
-    lastErr = formatZodError(res.error);
-    if (attempt < maxRetries) {
-      await ctx.agents.sendPromptAndWait(
-        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.`
+    const resolved = opts.agentRefs ? get(opts.agentRefs, agentRef) : void 0;
+    if (!resolved) {
+      const available = opts.agentRefs ? opts.agentRefs instanceof Map ? [...opts.agentRefs.keys()] : Object.keys(opts.agentRefs) : [];
+      throw new WorkflowCompileError(
+        `agent step '${id}' references unknown agent ref '${agentRef}'` + (available.length > 0 ? ` \u2014 available refs: ${available.join(", ")}` : " \u2014 no agent refs are configured for this compile (not running in an app context?)")
       );
     }
+    adapter = resolved.adapter;
+    options = resolved.options;
   }
-  throw new Error(`step '${step.id}': output_invalid \u2014 final message never matched outputSchema (${lastErr})`);
+  return buildAgentStep(id, {
+    prompt: (b) => String(resolveValue(prompt, b)),
+    ...adapter !== void 0 ? { adapter } : {},
+    ...step.sessionRef !== void 0 ? { sessionRef: step.sessionRef } : {},
+    ...step.model !== void 0 ? { model: step.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 } : {},
+    ...step.maxRetries !== void 0 ? { maxRetries: step.maxRetries } : {},
+    ...step.harness !== void 0 ? { harness: step.harness } : {}
+  });
 }
-async function execStep(step, ctx, item, index) {
-  const { state, signal } = ctx;
-  const b = view(state, item, index);
-  if (step.kind !== "agent") {
-    ctx.onStepStart?.(step.id);
+function compileGateStep(step, id) {
+  const command = f(step, "command");
+  if (typeof command !== "string" || command.trim().length === 0) {
+    throw new WorkflowCompileError(`gate step '${id}' needs a non-empty 'command'`);
   }
+  const args = f(step, "args");
+  const cwd = f(step, "cwd");
+  const reportPath = f(step, "report");
+  const timeoutMs = f(step, "timeout_ms");
+  const retry = f(step, "retry");
+  const onFail = f(
+    step,
+    "on_fail"
+  );
+  return {
+    kind: "gate",
+    id,
+    command,
+    ...args !== void 0 ? { args } : {},
+    ...cwd !== void 0 ? { cwd } : {},
+    ...reportPath !== void 0 ? { reportPath } : {},
+    ...timeoutMs !== void 0 ? { timeoutMs } : {},
+    ...retry !== void 0 ? {
+      retry: {
+        maxAttempts: retry.max_attempts,
+        backoff: retry.backoff,
+        ...retry.initial_ms !== void 0 ? { initialMs: retry.initial_ms } : {}
+      }
+    } : {},
+    ...onFail !== void 0 ? { onFail: { reprompt: onFail.reprompt, ...onFail.with !== void 0 ? { with: onFail.with } : {} } } : {}
+  };
+}
+function compileStep(step, ctx) {
+  const opts = ctx.opts;
+  const id = step.id;
   switch (step.kind) {
     case "tool": {
-      const input = step.input(b);
-      const runIt = () => runTool({
-        tool: step.tool,
-        candidates: step.candidates,
-        input,
-        context: step.context ? step.context(b) : void 0,
-        resolverContext: step.resolverContext,
-        secrets: step.secrets,
-        signal
+      const ref = typeof step.tool === "string" ? step.tool : step.tool.entry;
+      const toolId = normalizeToolId(ref);
+      const tool = get(opts.tools, toolId);
+      if (!tool)
+        throw new WorkflowCompileError(`no tool registered for '${toolId}'`);
+      const inputs = f(step, "inputs") ?? {};
+      assertKnownStepRefs(inputs, ctx.knownStepIds, `tool step '${id}' inputs`, {
+        makeError: (message) => new WorkflowCompileError(message)
       });
-      if (!isCacheEnabled(ctx, step)) return runIt();
-      const c = await readStepCache(ctx, step, input);
-      if (c.hit) return c.output;
-      const out = await runIt();
-      await ctx.cache.set(c.key, { output: out, resolvedInputHash: c.hash });
-      return out;
-    }
-    case "transform":
-      return step.compute(b);
-    case "map": {
-      const arr = [...step.over(b)];
-      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;
-        }
-        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
+        kind: "tool",
+        id,
+        tool,
+        candidates: opts.candidates,
+        input: (b) => resolveValue(inputs, b),
+        context: opts.contextFor ? (b) => opts.contextFor(toolId, b) : void 0
       };
     }
-    case "pipeline": {
-      const items = [...step.over(b)];
-      const tolerant = step.onError === "collect";
-      if (items.length === 0) return tolerant ? { results: [], succeeded: 0, failed: 0 } : [];
-      const cap = Math.max(1, step.concurrency ?? items.length);
-      const results = new Array(items.length);
-      let next = 0;
-      const runItem = async (idx) => {
-        let prev = void 0;
-        try {
-          for (const stage of step.stages) {
-            prev = await execStep(stage(items[idx], idx, prev, view(state, items[idx], idx)), ctx, items[idx], idx);
-          }
-          results[idx] = tolerant ? { status: "fulfilled", index: idx, value: prev } : prev;
-        } catch (err) {
-          if (!tolerant) throw err;
-          results[idx] = { status: "rejected", index: idx, item: items[idx], error: errorMessage(err) };
-        }
-      };
-      const worker = async () => {
-        while (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;
+    case "map": {
+      const over = f(step, "over");
+      const inner = compileStepList(f(step, "steps"), `${id}__body`, ctx);
+      const onError = f(step, "onError");
       return {
-        results: outcomes,
-        succeeded: outcomes.filter((r) => r.status === "fulfilled").length,
-        failed: outcomes.filter((r) => r.status === "rejected").length
+        kind: "map",
+        id,
+        parallelism: f(step, "parallelism"),
+        over: (b) => resolveRef(over, b),
+        body: () => inner,
+        ...onError !== void 0 ? { onError } : {}
       };
     }
-    case "branch": {
-      const chosen = step.cond(b) ? step.then : step.otherwise ?? [];
-      return runSequence(chosen, ctx, item, index);
-    }
     case "loop": {
-      let iterations = 0;
-      let last;
-      while (iterations < step.maxIterations && step.while(view(state, item, index))) {
-        last = await runSequence(step.body, ctx, item, index);
-        iterations++;
-      }
-      return last;
-    }
-    case "parallel": {
-      const outs = await Promise.all(
-        step.branches.map(
-          (br) => runSequence(br.steps, ctx, item, index).then((last) => ({
-            id: br.id,
-            last
-          }))
-        )
-      );
-      const record = {};
-      for (const { id, last } of outs) record[id] = last;
-      return record;
+      const whileExpr = f(step, "while");
+      return {
+        kind: "loop",
+        id,
+        maxIterations: f(step, "max_iterations"),
+        while: (b) => evalPredicate(whileExpr, b),
+        body: [compileStepList(f(step, "steps"), `${id}__body`, ctx)]
+      };
+    }
+    case "parallel": {
+      const branches = f(step, "branches");
+      return {
+        kind: "parallel",
+        id,
+        branches: branches.map((br) => ({
+          id: br.id,
+          steps: [compileStepList(br.steps, `${id}__${br.id}`, ctx)]
+        }))
+      };
     }
     case "approval": {
-      const prompt = step.prompt(b);
-      const approvers = step.approvers ?? [];
-      const approved = ctx.approve ? await ctx.approve({ stepId: step.id, prompt, approvers }) : true;
-      const followups = approved ? step.onApprove ?? [] : step.onReject ?? [];
-      await runSequence(followups, ctx, item, index);
-      return { approved };
+      const prompt = f(step, "prompt");
+      const approvers = (f(step, "approvers") ?? []).map(
+        (a) => a.role ?? a.userId ?? String(a)
+      );
+      const artifacts = f(step, "artifacts");
+      const timeoutMs = f(step, "timeout_ms");
+      return {
+        kind: "approval",
+        id,
+        approvers,
+        ...artifacts !== void 0 ? { artifacts } : {},
+        ...timeoutMs !== void 0 ? { timeoutMs } : {},
+        prompt: (b) => String(resolveValue(prompt, b))
+      };
     }
     case "suspend": {
-      if (!ctx.resume) throw new WorkflowSuspendedError(step.id, step.on);
-      return ctx.resume({ stepId: step.id, on: step.on });
+      const resume = f(step, "resume");
+      return { kind: "suspend", id, on: resume.on, timeoutMs: resume.timeout_ms };
     }
-    case "group":
-      return runSequence(step.steps, ctx, item, index);
     case "subworkflow": {
-      const childInput = step.input ? step.input(b) : state.input;
-      const child = await runWorkflowInner(step.workflow, childInput, {
-        approve: ctx.approve,
-        resume: ctx.resume,
-        signal,
-        agents: ctx.agents,
-        cwd: ctx.cwd,
-        workspaceSlug: ctx.workspaceSlug,
-        cache: ctx.cache,
-        cacheKey: ctx.cacheKey
+      const wfId = f(step, "workflow");
+      const child = opts.workflows ? get(opts.workflows, wfId) : void 0;
+      if (!child)
+        throw new WorkflowCompileError(
+          `subworkflow '${wfId}' not found \u2014 pass it in opts.workflows`
+        );
+      const compiledChild = compileWorkflow(child, opts);
+      const inputs = f(step, "inputs");
+      if (inputs === void 0) {
+        return { kind: "subworkflow", id, workflow: compiledChild };
+      }
+      assertKnownStepRefs(inputs, ctx.knownStepIds, `subworkflow step '${id}' inputs`, {
+        makeError: (message) => new WorkflowCompileError(message)
       });
-      return child.output;
+      const entries = Object.entries(inputs);
+      return {
+        kind: "subworkflow",
+        id,
+        workflow: compiledChild,
+        // Each top-level key resolves strictly: a missing referenced field
+        // throws at run time naming this step + key (no silent `undefined`).
+        input: (b) => {
+          const out = {};
+          for (const [k, v] of entries)
+            out[k] = resolveValueStrict(v, b, `subworkflow step '${id}' input key '${k}'`);
+          return out;
+        }
+      };
     }
     case "agent": {
-      if (!ctx.agents) throw new Error(`step '${step.id}': AgentStep requires a host agents implementation`);
-      if (!isCacheEnabled(ctx, step)) return execAgentStep(step, ctx, b);
-      const resolved = {
-        prompt: step.prompt(b),
-        adapter: step.adapter ? resolveSel(step.adapter, b) : void 0,
-        sessionRef: step.sessionRef
-      };
-      const c = await readStepCache(ctx, step, resolved);
-      if (c.hit) return c.output;
-      const out = await execAgentStep(step, ctx, b);
-      await ctx.cache.set(c.key, { output: out, resolvedInputHash: c.hash });
-      return out;
+      if (typeof step.prompt === "function") {
+        const passthrough = step;
+        return passthrough;
+      }
+      return compileAgentStep(step, id, ctx);
+    }
+    case "gate":
+      return compileGateStep(step, id);
+    case "transform": {
+      const passthrough = step;
+      return passthrough;
     }
+    case "branch":
+      throw new WorkflowCompileError(
+        `internal: branch step '${id}' reached compileStep directly \u2014 branch steps must be compiled via the sibling-list walker`
+      );
+    default:
+      throw new WorkflowCompileError(
+        `unsupported step kind '${step.kind}' (step '${id}')`
+      );
   }
 }
-async function runWorkflowInner(workflow, input, hooks, maxTotalCostUsd) {
-  const state = { input, steps: {}, costBySession: /* @__PURE__ */ new Map(), maxTotalCostUsd };
-  const ctx = { state, ...hooks };
-  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;
+
+// src/ref-string.ts
+function resolveRefString(stepId, field, value, b, onUnmatched = "passthrough") {
+  if (value.startsWith("$$")) return value.slice(1);
+  let hit;
+  try {
+    hit = resolveRefPrefixed(value, b);
+  } catch (err) {
+    throw new Error(
+      `step '${stepId}': ${field} '${value}' is not a valid reference \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
   }
-  const bindings = view(state);
-  const output = workflow.output ? workflow.output(bindings) : lastId !== void 0 ? state.steps[lastId] : void 0;
-  return { output, bindings };
+  if (!hit) {
+    if (onUnmatched === "error" && value.startsWith("$")) {
+      throw new Error(
+        `step '${stepId}': ${field} '${value}' is not a valid reference \u2014 a leading '$' must open a $input/$item/$steps.<id>/$index reference ('$$' escapes a literal '$')`
+      );
+    }
+    return value;
+  }
+  const token = value.slice(0, value.length - hit.rest.length);
+  if (hit.resolved === void 0) {
+    throw new Error(
+      `step '${stepId}': ${field} '${token}' resolves to nothing \u2014 the referenced field does not exist`
+    );
+  }
+  return String(hit.resolved) + hit.rest;
 }
-async function runWorkflow(args) {
-  return runWorkflowInner(args.workflow, args.input, {
-    approve: args.approve,
-    resume: args.resume,
-    signal: args.signal,
-    agents: args.agents,
-    cwd: args.cwd,
-    workspaceSlug: args.workspaceSlug,
-    cache: args.cache,
-    cacheKey: args.cacheKey,
-    onStepStart: args.onStepStart,
-    onStepComplete: args.onStepComplete
-  }, args.maxTotalCostUsd);
+var NodeFsPort = class {
+  root;
+  constructor(root) {
+    this.root = root;
+  }
+  resolve(p) {
+    const normalized = p.replace(/^\/+/, "");
+    if (normalized.startsWith("..")) {
+      throw new Error(`NodeFsPort: path "${p}" escapes the workspace root "${this.root}"`);
+    }
+    return join(this.root, normalized);
+  }
+  async exists(p) {
+    try {
+      await stat(this.resolve(p));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async readFile(p) {
+    return readFile(this.resolve(p), "utf8");
+  }
+  async writeFile(p, content) {
+    const target = this.resolve(p);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, content, "utf8");
+  }
+  async appendFile(p, content) {
+    const target = this.resolve(p);
+    await mkdir(dirname(target), { recursive: true });
+    await appendFile(target, content, "utf8");
+  }
+  async readdir(p) {
+    return readdir(this.resolve(p));
+  }
+  async walk(p) {
+    const out = [];
+    const visit = async (dir) => {
+      let entries = [];
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const ent of entries) {
+        if (ent.name.startsWith(".")) continue;
+        const full = join(dir, ent.name);
+        if (ent.isDirectory()) {
+          await visit(full);
+        } else if (ent.isFile()) {
+          out.push(full);
+        }
+      }
+    };
+    await visit(this.resolve(p));
+    const prefix = this.resolve(p);
+    return out.map((f2) => f2.slice(prefix.length).replace(/^\//, ""));
+  }
+  async stat(p) {
+    try {
+      const s = await stat(this.resolve(p));
+      return {
+        kind: s.isDirectory() ? "directory" : "file",
+        ...s.isFile() ? { bytes: s.size } : {},
+        modifiedAt: s.mtime
+      };
+    } catch {
+      return null;
+    }
+  }
+  async lock() {
+    return { release: async () => {
+    } };
+  }
+};
+
+// src/knowledge.ts
+var DEFAULT_MAX_ENTRIES = 50;
+function resolveStringArray(stepId, index, field, values, b) {
+  if (values === void 0) return void 0;
+  return values.map(
+    (v) => resolveRefString(stepId, `harness.knowledge[${index}].${field}`, v, b)
+  );
+}
+function resolveKnowledgeSelectors(stepId, selectors, b) {
+  return selectors.map((sel, index) => {
+    const deferred = sel.deferred === true;
+    const workspace = deferred ? resolveRefString(stepId, `harness.knowledge[${index}].workspace`, sel.workspace, b) : sel.workspace;
+    return {
+      ...sel,
+      deferred: void 0,
+      workspace,
+      ...sel.anyOf !== void 0 ? { anyOf: deferred ? resolveStringArray(stepId, index, "anyOf", sel.anyOf, b) : [...sel.anyOf] } : {},
+      ...sel.allOf !== void 0 ? { allOf: deferred ? resolveStringArray(stepId, index, "allOf", sel.allOf, b) : [...sel.allOf] } : {},
+      ...sel.kinds !== void 0 ? { kinds: deferred ? resolveStringArray(stepId, index, "kinds", sel.kinds, b) : [...sel.kinds] } : {}
+    };
+  });
+}
+function workspaceDirName(workspace) {
+  const trimmed = workspace.replace(/\/+$/, "");
+  return basename(trimmed) || trimmed;
 }
+function safeSlug(slug) {
+  return slug.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+async function materializeKnowledge(stepId, selectors, stepCwd) {
+  const knowledgeDir = join(stepCwd, ".knowledge");
+  const records = [];
+  const warnings = [];
+  const indexSections = [];
+  let written = 0;
+  for (const [i, sel] of selectors.entries()) {
+    if (sel.mode !== void 0 && sel.mode !== "files") {
+      throw new Error(
+        `step '${stepId}': harness.knowledge[${i}].mode must be "files" (v1 supports no other mode)`
+      );
+    }
+    const workspace = sel.workspace;
+    if (typeof workspace !== "string" || workspace.length === 0) {
+      throw new Error(
+        `step '${stepId}': harness.knowledge[${i}] needs a non-empty 'workspace'`
+      );
+    }
+    if (!isAbsolute(workspace)) {
+      throw new Error(
+        `step '${stepId}': harness.knowledge[${i}].workspace '${workspace}' must be absolute by run time \u2014 the loader resolves relative paths; did you bypass loadWorkflowHandle?`
+      );
+    }
+    const fs = new NodeFsPort(workspace);
+    const rootStat = await fs.stat(".");
+    if (rootStat === null || rootStat.kind !== "directory") {
+      const warning = `knowledge-workspace-missing: harness.knowledge[${i}] (workspace '${workspace}') does not name an existing directory`;
+      warnings.push(warning);
+      records.push({ workspace, matched: 0, written: 0 });
+      continue;
+    }
+    const kinds = (sel.kinds ?? []).filter((k) => isRefinedKind(k));
+    const resolved = filterEntriesByAllOf(
+      await resolveKnowledge({
+        fs,
+        query: {
+          ...sel.anyOf && sel.anyOf.length > 0 ? { tags: [...sel.anyOf] } : {},
+          ...kinds.length > 0 ? { kinds } : {}
+        }
+      }),
+      sel.allOf
+    );
+    const sorted = [...resolved].sort((a, b) => a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0);
+    const cap = sel.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const picked = sorted.slice(0, cap);
+    const dirName = workspaceDirName(workspace);
+    const lines = [];
+    for (const entry of picked) {
+      const rel = join(dirName, `${safeSlug(entry.slug)}.md`);
+      const raw = await fs.readFile(entry.path);
+      await mkdir(join(knowledgeDir, dirName), { recursive: true });
+      await writeFile(join(knowledgeDir, rel), raw, "utf8");
+      lines.push(
+        `- [${entry.title || entry.slug}](${rel.split("\\").join("/")}) \u2014 ${entry.kind}, ${entry.tags.join(", ")}`
+      );
+    }
+    written += picked.length;
+    if (lines.length > 0) {
+      indexSections.push(`## ${dirName}
 
-// src/build-agent-step.ts
-function buildAgentStep(id, fields) {
-  const prompt = fields.prompt;
-  return {
-    kind: "agent",
-    id,
-    ...fields.adapter !== void 0 ? { adapter: fields.adapter } : {},
-    ...fields.sessionRef !== void 0 ? { sessionRef: fields.sessionRef } : {},
-    ...fields.sandbox !== void 0 ? { sandbox: fields.sandbox } : {},
-    ...fields.cacheable ? { cacheable: true } : {},
-    ...fields.options !== void 0 ? { options: fields.options } : {},
-    prompt: typeof prompt === "function" ? prompt : ((_b) => prompt),
-    policy: fields.policy ?? { awaiting: "fail" },
-    ...fields.outputSchema !== void 0 ? { outputSchema: fields.outputSchema } : {},
-    ...fields.maxRetries !== void 0 ? { maxRetries: fields.maxRetries } : {}
-  };
+${lines.join("\n")}`);
+    }
+    records.push({ workspace, matched: resolved.length, written: picked.length });
+    if (resolved.length === 0) {
+      warnings.push(
+        `knowledge-empty: harness.knowledge[${i}] (workspace '${workspace}') matched 0 entries`
+      );
+    }
+  }
+  const index = "# Knowledge index\n\n" + (indexSections.length > 0 ? indexSections.join("\n\n") : "_No entries matched._") + "\n";
+  await mkdir(knowledgeDir, { recursive: true });
+  await writeFile(join(knowledgeDir, "INDEX.md"), index, "utf8");
+  return { records, written, warnings };
 }
 
-// src/compile-workflow.ts
-var WorkflowCompileError = class extends Error {
-  constructor(message) {
-    super(`compileWorkflow: ${message}`);
-    this.name = "WorkflowCompileError";
+// src/run-workflow.ts
+var WorkflowSuspendedError = class extends Error {
+  constructor(stepId, on) {
+    super(
+      `workflow suspended at step '${stepId}' awaiting [${on.join(", ")}] \u2014 no resume hook supplied`
+    );
+    this.stepId = stepId;
+    this.on = on;
+    this.name = "WorkflowSuspendedError";
   }
+  stepId;
+  on;
 };
-var get = (m, key) => m instanceof Map ? m.get(key) : m[key];
-function dig(value, path) {
-  let v = value;
-  for (const seg of path) {
-    if (v == null) return void 0;
-    v = v[seg];
-  }
-  return v;
+function view(state, item, index) {
+  return { input: state.input, steps: state.steps, item, index };
 }
-function resolveRef(ref, b) {
-  if (ref === "$index") return b.index;
-  const m = ref.match(/^\$(input|item|steps)((?:\.[^.]+)*)$/);
-  if (!m) throw new WorkflowCompileError(`bad reference '${ref}'`);
-  const segs = m[2] ? m[2].slice(1).split(".") : [];
-  switch (m[1]) {
-    case "input":
-      return dig(b.input, segs);
-    case "item":
-      return dig(b.item, segs);
-    case "steps": {
-      const [stepId, ...rest] = segs;
-      if (!stepId) throw new WorkflowCompileError(`'$steps' needs a step id`);
-      return dig(b.steps[stepId], rest);
-    }
-  }
+function resolveSel(sel, b) {
+  return typeof sel === "function" ? sel(b) : sel;
 }
-function resolveValue(node, b) {
-  if (typeof node === "string") {
-    if (node.startsWith("$$")) return node.slice(1);
-    if (node.startsWith("$")) return resolveRef(node, b);
-    return node;
-  }
-  if (Array.isArray(node)) return node.map((n) => resolveValue(n, b));
-  if (node && typeof node === "object") {
-    const out = {};
-    for (const [k, v] of Object.entries(node))
-      out[k] = resolveValue(v, b);
-    return out;
-  }
-  return node;
+function extractJsonCandidate(raw) {
+  const jsonFence = /```json\s*([\s\S]*?)```/g;
+  const lastJson = lastMatch(jsonFence, raw);
+  if (lastJson !== void 0) return lastJson;
+  const anyFence = /```\s*([\s\S]*?)```/g;
+  const lastAny = lastMatch(anyFence, raw);
+  if (lastAny !== void 0) return lastAny;
+  return raw.trim();
+}
+function lastMatch(re, s) {
+  let m;
+  let last = null;
+  while ((m = re.exec(s)) !== null) last = m;
+  return last ? last[1]?.trim() : void 0;
+}
+function spentUsd(state) {
+  let total = 0;
+  for (const c of state.costBySession.values()) total += c;
+  return total;
 }
-var COMPARATORS = {
-  "<": (a, c) => a < c,
-  "<=": (a, c) => a <= c,
-  ">": (a, c) => a > c,
-  ">=": (a, c) => a >= c
-};
-function literal(token, b) {
-  if (token.startsWith("$")) return resolveRef(token, b);
-  if (token === "true") return true;
-  if (token === "false") return false;
-  if (token === "null") return null;
-  if (/^-?\d+(\.\d+)?$/.test(token)) return Number(token);
-  return token.replace(/^['"]|['"]$/g, "");
+function hashResolvedInputs(kind, resolved) {
+  return createHash("sha256").update(`${kind}\0${JSON.stringify(resolved) ?? "undefined"}`).digest("hex");
 }
-function evalPredicate(expr, b) {
-  const m = expr.match(/^(.+?)\s*(==|!=|<=|>=|<|>)\s*(.+)$/);
-  if (!m) return Boolean(literal(expr.trim(), b));
-  const left = literal(m[1].trim(), b);
-  const right = literal(m[3].trim(), b);
-  switch (m[2]) {
-    case "==":
-      return left === right;
-    case "!=":
-      return left !== right;
-    default: {
-      const cmp = COMPARATORS[m[2]];
-      return cmp(Number(left), Number(right));
-    }
+function stepJournalKey(cacheKey, step) {
+  return `${cacheKey}\0${step.id}\0${step.kind}`;
+}
+function isCacheEnabled(ctx, step) {
+  return step.cacheable === true && ctx.cache !== void 0 && ctx.cacheKey !== void 0;
+}
+async function readStepCache(ctx, step, resolvedInputs) {
+  const key = stepJournalKey(ctx.cacheKey, step);
+  const hash = hashResolvedInputs(step.kind, resolvedInputs);
+  const entry = await ctx.cache.get(key);
+  if (entry !== void 0 && entry.resolvedInputHash === hash) {
+    return { hit: true, output: entry.output };
   }
+  return { hit: false, key, hash };
 }
-function normalizeToolId(ref) {
-  let s = ref.trim();
-  if (s.endsWith("/TOOL.md")) s = s.slice(0, -"/TOOL.md".length);
-  const slash = s.lastIndexOf("/");
-  return slash === -1 ? s : s.slice(slash + 1);
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
 }
-var f = (step, key) => step[key];
-function assertLinear(steps) {
-  steps.forEach((s, i) => {
-    const next = s.next;
-    const followingId = steps[i + 1]?.id;
-    if (next && next !== followingId) {
-      throw new WorkflowCompileError(
-        `step '${s.id}' has a non-linear next='${next}' \u2014 the structured-subset compiler only runs steps in document order. Hand-author a BranchStep or nest structurally.`
-      );
-    }
-  });
+function formatZodError(err) {
+  return err.issues.map((i) => `${i.path.length > 0 ? i.path.join(".") + ": " : ""}${i.message}`).join(", ");
 }
-function collectStepIds(steps, ids = /* @__PURE__ */ new Set()) {
+async function runSequence(steps, ctx, item, index) {
+  let last;
   for (const s of steps) {
-    if (typeof s?.id === "string") ids.add(s.id);
-    if (Array.isArray(s?.steps)) collectStepIds(s.steps, ids);
-    if (Array.isArray(s?.branches)) {
-      for (const br of s.branches) {
-        if (Array.isArray(br?.steps)) collectStepIds(br.steps, ids);
-      }
-    }
+    const out = await execStep(s, ctx, item, index);
+    ctx.state.steps[s.id] = out;
+    ctx.onStepComplete?.(s.id, out);
+    last = out;
   }
-  return ids;
+  return last;
 }
-function assertKnownStepRefs(node, knownStepIds, label) {
-  if (typeof node === "string") {
-    if (node.startsWith("$$")) return;
-    const m = node.match(/^\$steps\.([^.]+)/);
-    if (m && !knownStepIds.has(m[1])) {
-      throw new WorkflowCompileError(
-        `${label} references unknown step '${m[1]}' via '${node}' \u2014 no step with that id exists in this workflow`
+async function execAgentStep(step, ctx, b) {
+  ctx.onStepStart?.(step.id);
+  if (step.adapter && ctx.state.maxTotalCostUsd !== void 0 && spentUsd(ctx.state) >= ctx.state.maxTotalCostUsd) {
+    throw new Error(
+      `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);
+  let knowledgeOut;
+  let knowledgeWarnings = [];
+  if (step.harness?.knowledge && step.harness.knowledge.length > 0) {
+    if (cwd === void 0) {
+      throw new Error(
+        `step '${step.id}': harness.knowledge requires a resolvable working directory (set step cwd, harness.cwd, or the run cwd)`
       );
     }
-    return;
+    const knowledgeSelectors = resolveKnowledgeSelectors(step.id, step.harness.knowledge, b).map(
+      (sel) => ({
+        ...sel,
+        workspace: isAbsolute(sel.workspace) ? sel.workspace : join(cwd, sel.workspace)
+      })
+    );
+    const materialized = await materializeKnowledge(step.id, knowledgeSelectors, cwd);
+    knowledgeOut = materialized.records;
+    knowledgeWarnings = materialized.warnings;
+    if (materialized.written > 0) {
+      const note = `Knowledge for this step is materialized under .knowledge/ (see .knowledge/INDEX.md, ${materialized.written} entries).`;
+      const inner = step.prompt;
+      step = { ...step, prompt: (b2) => `${note}
+
+${inner(b2)}` };
+    }
   }
-  if (Array.isArray(node)) {
-    node.forEach((n) => assertKnownStepRefs(n, knownStepIds, label));
-    return;
+  const sandbox = typeof step.sandbox === "function" ? step.sandbox(b) : step.sandbox;
+  const model = step.model !== void 0 ? resolveSel(step.model, b) : void 0;
+  const harness = step.harness !== void 0 || model !== void 0 ? {
+    ...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);
+  if (!sessionId) throw new Error(`step '${step.id}': no session (adapter and sessionRef both unresolved)`);
+  if (knowledgeWarnings.length > 0 && ctx.agents.emitHarnessWarning) {
+    ctx.agents.emitHarnessWarning({
+      sessionId,
+      warnings: knowledgeWarnings,
+      label: step.id
+    });
   }
-  if (node && typeof node === "object") {
-    for (const v of Object.values(node)) assertKnownStepRefs(v, knownStepIds, label);
+  const harnessOut = harness !== void 0 ? {
+    ...harness,
+    ...harness.tools && harness.tools.length > 0 ? { toolsApplied: false } : {}
+  } : void 0;
+  await ctx.agents.sendPromptAndWait(sessionId, step.prompt(b));
+  if (step.policy && ctx.agents.onAwaitingInput) {
+    await ctx.agents.onAwaitingInput(sessionId, step.policy);
   }
-}
-function compileWorkflow(handle, opts) {
-  const steps = handle.steps;
-  if (handle.start && handle.start !== steps[0]?.id) {
-    throw new WorkflowCompileError(
-      `start='${handle.start}' is not the first step \u2014 structured-subset runs in order`
-    );
+  if (ctx.agents.readCostUsd) {
+    ctx.state.costBySession.set(sessionId, await ctx.agents.readCostUsd(sessionId));
   }
-  const ctx = { opts, knownStepIds: collectStepIds(steps) };
-  const result = handle.result;
-  const output = result !== void 0 ? (b) => resolveValue(result, b) : void 0;
-  return {
-    id: handle.id,
-    description: handle.description,
-    steps: compileSiblingsToSteps(steps, ctx),
-    ...output ? { output } : {}
-  };
-}
-function compileSiblingsToSteps(steps, ctx) {
-  assertLinear(steps);
-  const out = [];
-  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 (!step.outputSchema) {
+    let text;
+    if (ctx.agents.readFinalMessage) {
+      try {
+        text = await ctx.agents.readFinalMessage(sessionId);
+      } catch {
+      }
     }
-    out.push(compileStep(s, ctx));
+    return { sessionId, ...text !== void 0 ? { text } : {}, ...harnessOut ? { harness: harnessOut } : {}, ...knowledgeOut ? { knowledgeApplied: knowledgeOut } : {} };
   }
-  return out;
-}
-function compileStepList(steps, id, ctx) {
-  const compiled = compileSiblingsToSteps(steps, ctx);
-  if (compiled.length === 1) return compiled[0];
-  return { kind: "group", id, steps: compiled };
-}
-function compileBranchChain(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.`
+  if (!ctx.agents.readFinalMessage) {
+    throw new Error(`step '${step.id}': outputSchema requires a host with readFinalMessage`);
+  }
+  const maxRetries = step.maxRetries ?? 2;
+  let lastErr = "";
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const raw = await ctx.agents.readFinalMessage(sessionId);
+    const candidate = extractJsonCandidate(raw);
+    let value;
+    try {
+      value = JSON.parse(candidate);
+    } catch {
+      lastErr = "not valid JSON";
+      if (attempt < maxRetries) {
+        await ctx.agents.sendPromptAndWait(
+          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.`
+        );
+      }
+      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);
+    if (attempt < maxRetries) {
+      await ctx.agents.sendPromptAndWait(
+        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.`
       );
     }
-    return idx;
-  };
-  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--) {
-    const br = branches[k];
-    const targetIdx = resolveTarget(br.next, `branches[${k}].next`);
-    const thenSteps = compileSiblingsToSteps(steps.slice(targetIdx), ctx);
-    const condExpr = br.when;
-    const nodeId = k === 0 ? branchStep.id : `${branchStep.id}__branch${k}`;
-    otherwise = [
-      {
-        kind: "branch",
-        id: nodeId,
-        cond: (b) => evalPredicate(condExpr, b),
-        then: thenSteps,
-        ...otherwise.length > 0 ? { otherwise } : {}
-      }
-    ];
   }
-  return otherwise[0];
+  throw new Error(`step '${step.id}': output_invalid \u2014 final message never matched outputSchema (${lastErr})`);
 }
-function compileAgentStep(step, id, ctx) {
-  const opts = ctx.opts;
-  const prompt = f(step, "prompt");
-  if (typeof prompt !== "string" || prompt.length === 0) {
-    throw new WorkflowCompileError(`agent step '${id}' needs a non-empty 'prompt'`);
+function tryParseJson(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return void 0;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return void 0;
   }
-  let adapter = typeof step.adapter === "string" ? step.adapter : void 0;
-  let options = step.options !== void 0 ? step.options : void 0;
-  const agentRef = step.agent?.ref;
-  if (agentRef !== void 0) {
-    if (typeof agentRef !== "string" || agentRef.trim().length === 0) {
-      throw new WorkflowCompileError(`agent step '${id}' has an empty 'agent.ref'`);
-    }
-    const resolved = opts.agentRefs ? get(opts.agentRefs, agentRef) : void 0;
-    if (!resolved) {
-      const available = opts.agentRefs ? opts.agentRefs instanceof Map ? [...opts.agentRefs.keys()] : Object.keys(opts.agentRefs) : [];
-      throw new WorkflowCompileError(
-        `agent step '${id}' references unknown agent ref '${agentRef}'` + (available.length > 0 ? ` \u2014 available refs: ${available.join(", ")}` : " \u2014 no agent refs are configured for this compile (not running in an app context?)")
+}
+function defaultRunGateCommand(spec) {
+  return new Promise((resolve2) => {
+    execFile(
+      spec.command,
+      [...spec.args],
+      { cwd: spec.cwd, timeout: spec.timeoutMs, maxBuffer: 10 * 1024 * 1024 },
+      (err, stdout, stderr) => {
+        if (!err) {
+          resolve2({ exitCode: 0, stdout, stderr });
+          return;
+        }
+        const nodeErr = err;
+        const timedOut = nodeErr.killed === true && nodeErr.signal !== void 0 && spec.timeoutMs !== void 0;
+        const exitCode = typeof nodeErr.code === "number" ? nodeErr.code : 1;
+        resolve2({ exitCode, stdout, stderr, ...timedOut ? { timedOut: true } : {} });
+      }
+    );
+  });
+}
+async function resolveGateReport(cmd, cwd, reportPath) {
+  const fromStdout = tryParseJson(cmd.stdout);
+  if (fromStdout !== void 0) return fromStdout;
+  if (!reportPath) return void 0;
+  try {
+    const abs = isAbsolute(reportPath) ? reportPath : join(cwd, reportPath);
+    const raw = await readFile(abs, "utf8");
+    return tryParseJson(raw);
+  } catch {
+    return void 0;
+  }
+}
+function resolveGateCwd(step, ctx, b) {
+  const fallback = ctx.cwd ?? process.cwd();
+  if (!step.cwd) return fallback;
+  const resolved = resolveRefString(step.id, "cwd", resolveSel(step.cwd, b), b, "error");
+  return isAbsolute(resolved) ? resolved : resolve(fallback, resolved);
+}
+async function execGateStep(step, ctx, b) {
+  const cwd = resolveGateCwd(step, ctx, b);
+  const args = (step.args ?? []).map(
+    (arg, index) => resolveRefString(step.id, `args[${index}]`, resolveSel(arg, b), b, "error")
+  );
+  const maxAttempts = Math.max(1, step.retry?.maxAttempts ?? 1);
+  let last;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (attempt > 1 && step.onFail?.reprompt) {
+      if (!ctx.agents) {
+        throw new Error(`step '${step.id}': on_fail.reprompt requires a host agents implementation`);
+      }
+      const targetSessionId = ctx.agents.resolveByLabel(step.onFail.reprompt);
+      if (!targetSessionId) {
+        throw new Error(
+          `step '${step.id}': on_fail.reprompt targets unknown step '${step.onFail.reprompt}' \u2014 no session found`
+        );
+      }
+      const reportText = JSON.stringify(last?.report ?? null, null, 2);
+      const extra = step.onFail.with ? `
+
+Additional context:
+${JSON.stringify(step.onFail.with, null, 2)}` : "";
+      await ctx.agents.sendPromptAndWait(
+        targetSessionId,
+        `Gate '${step.id}' failed (exit code ${last?.exitCode}). Report:
+${reportText}${extra}
+
+Please address the findings above, then reply when done.`
       );
     }
-    adapter = resolved.adapter;
-    options = resolved.options;
+    if (attempt > 1 && step.retry?.initialMs) {
+      const delayMs = step.retry.backoff === "exponential" ? step.retry.initialMs * 2 ** (attempt - 2) : step.retry.initialMs;
+      await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+    }
+    const cmdResult = await (ctx.runGateCommand ?? defaultRunGateCommand)({
+      command: step.command,
+      args,
+      cwd,
+      timeoutMs: step.timeoutMs
+    });
+    const report = await resolveGateReport(cmdResult, cwd, step.reportPath);
+    const ok = cmdResult.exitCode === 0;
+    last = { ok, exitCode: cmdResult.exitCode, report };
+    ctx.onGateReport?.({ stepId: step.id, ok, exitCode: cmdResult.exitCode, report, attempt });
+    if (ok) break;
+  }
+  if (!last.ok) {
+    const err = new Error(
+      `step '${step.id}': gate failed after ${maxAttempts} attempt(s) \u2014 exit code ${last.exitCode}`
+    );
+    err.exitCode = last.exitCode;
+    err.report = last.report;
+    throw err;
+  }
+  return last;
+}
+async function execStep(step, ctx, item, index) {
+  const { state, signal } = ctx;
+  const b = view(state, item, index);
+  if (step.kind !== "agent") {
+    ctx.onStepStart?.(step.id);
   }
-  return buildAgentStep(id, {
-    prompt: (b) => String(resolveValue(prompt, b)),
-    ...adapter !== void 0 ? { adapter } : {},
-    ...step.sessionRef !== void 0 ? { sessionRef: step.sessionRef } : {},
-    ...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 } : {},
-    ...step.maxRetries !== void 0 ? { maxRetries: step.maxRetries } : {}
-  });
-}
-function compileStep(step, ctx) {
-  const opts = ctx.opts;
-  const id = step.id;
   switch (step.kind) {
     case "tool": {
-      const ref = typeof step.tool === "string" ? step.tool : step.tool.entry;
-      const toolId = normalizeToolId(ref);
-      const tool = get(opts.tools, toolId);
-      if (!tool)
-        throw new WorkflowCompileError(`no tool registered for '${toolId}'`);
-      const inputs = f(step, "inputs") ?? {};
-      assertKnownStepRefs(inputs, ctx.knownStepIds, `tool step '${id}' inputs`);
-      return {
-        kind: "tool",
-        id,
-        tool,
-        candidates: opts.candidates,
-        input: (b) => resolveValue(inputs, b),
-        context: opts.contextFor ? (b) => opts.contextFor(toolId, b) : void 0
-      };
+      const input = step.input(b);
+      const runIt = () => runTool({
+        tool: step.tool,
+        candidates: step.candidates,
+        input,
+        context: step.context ? step.context(b) : void 0,
+        resolverContext: step.resolverContext,
+        secrets: step.secrets,
+        signal
+      });
+      if (!isCacheEnabled(ctx, step)) return runIt();
+      const c = await readStepCache(ctx, step, input);
+      if (c.hit) return c.output;
+      const out = await runIt();
+      await ctx.cache.set(c.key, { output: out, resolvedInputHash: c.hash });
+      return out;
     }
+    case "transform":
+      return step.compute(b);
     case "map": {
-      const over = f(step, "over");
-      const inner = compileStepList(f(step, "steps"), `${id}__body`, ctx);
-      const onError = f(step, "onError");
+      const arr = [...step.over(b)];
+      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;
+        }
+        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 {
-        kind: "map",
-        id,
-        parallelism: f(step, "parallelism"),
-        over: (b) => resolveRef(over, b),
-        body: () => inner,
-        ...onError !== void 0 ? { onError } : {}
+        results: outcomes,
+        succeeded: outcomes.filter((r) => r.status === "fulfilled").length,
+        failed: outcomes.filter((r) => r.status === "rejected").length
       };
     }
-    case "loop": {
-      const whileExpr = f(step, "while");
+    case "pipeline": {
+      const items = [...step.over(b)];
+      const tolerant = step.onError === "collect";
+      if (items.length === 0) return tolerant ? { results: [], succeeded: 0, failed: 0 } : [];
+      const cap = Math.max(1, step.concurrency ?? items.length);
+      const results = new Array(items.length);
+      let next = 0;
+      const runItem = async (idx) => {
+        let prev = void 0;
+        try {
+          for (const stage of step.stages) {
+            prev = await execStep(stage(items[idx], idx, prev, view(state, items[idx], idx)), ctx, items[idx], idx);
+          }
+          results[idx] = tolerant ? { status: "fulfilled", index: idx, value: prev } : prev;
+        } catch (err) {
+          if (!tolerant) throw err;
+          results[idx] = { status: "rejected", index: idx, item: items[idx], error: errorMessage(err) };
+        }
+      };
+      const worker = async () => {
+        while (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 {
-        kind: "loop",
-        id,
-        maxIterations: f(step, "max_iterations"),
-        while: (b) => evalPredicate(whileExpr, b),
-        body: [compileStepList(f(step, "steps"), `${id}__body`, ctx)]
+        results: outcomes,
+        succeeded: outcomes.filter((r) => r.status === "fulfilled").length,
+        failed: outcomes.filter((r) => r.status === "rejected").length
       };
     }
+    case "branch": {
+      const chosen = step.cond(b) ? step.then : step.otherwise ?? [];
+      return runSequence(chosen, ctx, item, index);
+    }
+    case "loop": {
+      let iterations = 0;
+      let last;
+      while (iterations < step.maxIterations && step.while(view(state, item, index))) {
+        last = await runSequence(step.body, ctx, item, index);
+        iterations++;
+      }
+      return last;
+    }
     case "parallel": {
-      const branches = f(step, "branches");
-      return {
-        kind: "parallel",
-        id,
-        branches: branches.map((br) => ({
-          id: br.id,
-          steps: [compileStepList(br.steps, `${id}__${br.id}`, ctx)]
-        }))
-      };
+      const outs = await Promise.all(
+        step.branches.map(
+          (br) => runSequence(br.steps, ctx, item, index).then((last) => ({
+            id: br.id,
+            last
+          }))
+        )
+      );
+      const record = {};
+      for (const { id, last } of outs) record[id] = last;
+      return record;
     }
     case "approval": {
-      const prompt = f(step, "prompt");
-      const approvers = (f(step, "approvers") ?? []).map(
-        (a) => a.role ?? a.userId ?? String(a)
-      );
-      return {
-        kind: "approval",
-        id,
+      const prompt = step.prompt(b);
+      const approvers = step.approvers ?? [];
+      const raw = ctx.approve ? await ctx.approve({
+        stepId: step.id,
+        prompt,
         approvers,
-        prompt: (b) => String(resolveValue(prompt, b))
-      };
+        ...step.artifacts !== void 0 ? { artifacts: step.artifacts } : {},
+        ...step.timeoutMs !== void 0 ? { timeoutMs: step.timeoutMs } : {}
+      }) : true;
+      const decision = typeof raw === "boolean" ? { approved: raw, who: "host" } : raw;
+      const approved = decision.approved;
+      const followups = approved ? step.onApprove ?? [] : step.onReject ?? [];
+      await runSequence(followups, ctx, item, index);
+      return { approved, who: decision.who, ...decision.note !== void 0 ? { note: decision.note } : {} };
     }
     case "suspend": {
-      const resume = f(step, "resume");
-      return { kind: "suspend", id, on: resume.on, timeoutMs: resume.timeout_ms };
+      if (!ctx.resume) throw new WorkflowSuspendedError(step.id, step.on);
+      return ctx.resume({ stepId: step.id, on: step.on });
     }
+    case "group":
+      return runSequence(step.steps, ctx, item, index);
     case "subworkflow": {
-      const wfId = f(step, "workflow");
-      const child = opts.workflows ? get(opts.workflows, wfId) : void 0;
-      if (!child)
-        throw new WorkflowCompileError(
-          `subworkflow '${wfId}' not found \u2014 pass it in opts.workflows`
-        );
-      const compiledChild = compileWorkflow(child, opts);
-      const inputs = f(step, "inputs");
-      if (inputs === void 0) {
-        return { kind: "subworkflow", id, workflow: compiledChild };
-      }
-      assertKnownStepRefs(inputs, ctx.knownStepIds, `subworkflow step '${id}' inputs`);
-      return {
-        kind: "subworkflow",
-        id,
-        workflow: compiledChild,
-        input: (b) => resolveValue(inputs, b)
-      };
+      const childInput = step.input ? step.input(b) : state.input;
+      const child = await runWorkflowInner(step.workflow, childInput, {
+        approve: ctx.approve,
+        resume: ctx.resume,
+        signal,
+        agents: ctx.agents,
+        cwd: ctx.cwd,
+        workspaceSlug: ctx.workspaceSlug,
+        cache: ctx.cache,
+        cacheKey: ctx.cacheKey,
+        runGateCommand: ctx.runGateCommand,
+        onGateReport: ctx.onGateReport
+      });
+      return child.output;
     }
     case "agent": {
-      if (typeof step.prompt === "function") {
-        const passthrough = step;
-        return passthrough;
-      }
-      return compileAgentStep(step, id, ctx);
-    }
-    case "transform": {
-      const passthrough = step;
-      return passthrough;
+      if (!ctx.agents) throw new Error(`step '${step.id}': AgentStep requires a host agents implementation`);
+      if (!isCacheEnabled(ctx, step)) return execAgentStep(step, ctx, b);
+      const resolved = {
+        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
+      };
+      const c = await readStepCache(ctx, step, resolved);
+      if (c.hit) return c.output;
+      const out = await execAgentStep(step, ctx, b);
+      await ctx.cache.set(c.key, { output: out, resolvedInputHash: c.hash });
+      return out;
     }
-    case "branch":
-      throw new WorkflowCompileError(
-        `internal: branch step '${id}' reached compileStep directly \u2014 branch steps must be compiled via the sibling-list walker`
-      );
-    default:
-      throw new WorkflowCompileError(
-        `unsupported step kind '${step.kind}' (step '${id}')`
-      );
+    case "gate":
+      return execGateStep(step, ctx, b);
+  }
+}
+async function runWorkflowInner(workflow, input, hooks, maxTotalCostUsd) {
+  const state = { input, steps: {}, costBySession: /* @__PURE__ */ new Map(), maxTotalCostUsd };
+  const ctx = { state, ...hooks };
+  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;
   }
+  const bindings = view(state);
+  const output = workflow.output ? workflow.output(bindings) : lastId !== void 0 ? state.steps[lastId] : void 0;
+  return { output, bindings };
+}
+async function runWorkflow(args) {
+  return runWorkflowInner(args.workflow, args.input, {
+    approve: args.approve,
+    resume: args.resume,
+    signal: args.signal,
+    agents: args.agents,
+    cwd: args.cwd,
+    workspaceSlug: args.workspaceSlug,
+    cache: args.cache,
+    cacheKey: args.cacheKey,
+    onStepStart: args.onStepStart,
+    onStepComplete: args.onStepComplete,
+    runGateCommand: args.runGateCommand,
+    onGateReport: args.onGateReport
+  }, args.maxTotalCostUsd);
 }
 function compileWorkflowManifest(source, opts) {
   const manifest = parseWorkflowManifest(source);
@@ -710,6 +1173,6 @@ function compileWorkflowManifest(source, opts) {
   return compileWorkflow(handle, opts);
 }
 
-export { WorkflowCompileError, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, resolveRef, resolveValue, runWorkflow };
+export { NodeFsPort, WorkflowCompileError, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, materializeKnowledge, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map