@agentproto/workflow-runtime 0.8.1 → 0.10.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,6 +12,663 @@ import { parseWorkflowManifest, workflowFromManifest } from '@agentproto/workflo
  * AIP-15 step-walker over @agentproto/driver runTool.
  */
 
+
+// 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 } : {},
+    ...fields.harness !== void 0 ? { harness: fields.harness } : {}
+  };
+}
+
+// src/compile-workflow.ts
+var WorkflowCompileError = class extends Error {
+  constructor(message) {
+    super(`compileWorkflow: ${message}`);
+    this.name = "WorkflowCompileError";
+  }
+};
+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;
+}
+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 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 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 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 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;
+}
+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 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 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);
+}
+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 collectStepIds(steps, ids = /* @__PURE__ */ new Set()) {
+  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);
+      }
+    }
+  }
+  return ids;
+}
+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 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));
+  }
+  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 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];
+}
+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'`);
+  }
+  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?)")
+      );
+    }
+    adapter = resolved.adapter;
+    options = resolved.options;
+  }
+  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 } : {},
+    ...step.harness !== void 0 ? { harness: step.harness } : {}
+  });
+}
+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 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)
+      });
+      return {
+        kind: "tool",
+        id,
+        tool,
+        candidates: opts.candidates,
+        input: (b) => resolveValue(inputs, b),
+        context: opts.contextFor ? (b) => opts.contextFor(toolId, b) : void 0
+      };
+    }
+    case "map": {
+      const over = f(step, "over");
+      const inner = compileStepList(f(step, "steps"), `${id}__body`, ctx);
+      const onError = f(step, "onError");
+      return {
+        kind: "map",
+        id,
+        parallelism: f(step, "parallelism"),
+        over: (b) => resolveRef(over, b),
+        body: () => inner,
+        ...onError !== void 0 ? { onError } : {}
+      };
+    }
+    case "loop": {
+      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 = 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": {
+      const resume = f(step, "resume");
+      return { kind: "suspend", id, on: resume.on, timeoutMs: resume.timeout_ms };
+    }
+    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`, {
+        makeError: (message) => new WorkflowCompileError(message)
+      });
+      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 (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}')`
+      );
+  }
+}
+
+// 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)}`
+    );
+  }
+  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;
+}
+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}
+
+${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/run-workflow.ts
 var WorkflowSuspendedError = class extends Error {
   constructor(stepId, on) {
     super(
@@ -86,16 +748,53 @@ 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.cwd ? resolveSel(step.cwd, b) : ctx.cwd;
+  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)`
+      );
+    }
+    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)}` };
+    }
+  }
   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 } : {}
+    ...step.options !== void 0 ? { options: step.options } : {},
+    ...step.harness !== void 0 ? { harness: step.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
+    });
+  }
+  const harnessOut = step.harness !== void 0 ? {
+    ...step.harness,
+    ...step.harness.tools && step.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);
@@ -111,7 +810,7 @@ async function execAgentStep(step, ctx, b) {
       } catch {
       }
     }
-    return { sessionId, ...text !== void 0 ? { text } : {} };
+    return { sessionId, ...text !== void 0 ? { text } : {}, ...harnessOut ? { harness: harnessOut } : {}, ...knowledgeOut ? { knowledgeApplied: knowledgeOut } : {} };
   }
   if (!ctx.agents.readFinalMessage) {
     throw new Error(`step '${step.id}': outputSchema requires a host with readFinalMessage`);
@@ -135,7 +834,7 @@ async function execAgentStep(step, ctx, b) {
       continue;
     }
     const res = step.outputSchema.safeParse(value);
-    if (res.success) return { sessionId, output: res.data };
+    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(
@@ -146,6 +845,109 @@ async function execAgentStep(step, ctx, b) {
   }
   throw new Error(`step '${step.id}': output_invalid \u2014 final message never matched outputSchema (${lastErr})`);
 }
+function tryParseJson(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return void 0;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return void 0;
+  }
+}
+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.`
+      );
+    }
+    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);
@@ -274,10 +1076,18 @@ async function execStep(step, ctx, item, index) {
     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 raw = ctx.approve ? await ctx.approve({
+        stepId: step.id,
+        prompt,
+        approvers,
+        ...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 };
+      return { approved, who: decision.who, ...decision.note !== void 0 ? { note: decision.note } : {} };
     }
     case "suspend": {
       if (!ctx.resume) throw new WorkflowSuspendedError(step.id, step.on);
@@ -295,7 +1105,9 @@ async function execStep(step, ctx, item, index) {
         cwd: ctx.cwd,
         workspaceSlug: ctx.workspaceSlug,
         cache: ctx.cache,
-        cacheKey: ctx.cacheKey
+        cacheKey: ctx.cacheKey,
+        runGateCommand: ctx.runGateCommand,
+        onGateReport: ctx.onGateReport
       });
       return child.output;
     }
@@ -313,6 +1125,8 @@ async function execStep(step, ctx, item, index) {
       await ctx.cache.set(c.key, { output: out, resolvedInputHash: c.hash });
       return out;
     }
+    case "gate":
+      return execGateStep(step, ctx, b);
   }
 }
 async function runWorkflowInner(workflow, input, hooks, maxTotalCostUsd) {
@@ -340,286 +1154,17 @@ async function runWorkflow(args) {
     cache: args.cache,
     cacheKey: args.cacheKey,
     onStepStart: args.onStepStart,
-    onStepComplete: args.onStepComplete
+    onStepComplete: args.onStepComplete,
+    runGateCommand: args.runGateCommand,
+    onGateReport: args.onGateReport
   }, args.maxTotalCostUsd);
 }
-
-// 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 } : {}
-  };
-}
-
-// src/compile-workflow.ts
-var WorkflowCompileError = class extends Error {
-  constructor(message) {
-    super(`compileWorkflow: ${message}`);
-    this.name = "WorkflowCompileError";
-  }
-};
-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 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 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;
-}
-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 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 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);
-}
-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 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`
-    );
-  }
-  assertLinear(steps);
-  const result = handle.result;
-  const output = result !== void 0 ? (b) => resolveValue(result, b) : void 0;
-  return {
-    id: handle.id,
-    description: handle.description,
-    steps: steps.map((s) => compileStep(s, opts)),
-    ...output ? { output } : {}
-  };
-}
-function compileStepList(steps, id, opts) {
-  assertLinear(steps);
-  if (steps.length === 1) return compileStep(steps[0], opts);
-  return { kind: "group", id, steps: steps.map((s) => compileStep(s, opts)) };
-}
-function compileAgentStep(step, id, opts) {
-  const prompt = f(step, "prompt");
-  if (typeof prompt !== "string" || prompt.length === 0) {
-    throw new WorkflowCompileError(`agent step '${id}' needs a non-empty 'prompt'`);
-  }
-  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?)")
-      );
-    }
-    adapter = resolved.adapter;
-    options = resolved.options;
-  }
-  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, 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") ?? {};
-      return {
-        kind: "tool",
-        id,
-        tool,
-        candidates: opts.candidates,
-        input: (b) => resolveValue(inputs, b),
-        context: opts.contextFor ? (b) => opts.contextFor(toolId, b) : void 0
-      };
-    }
-    case "map": {
-      const over = f(step, "over");
-      const inner = compileStepList(f(step, "steps"), `${id}__body`, opts);
-      const onError = f(step, "onError");
-      return {
-        kind: "map",
-        id,
-        parallelism: f(step, "parallelism"),
-        over: (b) => resolveRef(over, b),
-        body: () => inner,
-        ...onError !== void 0 ? { onError } : {}
-      };
-    }
-    case "loop": {
-      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`, opts)]
-      };
-    }
-    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}`, opts)]
-        }))
-      };
-    }
-    case "approval": {
-      const prompt = f(step, "prompt");
-      const approvers = (f(step, "approvers") ?? []).map(
-        (a) => a.role ?? a.userId ?? String(a)
-      );
-      return {
-        kind: "approval",
-        id,
-        approvers,
-        prompt: (b) => String(resolveValue(prompt, b))
-      };
-    }
-    case "suspend": {
-      const resume = f(step, "resume");
-      return { kind: "suspend", id, on: resume.on, timeoutMs: resume.timeout_ms };
-    }
-    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);
-      return { kind: "subworkflow", id, workflow: compiledChild };
-    }
-    case "agent": {
-      if (typeof step.prompt === "function") {
-        const passthrough = step;
-        return passthrough;
-      }
-      return compileAgentStep(step, id, opts);
-    }
-    case "transform": {
-      const passthrough = step;
-      return passthrough;
-    }
-    case "branch":
-      throw new WorkflowCompileError(
-        `goto-style 'branch' (step '${id}') is unsupported in the structured subset \u2014 hand-author a structured BranchStep, or nest.`
-      );
-    default:
-      throw new WorkflowCompileError(
-        `unsupported step kind '${step.kind}' (step '${id}')`
-      );
-  }
-}
 function compileWorkflowManifest(source, opts) {
   const manifest = parseWorkflowManifest(source);
   const handle = workflowFromManifest(manifest);
   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