@noetaris/harness 0.11.0 → 0.13.0

package/dist/index.js

@@ -564,6 +564,9 @@ function composeObservers(observers, onObserverError) {
     onStepSettled: (ctx, event) => {
       for (const o of observers) safeInvoke("onStepSettled", () => o.onStepSettled?.(ctx, event), onObserverError);
     },
+    onCheckpoint: (ctx, event) => {
+      for (const o of observers) safeInvoke("onCheckpoint", () => o.onCheckpoint?.(ctx, event), onObserverError);
+    },
     // Each observer isolated on its own; later keys win.
     carry: (ctx) => {
       let merged;
@@ -634,16 +637,14 @@ function extractRunListeners(resources) {
 // src/agent/ctx-within.ts
 function createWithinFn(observer, currentStep, onObserverError) {
   return (type, payload, fn) => {
-    const wrap = observer?.wrap;
     const stepCtx = currentStep();
-    if (wrap === void 0 || stepCtx === null) return fn();
-    return runWrapped((inner) => wrap(stepCtx, { kind: "event", type, payload }, inner), fn, onObserverError);
+    if (observer?.wrap === void 0 || stepCtx === null) return fn();
+    return runWrapped((inner) => observer.wrap?.(stepCtx, { kind: "event", type, payload }, inner), fn, onObserverError);
   };
 }
 function runStepScope(observer, stepCtx, fn, onObserverError) {
-  const wrap = observer?.wrap;
-  if (wrap === void 0) return fn();
-  return runWrapped((inner) => wrap(stepCtx, { kind: "step" }, inner), fn, onObserverError);
+  if (observer?.wrap === void 0) return fn();
+  return runWrapped((inner) => observer.wrap?.(stepCtx, { kind: "step" }, inner), fn, onObserverError);
 }
 
 // src/loop/loop-executor.ts
@@ -707,10 +708,9 @@ function applyUpdate(state, update, schema, touchedKeys) {
   }
 }
 function fireSettled(obs, stepCtx, stepStart, fields, onObserverError) {
-  const hook = obs?.onStepSettled;
-  if (hook === void 0) return;
+  if (obs?.onStepSettled === void 0) return;
   const event = { ...fields, durationMs: Date.now() - stepStart };
-  safeInvoke("onStepSettled", () => hook(stepCtx, event), onObserverError);
+  safeInvoke("onStepSettled", () => obs.onStepSettled?.(stepCtx, event), onObserverError);
 }
 function stepContextOf(runCtx, stepName) {
   return {
@@ -769,12 +769,39 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
   ctx["within"] = createWithinFn(obs, () => stepCtxRef.current, onObserverError);
   const telemetryObserver = obs !== void 0 ? composeObservers([obs], onObserverError) : NOOP_OBSERVER;
   let cursor = startCursor ?? graph.entryStep;
+  let first = true;
   try {
-    while (true) {
+    for (; ; first = false) {
       if (shouldStop?.()) {
         endRun("$stopped");
         return withCarrier({ state, signal: null, cursor, paused: true });
       }
+      if (callbacks?.debugGate !== void 0) {
+        const next = isForkCursor(cursor) ? cursor.fork : cursor;
+        const fork = isForkCursor(cursor) || graph.steps.some((s) => s.name === next && isForkDef(s));
+        const { patches, halt } = await callbacks.debugGate(next, state, {
+          branchPath: branchPath ?? [],
+          fork,
+          ...callbacks.touchedKeys !== void 0 ? { touchedKeys: callbacks.touchedKeys } : {},
+          ...ctx.signal !== void 0 ? { signal: ctx.signal } : {}
+        });
+        const nextCtx = stepContextOf(runCtx, next);
+        for (const patch of patches) {
+          safeInvoke("onEvent", () => obs?.onEvent?.(nextCtx, "debug.setState", { patch }), onObserverError);
+        }
+        if (halt || shouldStop?.()) {
+          endRun("$stopped");
+          return withCarrier({ state, signal: null, cursor, paused: true });
+        }
+      }
+      if (!first && callbacks?.checkpoint !== void 0 && typeof cursor === "string") {
+        const started = Date.now();
+        const saved = await callbacks.checkpoint(cursor, state, carrier);
+        if (saved !== void 0) {
+          const event = { step: cursor, version: saved.version, durationMs: Date.now() - started };
+          safeInvoke("onCheckpoint", () => obs?.onCheckpoint?.(runCtx, event), onObserverError);
+        }
+      }
       if (isForkCursor(cursor)) {
         const forkCursor = cursor;
         const forkNode = graph.steps.find((s) => s.name === forkCursor.fork);
@@ -961,7 +988,7 @@ async function dispatchFork(forkNode, priorBranches, outerState, outerCtx, schem
   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 { onBeforeStep: _outerOnBeforeStep, onAfterStep: _outerOnAfterStep, onComplete: _outerOnComplete, checkpoint: _outerCheckpoint, ...branchCallbacksRest } = callbacks ?? {};
   const branchCallbacksBase = callbacks !== void 0 ? branchCallbacksRest : void 0;
   const settled = await Promise.allSettled(
     forkNode.branches.map(async (branch, i) => {
@@ -1028,6 +1055,7 @@ async function dispatchFork(forkNode, priorBranches, outerState, outerCtx, schem
       } else {
         outerState[key] = outcome.result.state[key];
       }
+      callbacks?.touchedKeys?.add(key);
     }
   }
   return {
@@ -1093,6 +1121,13 @@ function defaultClaimTtlMs() {
   const ttlMs = Number(process.env["HARNESS_CLAIM_TTL_MS"]);
   return isValidTtlMs(ttlMs) ? ttlMs : 3e4;
 }
+function isCheckpointMode(value) {
+  return value === "off" || value === "step";
+}
+async function saveRun(store, agentId, sessionId, run, lease) {
+  if (lease !== null && lease !== void 0) await store.save(agentId, sessionId, run, { lease });
+  else await store.save(agentId, sessionId, run);
+}
 function collectPendingInterrupts(cursor, state) {
   if (cursor !== void 0 && isForkCursor(cursor)) {
     const result = [];
@@ -1114,14 +1149,23 @@ function storedSessionToPhase(loaded) {
   if (loaded === null) {
     return { phase: "fresh" };
   }
+  const step = loaded.step === void 0 ? "" : isForkCursor(loaded.step) ? loaded.step.fork : loaded.step;
   if (loaded.phase === "paused") {
-    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, pendingInterrupts };
     }
     return { phase: "paused", step, pendingInterrupts };
   }
+  if (loaded.phase === "running") {
+    const instanceId = loaded.metadata?.instanceId;
+    return {
+      phase: "running",
+      step,
+      ...instanceId !== void 0 ? { instanceId } : {},
+      checkpointedAt: loaded.settledAt
+    };
+  }
   if (loaded.signal !== void 0) {
     return { phase: "completed", signal: loaded.signal };
   }
@@ -1183,6 +1227,15 @@ var SessionInFlightError = class extends Error {
     this.sessionId = sessionId;
   }
 };
+var SessionInDebugError = class extends Error {
+  /** The session being debugged. */
+  sessionId;
+  constructor(sessionId) {
+    super(`session "${sessionId}" is being debugged`);
+    this.name = "SessionInDebugError";
+    this.sessionId = sessionId;
+  }
+};
 var SessionPendingInterruptError = class extends Error {
   /** The session that is awaiting an interrupt response. */
   sessionId;
@@ -1213,12 +1266,19 @@ var SessionBusyError = class extends Error {
 var LeaseExpiredError = class extends Error {
   /** The session whose lease expired. */
   sessionId;
-  constructor(sessionId) {
+  constructor(sessionId, cause) {
     super(`lease for session "${sessionId}" has expired \u2014 run stopped without saving`);
     this.name = "LeaseExpiredError";
     this.sessionId = sessionId;
+    if (cause !== void 0) this.cause = cause;
   }
 };
+function isLeaseLost(error) {
+  return error instanceof Error && error.name === "LeaseLostError";
+}
+function isConflict(error) {
+  return error instanceof Error && error.name === "ConcurrentModificationError";
+}
 
 // src/agent/ctx-keep-alive.ts
 function createKeepAliveFn(leaseRef, store, originalTtlMs) {
@@ -1328,7 +1388,7 @@ async function runWithSession(store, agentId, sessionId, runId, graph, initialSt
     }
     return false;
   };
-  const { mode = "run", requestId: callerRequestId, ...loopOptions } = options ?? {};
+  const { mode = "run", requestId: callerRequestId, checkpoint: checkpointMode = "off", ...loopOptions } = options ?? {};
   if (store === void 0) {
     const state2 = initializeState(null, initialStateArg, schema);
     const result2 = await runLoop(graph, state2, ctx, schema, composedShouldStop, void 0, {
@@ -1369,7 +1429,7 @@ async function runWithSession(store, agentId, sessionId, runId, graph, initialSt
       state: row.finalState,
       signal: row.signal ?? null,
       cursor: row.step ?? null,
-      paused: row.phase === "paused"
+      paused: row.phase !== "completed"
     };
   }
   const segmentRequestId = mode === "run" ? requestId : loaded?.requestId;
@@ -1378,8 +1438,47 @@ async function runWithSession(store, agentId, sessionId, runId, graph, initialSt
   const state = initializeState(base, input, schema);
   const initialStateSnapshot = { ...state };
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const metadata = options?.instanceId !== void 0 ? { instanceId: options.instanceId } : void 0;
+  let nextVersion = (loaded?.version ?? -1) + 1;
+  const baseRow = (carrier) => ({
+    agentId,
+    runId,
+    sessionId,
+    version: nextVersion,
+    startedAt,
+    settledAt: (/* @__PURE__ */ new Date()).toISOString(),
+    initialState: initialStateSnapshot,
+    ...metadata !== void 0 ? { metadata } : {},
+    ...carrier !== void 0 ? { carrier } : {},
+    ...segmentRequestId !== void 0 ? { requestId: segmentRequestId } : {}
+  });
+  const checkpoint = async (next, live, carrier) => {
+    let finalState;
+    try {
+      finalState = structuredClone(live);
+    } catch (error) {
+      options?.onStoreError?.(error, "checkpoint");
+      return void 0;
+    }
+    const row = { ...baseRow(carrier), phase: "running", step: next, finalState };
+    try {
+      await saveRun(store, agentId, sessionId, row, leaseRef.current);
+    } catch (error) {
+      if (isLeaseLost(error) || isConflict(error)) {
+        const expiredError = new LeaseExpiredError(sessionId, error);
+        options?.onStoreError?.(expiredError, "claim");
+        throw expiredError;
+      }
+      options?.onStoreError?.(error, "checkpoint");
+      return void 0;
+    }
+    nextVersion++;
+    await extendLease(store, leaseRef, options?.claimTtlMs ?? defaultClaimTtlMs());
+    return { version: row.version };
+  };
   const result = await runLoop(graph, state, ctx, schema, composedShouldStop, loaded?.step, {
     ...loopOptions,
+    ...checkpointMode === "step" ? { checkpoint } : {},
     runId,
     ...options?.parentRunId !== void 0 ? { parentRunId: options.parentRunId } : {},
     ...segmentRequestId !== void 0 ? { requestId: segmentRequestId } : {},
@@ -1390,53 +1489,39 @@ async function runWithSession(store, agentId, sessionId, runId, graph, initialSt
     options?.onStoreError?.(expiredError, "claim");
     throw expiredError;
   }
-  const settledAt = (/* @__PURE__ */ new Date()).toISOString();
-  const metadata = options?.instanceId !== void 0 ? { instanceId: options.instanceId } : void 0;
+  const saved = {
+    ...baseRow(result.carrier),
+    phase: result.paused ? "paused" : "completed",
+    finalState: result.state,
+    ...result.paused ? { step: result.cursor } : {},
+    ...result.signal !== null ? { signal: result.signal } : {}
+  };
   try {
-    const version = (loaded?.version ?? -1) + 1;
-    if (result.paused) {
-      const saved = {
-        agentId,
-        runId,
-        sessionId,
-        version,
-        startedAt,
-        settledAt,
-        phase: "paused",
-        initialState: initialStateSnapshot,
-        finalState: result.state,
-        step: result.cursor,
-        ...result.signal !== null ? { signal: result.signal } : {},
-        ...metadata !== void 0 ? { metadata } : {},
-        ...result.carrier !== void 0 ? { carrier: result.carrier } : {},
-        ...segmentRequestId !== void 0 ? { requestId: segmentRequestId } : {}
-      };
-      await store.save(agentId, sessionId, saved);
-    } else {
-      const saved = {
-        agentId,
-        runId,
-        sessionId,
-        version,
-        startedAt,
-        settledAt,
-        phase: "completed",
-        initialState: initialStateSnapshot,
-        finalState: result.state,
-        ...result.signal !== null ? { signal: result.signal } : {},
-        ...metadata !== void 0 ? { metadata } : {},
-        ...result.carrier !== void 0 ? { carrier: result.carrier } : {},
-        ...segmentRequestId !== void 0 ? { requestId: segmentRequestId } : {}
-      };
-      await store.save(agentId, sessionId, saved);
-    }
+    await saveRun(store, agentId, sessionId, saved, leaseRef.current);
   } catch (error) {
+    if (isLeaseLost(error)) {
+      const expiredError = new LeaseExpiredError(sessionId, error);
+      options?.onStoreError?.(expiredError, "claim");
+      throw expiredError;
+    }
     options?.onStoreError?.(error, "persist");
   }
   return result;
 }
+async function extendLease(store, leaseRef, ttlMs) {
+  const held = leaseRef.current;
+  if (held === null || typeof store.extendClaim !== "function") return;
+  try {
+    leaseRef.current = await store.extendClaim(held, { ttlMs });
+  } catch {
+  }
+}
 
 // src/agent/claim-scope.ts
+function heldLease(options) {
+  const lease = options.leaseRef?.current ?? null;
+  return lease !== null ? { lease } : {};
+}
 function failOutcome(failState, error) {
   const state = failState();
   state["$error"] = error;
@@ -1530,7 +1615,7 @@ function injectInterruptResponseIntoState(cursor, state, interruptId, response)
     found: true
   };
 }
-async function injectInterruptResponse(store, agentId, sessionId, interruptId, response) {
+async function injectInterruptResponse(store, agentId, sessionId, interruptId, response, lease) {
   const loaded = await store.load(agentId, sessionId);
   if (loaded === null) throw new NoInterruptError();
   if (loaded.phase !== "paused") throw new NoInterruptError();
@@ -1553,14 +1638,19 @@ async function injectInterruptResponse(store, agentId, sessionId, interruptId, r
     ...loaded.branchedFrom !== void 0 ? { branchedFrom: loaded.branchedFrom } : {},
     ...loaded.requestId !== void 0 ? { requestId: loaded.requestId } : {}
   };
-  await store.save(agentId, sessionId, updated);
+  await saveRun(store, agentId, sessionId, updated, lease);
 }
 async function injectThenRun(args) {
-  const { store, agentId, sessionId, interruptId, response, onStoreError, failState, run } = args;
+  const { store, agentId, sessionId, interruptId, response, lease, onStoreError, failState, run } = args;
   try {
-    await injectInterruptResponse(store, agentId, sessionId, interruptId, response);
+    await injectInterruptResponse(store, agentId, sessionId, interruptId, response, lease);
   } catch (injectError) {
     if (injectError instanceof NoInterruptError) throw injectError;
+    if (isLeaseLost(injectError)) {
+      const expiredError = new LeaseExpiredError(sessionId, injectError);
+      onStoreError?.(expiredError, "claim");
+      return failOutcome(failState, expiredError);
+    }
     const storeError = new StoreLoadError(injectError);
     onStoreError?.(storeError, "claim");
     return failOutcome(failState, storeError);
@@ -1617,6 +1707,572 @@ function createRunHandle(sessionId, runId, execution, stopFlag, stepRef, resumeF
   return handle;
 }
 
+// src/agent/debug-session.ts
+var DebugCommandError = class extends Error {
+  /**
+   * - `busy`: another command is still running
+   * - `not-held`: the focused frame is not held at a step stop (or, for `answer`, the session is not at
+   *   an interrupt stop; for `focus`, the frame is not held)
+   * - `not-a-fork`: `stepInto` where the next step is not a fork node
+   * - `reserved-key`: `setState` was given a framework key (`$…`)
+   * - `ended`: the session is over
+   */
+  reason;
+  /** The command that was refused. */
+  command;
+  constructor(reason, command, detail) {
+    super(`${command}(): ${detail ?? describeReason(reason)}`);
+    this.name = "DebugCommandError";
+    this.reason = reason;
+    this.command = command;
+  }
+};
+function describeReason(reason) {
+  switch (reason) {
+    case "busy":
+      return "another debug command is still running";
+    case "not-held":
+      return "the debug session is not stopped where this command applies";
+    case "not-a-fork":
+      return "the next step is not a fork";
+    case "reserved-key":
+      return "framework keys ($\u2026) cannot be set";
+    case "ended":
+      return "the debug session has ended";
+  }
+}
+function cloneOrShare(value) {
+  try {
+    return { value: structuredClone(value), shared: false };
+  } catch {
+    return { value, shared: true };
+  }
+}
+function snapshotOf(source) {
+  const values = {};
+  const shared = [];
+  for (const [key, raw] of Object.entries(source)) {
+    const copy = cloneOrShare(raw);
+    values[key] = copy.value;
+    if (copy.shared) shared.push(key);
+  }
+  return { values, shared };
+}
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  promise.catch(() => {
+  });
+  return { promise, resolve, reject };
+}
+var keyOf = (path) => JSON.stringify(path);
+var samePath = (a, b) => a.length === b.length && a.every((s, i) => s === b[i]);
+var within = (path, root) => path.length >= root.length && root.every((s, i) => s === path[i]);
+function branchStart(parentForkMode) {
+  return {
+    mode: parentForkMode === "fork-entry" ? "fork-entry" : "continue",
+    lastRelease: parentForkMode === "continue" || parentForkMode === void 0 ? "continue" : "hold"
+  };
+}
+function createDebugSession(args) {
+  const { store, signal, onEnd } = args;
+  let status = "starting";
+  let handle;
+  let topMode = "start";
+  let frames = /* @__PURE__ */ new Map();
+  let seq = 0;
+  let focus = [];
+  let lastByFrame = /* @__PURE__ */ new Map();
+  let topInterrupt;
+  let interrupts = [];
+  let pausedForks = /* @__PURE__ */ new Map();
+  let paused;
+  let stopRequested = false;
+  let lease = {};
+  let renewal;
+  const breakpoints = /* @__PURE__ */ new Map();
+  let command;
+  let idle;
+  const first = deferred();
+  let current = first.promise;
+  let started = false;
+  const ended = deferred();
+  const done = deferred();
+  const anyHeld = () => [...frames.values()].some((f) => f.status === "held");
+  const updateRenewal = () => {
+    if (!anyHeld()) {
+      if (renewal !== void 0) clearInterval(renewal);
+      renewal = void 0;
+      return;
+    }
+    if (renewal !== void 0) return;
+    const { leaseRef, claimTtlMs } = lease;
+    const extendClaim = store?.extendClaim;
+    if (leaseRef === void 0 || claimTtlMs === void 0 || typeof extendClaim !== "function") return;
+    const renew = () => {
+      const held = leaseRef.current;
+      if (held === null) return;
+      extendClaim.call(store, held, { ttlMs: claimTtlMs }).then((renewed) => {
+        leaseRef.current = renewed;
+      }, () => {
+      });
+    };
+    renew();
+    renewal = setInterval(renew, claimTtlMs / 3);
+    renewal.unref?.();
+  };
+  const frameOf = (path) => frames.get(keyOf(path));
+  const addFrame = (path, init) => {
+    const frame = { path, seq: seq++, patches: [], ...init };
+    frames.set(keyOf(path), frame);
+    return frame;
+  };
+  const treeOrder = (a, b) => {
+    const n = Math.min(a.path.length, b.path.length);
+    for (let i = 0; i < n; i++) {
+      if (a.path[i] !== b.path[i]) {
+        const sa = frameOf(a.path.slice(0, i + 1))?.seq ?? 0;
+        const sb = frameOf(b.path.slice(0, i + 1))?.seq ?? 0;
+        return sa - sb;
+      }
+    }
+    return a.path.length - b.path.length;
+  };
+  const sortedFrames = () => [...frames.values()].sort(treeOrder);
+  const dropDescendants = (root) => {
+    for (const [key, frame] of frames) {
+      if (frame.path.length > root.length && within(frame.path, root)) frames.delete(key);
+    }
+  };
+  const seedPausedFork = (frame, forkName) => {
+    const settled = pausedForks.get(keyOf(frame.path));
+    if (settled?.fork === void 0 || settled.name !== forkName) return;
+    pausedForks.delete(keyOf(frame.path));
+    for (const branch of settled.fork.branches) {
+      addFrame([...frame.path, branch.name], { status: branch.status === "done" ? "ended" : "running", ...branchStart(frame.forkMode) });
+    }
+  };
+  const setCurrent = (stop) => {
+    current = Promise.resolve(stop);
+    if (!started) {
+      started = true;
+      first.resolve(stop);
+    }
+  };
+  const deliver = (stop, frame) => {
+    focus = frame;
+    setCurrent(stop);
+    const c = command;
+    command = void 0;
+    c?.result.resolve(stop);
+    const w = idle;
+    idle = void 0;
+    w?.resolve(stop);
+  };
+  const offerStop = (stop) => {
+    if (!started) return deliver(stop, stop.frame);
+    if (command !== void 0) {
+      const { target, orphan } = command;
+      if (target === "any" || orphan !== void 0 || within(stop.frame, target)) deliver(stop, stop.frame);
+      return;
+    }
+    if (idle !== void 0) deliver(stop, stop.frame);
+  };
+  const branchEndStop = (frame, endedFrame) => {
+    const held = frame.stop;
+    const stop = {
+      kind: "step",
+      frame: frame.path,
+      reason: "branch-end",
+      ended: endedFrame,
+      runId: held.runId,
+      next: held.next,
+      ...held.last !== void 0 ? { last: held.last } : {},
+      state: held.state
+    };
+    frame.stop = stop;
+    return stop;
+  };
+  const afterFrameEnd = (endedFrame) => {
+    setTimeout(() => {
+      if (status !== "active") return;
+      const heldFrame = sortedFrames().find((f) => f.status === "held");
+      if (command !== void 0) {
+        if (command.orphan !== endedFrame) return;
+        if (heldFrame !== void 0) deliver(branchEndStop(heldFrame, endedFrame), heldFrame.path);
+        return;
+      }
+      if (!samePath(focus, endedFrame.frame)) return;
+      if (heldFrame !== void 0) {
+        focus = heldFrame.path;
+        setCurrent(branchEndStop(heldFrame, endedFrame));
+      } else {
+        idle ??= deferred();
+        current = idle.promise;
+      }
+    }, 0);
+  };
+  const onFrameEnd = (path, signal2) => {
+    const frame = frameOf(path);
+    if (frame === void 0) return;
+    frame.status = "ended";
+    const parent = frameOf(path.slice(0, -1));
+    if (parent !== void 0) parent.joinHold = frame.lastRelease === "hold";
+    const outcome = signal2 === "$interrupt" ? "interrupt" : signal2 === "$error" ? "error" : signal2 === "$stopped" ? "stopped" : "done";
+    const last = lastByFrame.get(keyOf(path));
+    const endedFrame = { frame: path, outcome, ...last !== void 0 ? { last } : {} };
+    updateRenewal();
+    if (command !== void 0) {
+      if (command.target !== "any" && samePath(command.target, path)) {
+        command.orphan = endedFrame;
+        afterFrameEnd(endedFrame);
+      }
+      return;
+    }
+    if (samePath(focus, path)) afterFrameEnd(endedFrame);
+  };
+  const onAbort = () => {
+    void session.stop();
+  };
+  const cleanup = () => {
+    for (const frame of frames.values()) if (frame.status === "held") frame.status = "ended";
+    updateRenewal();
+    signal?.removeEventListener("abort", onAbort);
+    onEnd();
+  };
+  const topLast = () => lastByFrame.get(keyOf([]));
+  const finish = (outcome) => {
+    const last = topLast();
+    const stop = { kind: "end", runId: handle.runId, ...last !== void 0 ? { last } : {}, outcome };
+    status = "ended";
+    cleanup();
+    done.resolve(outcome);
+    deliver(stop, []);
+    ended.resolve(stop);
+  };
+  const fail = (error) => {
+    status = "ended";
+    cleanup();
+    done.reject(error);
+    const c = command;
+    command = void 0;
+    c?.result.reject(error);
+    const w = idle;
+    idle = void 0;
+    w?.reject(error);
+    if (!started) first.reject(error);
+    else current = done.promise.then(() => {
+      throw error;
+    });
+    current.catch(() => {
+    });
+    ended.reject(error);
+  };
+  const pendingInterrupts = () => {
+    const pending = [];
+    const walk = (path) => {
+      const settled = lastByFrame.get(keyOf(path));
+      if (settled?.fork === void 0) return;
+      for (const branch of settled.fork.branches) {
+        if (branch.status !== "paused") continue;
+        const branchPath = [...path, branch.name];
+        const raised = interrupts.find((i) => samePath(i.branchPath, branchPath));
+        if (raised !== void 0) pending.push({ interruptId: raised.interruptId, prompt: raised.prompt, frame: branchPath });
+        else walk(branchPath);
+      }
+    };
+    if (topInterrupt !== void 0 && topLast()?.fork === void 0) {
+      pending.push({ interruptId: topInterrupt.interruptId, prompt: topInterrupt.prompt, frame: [] });
+    } else {
+      walk([]);
+    }
+    return pending;
+  };
+  const attach = (h) => {
+    h.then((outcome) => {
+      const last = topLast();
+      if (outcome.signal === "$interrupt" && !stopRequested && last !== void 0) {
+        const pending = pendingInterrupts();
+        const head = pending[0];
+        if (head !== void 0) {
+          status = "interrupt";
+          paused = { outcome, pending };
+          for (const frame of frames.values()) if (frame.status === "held") frame.status = "ended";
+          updateRenewal();
+          deliver({
+            kind: "interrupt",
+            frame: head.frame,
+            runId: h.runId,
+            last,
+            interruptId: head.interruptId,
+            prompt: head.prompt,
+            pending,
+            state: snapshotOf(outcome.state)
+          }, head.frame);
+          return;
+        }
+      }
+      finish(outcome);
+    }, fail);
+  };
+  const gate = async (next, state, info) => {
+    const path = info.branchPath;
+    let frame = frameOf(path);
+    if (frame === void 0) {
+      if (path.length === 0) {
+        frame = addFrame(path, { status: "running", mode: topMode, lastRelease: "hold" });
+      } else {
+        frame = addFrame(path, { status: "running", ...branchStart(frameOf(path.slice(0, -1))?.forkMode) });
+      }
+    } else if (frame.status === "in-fork") {
+      dropDescendants(path);
+      frame.mode = frame.joinHold === false ? "continue" : "step";
+      frame.joinHold = void 0;
+      frame.forkMode = void 0;
+    }
+    if (info.signal?.aborted === true) return { patches: [], halt: true };
+    let reason;
+    let condition;
+    if (frame.mode !== "continue") {
+      reason = frame.mode;
+    } else {
+      const breakpoint = breakpoints.get(next);
+      if (breakpoint !== void 0) {
+        try {
+          if (breakpoint.when === void 0 || breakpoint.when(state)) reason = "breakpoint";
+        } catch (error) {
+          reason = "breakpoint";
+          condition = { error };
+        }
+      }
+    }
+    const enter = () => {
+      frame.before = snapshotOf(state);
+      if (info.fork) {
+        frame.status = "in-fork";
+        frame.forkMode ??= frame.mode === "continue" ? "continue" : "over";
+        seedPausedFork(frame, next);
+      } else {
+        frame.status = "running";
+      }
+    };
+    if (reason === void 0) {
+      enter();
+      return { patches: [], halt: false };
+    }
+    frame.status = "held";
+    frame.next = next;
+    frame.isFork = info.fork;
+    frame.live = state;
+    frame.forkMode = void 0;
+    if (info.touchedKeys !== void 0) frame.touched = info.touchedKeys;
+    const last = lastByFrame.get(keyOf(path));
+    const stop = {
+      kind: "step",
+      frame: path,
+      reason,
+      runId: handle.runId,
+      next,
+      ...last !== void 0 ? { last } : {},
+      state: snapshotOf(state),
+      ...condition !== void 0 ? { conditionError: condition.error } : {}
+    };
+    frame.stop = stop;
+    const released = new Promise((resolve) => {
+      frame.release = resolve;
+    });
+    const onHalt = () => {
+      frame.release?.({ patches: [], halt: true });
+    };
+    info.signal?.addEventListener("abort", onHalt);
+    updateRenewal();
+    offerStop(stop);
+    const result = await released;
+    info.signal?.removeEventListener("abort", onHalt);
+    frame.release = void 0;
+    frame.live = void 0;
+    if (!result.halt) enter();
+    updateRenewal();
+    return result;
+  };
+  const release = (frame, how, halt = false) => {
+    if (!halt) {
+      frame.mode = how === "next" ? "step" : "continue";
+      frame.lastRelease = how === "next" || how === "stepInto" ? "hold" : "continue";
+      if (frame.isFork === true) frame.forkMode = how === "stepInto" ? "fork-entry" : how === "next" ? "over" : "continue";
+      frame.status = frame.isFork === true ? "in-fork" : "running";
+    }
+    const patches = frame.patches;
+    frame.patches = [];
+    const r = frame.release;
+    frame.release = void 0;
+    r?.({ patches, halt });
+  };
+  const observer = {
+    onStepSettled: (ctx, e) => {
+      const path = ctx.branchPath ?? [];
+      if (path.length === 0) {
+        topInterrupt = e.interrupt !== void 0 ? { interruptId: e.interrupt.interruptId, prompt: e.interrupt.prompt, branchPath: [] } : void 0;
+      }
+      lastByFrame.set(keyOf(path), {
+        name: ctx.stepName,
+        outcome: e.outcome,
+        ...e.update !== void 0 ? { update: snapshotOf(e.update) } : {},
+        ...e.signal !== void 0 ? { signal: e.signal } : {},
+        next: e.next,
+        ...e.error !== void 0 ? { error: e.error } : {},
+        before: frameOf(path)?.before ?? { values: {}, shared: [] },
+        durationMs: e.durationMs,
+        ...e.fork !== void 0 ? { fork: e.fork } : {}
+      });
+    },
+    onInterrupt: (ctx, e) => {
+      interrupts.push({ interruptId: e.interruptId, prompt: e.prompt, branchPath: ctx.branchPath ?? [] });
+    },
+    onRunEnd: (ctx, e) => {
+      if (ctx.branchPath !== void 0) onFrameEnd(ctx.branchPath, e.signal);
+    }
+  };
+  const refuse = (name) => {
+    if (status === "ended") return new DebugCommandError("ended", name);
+    if (status === "starting" || !started || command !== void 0) return new DebugCommandError("busy", name);
+    if (status === "interrupt" && name !== "answer") return new DebugCommandError("not-held", name);
+    if (status === "active" && name === "answer") return new DebugCommandError("not-held", name);
+    return void 0;
+  };
+  const issue = (target) => {
+    const result = deferred();
+    command = { target, result };
+    return result.promise;
+  };
+  const drive = (how) => {
+    const refused = refuse(how);
+    if (refused !== void 0) return Promise.reject(refused);
+    const frame = frameOf(focus);
+    if (frame === void 0 || frame.status !== "held") return Promise.reject(new DebugCommandError("not-held", how));
+    if (how === "stepInto" && frame.isFork !== true) return Promise.reject(new DebugCommandError("not-a-fork", how));
+    const p = issue(frame.path);
+    release(frame, how);
+    updateRenewal();
+    return p;
+  };
+  const session = {
+    get sessionId() {
+      return handle.sessionId;
+    },
+    get runId() {
+      return handle.runId;
+    },
+    get current() {
+      return current;
+    },
+    get done() {
+      return done.promise;
+    },
+    get breakpoints() {
+      return [...breakpoints.values()];
+    },
+    get frames() {
+      return sortedFrames().map((f) => ({ frame: f.path, status: f.status, ...f.status === "held" && f.next !== void 0 ? { next: f.next } : {} }));
+    },
+    focus: (path) => {
+      const frame = frameOf(path);
+      if (status !== "active" || frame === void 0 || frame.status !== "held" || frame.stop === void 0) {
+        throw new DebugCommandError("not-held", "focus");
+      }
+      focus = frame.path;
+      setCurrent(frame.stop);
+      return frame.stop;
+    },
+    next: () => drive("next"),
+    continue: () => drive("continue"),
+    stepInto: () => drive("stepInto"),
+    continueAll: () => {
+      const refused = refuse("continueAll");
+      if (refused !== void 0) return Promise.reject(refused);
+      const p = issue("any");
+      for (const frame of sortedFrames()) if (frame.status === "held") release(frame, "continueAll");
+      updateRenewal();
+      return p;
+    },
+    answer: (response, id) => {
+      const at = paused;
+      const refused = refuse("answer") ?? (at === void 0 ? new DebugCommandError("not-held", "answer") : void 0);
+      if (refused !== void 0 || at === void 0) return Promise.reject(refused);
+      const target = id ?? at.pending[0].interruptId;
+      if (!at.pending.some((p2) => p2.interruptId === target)) return Promise.reject(new NoInterruptError());
+      let resumed;
+      try {
+        resumed = handle.resume(response, target);
+      } catch (error) {
+        return Promise.reject(error);
+      }
+      pausedForks = new Map([...lastByFrame].filter(([, s]) => s.fork !== void 0 && (s.outcome === "interrupt" || s.outcome === "stopped")));
+      handle = resumed;
+      paused = void 0;
+      status = "active";
+      topMode = "resume";
+      frames = /* @__PURE__ */ new Map();
+      focus = [];
+      lastByFrame = /* @__PURE__ */ new Map();
+      topInterrupt = void 0;
+      interrupts = [];
+      lease = {};
+      const p = issue([]);
+      attach(handle);
+      return p;
+    },
+    setState: (patch) => {
+      if (status === "ended") throw new DebugCommandError("ended", "setState");
+      const frame = frameOf(focus);
+      if (status !== "active" || frame === void 0 || frame.status !== "held" || frame.live === void 0) {
+        throw new DebugCommandError("not-held", "setState");
+      }
+      const reserved = Object.keys(patch).find((k) => k.startsWith("$"));
+      if (reserved !== void 0) throw new DebugCommandError("reserved-key", "setState", `framework key "${reserved}" cannot be set`);
+      const reported = {};
+      for (const [key, value] of Object.entries(patch)) {
+        frame.live[key] = cloneOrShare(value).value;
+        reported[key] = cloneOrShare(value).value;
+        frame.touched?.add(key);
+      }
+      frame.patches.push(reported);
+      return snapshotOf(frame.live);
+    },
+    setBreakpoint: (step, when) => {
+      breakpoints.set(step, { step, ...when !== void 0 ? { when } : {} });
+    },
+    clearBreakpoint: (step) => {
+      breakpoints.delete(step);
+    },
+    stop: () => {
+      if (status === "ended") return ended.promise;
+      stopRequested = true;
+      if (status === "interrupt" && paused !== void 0) {
+        finish(paused.outcome);
+        return ended.promise;
+      }
+      handle.stop();
+      for (const frame of frames.values()) if (frame.status === "held") release(frame, "continueAll", true);
+      return ended.promise;
+    }
+  };
+  handle = args.start({ gate, observer, onLease: (l) => {
+    lease = l;
+  } });
+  status = "active";
+  attach(handle);
+  if (signal !== void 0) {
+    signal.addEventListener("abort", onAbort);
+    if (signal.aborted) onAbort();
+  }
+  return session;
+}
+
 // src/agent/create-agent.ts
 import { randomUUID } from "crypto";
 
@@ -1738,13 +2394,26 @@ var InvalidClaimOptionsError = class extends Error {
     this.ttlMs = ttlMs;
   }
 };
+var AGENT_OPTION_EXPECTED = { observer: "an object", onObserverError: "a function", checkpoint: "'off' or 'step'" };
+var InvalidAgentOptionError = class extends Error {
+  /** The option that was rejected. */
+  key;
+  /** The rejected value, as given. */
+  value;
+  constructor(key, value) {
+    super(`${key} must be ${AGENT_OPTION_EXPECTED[key]} \u2014 got ${describeValue(value)} in createAgent options`);
+    this.name = "InvalidAgentOptionError";
+    this.key = key;
+    this.value = value;
+  }
+};
 var InvalidRunResourceError = class extends Error {
   /** The resource key that was rejected. */
   key;
   /** The rejected value, as given. */
   value;
   constructor(key, value) {
-    super(`${key} must be a non-empty string \u2014 got ${describeValue(value)} in agent.run() resources`);
+    super(key === "checkpoint" ? `checkpoint must be 'off' or 'step' \u2014 got ${describeValue(value)} in the call's resources` : `${key} must be a non-empty string \u2014 got ${describeValue(value)} in agent.run() resources`);
     this.name = "InvalidRunResourceError";
     this.key = key;
     this.value = value;
@@ -1756,6 +2425,12 @@ function readIdResource(resources, key) {
   if (typeof value !== "string" || value.length === 0) throw new InvalidRunResourceError(key, value);
   return value;
 }
+function readCheckpointResource(resources) {
+  const value = resources["checkpoint"];
+  if (value === void 0) return void 0;
+  if (!isCheckpointMode(value)) throw new InvalidRunResourceError("checkpoint", value);
+  return value;
+}
 var _agentInternals = /* @__PURE__ */ Symbol("_agentInternals");
 function createAgent(id, h, slots, agentOptions) {
   const internals = getInternals(h);
@@ -1793,6 +2468,27 @@ function createAgent(id, h, slots, agentOptions) {
     agentClaimOptions = { ttlMs };
   }
   const fallbackClaimOptions = () => agentClaimOptions ?? { ttlMs: defaultClaimTtlMs() };
+  const agentObserver = agentOptions?.observer;
+  if (agentObserver !== void 0 && (agentObserver === null || typeof agentObserver !== "object" || Array.isArray(agentObserver))) {
+    throw new InvalidAgentOptionError("observer", agentObserver);
+  }
+  const agentErrorSink = agentOptions?.onObserverError;
+  if (agentErrorSink !== void 0 && typeof agentErrorSink !== "function") {
+    throw new InvalidAgentOptionError("onObserverError", agentErrorSink);
+  }
+  const resolveObserver = (resources) => {
+    const runObserver = extractRunObserver(resources);
+    const onObserverError = extractRunErrorSink(resources) ?? agentErrorSink;
+    const observer = agentObserver === void 0 ? runObserver : runObserver === void 0 || runObserver === agentObserver ? agentObserver : composeObservers([agentObserver, runObserver], onObserverError);
+    return {
+      ...observer !== void 0 ? { observer } : {},
+      ...onObserverError !== void 0 ? { onObserverError } : {}
+    };
+  };
+  const agentCheckpoint = agentOptions?.checkpoint;
+  if (agentCheckpoint !== void 0 && !isCheckpointMode(agentCheckpoint)) {
+    throw new InvalidAgentOptionError("checkpoint", agentCheckpoint);
+  }
   const resolvedProviders = /* @__PURE__ */ new Map();
   const storeEntries = [];
   const runtimeKeys = /* @__PURE__ */ new Set();
@@ -1842,12 +2538,13 @@ function createAgent(id, h, slots, agentOptions) {
     runtimeKeys,
     requiredKeys
   };
-  const reservedRunKeys = /* @__PURE__ */ new Set(["sessionId", "requestId", "signal", "events", "listeners", "observer", "onObserverError", "claimOptions", "parentRunId"]);
+  const reservedRunKeys = /* @__PURE__ */ new Set(["sessionId", "requestId", "signal", "events", "listeners", "observer", "onObserverError", "claimOptions", "parentRunId", "checkpoint"]);
   const inFlightSessions = /* @__PURE__ */ new Set();
+  const debugSessions = /* @__PURE__ */ new Set();
   const interruptPendingSessions = /* @__PURE__ */ new Set();
   const resumeFailState = () => initializeState(null, {}, agentInternals.stateSchema);
   const makeAgentResumeHandle = (resp, sId, iId, resumeResources) => {
-    const { onStoreError, observer, onObserverError, telemetrySlots, parentRunId, claimOptions } = resumeResources;
+    const { onStoreError, observer, onObserverError, telemetrySlots, parentRunId, claimOptions, checkpoint } = resumeResources;
     let _stopped = false;
     const abortController = new AbortController();
     const flag = {
@@ -1880,6 +2577,7 @@ function createAgent(id, h, slots, agentOptions) {
               sessionId: sId,
               interruptId: iId,
               response: resp,
+              ...heldLease(lease),
               ...onStoreError !== void 0 ? { onStoreError } : {},
               failState: resumeFailState,
               run: async () => {
@@ -1902,6 +2600,7 @@ function createAgent(id, h, slots, agentOptions) {
                   agentCtx,
                   {
                     mode: "resume",
+                    checkpoint,
                     shouldStop: () => flag.stopped,
                     onBeforeStep: (n) => {
                       ref.current = n;
@@ -1933,266 +2632,280 @@ function createAgent(id, h, slots, agentOptions) {
     };
     return createRunHandle(sId, rId, exec, flag, ref, resumeFn);
   };
-  const agent = {
-    id,
-    run: (initialState, resources) => {
-      for (const key of Object.keys(resources)) {
-        if (reservedRunKeys.has(key)) continue;
-        if (!agentInternals.runtimeKeys.has(key) && !agentInternals.requiredKeys.has(key)) {
-          throw new UnknownRunSlotError(key);
-        }
+  const startRun = (initialState, resources, debug) => {
+    for (const key of Object.keys(resources)) {
+      if (reservedRunKeys.has(key)) continue;
+      if (!agentInternals.runtimeKeys.has(key) && !agentInternals.requiredKeys.has(key)) {
+        throw new UnknownRunSlotError(key);
       }
-      for (const key of Object.keys(resources)) {
-        if (reservedRunKeys.has(key)) continue;
-        if (agentInternals.requiredKeys.has(key)) {
-          throw new RequiredSlotInRunError(key);
-        }
+    }
+    for (const key of Object.keys(resources)) {
+      if (reservedRunKeys.has(key)) continue;
+      if (agentInternals.requiredKeys.has(key)) {
+        throw new RequiredSlotInRunError(key);
       }
-      for (const key of agentInternals.runtimeKeys) {
-        if (!(key in resources)) {
-          throw new MissingRuntimeSlotError(key);
-        }
+    }
+    for (const key of agentInternals.runtimeKeys) {
+      if (!(key in resources)) {
+        throw new MissingRuntimeSlotError(key);
       }
-      const sessionId = readIdResource(resources, "sessionId") ?? randomUUID();
-      const requestId = readIdResource(resources, "requestId");
-      const runId = randomUUID();
-      if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
-      if (capturedStore === void 0 && interruptPendingSessions.has(sessionId)) throw new SessionPendingInterruptError(sessionId);
-      inFlightSessions.add(sessionId);
-      let _stopped = false;
-      const abortController = new AbortController();
-      const stopFlag = {
-        get stopped() {
-          return _stopped;
-        },
-        set stopped(v) {
-          _stopped = v;
-          if (v) abortController.abort();
-        }
-      };
-      const rawSignal = resources["signal"];
-      let ctxSignal = abortController.signal;
-      if (rawSignal instanceof AbortSignal) {
-        ctxSignal = rawSignal;
-        rawSignal.addEventListener("abort", () => {
-          stopFlag.stopped = true;
-          abortController.abort();
-        }, { once: true });
-        if (rawSignal.aborted) stopFlag.stopped = true;
-      }
-      const stepRef = { current: null };
-      const runtimeSlots = {};
-      for (const key of agentInternals.runtimeKeys) {
-        if (reservedRunKeys.has(key)) continue;
-        runtimeSlots[key] = resources[key];
-      }
-      const ctx = {
-        ...Object.fromEntries(agentInternals.resolvedProviders),
-        ...runtimeSlots,
-        agentId: id,
-        sessionId,
-        runId,
-        signal: ctxSignal,
-        ...agentOptions?.instanceId !== void 0 ? { instanceId: agentOptions.instanceId } : {}
-      };
-      const events = extractRunEvents(resources);
-      const listeners = extractRunListeners(resources);
-      const observer = extractRunObserver(resources);
-      const onObserverError = extractRunErrorSink(resources);
-      const telemetrySlots = buildTelemetrySlots([
-        ...agentInternals.resolvedProviders.entries(),
-        ...Object.entries(runtimeSlots)
-      ]);
-      const parentRunId = typeof resources["parentRunId"] === "string" ? resources["parentRunId"] : void 0;
-      const claimOptions = parseClaimOptions(resources["claimOptions"], fallbackClaimOptions());
-      const options = {
-        mode: "run",
-        ...requestId !== void 0 ? { requestId } : {},
-        shouldStop: () => stopFlag.stopped,
-        onBeforeStep: (name, state) => {
-          stepRef.current = name;
-          events.onBeforeStep?.(name, state);
-        },
-        // spread optional event callbacks only when defined (exactOptionalPropertyTypes requires omission, not undefined)
-        ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
-        ...events.onAfterStep !== void 0 ? { onAfterStep: events.onAfterStep } : {},
-        ...events.onError !== void 0 ? { onError: events.onError } : {},
-        ...events.onComplete !== void 0 ? { onComplete: events.onComplete } : {},
-        ...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 } : {},
-        ...telemetrySlots.length > 0 ? { telemetrySlots } : {}
-      };
-      let lastResult = null;
-      const execution = (async () => {
-        await Promise.resolve();
-        try {
-          return await runClaimed({
-            store: capturedStore,
-            agentId: id,
-            sessionId,
-            claimOptions,
-            ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
-            failState: () => initializeState(null, initialState, agentInternals.stateSchema),
-            body: async (lease) => {
-              const r = await runWithSession(
-                capturedStore,
-                id,
+    }
+    const sessionId = readIdResource(resources, "sessionId") ?? randomUUID();
+    const requestId = readIdResource(resources, "requestId");
+    const checkpoint = readCheckpointResource(resources) ?? agentCheckpoint ?? "off";
+    const runId = randomUUID();
+    if (debugSessions.has(sessionId)) throw new SessionInDebugError(sessionId);
+    if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
+    if (capturedStore === void 0 && interruptPendingSessions.has(sessionId)) throw new SessionPendingInterruptError(sessionId);
+    inFlightSessions.add(sessionId);
+    let _stopped = false;
+    const abortController = new AbortController();
+    const stopFlag = {
+      get stopped() {
+        return _stopped;
+      },
+      set stopped(v) {
+        _stopped = v;
+        if (v) abortController.abort();
+      }
+    };
+    const rawSignal = debug === void 0 ? resources["signal"] : void 0;
+    let ctxSignal = abortController.signal;
+    if (rawSignal instanceof AbortSignal) {
+      ctxSignal = rawSignal;
+      rawSignal.addEventListener("abort", () => {
+        stopFlag.stopped = true;
+        abortController.abort();
+      }, { once: true });
+      if (rawSignal.aborted) stopFlag.stopped = true;
+    }
+    const stepRef = { current: null };
+    const runtimeSlots = {};
+    for (const key of agentInternals.runtimeKeys) {
+      if (reservedRunKeys.has(key)) continue;
+      runtimeSlots[key] = resources[key];
+    }
+    const ctx = {
+      ...Object.fromEntries(agentInternals.resolvedProviders),
+      ...runtimeSlots,
+      agentId: id,
+      sessionId,
+      runId,
+      signal: ctxSignal,
+      ...agentOptions?.instanceId !== void 0 ? { instanceId: agentOptions.instanceId } : {}
+    };
+    const events = extractRunEvents(resources);
+    const listeners = extractRunListeners(resources);
+    const resolved = resolveObserver(resources);
+    const onObserverError = resolved.onObserverError;
+    const observer = debug === void 0 ? resolved.observer : resolved.observer === void 0 ? debug.observer : composeObservers([resolved.observer, debug.observer], onObserverError);
+    const telemetrySlots = buildTelemetrySlots([
+      ...agentInternals.resolvedProviders.entries(),
+      ...Object.entries(runtimeSlots)
+    ]);
+    const parentRunId = typeof resources["parentRunId"] === "string" ? resources["parentRunId"] : void 0;
+    const claimOptions = parseClaimOptions(resources["claimOptions"], fallbackClaimOptions());
+    const options = {
+      mode: "run",
+      checkpoint,
+      ...requestId !== void 0 ? { requestId } : {},
+      shouldStop: () => stopFlag.stopped,
+      onBeforeStep: (name, state) => {
+        stepRef.current = name;
+        events.onBeforeStep?.(name, state);
+      },
+      // spread optional event callbacks only when defined (exactOptionalPropertyTypes requires omission, not undefined)
+      ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
+      ...events.onAfterStep !== void 0 ? { onAfterStep: events.onAfterStep } : {},
+      ...events.onError !== void 0 ? { onError: events.onError } : {},
+      ...events.onComplete !== void 0 ? { onComplete: events.onComplete } : {},
+      ...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 } : {},
+      ...telemetrySlots.length > 0 ? { telemetrySlots } : {},
+      ...debug !== void 0 ? { debugGate: debug.gate } : {}
+    };
+    let lastResult = null;
+    const execution = (async () => {
+      await Promise.resolve();
+      try {
+        return await runClaimed({
+          store: capturedStore,
+          agentId: id,
+          sessionId,
+          claimOptions,
+          ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
+          failState: () => initializeState(null, initialState, agentInternals.stateSchema),
+          body: async (lease) => {
+            debug?.onLease(lease);
+            const r = await runWithSession(
+              capturedStore,
+              id,
+              sessionId,
+              runId,
+              agentInternals.loopDef,
+              initialState,
+              agentInternals.stateSchema,
+              ctx,
+              { ...options, ...lease }
+            );
+            if (capturedStore === void 0 && r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
+            lastResult = { state: r.state, cursor: r.cursor, runId, ...r.carrier !== void 0 ? { carrier: r.carrier } : {} };
+            return { state: r.state, signal: r.signal };
+          }
+        });
+      } finally {
+        inFlightSessions.delete(sessionId);
+      }
+    })();
+    const buildResumeFn = () => {
+      return (response, interruptId) => {
+        if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
+        interruptPendingSessions.delete(sessionId);
+        inFlightSessions.add(sessionId);
+        let _resumeStopped = false;
+        const resumeAbortController = new AbortController();
+        const resumeStopFlag = {
+          get stopped() {
+            return _resumeStopped;
+          },
+          set stopped(v) {
+            _resumeStopped = v;
+            if (v) resumeAbortController.abort();
+          }
+        };
+        const resumeStepRef = { current: null };
+        const resumeRunId = randomUUID();
+        const resumeExecution = (async () => {
+          await Promise.resolve();
+          try {
+            const resumeCtx = {
+              ...ctx,
+              runId: resumeRunId,
+              signal: resumeAbortController.signal
+            };
+            if (capturedStore !== void 0) {
+              const store = capturedStore;
+              const onStoreError = events.onStoreError;
+              return await runClaimed({
+                store,
+                agentId: id,
                 sessionId,
-                runId,
-                agentInternals.loopDef,
-                initialState,
-                agentInternals.stateSchema,
-                ctx,
-                { ...options, ...lease }
-              );
-              if (capturedStore === void 0 && r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
-              lastResult = { state: r.state, cursor: r.cursor, runId, ...r.carrier !== void 0 ? { carrier: r.carrier } : {} };
-              return { state: r.state, signal: r.signal };
-            }
-          });
-        } finally {
-          inFlightSessions.delete(sessionId);
-        }
-      })();
-      const buildResumeFn = () => {
-        return (response, interruptId) => {
-          if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
-          interruptPendingSessions.delete(sessionId);
-          inFlightSessions.add(sessionId);
-          let _resumeStopped = false;
-          const resumeAbortController = new AbortController();
-          const resumeStopFlag = {
-            get stopped() {
-              return _resumeStopped;
-            },
-            set stopped(v) {
-              _resumeStopped = v;
-              if (v) resumeAbortController.abort();
-            }
-          };
-          const resumeStepRef = { current: null };
-          const resumeRunId = randomUUID();
-          const resumeExecution = (async () => {
-            await Promise.resolve();
-            try {
-              const resumeCtx = {
-                ...ctx,
-                runId: resumeRunId,
-                signal: resumeAbortController.signal
-              };
-              if (capturedStore !== void 0) {
-                const store = capturedStore;
-                const onStoreError = events.onStoreError;
-                return await runClaimed({
+                claimOptions,
+                ...onStoreError !== void 0 ? { onStoreError } : {},
+                failState: resumeFailState,
+                body: (lease) => injectThenRun({
                   store,
                   agentId: id,
                   sessionId,
-                  claimOptions,
+                  interruptId,
+                  response,
+                  ...heldLease(lease),
                   ...onStoreError !== void 0 ? { onStoreError } : {},
                   failState: resumeFailState,
-                  body: (lease) => injectThenRun({
-                    store,
-                    agentId: id,
-                    sessionId,
-                    interruptId,
-                    response,
-                    ...onStoreError !== void 0 ? { onStoreError } : {},
-                    failState: resumeFailState,
-                    run: async () => {
-                      const r2 = await runWithSession(
-                        store,
-                        id,
-                        sessionId,
-                        resumeRunId,
-                        agentInternals.loopDef,
-                        {},
-                        agentInternals.stateSchema,
-                        resumeCtx,
-                        {
-                          mode: "resume",
-                          shouldStop: () => resumeStopFlag.stopped,
-                          onBeforeStep: (n, s) => {
-                            resumeStepRef.current = n;
-                            events.onBeforeStep?.(n, s);
-                          },
-                          // spread optional event callbacks only when defined (exactOptionalPropertyTypes requires omission, not undefined)
-                          ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
-                          ...events.onAfterStep !== void 0 ? { onAfterStep: events.onAfterStep } : {},
-                          ...events.onError !== void 0 ? { onError: events.onError } : {},
-                          ...events.onComplete !== void 0 ? { onComplete: events.onComplete } : {},
-                          ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
-                          ...Object.keys(listeners).length > 0 ? { listeners } : {},
-                          ...observer !== void 0 ? { observer } : {},
-                          ...onObserverError !== void 0 ? { onObserverError } : {},
-                          ...telemetrySlots.length > 0 ? { telemetrySlots } : {},
-                          ...agentOptions?.instanceId !== void 0 ? { instanceId: agentOptions.instanceId } : {},
-                          ...lease
-                        }
-                      );
-                      lastResult = { state: r2.state, cursor: r2.cursor, runId: resumeRunId, ...r2.carrier !== void 0 ? { carrier: r2.carrier } : {} };
-                      return { state: r2.state, signal: r2.signal };
-                    }
-                  })
-                });
-              }
-              const prev = lastResult;
-              if (prev === null) throw new NoInterruptError();
-              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,
-                resumeCtx,
-                agentInternals.stateSchema,
-                () => resumeStopFlag.stopped,
-                cursor,
-                {
-                  runId: resumeRunId,
-                  resumedFrom: { runId: prev.runId, ...prev.carrier !== void 0 ? { carrier: prev.carrier } : {} },
-                  onBeforeStep: (n, s) => {
-                    resumeStepRef.current = n;
-                    events.onBeforeStep?.(n, s);
-                  },
-                  ...events.onAfterStep !== void 0 ? { onAfterStep: events.onAfterStep } : {},
-                  ...events.onError !== void 0 ? { onError: events.onError } : {},
-                  ...events.onComplete !== void 0 ? { onComplete: events.onComplete } : {},
-                  ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
-                  ...Object.keys(listeners).length > 0 ? { listeners } : {},
-                  ...observer !== void 0 ? { observer } : {},
-                  ...onObserverError !== void 0 ? { onObserverError } : {},
-                  ...telemetrySlots.length > 0 ? { telemetrySlots } : {}
-                }
-              );
-              if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
-              lastResult = { state: r.state, cursor: r.cursor, runId: resumeRunId, ...r.carrier !== void 0 ? { carrier: r.carrier } : {} };
-              return { state: r.state, signal: r.signal };
-            } finally {
-              inFlightSessions.delete(sessionId);
+                  run: async () => {
+                    debug?.onLease(lease);
+                    const r2 = await runWithSession(
+                      store,
+                      id,
+                      sessionId,
+                      resumeRunId,
+                      agentInternals.loopDef,
+                      {},
+                      agentInternals.stateSchema,
+                      resumeCtx,
+                      {
+                        mode: "resume",
+                        checkpoint,
+                        shouldStop: () => resumeStopFlag.stopped,
+                        onBeforeStep: (n, s) => {
+                          resumeStepRef.current = n;
+                          events.onBeforeStep?.(n, s);
+                        },
+                        // spread optional event callbacks only when defined (exactOptionalPropertyTypes requires omission, not undefined)
+                        ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
+                        ...events.onAfterStep !== void 0 ? { onAfterStep: events.onAfterStep } : {},
+                        ...events.onError !== void 0 ? { onError: events.onError } : {},
+                        ...events.onComplete !== void 0 ? { onComplete: events.onComplete } : {},
+                        ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
+                        ...Object.keys(listeners).length > 0 ? { listeners } : {},
+                        ...observer !== void 0 ? { observer } : {},
+                        ...onObserverError !== void 0 ? { onObserverError } : {},
+                        ...telemetrySlots.length > 0 ? { telemetrySlots } : {},
+                        ...agentOptions?.instanceId !== void 0 ? { instanceId: agentOptions.instanceId } : {},
+                        ...debug !== void 0 ? { debugGate: debug.gate } : {},
+                        ...lease
+                      }
+                    );
+                    lastResult = { state: r2.state, cursor: r2.cursor, runId: resumeRunId, ...r2.carrier !== void 0 ? { carrier: r2.carrier } : {} };
+                    return { state: r2.state, signal: r2.signal };
+                  }
+                })
+              });
             }
-          })();
-          return createRunHandle(sessionId, resumeRunId, resumeExecution, resumeStopFlag, resumeStepRef, buildResumeFn());
-        };
+            const prev = lastResult;
+            if (prev === null) throw new NoInterruptError();
+            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,
+              resumeCtx,
+              agentInternals.stateSchema,
+              () => resumeStopFlag.stopped,
+              cursor,
+              {
+                runId: resumeRunId,
+                resumedFrom: { runId: prev.runId, ...prev.carrier !== void 0 ? { carrier: prev.carrier } : {} },
+                onBeforeStep: (n, s) => {
+                  resumeStepRef.current = n;
+                  events.onBeforeStep?.(n, s);
+                },
+                ...events.onAfterStep !== void 0 ? { onAfterStep: events.onAfterStep } : {},
+                ...events.onError !== void 0 ? { onError: events.onError } : {},
+                ...events.onComplete !== void 0 ? { onComplete: events.onComplete } : {},
+                ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
+                ...Object.keys(listeners).length > 0 ? { listeners } : {},
+                ...observer !== void 0 ? { observer } : {},
+                ...onObserverError !== void 0 ? { onObserverError } : {},
+                ...telemetrySlots.length > 0 ? { telemetrySlots } : {},
+                ...debug !== void 0 ? { debugGate: debug.gate } : {}
+              }
+            );
+            if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
+            lastResult = { state: r.state, cursor: r.cursor, runId: resumeRunId, ...r.carrier !== void 0 ? { carrier: r.carrier } : {} };
+            return { state: r.state, signal: r.signal };
+          } finally {
+            inFlightSessions.delete(sessionId);
+          }
+        })();
+        return createRunHandle(sessionId, resumeRunId, resumeExecution, resumeStopFlag, resumeStepRef, buildResumeFn());
       };
-      return createRunHandle(sessionId, runId, execution, stopFlag, stepRef, buildResumeFn());
-    },
+    };
+    return createRunHandle(sessionId, runId, execution, stopFlag, stepRef, buildResumeFn());
+  };
+  const agent = {
+    id,
+    run: (initialState, resources) => startRun(initialState, resources),
     resume: (response, sessionId, interruptId, resources) => {
+      if (debugSessions.has(sessionId)) throw new SessionInDebugError(sessionId);
       if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
+      const checkpoint = readCheckpointResource(resources ?? {}) ?? agentCheckpoint ?? "off";
       interruptPendingSessions.delete(sessionId);
       inFlightSessions.add(sessionId);
       const events = extractRunEvents(resources ?? {});
-      const observer = extractRunObserver(resources ?? {});
-      const onObserverError = extractRunErrorSink(resources ?? {});
+      const { observer, onObserverError } = resolveObserver(resources ?? {});
       const telemetrySlots = buildTelemetrySlots(agentInternals.resolvedProviders.entries());
       const parentRunId = resources?.["parentRunId"];
       const claimOptions = parseClaimOptions(resources?.["claimOptions"], fallbackClaimOptions());
       return makeAgentResumeHandle(response, sessionId, interruptId, {
         claimOptions,
+        checkpoint,
         ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
         ...observer !== void 0 ? { observer } : {},
         ...onObserverError !== void 0 ? { onObserverError } : {},
@@ -2200,12 +2913,33 @@ function createAgent(id, h, slots, agentOptions) {
         ...typeof parentRunId === "string" ? { parentRunId } : {}
       });
     },
+    debug: (initialState, resources) => {
+      const rawSignal = resources["signal"];
+      let sessionId;
+      const session = createDebugSession({
+        start: (hooks) => {
+          const handle = startRun(initialState, resources, hooks);
+          sessionId = handle.sessionId;
+          return handle;
+        },
+        store: capturedStore,
+        signal: rawSignal instanceof AbortSignal ? rawSignal : void 0,
+        onEnd: () => {
+          if (sessionId !== void 0) debugSessions.delete(sessionId);
+        }
+      });
+      debugSessions.add(session.sessionId);
+      return session;
+    },
     status: (sessionId) => querySessionPhase(capturedStore, id, sessionId),
     [_agentInternals]: agentInternals
   };
   return agent;
 }
 export {
+  DebugCommandError,
+  InvalidAgentOptionError,
+  InvalidClaimOptionsError,
   InvalidRunResourceError,
   LeaseExpiredError,
   LoopNotDefinedError,
@@ -2213,6 +2947,7 @@ export {
   REQUIRED_TAG,
   RUNTIME_TAG,
   SessionBusyError,
+  SessionInDebugError,
   SessionInFlightError,
   SessionPendingInterruptError,
   StoreLoadError,