@noetaris/harness 0.3.1 → 0.4.0

package/dist/index.js

@@ -20,6 +20,9 @@ function isRuntimeMarker(value) {
 }
 
 // src/loop/loop-dsl.ts
+function isForkDef(node) {
+  return "branches" in node;
+}
 var InvalidLoopBuilderError = class extends Error {
   constructor() {
     super("argument is not a LoopBuilder instance \u2014 was it created by createLoopBuilder?");
@@ -27,6 +30,9 @@ var InvalidLoopBuilderError = class extends Error {
   }
 };
 var _builderState = /* @__PURE__ */ Symbol("builderState");
+function isForkNodeMutable(node) {
+  return "branches" in node;
+}
 function deepFreeze(obj) {
   Object.freeze(obj);
   for (const value of Object.values(obj)) {
@@ -65,6 +71,32 @@ function createLoopBuilder() {
       }
       return this;
     },
+    fork(name) {
+      const forkNode = { name, branches: [], next: void 0 };
+      state.steps.push(forkNode);
+      if (state.startCalled && state.entryStep === void 0) {
+        state.entryStep = name;
+      }
+      return this;
+    },
+    branch(name, builderFn) {
+      const currentNode = state.steps.at(-1);
+      if (currentNode === void 0 || !isForkNodeMutable(currentNode)) {
+        throw new Error(
+          ".branch() must be called immediately after .fork() or another .branch() on the same fork"
+        );
+      }
+      const branchBuilder = createLoopBuilder();
+      builderFn(branchBuilder);
+      const branchDefinition = extractLoopDefinition(
+        branchBuilder
+      );
+      currentNode.branches.push({ name, definition: branchDefinition });
+      return this;
+    },
+    join(name, options) {
+      return this.step(name, options);
+    },
     on(signal) {
       if (state.steps.length === 0) {
         return {
@@ -72,17 +104,23 @@ function createLoopBuilder() {
           end: () => this
         };
       }
-      const currentStep = state.steps.at(-1);
+      const currentNode = state.steps.at(-1);
+      if (isForkNodeMutable(currentNode)) {
+        throw new Error(
+          ".on() cannot be called on a fork \u2014 a fork has no run/route to emit a signal from"
+        );
+      }
+      const currentStep = currentNode;
       return {
         to: (step) => {
-          currentStep?.transitions.push({
+          currentStep.transitions.push({
             signal,
             target: { kind: "step", name: step }
           });
           return this;
         },
         end: () => {
-          currentStep?.transitions.push({
+          currentStep.transitions.push({
             signal,
             target: { kind: "end" }
           });
@@ -92,9 +130,9 @@ function createLoopBuilder() {
     },
     next(name) {
       if (state.steps.length > 0) {
-        const currentStep = state.steps.at(-1);
-        if (currentStep !== void 0) {
-          currentStep.next = name;
+        const currentNode = state.steps.at(-1);
+        if (currentNode !== void 0) {
+          currentNode.next = name;
         }
       }
       return this;
@@ -112,19 +150,30 @@ function extractLoopDefinition(builder) {
     throw new InvalidLoopBuilderError();
   }
   const state = builder[_builderState];
-  const immutableSteps = state.steps.map((step) => {
-    const transitions = Object.freeze([...step.transitions]);
+  const immutableSteps = state.steps.map((node) => {
+    if (isForkNodeMutable(node)) {
+      const branches = Object.freeze(
+        node.branches.map((b) => Object.freeze({ name: b.name, definition: b.definition }))
+      );
+      const forkDef = {
+        name: node.name,
+        branches,
+        next: node.next
+      };
+      return Object.freeze(forkDef);
+    }
+    const transitions = Object.freeze([...node.transitions]);
     for (const transition of transitions) {
       Object.freeze(transition);
       Object.freeze(transition.target);
     }
     const stepDef = {
-      name: step.name,
-      run: step.run,
-      route: step.route,
+      name: node.name,
+      run: node.run,
+      route: node.route,
       transitions,
-      next: step.next,
-      errorAware: step.errorAware
+      next: node.next,
+      errorAware: node.errorAware
     };
     return Object.freeze(stepDef);
   });
@@ -148,30 +197,85 @@ ${violations.map((v) => `  - ${v}`).join("\n")}`);
   }
 };
 function validateLoop(def) {
+  const violations = collectViolations(def, void 0);
+  const nameLocations = /* @__PURE__ */ new Map();
+  collectNameLocations(def, void 0, nameLocations);
+  for (const [name, locations] of nameLocations) {
+    if (locations.length > 1) {
+      violations.push(
+        `name "${name}" is declared more than once across the nested structure: ${locations.join(", ")}`
+      );
+    }
+  }
+  if (violations.length > 0) {
+    throw new LoopValidationError(violations);
+  }
+}
+function collectViolations(def, pathLabel) {
+  const prefix = pathLabel !== void 0 ? `in branch "${pathLabel}": ` : "";
+  const violations = collectStructuralViolations(def).map((v) => prefix + v);
+  for (const node of def.steps) {
+    if (!isForkDef(node)) continue;
+    if (node.branches.length < 2) {
+      violations.push(
+        `${prefix}fork "${node.name}" must have at least 2 branches (found ${node.branches.length})`
+      );
+    }
+    const seenBranchNames = /* @__PURE__ */ new Set();
+    for (const branch of node.branches) {
+      if (seenBranchNames.has(branch.name)) {
+        violations.push(`${prefix}fork "${node.name}" has duplicate branch name "${branch.name}"`);
+      }
+      seenBranchNames.add(branch.name);
+    }
+    for (const branch of node.branches) {
+      const branchPath = pathLabel !== void 0 ? `${pathLabel}/${node.name}/${branch.name}` : `${node.name}/${branch.name}`;
+      violations.push(...collectViolations(branch.definition, branchPath));
+    }
+  }
+  return violations;
+}
+function collectNameLocations(def, path, acc) {
+  for (const node of def.steps) {
+    const location = path !== void 0 ? `${path}/${node.name}` : node.name;
+    const locations = acc.get(node.name) ?? [];
+    locations.push(location);
+    acc.set(node.name, locations);
+    if (isForkDef(node)) {
+      for (const branch of node.branches) {
+        const branchPath = path !== void 0 ? `${path}/${node.name}/${branch.name}` : `${node.name}/${branch.name}`;
+        collectNameLocations(branch.definition, branchPath, acc);
+      }
+    }
+  }
+}
+function collectStructuralViolations(def) {
   const violations = [];
   const names = new Set(def.steps.map((s) => s.name));
-  for (const step of def.steps) {
+  const stepNodes = def.steps.filter((s) => !isForkDef(s));
+  for (const step of stepNodes) {
     if (step.run === void 0 && step.route === void 0) {
       violations.push(`step "${step.name}" must have at least one of run or route`);
     }
   }
-  for (const step of def.steps) {
+  for (const step of stepNodes) {
     if (step.route !== void 0 && step.transitions.length === 0) {
       violations.push(`step "${step.name}" has route but no .on() transitions \u2014 every signal must be handled`);
     }
   }
-  for (const [i, step] of def.steps.entries()) {
-    if (step === void 0) continue;
-    if (step.route === void 0) {
+  for (const [i, node] of def.steps.entries()) {
+    if (node === void 0) continue;
+    const hasRoute = !isForkDef(node) && node.route !== void 0;
+    if (!hasRoute) {
       const isLast = i === def.steps.length - 1;
-      if (isLast && step.next === void 0) {
+      if (isLast && node.next === void 0) {
         violations.push(
-          `step "${step.name}" has no route, no explicit .next(), and no following step \u2014 no exit path`
+          `step "${node.name}" has no route, no explicit .next(), and no following step \u2014 no exit path`
         );
       }
     }
   }
-  for (const step of def.steps) {
+  for (const step of stepNodes) {
     if (step.route !== void 0 && step.next !== void 0) {
       violations.push(`step "${step.name}" has both route and .next() \u2014 these are mutually exclusive`);
     }
@@ -183,7 +287,7 @@ function validateLoop(def) {
     }
     seen.add(step.name);
   }
-  for (const step of def.steps) {
+  for (const step of stepNodes) {
     for (const transition of step.transitions) {
       if (transition.target.kind === "step") {
         if (!names.has(transition.target.name)) {
@@ -193,10 +297,12 @@ function validateLoop(def) {
         }
       }
     }
-    if (step.next !== void 0) {
-      if (!names.has(step.next)) {
+  }
+  for (const node of def.steps) {
+    if (node.next !== void 0) {
+      if (!names.has(node.next)) {
         violations.push(
-          `step "${step.name}" has .next("${step.next}") but step "${step.next}" is not declared`
+          `step "${node.name}" has .next("${node.next}") but step "${node.next}" is not declared`
         );
       }
     }
@@ -213,7 +319,7 @@ function validateLoop(def) {
     violations.push(`l.start() was called but no step was declared after it \u2014 declare at least one step`);
   }
   let hasExit = false;
-  for (const step of def.steps) {
+  for (const step of stepNodes) {
     for (const transition of step.transitions) {
       if (transition.target.kind === "end") {
         hasExit = true;
@@ -236,36 +342,39 @@ function validateLoop(def) {
     }
     while (queue.length > 0) {
       const currentName = queue.shift();
-      const currentStep = def.steps.find((s) => s.name === currentName);
-      if (!currentStep) continue;
-      for (const transition of currentStep.transitions) {
-        if (transition.target.kind === "step") {
-          if (!reachable.has(transition.target.name)) {
-            reachable.add(transition.target.name);
-            queue.push(transition.target.name);
+      const currentNode = def.steps.find((s) => s.name === currentName);
+      if (!currentNode) continue;
+      if (!isForkDef(currentNode)) {
+        for (const transition of currentNode.transitions) {
+          if (transition.target.kind === "step") {
+            if (!reachable.has(transition.target.name)) {
+              reachable.add(transition.target.name);
+              queue.push(transition.target.name);
+            }
           }
         }
       }
-      if (currentStep.route !== void 0) {
-        if (currentStep.next !== void 0 && !reachable.has(currentStep.next)) {
-          reachable.add(currentStep.next);
-          queue.push(currentStep.next);
+      const hasRoute = !isForkDef(currentNode) && currentNode.route !== void 0;
+      if (hasRoute) {
+        if (currentNode.next !== void 0 && !reachable.has(currentNode.next)) {
+          reachable.add(currentNode.next);
+          queue.push(currentNode.next);
         }
       } else {
-        if (currentStep.next !== void 0) {
-          if (!reachable.has(currentStep.next)) {
-            reachable.add(currentStep.next);
-            queue.push(currentStep.next);
+        if (currentNode.next !== void 0) {
+          if (!reachable.has(currentNode.next)) {
+            reachable.add(currentNode.next);
+            queue.push(currentNode.next);
           }
         } else {
           const currentIndex = def.steps.findIndex((s) => s.name === currentName);
           if (currentIndex !== -1 && currentIndex < def.steps.length - 1) {
-            const nextStep = def.steps[currentIndex + 1];
-            if (nextStep !== void 0) {
-              const nextStepName = nextStep.name;
-              if (!reachable.has(nextStepName)) {
-                reachable.add(nextStepName);
-                queue.push(nextStepName);
+            const nextNode = def.steps[currentIndex + 1];
+            if (nextNode !== void 0) {
+              const nextNodeName = nextNode.name;
+              if (!reachable.has(nextNodeName)) {
+                reachable.add(nextNodeName);
+                queue.push(nextNodeName);
               }
             }
           }
@@ -278,16 +387,14 @@ function validateLoop(def) {
       }
     }
   }
-  for (const step of def.steps) {
+  for (const step of stepNodes) {
     if (step.route === void 0 && step.transitions.length > 0) {
       violations.push(
         `step "${step.name}" has .on() transitions but no route \u2014 .on() is only valid when route is set`
       );
     }
   }
-  if (violations.length > 0) {
-    throw new LoopValidationError(violations);
-  }
+  return violations;
 }
 
 // src/harness/harness-builder.ts
@@ -398,10 +505,11 @@ var InterruptPause = class extends Error {
 function isInterruptPause(error) {
   return error instanceof InterruptPause;
 }
-function createInterruptFn(state, callCountRef) {
+function createInterruptFn(state, callCountRef, branchPath) {
+  const prefix = branchPath !== void 0 && branchPath.length > 0 ? `${branchPath.join(":")}:` : "";
   return async (prompt, id) => {
     const isAutoId = id === void 0;
-    const effectiveId = isAutoId ? `$auto:${callCountRef.current}` : id;
+    const effectiveId = isAutoId ? `$auto:${prefix}${callCountRef.current}` : id;
     if (isAutoId) {
       callCountRef.current++;
     }
@@ -432,6 +540,9 @@ function extractRunListeners(resources) {
 }
 
 // src/loop/loop-executor.ts
+function isForkCursor(cursor) {
+  return typeof cursor !== "string";
+}
 var UnknownSignalError = class extends Error {
   step;
   signal;
@@ -452,6 +563,20 @@ var NoNextStepError = class extends Error {
     this.step = step;
   }
 };
+var MissingReducerError = class extends Error {
+  fork;
+  key;
+  branches;
+  constructor(fork, key, branches) {
+    super(
+      `fork "${fork}": state key "${key}" was touched by multiple branches (${branches.join(", ")}) but has no reducer declared \u2014 add field({ reduce }) for "${key}"`
+    );
+    this.name = "MissingReducerError";
+    this.fork = fork;
+    this.key = key;
+    this.branches = branches;
+  }
+};
 function buildImplicitNextMap(graph) {
   const map = /* @__PURE__ */ new Map();
   for (let i = 0; i < graph.steps.length; i++) {
@@ -461,7 +586,7 @@ function buildImplicitNextMap(graph) {
   }
   return map;
 }
-function applyUpdate(state, update, schema) {
+function applyUpdate(state, update, schema, touchedKeys) {
   for (const [key, value] of Object.entries(update)) {
     if (key === "$error" || key === "$interrupt" || key === "$interruptResponses") continue;
     const reducer = schema?.[key]?.reduce;
@@ -470,6 +595,7 @@ function applyUpdate(state, update, schema) {
     } else {
       state[key] = value;
     }
+    touchedKeys?.add(key);
   }
 }
 async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callbacks) {
@@ -485,12 +611,13 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
     sessionId: ctx.sessionId,
     runId: typeof callbacks?.runId === "string" ? callbacks.runId : "",
     ...typeof callbacks?.parentRunId === "string" ? { parentRunId: callbacks.parentRunId } : {},
-    ...typeof ctx.instanceId === "string" ? { instanceId: ctx.instanceId } : {}
+    ...typeof ctx.instanceId === "string" ? { instanceId: ctx.instanceId } : {},
+    ...callbacks?.branchPath !== void 0 && callbacks.branchPath.length > 0 ? { branchPath: callbacks.branchPath } : {}
   };
   obs?.onRunStart?.(runCtx);
   const callCountRef = { current: 0 };
   const stepCtxRef = { current: null };
-  ctx["interrupt"] = createInterruptFn(state, callCountRef);
+  ctx["interrupt"] = createInterruptFn(state, callCountRef, callbacks?.branchPath);
   ctx["emit"] = createEmitFn(callbacks?.listeners ?? {}, obs, stepCtxRef);
   let cursor = startCursor ?? graph.entryStep;
   while (true) {
@@ -498,10 +625,64 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
       obs?.onRunEnd?.(runCtx, { signal: "$stopped", durationMs: Date.now() - runStart });
       return { state, signal: null, cursor, paused: true };
     }
+    if (isForkCursor(cursor)) {
+      const forkCursor = cursor;
+      const forkNode = graph.steps.find((s) => s.name === forkCursor.fork);
+      if (!isForkDef(forkNode)) {
+        throw new NoNextStepError(forkCursor.fork);
+      }
+      onBeforeStep?.(forkNode.name, { ...state });
+      const outcome = await handleFork(
+        forkNode,
+        forkCursor.branches,
+        state,
+        ctx,
+        schema,
+        shouldStop,
+        callbacks,
+        obs,
+        runCtx,
+        runStart,
+        implicitNextMap,
+        graph
+      );
+      if (outcome.done) {
+        return outcome.result;
+      }
+      cursor = outcome.nextCursor;
+      continue;
+    }
     onBeforeStep?.(cursor, { ...state });
-    const step = graph.steps.find((s) => s.name === cursor);
+    const node = graph.steps.find((s) => s.name === cursor);
+    if (isForkDef(node)) {
+      const outcome = await handleFork(
+        node,
+        void 0,
+        state,
+        ctx,
+        schema,
+        shouldStop,
+        callbacks,
+        obs,
+        runCtx,
+        runStart,
+        implicitNextMap,
+        graph
+      );
+      if (outcome.done) {
+        return outcome.result;
+      }
+      cursor = outcome.nextCursor;
+      continue;
+    }
+    const step = node;
     callCountRef.current = 0;
-    const stepCtx = { agentId: ctx.agentId, sessionId: ctx.sessionId, stepName: cursor };
+    const stepCtx = {
+      agentId: ctx.agentId,
+      sessionId: ctx.sessionId,
+      stepName: cursor,
+      ...callbacks?.branchPath !== void 0 && callbacks.branchPath.length > 0 ? { branchPath: callbacks.branchPath } : {}
+    };
     stepCtxRef.current = stepCtx;
     const stepStart = Date.now();
     obs?.onStepStart?.(stepCtx);
@@ -518,7 +699,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
           state,
           ctx
         );
-        applyUpdate(state, update, schema);
+        applyUpdate(state, update, schema, callbacks?.touchedKeys);
         if (hadResponses) {
           state.$interrupt = null;
           state.$interruptResponses = {};
@@ -578,18 +759,161 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
     }
   }
 }
+async function runBranch(branch, prior, outerState, outerCtx, schema, shouldStop, branchSignal, branchCallbacks) {
+  if (prior !== void 0 && prior.status === "done") {
+    return {
+      name: branch.name,
+      result: { state: prior.state, signal: null, cursor: null, paused: false },
+      touchedKeys: new Set(prior.touchedKeys)
+    };
+  }
+  const touchedKeys = new Set(prior?.status === "paused" ? prior.touchedKeys : []);
+  const privateState = prior !== void 0 ? { ...prior.state } : { ...outerState };
+  const privateCtx = { ...outerCtx, signal: branchSignal };
+  const branchStartCursor = prior?.status === "paused" ? prior.cursor : void 0;
+  const branchPath = [...branchCallbacks?.branchPath ?? [], branch.name];
+  const result = await runLoop(
+    branch.definition,
+    privateState,
+    privateCtx,
+    schema,
+    shouldStop,
+    branchStartCursor,
+    { ...branchCallbacks, touchedKeys, branchPath }
+  );
+  return { name: branch.name, result, touchedKeys };
+}
+async function dispatchFork(forkNode, priorBranches, outerState, outerCtx, schema, shouldStop, callbacks) {
+  const priorByName = new Map((priorBranches ?? []).map((b) => [b.name, b]));
+  const localAborts = forkNode.branches.map(() => new AbortController());
+  const outerSignal = outerCtx.signal;
+  const branchSignals = forkNode.branches.map(
+    (_, i) => outerSignal !== void 0 ? AbortSignal.any([outerSignal, localAborts[i].signal]) : localAborts[i].signal
+  );
+  const { onBeforeStep: _outerOnBeforeStep, onAfterStep: _outerOnAfterStep, onComplete: _outerOnComplete, ...branchCallbacksRest } = callbacks ?? {};
+  const branchCallbacksBase = callbacks !== void 0 ? branchCallbacksRest : void 0;
+  const outcomes = await Promise.all(
+    forkNode.branches.map(async (branch, i) => {
+      const prior = priorByName.get(branch.name);
+      const outcome = await runBranch(branch, prior, outerState, outerCtx, schema, shouldStop, branchSignals[i], branchCallbacksBase);
+      if (outcome.result.paused && outcome.result.signal === "$error") {
+        for (const controller of localAborts) controller.abort();
+      }
+      return outcome;
+    })
+  );
+  const failed = outcomes.find((o) => o.result.paused && o.result.signal === "$error");
+  if (failed !== void 0) {
+    return { kind: "failed", error: failed.result.state.$error };
+  }
+  const anyPaused = outcomes.some((o) => o.result.paused);
+  if (anyPaused) {
+    const branches = outcomes.map((o) => {
+      if (o.result.paused) {
+        return {
+          name: o.name,
+          status: "paused",
+          state: o.result.state,
+          cursor: o.result.cursor,
+          touchedKeys: [...o.touchedKeys]
+        };
+      }
+      return {
+        name: o.name,
+        status: "done",
+        state: o.result.state,
+        touchedKeys: [...o.touchedKeys]
+      };
+    });
+    return { kind: "paused", forkCursor: { kind: "fork", fork: forkNode.name, branches } };
+  }
+  const keyOwners = /* @__PURE__ */ new Map();
+  for (const outcome of outcomes) {
+    for (const key of outcome.touchedKeys) {
+      const owners = keyOwners.get(key) ?? [];
+      owners.push(outcome.name);
+      keyOwners.set(key, owners);
+    }
+  }
+  for (const outcome of outcomes) {
+    for (const key of outcome.touchedKeys) {
+      const owners = keyOwners.get(key);
+      if (owners.length > 1) {
+        const reducer = schema?.[key]?.reduce;
+        if (reducer === void 0) {
+          throw new MissingReducerError(forkNode.name, key, owners);
+        }
+        outerState[key] = reducer(outerState[key], outcome.result.state[key]);
+      } else {
+        outerState[key] = outcome.result.state[key];
+      }
+    }
+  }
+  return { kind: "success" };
+}
+async function handleFork(forkNode, priorBranches, state, ctx, schema, shouldStop, callbacks, obs, runCtx, runStart, implicitNextMap, graph) {
+  const stepCtx = {
+    agentId: ctx.agentId,
+    sessionId: ctx.sessionId,
+    stepName: forkNode.name,
+    ...callbacks?.branchPath !== void 0 && callbacks.branchPath.length > 0 ? { branchPath: callbacks.branchPath } : {}
+  };
+  const stepStart = Date.now();
+  obs?.onStepStart?.(stepCtx);
+  const dispatch = await dispatchFork(forkNode, priorBranches, state, ctx, schema, shouldStop, callbacks);
+  if (dispatch.kind === "paused") {
+    obs?.onRunEnd?.(runCtx, { signal: "$interrupt", durationMs: Date.now() - runStart });
+    return { done: true, result: { state, signal: "$interrupt", cursor: dispatch.forkCursor, paused: true } };
+  }
+  if (dispatch.kind === "failed") {
+    state.$error = dispatch.error;
+    callbacks?.onError?.(state.$error, forkNode.name);
+    obs?.onStepError?.(stepCtx, { error: state.$error, durationMs: Date.now() - stepStart });
+    if (graph.onError !== void 0) {
+      return { done: false, nextCursor: graph.onError };
+    }
+    obs?.onRunEnd?.(runCtx, { signal: "$error", durationMs: Date.now() - runStart });
+    return { done: true, result: { state, signal: "$error", cursor: forkNode.name, paused: true } };
+  }
+  state.$error = null;
+  obs?.onStepEnd?.(stepCtx, { durationMs: Date.now() - stepStart });
+  callbacks?.onAfterStep?.(forkNode.name, state);
+  const next = forkNode.next ?? implicitNextMap.get(forkNode.name) ?? null;
+  if (next === null) {
+    throw new NoNextStepError(forkNode.name);
+  }
+  return { done: false, nextCursor: next };
+}
 
 // src/agent/session-store.ts
+function collectPendingInterrupts(cursor, state) {
+  if (cursor !== void 0 && isForkCursor(cursor)) {
+    const result = [];
+    for (const branch of cursor.branches) {
+      if (branch.status !== "paused") continue;
+      const paused = branch;
+      for (const pi of collectPendingInterrupts(paused.cursor, paused.state)) {
+        result.push({ ...pi, step: `${cursor.fork}/${paused.name}/${pi.step}` });
+      }
+    }
+    return result;
+  }
+  const interrupt = state["$interrupt"];
+  if (interrupt === null || interrupt === void 0) return [];
+  const step = typeof cursor === "string" ? cursor : "";
+  return [{ interruptId: interrupt.interruptId, prompt: interrupt.prompt, step }];
+}
 function storedSessionToPhase(loaded) {
   if (loaded === null) {
     return { phase: "fresh" };
   }
   if (loaded.phase === "paused") {
-    const step = loaded.step ?? "";
+    const step = loaded.step === void 0 ? "" : isForkCursor(loaded.step) ? loaded.step.fork : loaded.step;
+    const pendingInterrupts = collectPendingInterrupts(loaded.step, loaded.finalState);
     if (loaded.signal !== void 0) {
-      return { phase: "paused", step, signal: loaded.signal };
+      return { phase: "paused", step, signal: loaded.signal, pendingInterrupts };
     }
-    return { phase: "paused", step };
+    return { phase: "paused", step, pendingInterrupts };
   }
   if (loaded.signal !== void 0) {
     return { phase: "completed", signal: loaded.signal };
@@ -732,7 +1056,7 @@ function noopStop() {
 }
 
 // src/agent/session-lifecycle.ts
-function resolveSessionStore(storeEntries) {
+function resolveSessionStore(storeEntries, overrides) {
   let result = void 0;
   for (const entry of storeEntries) {
     if (entry.kind !== "store") continue;
@@ -740,7 +1064,8 @@ function resolveSessionStore(storeEntries) {
     if (value === null || typeof value !== "object") continue;
     const rec = value;
     if (!("session" in rec)) continue;
-    const session = rec["session"];
+    const rawSession = rec["session"];
+    const session = overrides !== void 0 && "session" in overrides ? overrides["session"] : rawSession;
     if (session === null || typeof session !== "object") continue;
     const s = session;
     if (typeof s["load"] === "function" && typeof s["save"] === "function") {
@@ -865,19 +1190,53 @@ var NoInterruptError = class extends Error {
     this.name = "NoInterruptError";
   }
 };
+function injectIntoForkCursor(cursor, interruptId, response) {
+  let matched = false;
+  const branches = cursor.branches.map((branch) => {
+    if (matched || branch.status !== "paused") return branch;
+    const paused = branch;
+    const branchInterrupt = paused.state["$interrupt"];
+    if (branchInterrupt !== null && branchInterrupt !== void 0 && branchInterrupt.interruptId === interruptId) {
+      matched = true;
+      const existing = paused.state["$interruptResponses"] ?? {};
+      return {
+        ...paused,
+        state: { ...paused.state, $interrupt: null, $interruptResponses: { ...existing, [interruptId]: response } }
+      };
+    }
+    if (isForkCursor(paused.cursor)) {
+      const nested = injectIntoForkCursor(paused.cursor, interruptId, response);
+      if (nested !== null) {
+        matched = true;
+        return { ...paused, cursor: nested };
+      }
+    }
+    return branch;
+  });
+  return matched ? { ...cursor, branches } : null;
+}
+function injectInterruptResponseIntoState(cursor, state, interruptId, response) {
+  if (cursor !== void 0 && isForkCursor(cursor)) {
+    const updated = injectIntoForkCursor(cursor, interruptId, response);
+    return updated === null ? { cursor, state, found: false } : { cursor: updated, state, found: true };
+  }
+  const interrupt = state["$interrupt"];
+  if (interrupt === null || interrupt === void 0 || interrupt.interruptId !== interruptId) {
+    return { cursor, state, found: false };
+  }
+  const existing = state["$interruptResponses"] ?? {};
+  return {
+    cursor,
+    state: { ...state, $interrupt: null, $interruptResponses: { ...existing, [interruptId]: response } },
+    found: true
+  };
+}
 async function injectInterruptResponse(store, agentId, sessionId, interruptId, response) {
   const loaded = await store.load(agentId, sessionId);
   if (loaded === null) throw new NoInterruptError();
   if (loaded.phase !== "paused") throw new NoInterruptError();
-  const interrupt = loaded.finalState.$interrupt;
-  if (interrupt === null) throw new NoInterruptError();
-  if (interrupt.interruptId !== interruptId) throw new NoInterruptError();
-  const existingResponses = loaded.finalState.$interruptResponses ?? {};
-  const newState = {
-    ...loaded.finalState,
-    $interrupt: null,
-    $interruptResponses: { ...existingResponses, [interruptId]: response }
-  };
+  const result = injectInterruptResponseIntoState(loaded.step, loaded.finalState, interruptId, response);
+  if (!result.found) throw new NoInterruptError();
   const updated = {
     agentId: loaded.agentId,
     runId: loaded.runId,
@@ -887,8 +1246,8 @@ async function injectInterruptResponse(store, agentId, sessionId, interruptId, r
     settledAt: loaded.settledAt,
     phase: "paused",
     initialState: loaded.initialState,
-    finalState: newState,
-    ...loaded.step !== void 0 ? { step: loaded.step } : {},
+    finalState: result.state,
+    ...result.cursor !== void 0 ? { step: result.cursor } : {},
     ...loaded.signal !== void 0 ? { signal: loaded.signal } : {}
   };
   await store.save(agentId, sessionId, updated);
@@ -1022,6 +1381,24 @@ var UnknownRunSlotError = class extends Error {
     this.key = key;
   }
 };
+var MissingStoreSlotError = class extends Error {
+  /** The store key (e.g. `"session"`) that was not provided. */
+  key;
+  constructor(key) {
+    super(`required store slot "${key}" was not provided in createAgent options.stores`);
+    this.name = "MissingStoreSlotError";
+    this.key = key;
+  }
+};
+var UnexpectedStoreSlotError = class extends Error {
+  /** The unexpected store key. */
+  key;
+  constructor(key) {
+    super(`store slot "${key}" was not declared as required() in the harness \u2014 do not pass it in options.stores`);
+    this.name = "UnexpectedStoreSlotError";
+    this.key = key;
+  }
+};
 var _agentInternals = /* @__PURE__ */ Symbol("_agentInternals");
 function createAgent(id, h, slots, agentOptions) {
   const internals = getInternals(h);
@@ -1070,7 +1447,27 @@ function createAgent(id, h, slots, agentOptions) {
       }
     }
   }
-  const capturedStore = resolveSessionStore(storeEntries);
+  let sessionIsRequired = false;
+  for (const entry of storeEntries) {
+    const storeValue = entry.value;
+    if (storeValue === null || typeof storeValue !== "object") continue;
+    const storeRec = storeValue;
+    if ("session" in storeRec && isRequiredMarker(storeRec["session"])) {
+      sessionIsRequired = true;
+    }
+  }
+  const sessionStoreOverride = agentOptions?.stores?.["session"];
+  const storeOverrides = {};
+  if (sessionIsRequired) {
+    if (sessionStoreOverride === void 0) throw new MissingStoreSlotError("session");
+    storeOverrides["session"] = sessionStoreOverride;
+  } else if (sessionStoreOverride !== void 0) {
+    throw new UnexpectedStoreSlotError("session");
+  }
+  const capturedStore = resolveSessionStore(
+    storeEntries,
+    Object.keys(storeOverrides).length > 0 ? storeOverrides : void 0
+  );
   const agentInternals = {
     agentId: id,
     resolvedProviders,
@@ -1409,11 +1806,10 @@ function createAgent(id, h, slots, agentOptions) {
               }
               const prev = lastResult;
               if (prev === null) throw new NoInterruptError();
-              const state = prev.state;
-              const existing = state.$interruptResponses ?? {};
-              state.$interruptResponses = { ...existing, [interruptId]: response };
-              state.$interrupt = null;
-              const cursor = prev.cursor ?? void 0;
+              const injected = injectInterruptResponseIntoState(prev.cursor ?? void 0, prev.state, interruptId, response);
+              if (!injected.found) throw new NoInterruptError();
+              const state = injected.state;
+              const cursor = injected.cursor;
               const r = await runLoop(
                 agentInternals.loopDef,
                 state,
@@ -1521,6 +1917,8 @@ export {
   createAgent,
   createHarness,
   field,
+  isForkCursor,
+  isForkDef,
   isRequiredMarker,
   isRuntimeMarker,
   required,