@noetaris/harness 0.3.2 → 0.5.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
@@ -384,6 +491,51 @@ function createBuilderInstance(internals) {
   return builder;
 }
 
+// src/agent/observer.ts
+function reportObserverError(error, ctx, sink) {
+  if (sink !== void 0) {
+    try {
+      sink(error, ctx);
+    } catch (sinkError) {
+      console.error(`[harness] onObserverError sink threw while handling '${ctx.hookName}':`, sinkError);
+    }
+    return;
+  }
+  console.error(`[harness] observer hook '${ctx.hookName}' threw:`, error);
+}
+function safeInvoke(hookName, call, sink) {
+  try {
+    call();
+  } catch (error) {
+    reportObserverError(error, { hookName }, sink);
+  }
+}
+function composeObservers(observers, onObserverError) {
+  return {
+    onRunStart: (ctx) => {
+      for (const o of observers) safeInvoke("onRunStart", () => o.onRunStart?.(ctx), onObserverError);
+    },
+    onRunEnd: (ctx, event) => {
+      for (const o of observers) safeInvoke("onRunEnd", () => o.onRunEnd?.(ctx, event), onObserverError);
+    },
+    onStepStart: (ctx) => {
+      for (const o of observers) safeInvoke("onStepStart", () => o.onStepStart?.(ctx), onObserverError);
+    },
+    onStepEnd: (ctx, event) => {
+      for (const o of observers) safeInvoke("onStepEnd", () => o.onStepEnd?.(ctx, event), onObserverError);
+    },
+    onStepError: (ctx, event) => {
+      for (const o of observers) safeInvoke("onStepError", () => o.onStepError?.(ctx, event), onObserverError);
+    },
+    onInterrupt: (ctx, event) => {
+      for (const o of observers) safeInvoke("onInterrupt", () => o.onInterrupt?.(ctx, event), onObserverError);
+    },
+    onEvent: (ctx, type, payload) => {
+      for (const o of observers) safeInvoke("onEvent", () => o.onEvent?.(ctx, type, payload), onObserverError);
+    }
+  };
+}
+
 // src/agent/ctx-interrupt.ts
 var InterruptPause = class extends Error {
   interruptId;
@@ -398,10 +550,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++;
     }
@@ -415,11 +568,12 @@ function createInterruptFn(state, callCountRef) {
 }
 
 // src/agent/ctx-emit.ts
-function createEmitFn(listeners, observer, stepCtxRef) {
+function createEmitFn(listeners, observer, stepCtxRef, onObserverError) {
   return (name, payload) => {
     listeners[name]?.(payload);
     if (observer !== void 0 && stepCtxRef !== void 0 && stepCtxRef.current !== null) {
-      observer.onEvent?.(stepCtxRef.current, name, payload);
+      const ctx = stepCtxRef.current;
+      safeInvoke("onEvent", () => observer.onEvent?.(ctx, name, payload), onObserverError);
     }
   };
 }
@@ -432,6 +586,10 @@ function extractRunListeners(resources) {
 }
 
 // src/loop/loop-executor.ts
+var NOOP_OBSERVER = {};
+function isForkCursor(cursor) {
+  return typeof cursor !== "string";
+}
 var UnknownSignalError = class extends Error {
   step;
   signal;
@@ -452,6 +610,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 +633,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,11 +642,13 @@ function applyUpdate(state, update, schema) {
     } else {
       state[key] = value;
     }
+    touchedKeys?.add(key);
   }
 }
 async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callbacks) {
   const { onBeforeStep, onAfterStep, onError, onComplete, onInterrupt } = callbacks ?? {};
   const obs = callbacks?.observer;
+  const onObserverError = callbacks?.onObserverError;
   const implicitNextMap = buildImplicitNextMap(graph);
   if (!("$error" in state)) state.$error = null;
   if (!("$interrupt" in state)) state.$interrupt = null;
@@ -485,29 +659,86 @@ 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);
+  safeInvoke("onRunStart", () => obs?.onRunStart?.(runCtx), onObserverError);
   const callCountRef = { current: 0 };
   const stepCtxRef = { current: null };
-  ctx["interrupt"] = createInterruptFn(state, callCountRef);
-  ctx["emit"] = createEmitFn(callbacks?.listeners ?? {}, obs, stepCtxRef);
+  ctx["interrupt"] = createInterruptFn(state, callCountRef, callbacks?.branchPath);
+  ctx["emit"] = createEmitFn(callbacks?.listeners ?? {}, obs, stepCtxRef, onObserverError);
   let cursor = startCursor ?? graph.entryStep;
   while (true) {
     if (shouldStop?.()) {
-      obs?.onRunEnd?.(runCtx, { signal: "$stopped", durationMs: Date.now() - runStart });
+      safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$stopped", durationMs: Date.now() - runStart }), onObserverError);
       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);
-    if (callbacks?.setStepContextSlots !== void 0) {
-      for (const slot of callbacks.setStepContextSlots) {
-        slot.setStepContext(stepCtx);
+    safeInvoke("onStepStart", () => obs?.onStepStart?.(stepCtx), onObserverError);
+    if (callbacks?.telemetrySlots !== void 0) {
+      const telemetry = { observer: obs ?? NOOP_OBSERVER, stepContext: stepCtx };
+      for (const { key, slot } of callbacks.telemetrySlots) {
+        ;
+        ctx[key] = slot.withTelemetry(telemetry);
       }
     }
     let runSucceeded = false;
@@ -518,7 +749,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 = {};
@@ -527,19 +758,19 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
       } catch (e) {
         if (isInterruptPause(e)) {
           onInterrupt?.(e.prompt, e.interruptId);
-          obs?.onInterrupt?.(stepCtx, { prompt: e.prompt, interruptId: e.interruptId });
-          obs?.onRunEnd?.(runCtx, { signal: "$interrupt", durationMs: Date.now() - runStart });
+          safeInvoke("onInterrupt", () => obs?.onInterrupt?.(stepCtx, { prompt: e.prompt, interruptId: e.interruptId }), onObserverError);
+          safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$interrupt", durationMs: Date.now() - runStart }), onObserverError);
           return { state, signal: "$interrupt", cursor, paused: true };
         }
         state.$error = e instanceof Error ? e : new Error(String(e));
         onError?.(state.$error, cursor);
-        obs?.onStepError?.(stepCtx, { error: state.$error, durationMs: Date.now() - stepStart });
+        safeInvoke("onStepError", () => obs?.onStepError?.(stepCtx, { error: state.$error, durationMs: Date.now() - stepStart }), onObserverError);
       }
     }
     if (runSucceeded) {
       state.$error = null;
       onAfterStep?.(cursor, state);
-      obs?.onStepEnd?.(stepCtx, { durationMs: Date.now() - stepStart });
+      safeInvoke("onStepEnd", () => obs?.onStepEnd?.(stepCtx, { durationMs: Date.now() - stepStart }), onObserverError);
     }
     const callRoute = step.route !== void 0 && (runSucceeded || step.run === void 0 || step.errorAware);
     if (callRoute) {
@@ -549,7 +780,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
         signal = routeFn(state);
       } catch (e) {
         state.$error = e instanceof Error ? e : new Error(String(e));
-        obs?.onRunEnd?.(runCtx, { signal: "$error", durationMs: Date.now() - runStart });
+        safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$error", durationMs: Date.now() - runStart }), onObserverError);
         return { state, signal: "$error", cursor, paused: true };
       }
       const transition = step.transitions.find((t) => t.signal === signal);
@@ -558,7 +789,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
       }
       if (transition.target.kind === "end") {
         onComplete?.(state, signal);
-        obs?.onRunEnd?.(runCtx, { signal, durationMs: Date.now() - runStart });
+        safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal, durationMs: Date.now() - runStart }), onObserverError);
         return { state, signal, cursor: null, paused: false };
       }
       cursor = transition.target.name;
@@ -566,7 +797,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
       if (graph.onError !== void 0) {
         cursor = graph.onError;
       } else {
-        obs?.onRunEnd?.(runCtx, { signal: "$error", durationMs: Date.now() - runStart });
+        safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$error", durationMs: Date.now() - runStart }), onObserverError);
         return { state, signal: "$error", cursor, paused: true };
       }
     } else {
@@ -578,18 +809,162 @@ 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();
+  const onObserverError = callbacks?.onObserverError;
+  safeInvoke("onStepStart", () => obs?.onStepStart?.(stepCtx), onObserverError);
+  const dispatch = await dispatchFork(forkNode, priorBranches, state, ctx, schema, shouldStop, callbacks);
+  if (dispatch.kind === "paused") {
+    safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$interrupt", durationMs: Date.now() - runStart }), onObserverError);
+    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);
+    safeInvoke("onStepError", () => obs?.onStepError?.(stepCtx, { error: state.$error, durationMs: Date.now() - stepStart }), onObserverError);
+    if (graph.onError !== void 0) {
+      return { done: false, nextCursor: graph.onError };
+    }
+    safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$error", durationMs: Date.now() - runStart }), onObserverError);
+    return { done: true, result: { state, signal: "$error", cursor: forkNode.name, paused: true } };
+  }
+  state.$error = null;
+  safeInvoke("onStepEnd", () => obs?.onStepEnd?.(stepCtx, { durationMs: Date.now() - stepStart }), onObserverError);
+  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 };
@@ -866,19 +1241,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,
@@ -888,8 +1297,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);
@@ -957,12 +1366,24 @@ function extractRunEvents(resources) {
 }
 
 // src/agent/create-agent.ts
-var NOOP_OBSERVER = {};
+function buildTelemetrySlots(entries) {
+  const out = [];
+  for (const [key, slot] of entries) {
+    if (slot !== null && typeof slot === "object" && typeof slot["withTelemetry"] === "function") {
+      out.push({ key, slot });
+    }
+  }
+  return out;
+}
 function extractRunObserver(resources) {
   const raw = resources["observer"];
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return void 0;
   return raw;
 }
+function extractRunErrorSink(resources) {
+  const raw = resources["onObserverError"];
+  return typeof raw === "function" ? raw : void 0;
+}
 var MissingLoopError = class extends Error {
   constructor() {
     super("harness has no loop \u2014 call h.loop() before createAgent(id, h, slots)");
@@ -1120,10 +1541,10 @@ function createAgent(id, h, slots, agentOptions) {
     runtimeKeys,
     requiredKeys
   };
-  const reservedRunKeys = /* @__PURE__ */ new Set(["sessionId", "signal", "events", "listeners", "observer", "claimOptions", "parentRunId"]);
+  const reservedRunKeys = /* @__PURE__ */ new Set(["sessionId", "signal", "events", "listeners", "observer", "onObserverError", "claimOptions", "parentRunId"]);
   const inFlightSessions = /* @__PURE__ */ new Set();
   const interruptPendingSessions = /* @__PURE__ */ new Set();
-  const makeAgentResumeHandle = (resp, sId, iId, resumeOpts, observer, setStepContextSlots) => {
+  const makeAgentResumeHandle = (resp, sId, iId, resumeOpts, observer, onObserverError, telemetrySlots) => {
     let _stopped = false;
     const abortController = new AbortController();
     const flag = {
@@ -1198,7 +1619,8 @@ function createAgent(id, h, slots, agentOptions) {
               ...resumeOpts?.onStoreError !== void 0 ? { onStoreError: resumeOpts.onStoreError } : {},
               ...leaseRef !== void 0 ? { leaseRef, claimTtlMs: claimOptions.ttlMs } : {},
               ...observer !== void 0 ? { observer } : {},
-              ...setStepContextSlots !== void 0 && setStepContextSlots.length > 0 ? { setStepContextSlots } : {}
+              ...onObserverError !== void 0 ? { onObserverError } : {},
+              ...telemetrySlots !== void 0 && telemetrySlots.length > 0 ? { telemetrySlots } : {}
             }
           );
           if (r.signal === "$interrupt") interruptPendingSessions.add(sId);
@@ -1294,17 +1716,11 @@ function createAgent(id, h, slots, agentOptions) {
       const events = extractRunEvents(resources);
       const listeners = extractRunListeners(resources);
       const observer = extractRunObserver(resources);
-      for (const slot of [...agentInternals.resolvedProviders.values(), ...Object.values(runtimeSlots)]) {
-        if (slot !== null && typeof slot === "object" && typeof slot["bindObserver"] === "function") {
-          slot.bindObserver(observer ?? NOOP_OBSERVER);
-        }
-      }
-      const setStepContextSlots = [];
-      for (const slot of [...agentInternals.resolvedProviders.values(), ...Object.values(runtimeSlots)]) {
-        if (slot !== null && typeof slot === "object" && typeof slot["setStepContext"] === "function") {
-          setStepContextSlots.push(slot);
-        }
-      }
+      const onObserverError = extractRunErrorSink(resources);
+      const telemetrySlots = buildTelemetrySlots([
+        ...agentInternals.resolvedProviders.entries(),
+        ...Object.entries(runtimeSlots)
+      ]);
       const parentRunId = typeof resources["parentRunId"] === "string" ? resources["parentRunId"] : void 0;
       const options = {
         shouldStop: () => stopFlag.stopped,
@@ -1320,9 +1736,10 @@ function createAgent(id, h, slots, agentOptions) {
         ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
         ...Object.keys(listeners).length > 0 ? { listeners } : {},
         ...observer !== void 0 ? { observer } : {},
+        ...onObserverError !== void 0 ? { onObserverError } : {},
         ...agentOptions?.instanceId !== void 0 ? { instanceId: agentOptions.instanceId } : {},
         ...parentRunId !== void 0 ? { parentRunId } : {},
-        ...setStepContextSlots.length > 0 ? { setStepContextSlots } : {}
+        ...telemetrySlots.length > 0 ? { telemetrySlots } : {}
       };
       let lastResult = null;
       const execution = (async () => {
@@ -1439,7 +1856,8 @@ function createAgent(id, h, slots, agentOptions) {
                     ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
                     ...Object.keys(listeners).length > 0 ? { listeners } : {},
                     ...observer !== void 0 ? { observer } : {},
-                    ...setStepContextSlots.length > 0 ? { setStepContextSlots } : {}
+                    ...onObserverError !== void 0 ? { onObserverError } : {},
+                    ...telemetrySlots.length > 0 ? { telemetrySlots } : {}
                   }
                 );
                 if (r2.signal === "$interrupt") interruptPendingSessions.add(sessionId);
@@ -1448,11 +1866,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,
@@ -1472,7 +1889,8 @@ function createAgent(id, h, slots, agentOptions) {
                   ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
                   ...Object.keys(listeners).length > 0 ? { listeners } : {},
                   ...observer !== void 0 ? { observer } : {},
-                  ...setStepContextSlots.length > 0 ? { setStepContextSlots } : {}
+                  ...onObserverError !== void 0 ? { onObserverError } : {},
+                  ...telemetrySlots.length > 0 ? { telemetrySlots } : {}
                 }
               );
               if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
@@ -1501,51 +1919,15 @@ function createAgent(id, h, slots, agentOptions) {
       const events = extractRunEvents(resources ?? {});
       const resumeOpts = events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : void 0;
       const observer = extractRunObserver(resources ?? {});
-      for (const slot of agentInternals.resolvedProviders.values()) {
-        if (slot !== null && typeof slot === "object" && typeof slot["bindObserver"] === "function") {
-          slot.bindObserver(observer ?? NOOP_OBSERVER);
-        }
-      }
-      const setStepContextSlots = [];
-      for (const slot of agentInternals.resolvedProviders.values()) {
-        if (slot !== null && typeof slot === "object" && typeof slot["setStepContext"] === "function") {
-          setStepContextSlots.push(slot);
-        }
-      }
-      return makeAgentResumeHandle(response, sessionId, interruptId, resumeOpts, observer ?? void 0, setStepContextSlots.length > 0 ? setStepContextSlots : void 0);
+      const onObserverError = extractRunErrorSink(resources ?? {});
+      const telemetrySlots = buildTelemetrySlots(agentInternals.resolvedProviders.entries());
+      return makeAgentResumeHandle(response, sessionId, interruptId, resumeOpts, observer ?? void 0, onObserverError ?? void 0, telemetrySlots.length > 0 ? telemetrySlots : void 0);
     },
     status: (sessionId) => querySessionPhase(capturedStore, id, sessionId),
     [_agentInternals]: agentInternals
   };
   return agent;
 }
-
-// src/agent/observer.ts
-function composeObservers(...observers) {
-  return {
-    onRunStart: (ctx) => {
-      for (const o of observers) o.onRunStart?.(ctx);
-    },
-    onRunEnd: (ctx, event) => {
-      for (const o of observers) o.onRunEnd?.(ctx, event);
-    },
-    onStepStart: (ctx) => {
-      for (const o of observers) o.onStepStart?.(ctx);
-    },
-    onStepEnd: (ctx, event) => {
-      for (const o of observers) o.onStepEnd?.(ctx, event);
-    },
-    onStepError: (ctx, event) => {
-      for (const o of observers) o.onStepError?.(ctx, event);
-    },
-    onInterrupt: (ctx, event) => {
-      for (const o of observers) o.onInterrupt?.(ctx, event);
-    },
-    onEvent: (ctx, type, payload) => {
-      for (const o of observers) o.onEvent?.(ctx, type, payload);
-    }
-  };
-}
 export {
   LeaseExpiredError,
   LoopNotDefinedError,
@@ -1560,6 +1942,8 @@ export {
   createAgent,
   createHarness,
   field,
+  isForkCursor,
+  isForkDef,
   isRequiredMarker,
   isRuntimeMarker,
   required,