@noetaris/harness 0.1.0 → 0.3.0

package/dist/index.js

@@ -304,6 +304,12 @@ var HarnessInternalsError = class extends Error {
     this.name = "HarnessInternalsError";
   }
 };
+var LoopNotDefinedError = class extends Error {
+  constructor() {
+    super("loop is not defined \u2014 call h.loop() before accessing h.definition()");
+    this.name = "LoopNotDefinedError";
+  }
+};
 function createHarness() {
   return (stateSchema) => {
     const internals = {
@@ -367,14 +373,17 @@ function createBuilderInstance(internals) {
       };
       return createBuilderInstance(newInternals);
     },
+    definition() {
+      if (internals.loopDef === void 0) {
+        throw new LoopNotDefinedError();
+      }
+      return internals.loopDef;
+    },
     [_internals]: internals
   };
   return builder;
 }
 
-// src/agent/session-lifecycle.ts
-import { randomUUID } from "crypto";
-
 // src/agent/ctx-interrupt.ts
 var InterruptPause = class extends Error {
   interruptId;
@@ -406,9 +415,12 @@ function createInterruptFn(state, callCountRef) {
 }
 
 // src/agent/ctx-emit.ts
-function createEmitFn(listeners) {
+function createEmitFn(listeners, observer, stepCtxRef) {
   return (name, payload) => {
     listeners[name]?.(payload);
+    if (observer !== void 0 && stepCtxRef !== void 0 && stepCtxRef.current !== null) {
+      observer.onEvent?.(stepCtxRef.current, name, payload);
+    }
   };
 }
 function extractRunListeners(resources) {
@@ -462,21 +474,42 @@ function applyUpdate(state, update, schema) {
 }
 async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callbacks) {
   const { onBeforeStep, onAfterStep, onError, onComplete, onInterrupt } = callbacks ?? {};
+  const obs = callbacks?.observer;
   const implicitNextMap = buildImplicitNextMap(graph);
   if (!("$error" in state)) state.$error = null;
   if (!("$interrupt" in state)) state.$interrupt = null;
   if (!("$interruptResponses" in state)) state.$interruptResponses = {};
+  const runStart = Date.now();
+  const runCtx = {
+    agentId: ctx.agentId,
+    sessionId: ctx.sessionId,
+    runId: typeof callbacks?.runId === "string" ? callbacks.runId : "",
+    ...typeof callbacks?.parentRunId === "string" ? { parentRunId: callbacks.parentRunId } : {},
+    ...typeof ctx.instanceId === "string" ? { instanceId: ctx.instanceId } : {}
+  };
+  obs?.onRunStart?.(runCtx);
   const callCountRef = { current: 0 };
+  const stepCtxRef = { current: null };
   ctx["interrupt"] = createInterruptFn(state, callCountRef);
-  ctx["emit"] = createEmitFn(callbacks?.listeners ?? {});
+  ctx["emit"] = createEmitFn(callbacks?.listeners ?? {}, obs, stepCtxRef);
   let cursor = startCursor ?? graph.entryStep;
   while (true) {
     if (shouldStop?.()) {
+      obs?.onRunEnd?.(runCtx, { signal: "$stopped", durationMs: Date.now() - runStart });
       return { state, signal: null, cursor, paused: true };
     }
     onBeforeStep?.(cursor, { ...state });
     const step = graph.steps.find((s) => s.name === cursor);
     callCountRef.current = 0;
+    const stepCtx = { agentId: ctx.agentId, sessionId: ctx.sessionId, stepName: cursor };
+    stepCtxRef.current = stepCtx;
+    const stepStart = Date.now();
+    obs?.onStepStart?.(stepCtx);
+    if (callbacks?.setStepContextSlots !== void 0) {
+      for (const slot of callbacks.setStepContextSlots) {
+        slot.setStepContext(stepCtx);
+      }
+    }
     let runSucceeded = false;
     if (step.run !== void 0) {
       const hadResponses = Object.keys(state.$interruptResponses).length > 0;
@@ -494,15 +527,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 });
           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 });
       }
     }
     if (runSucceeded) {
       state.$error = null;
       onAfterStep?.(cursor, state);
+      obs?.onStepEnd?.(stepCtx, { durationMs: Date.now() - stepStart });
     }
     const callRoute = step.route !== void 0 && (runSucceeded || step.run === void 0 || step.errorAware);
     if (callRoute) {
@@ -512,6 +549,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 });
         return { state, signal: "$error", cursor, paused: true };
       }
       const transition = step.transitions.find((t) => t.signal === signal);
@@ -520,6 +558,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 });
         return { state, signal, cursor: null, paused: false };
       }
       cursor = transition.target.name;
@@ -527,6 +566,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 });
         return { state, signal: "$error", cursor, paused: true };
       }
     } else {
@@ -604,6 +644,7 @@ function buildResumedState(stored, initialStateArg, argKeys, schema) {
 
 // src/agent/concurrency-errors.ts
 var SessionInFlightError = class extends Error {
+  /** The session that was already in-flight. */
   sessionId;
   constructor(sessionId) {
     super(`session "${sessionId}" is already in-flight`);
@@ -612,6 +653,7 @@ var SessionInFlightError = class extends Error {
   }
 };
 var SessionPendingInterruptError = class extends Error {
+  /** The session that is awaiting an interrupt response. */
   sessionId;
   constructor(sessionId) {
     super(`session "${sessionId}" is paused on an interrupt \u2014 use agent.resume() instead of agent.run()`);
@@ -627,6 +669,67 @@ var StoreLoadError = class extends Error {
     this.cause = cause;
   }
 };
+var SessionBusyError = class extends Error {
+  /** The session that is currently claimed by another instance. */
+  sessionId;
+  constructor(sessionId, retryAfter) {
+    super(`session "${sessionId}" is currently claimed by another instance`);
+    this.name = "SessionBusyError";
+    this.sessionId = sessionId;
+    if (retryAfter !== void 0) this.retryAfter = retryAfter;
+  }
+};
+var LeaseExpiredError = class extends Error {
+  /** The session whose lease expired. */
+  sessionId;
+  constructor(sessionId) {
+    super(`lease for session "${sessionId}" has expired \u2014 run stopped without saving`);
+    this.name = "LeaseExpiredError";
+    this.sessionId = sessionId;
+  }
+};
+
+// src/agent/ctx-keep-alive.ts
+function createKeepAliveFn(leaseRef, store, originalTtlMs) {
+  function keepAlive(options) {
+    const isBackground = typeof options === "object" && options !== null && "every" in options;
+    const extendClaim = store?.extendClaim;
+    if (isBackground) {
+      if (leaseRef.current === null || typeof extendClaim !== "function") {
+        return noopStop;
+      }
+      let handle = setInterval(() => {
+        if (leaseRef.current === null) {
+          return;
+        }
+        void (async () => {
+          try {
+            const renewed = await extendClaim.call(store, leaseRef.current, { ttlMs: originalTtlMs });
+            leaseRef.current = renewed;
+          } catch {
+          }
+        })();
+      }, options.every);
+      return function stop() {
+        if (handle !== null) {
+          clearInterval(handle);
+          handle = null;
+        }
+      };
+    }
+    if (leaseRef.current === null || typeof extendClaim !== "function") {
+      return Promise.resolve();
+    }
+    const snapshot = leaseRef.current;
+    return (async () => {
+      const renewed = await extendClaim.call(store, snapshot, { ttlMs: originalTtlMs });
+      leaseRef.current = renewed;
+    })();
+  }
+  return keepAlive;
+}
+function noopStop() {
+}
 
 // src/agent/session-lifecycle.ts
 function resolveSessionStore(storeEntries) {
@@ -646,21 +749,43 @@ function resolveSessionStore(storeEntries) {
   }
   return result;
 }
-async function querySessionPhase(store, sessionId) {
+async function querySessionPhase(store, agentId, sessionId) {
   if (store === void 0) {
     return { phase: "fresh" };
   }
-  const loaded = await store.load(sessionId);
+  const loaded = await store.load(agentId, sessionId);
   return storedSessionToPhase(loaded);
 }
-async function runWithSession(store, sessionId, graph, initialStateArg, schema, ctx, options) {
+async function runWithSession(store, agentId, sessionId, runId, graph, initialStateArg, schema, ctx, options) {
+  const leaseRef = options?.leaseRef ?? { current: null };
+  const keepAlive = createKeepAliveFn(leaseRef, store, options?.claimTtlMs ?? 3e4);
+  ctx["keepAlive"] = keepAlive;
+  let leaseExpired = false;
+  const composedShouldStop = () => {
+    if (options?.shouldStop?.() === true) return true;
+    if (leaseRef.current !== null && leaseRef.current.expiresAt <= Date.now()) {
+      leaseExpired = true;
+      return true;
+    }
+    return false;
+  };
   if (store === void 0) {
     const state2 = initializeState(null, initialStateArg, schema);
-    return runLoop(graph, state2, ctx, schema, options?.shouldStop, void 0, options);
+    const result2 = await runLoop(graph, state2, ctx, schema, composedShouldStop, void 0, {
+      ...options,
+      runId,
+      ...options?.parentRunId !== void 0 ? { parentRunId: options.parentRunId } : {}
+    });
+    if (leaseExpired) {
+      const expiredError = new LeaseExpiredError(sessionId);
+      options?.onStoreError?.(expiredError, "claim");
+      throw expiredError;
+    }
+    return result2;
   }
   let loaded;
   try {
-    loaded = await store.load(sessionId);
+    loaded = await store.load(agentId, sessionId);
   } catch (error) {
     const storeError = new StoreLoadError(error);
     options?.onStoreError?.(storeError, "load");
@@ -668,38 +793,62 @@ async function runWithSession(store, sessionId, graph, initialStateArg, schema,
     failState["$error"] = storeError;
     return { state: failState, signal: "$error", paused: false, cursor: null };
   }
-  const runId = randomUUID();
+  if (loaded !== null && loaded.phase === "completed") {
+    return {
+      state: loaded.finalState,
+      signal: loaded.signal ?? null,
+      cursor: null,
+      paused: false
+    };
+  }
   const state = initializeState(loaded, initialStateArg, schema);
   const initialStateSnapshot = { ...state };
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const result = await runLoop(graph, state, ctx, schema, options?.shouldStop, loaded?.step, options);
+  const result = await runLoop(graph, state, ctx, schema, composedShouldStop, loaded?.step, {
+    ...options,
+    runId,
+    ...options?.parentRunId !== void 0 ? { parentRunId: options.parentRunId } : {}
+  });
+  if (leaseExpired) {
+    const expiredError = new LeaseExpiredError(sessionId);
+    options?.onStoreError?.(expiredError, "claim");
+    throw expiredError;
+  }
   const settledAt = (/* @__PURE__ */ new Date()).toISOString();
+  const metadata = options?.instanceId !== void 0 ? { instanceId: options.instanceId } : void 0;
   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 } : {}
+        ...result.signal !== null ? { signal: result.signal } : {},
+        ...metadata !== void 0 ? { metadata } : {}
       };
-      await store.save(sessionId, saved);
+      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 } : {}
+        ...result.signal !== null ? { signal: result.signal } : {},
+        ...metadata !== void 0 ? { metadata } : {}
       };
-      await store.save(sessionId, saved);
+      await store.save(agentId, sessionId, saved);
     }
   } catch (error) {
     options?.onStoreError?.(error, "persist");
@@ -716,8 +865,8 @@ var NoInterruptError = class extends Error {
     this.name = "NoInterruptError";
   }
 };
-async function injectInterruptResponse(store, sessionId, interruptId, response) {
-  const loaded = await store.load(sessionId);
+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;
@@ -730,8 +879,10 @@ async function injectInterruptResponse(store, sessionId, interruptId, response)
     $interruptResponses: { ...existingResponses, [interruptId]: response }
   };
   const updated = {
+    agentId: loaded.agentId,
     runId: loaded.runId,
     sessionId: loaded.sessionId,
+    version: loaded.version + 1,
     startedAt: loaded.startedAt,
     settledAt: loaded.settledAt,
     phase: "paused",
@@ -740,11 +891,11 @@ async function injectInterruptResponse(store, sessionId, interruptId, response)
     ...loaded.step !== void 0 ? { step: loaded.step } : {},
     ...loaded.signal !== void 0 ? { signal: loaded.signal } : {}
   };
-  await store.save(sessionId, updated);
+  await store.save(agentId, sessionId, updated);
 }
 
 // src/agent/run-handle.ts
-function createRunHandle(sessionId, execution, stopFlag, stepRef, resumeFn) {
+function createRunHandle(sessionId, runId, execution, stopFlag, stepRef, resumeFn) {
   let settledOutcome = null;
   const settled = execution.then(
     (outcome) => {
@@ -782,6 +933,9 @@ function createRunHandle(sessionId, execution, stopFlag, stepRef, resumeFn) {
     get sessionId() {
       return sessionId;
     },
+    get runId() {
+      return runId;
+    },
     get currentStep() {
       return stepRef.current;
     }
@@ -790,7 +944,7 @@ function createRunHandle(sessionId, execution, stopFlag, stepRef, resumeFn) {
 }
 
 // src/agent/create-agent.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID } from "crypto";
 
 // src/agent/event-callbacks.ts
 function extractRunEvents(resources) {
@@ -802,13 +956,20 @@ function extractRunEvents(resources) {
 }
 
 // src/agent/create-agent.ts
+var NOOP_OBSERVER = {};
+function extractRunObserver(resources) {
+  const raw = resources["observer"];
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  return raw;
+}
 var MissingLoopError = class extends Error {
   constructor() {
-    super("harness has no loop \u2014 call h.loop() before createAgent()");
+    super("harness has no loop \u2014 call h.loop() before createAgent(id, h, slots)");
     this.name = "MissingLoopError";
   }
 };
 var MissingSlotError = class extends Error {
+  /** The missing slot key. */
   key;
   constructor(key) {
     super(`required slot "${key}" was not provided in createAgent slots`);
@@ -817,6 +978,7 @@ var MissingSlotError = class extends Error {
   }
 };
 var RuntimeSlotInAgentError = class extends Error {
+  /** The offending slot key. */
   key;
   constructor(key) {
     super(`slot "${key}" is a runtime() slot \u2014 provide it in agent.run(), not createAgent()`);
@@ -825,6 +987,7 @@ var RuntimeSlotInAgentError = class extends Error {
   }
 };
 var UnknownSlotError = class extends Error {
+  /** The unknown slot key. */
   key;
   constructor(key) {
     super(`slot "${key}" is not declared in the harness \u2014 remove it or add h.provide("${key}", required())`);
@@ -833,6 +996,7 @@ var UnknownSlotError = class extends Error {
   }
 };
 var MissingRuntimeSlotError = class extends Error {
+  /** The missing runtime slot key. */
   key;
   constructor(key) {
     super(`runtime slot "${key}" was not provided in agent.run() resources`);
@@ -841,6 +1005,7 @@ var MissingRuntimeSlotError = class extends Error {
   }
 };
 var RequiredSlotInRunError = class extends Error {
+  /** The offending slot key. */
   key;
   constructor(key) {
     super(`slot "${key}" is a required() slot \u2014 provide it in createAgent(), not agent.run()`);
@@ -849,6 +1014,7 @@ var RequiredSlotInRunError = class extends Error {
   }
 };
 var UnknownRunSlotError = class extends Error {
+  /** The unknown resource key. */
   key;
   constructor(key) {
     super(`slot "${key}" is not a runtime() slot \u2014 do not pass it in agent.run() resources`);
@@ -857,7 +1023,7 @@ var UnknownRunSlotError = class extends Error {
   }
 };
 var _agentInternals = /* @__PURE__ */ Symbol("_agentInternals");
-function createAgent(h, slots) {
+function createAgent(id, h, slots, agentOptions) {
   const internals = getInternals(h);
   if (internals.loopDef === void 0) {
     throw new MissingLoopError();
@@ -906,6 +1072,7 @@ function createAgent(h, slots) {
   }
   const capturedStore = resolveSessionStore(storeEntries);
   const agentInternals = {
+    agentId: id,
     resolvedProviders,
     storeEntries,
     loopDef: internals.loopDef,
@@ -914,38 +1081,104 @@ function createAgent(h, slots) {
     runtimeKeys,
     requiredKeys
   };
-  const reservedRunKeys = /* @__PURE__ */ new Set(["sessionId", "signal", "events", "listeners"]);
+  const reservedRunKeys = /* @__PURE__ */ new Set(["sessionId", "signal", "events", "listeners", "observer", "claimOptions", "parentRunId"]);
   const inFlightSessions = /* @__PURE__ */ new Set();
   const interruptPendingSessions = /* @__PURE__ */ new Set();
-  const makeAgentResumeHandle = (resp, sId, iId) => {
-    const flag = { stopped: false };
+  const makeAgentResumeHandle = (resp, sId, iId, resumeOpts, observer, setStepContextSlots) => {
+    let _stopped = false;
+    const abortController = new AbortController();
+    const flag = {
+      get stopped() {
+        return _stopped;
+      },
+      set stopped(v) {
+        _stopped = v;
+        if (v) abortController.abort();
+      }
+    };
     const ref = { current: null };
+    const rId = randomUUID();
     const exec = (async () => {
       await Promise.resolve();
+      const claimOptions = { ttlMs: 3e4 };
+      let leaseRef = void 0;
       try {
-        if (capturedStore === void 0) throw new NoInterruptError();
-        await injectInterruptResponse(capturedStore, sId, iId, resp);
-        const agentCtx = {
-          ...Object.fromEntries(agentInternals.resolvedProviders),
-          sessionId: sId
-        };
-        const r = await runWithSession(
-          capturedStore,
-          sId,
-          agentInternals.loopDef,
-          {},
-          agentInternals.stateSchema,
-          agentCtx,
-          {
-            shouldStop: () => flag.stopped,
-            onBeforeStep: (n) => {
-              ref.current = n;
+        if (typeof capturedStore?.claim === "function") {
+          let lease;
+          try {
+            lease = await capturedStore.claim(id, sId, claimOptions);
+          } catch (claimError) {
+            const loadError = new StoreLoadError(claimError);
+            resumeOpts?.onStoreError?.(loadError, "claim");
+            const failState = initializeState(null, {}, agentInternals.stateSchema);
+            failState["$error"] = loadError;
+            return { state: failState, signal: "$error" };
+          }
+          if (lease === null) {
+            const busyError = new SessionBusyError(sId);
+            resumeOpts?.onStoreError?.(busyError, "claim");
+            const failState = initializeState(null, {}, agentInternals.stateSchema);
+            failState["$error"] = busyError;
+            return { state: failState, signal: "$error" };
+          }
+          leaseRef = { current: lease };
+        }
+        try {
+          if (capturedStore === void 0) throw new NoInterruptError();
+          try {
+            await injectInterruptResponse(capturedStore, id, sId, iId, resp);
+          } catch (injectError) {
+            if (injectError instanceof NoInterruptError) throw injectError;
+            const storeError = new StoreLoadError(injectError);
+            resumeOpts?.onStoreError?.(storeError, "claim");
+            const failState = initializeState(null, {}, agentInternals.stateSchema);
+            failState["$error"] = storeError;
+            return { state: failState, signal: "$error" };
+          }
+          const agentCtx = {
+            ...Object.fromEntries(agentInternals.resolvedProviders),
+            agentId: id,
+            sessionId: sId,
+            runId: rId,
+            signal: abortController.signal
+          };
+          const r = await runWithSession(
+            capturedStore,
+            id,
+            sId,
+            rId,
+            agentInternals.loopDef,
+            {},
+            agentInternals.stateSchema,
+            agentCtx,
+            {
+              shouldStop: () => flag.stopped,
+              onBeforeStep: (n) => {
+                ref.current = n;
+              },
+              ...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 } : {}
             }
-            // _state unused in cross-process resume — no events available
+          );
+          if (r.signal === "$interrupt") interruptPendingSessions.add(sId);
+          return { state: r.state, signal: r.signal };
+        } catch (error) {
+          if (error instanceof LeaseExpiredError) {
+            const failState = initializeState(null, {}, agentInternals.stateSchema);
+            failState["$error"] = error;
+            return { state: failState, signal: "$error" };
           }
-        );
-        if (r.signal === "$interrupt") interruptPendingSessions.add(sId);
-        return { state: r.state, signal: r.signal };
+          throw error;
+        } finally {
+          if (leaseRef !== void 0 && typeof capturedStore?.release === "function") {
+            try {
+              await capturedStore.release(leaseRef.current);
+            } catch {
+            }
+          }
+        }
       } finally {
         inFlightSessions.delete(sId);
       }
@@ -956,9 +1189,10 @@ function createAgent(h, slots) {
       inFlightSessions.add(sId);
       return makeAgentResumeHandle(r, sId, i);
     };
-    return createRunHandle(sId, exec, flag, ref, resumeFn);
+    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;
@@ -977,15 +1211,29 @@ function createAgent(h, slots) {
           throw new MissingRuntimeSlotError(key);
         }
       }
-      const sessionId = typeof resources["sessionId"] === "string" ? resources["sessionId"] : randomUUID2();
+      const sessionId = typeof resources["sessionId"] === "string" ? resources["sessionId"] : randomUUID();
+      const runId = randomUUID();
       if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
       if (interruptPendingSessions.has(sessionId)) throw new SessionPendingInterruptError(sessionId);
       inFlightSessions.add(sessionId);
-      const stopFlag = { stopped: false };
+      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;
       }
@@ -998,10 +1246,27 @@ function createAgent(h, slots) {
       const ctx = {
         ...Object.fromEntries(agentInternals.resolvedProviders),
         ...runtimeSlots,
-        sessionId
+        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);
+      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 parentRunId = typeof resources["parentRunId"] === "string" ? resources["parentRunId"] : void 0;
       const options = {
         shouldStop: () => stopFlag.stopped,
         onBeforeStep: (name, state) => {
@@ -1014,24 +1279,72 @@ function createAgent(h, slots) {
         ...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 } : {}
+        ...Object.keys(listeners).length > 0 ? { listeners } : {},
+        ...observer !== void 0 ? { observer } : {},
+        ...agentOptions?.instanceId !== void 0 ? { instanceId: agentOptions.instanceId } : {},
+        ...parentRunId !== void 0 ? { parentRunId } : {},
+        ...setStepContextSlots.length > 0 ? { setStepContextSlots } : {}
       };
       let lastResult = null;
       const execution = (async () => {
         await Promise.resolve();
+        const rawClaimOpts = resources["claimOptions"];
+        const claimOptions = typeof rawClaimOpts === "object" && rawClaimOpts !== null && typeof rawClaimOpts["ttlMs"] === "number" ? rawClaimOpts : { ttlMs: 3e4 };
+        let leaseRef = void 0;
         try {
-          const r = await runWithSession(
-            capturedStore,
-            sessionId,
-            agentInternals.loopDef,
-            initialState,
-            agentInternals.stateSchema,
-            ctx,
-            options
-          );
-          if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
-          lastResult = { state: r.state, cursor: r.cursor };
-          return { state: r.state, signal: r.signal };
+          if (typeof capturedStore?.claim === "function") {
+            let lease;
+            try {
+              lease = await capturedStore.claim(id, sessionId, claimOptions);
+            } catch (claimError) {
+              const loadError = new StoreLoadError(claimError);
+              events.onStoreError?.(loadError, "claim");
+              const failState = initializeState(null, initialState, agentInternals.stateSchema);
+              failState["$error"] = loadError;
+              return { state: failState, signal: "$error" };
+            }
+            if (lease === null) {
+              const busyError = new SessionBusyError(sessionId);
+              events.onStoreError?.(busyError, "claim");
+              const failState = initializeState(null, initialState, agentInternals.stateSchema);
+              failState["$error"] = busyError;
+              return { state: failState, signal: "$error" };
+            }
+            leaseRef = { current: lease };
+          }
+          try {
+            const r = await runWithSession(
+              capturedStore,
+              id,
+              sessionId,
+              runId,
+              agentInternals.loopDef,
+              initialState,
+              agentInternals.stateSchema,
+              ctx,
+              {
+                ...options,
+                ...leaseRef !== void 0 ? { leaseRef, claimTtlMs: claimOptions.ttlMs } : {}
+              }
+            );
+            if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
+            lastResult = { state: r.state, cursor: r.cursor };
+            return { state: r.state, signal: r.signal };
+          } catch (error) {
+            if (error instanceof LeaseExpiredError) {
+              const failState = initializeState(null, initialState, agentInternals.stateSchema);
+              failState["$error"] = error;
+              return { state: failState, signal: "$error" };
+            }
+            throw error;
+          } finally {
+            if (leaseRef !== void 0 && typeof capturedStore?.release === "function") {
+              try {
+                await capturedStore.release(leaseRef.current);
+              } catch {
+              }
+            }
+          }
         } finally {
           inFlightSessions.delete(sessionId);
         }
@@ -1041,20 +1354,38 @@ function createAgent(h, slots) {
           if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
           interruptPendingSessions.delete(sessionId);
           inFlightSessions.add(sessionId);
-          const resumeStopFlag = { stopped: false };
+          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) {
-                await injectInterruptResponse(capturedStore, sessionId, interruptId, response);
+                await injectInterruptResponse(capturedStore, id, sessionId, interruptId, response);
                 const r2 = await runWithSession(
                   capturedStore,
+                  id,
                   sessionId,
+                  resumeRunId,
                   agentInternals.loopDef,
                   {},
                   agentInternals.stateSchema,
-                  ctx,
+                  resumeCtx,
                   {
                     shouldStop: () => resumeStopFlag.stopped,
                     onBeforeStep: (n, s) => {
@@ -1067,7 +1398,9 @@ function createAgent(h, slots) {
                     ...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 } : {}
+                    ...Object.keys(listeners).length > 0 ? { listeners } : {},
+                    ...observer !== void 0 ? { observer } : {},
+                    ...setStepContextSlots.length > 0 ? { setStepContextSlots } : {}
                   }
                 );
                 if (r2.signal === "$interrupt") interruptPendingSessions.add(sessionId);
@@ -1084,11 +1417,12 @@ function createAgent(h, slots) {
               const r = await runLoop(
                 agentInternals.loopDef,
                 state,
-                ctx,
+                resumeCtx,
                 agentInternals.stateSchema,
                 () => resumeStopFlag.stopped,
                 cursor,
                 {
+                  runId: resumeRunId,
                   onBeforeStep: (n, s) => {
                     resumeStepRef.current = n;
                     events.onBeforeStep?.(n, s);
@@ -1097,39 +1431,91 @@ function createAgent(h, slots) {
                   ...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 } : {}
+                  ...Object.keys(listeners).length > 0 ? { listeners } : {},
+                  ...observer !== void 0 ? { observer } : {},
+                  ...setStepContextSlots.length > 0 ? { setStepContextSlots } : {}
                 }
               );
               if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
               lastResult = { state: r.state, cursor: r.cursor };
               return { state: r.state, signal: r.signal };
+            } catch (error) {
+              if (error instanceof LeaseExpiredError) {
+                const failState = initializeState(null, initialState, agentInternals.stateSchema);
+                failState["$error"] = error;
+                return { state: failState, signal: "$error" };
+              }
+              throw error;
             } finally {
               inFlightSessions.delete(sessionId);
             }
           })();
-          return createRunHandle(sessionId, resumeExecution, resumeStopFlag, resumeStepRef, buildResumeFn());
+          return createRunHandle(sessionId, resumeRunId, resumeExecution, resumeStopFlag, resumeStepRef, buildResumeFn());
         };
       };
-      return createRunHandle(sessionId, execution, stopFlag, stepRef, buildResumeFn());
+      return createRunHandle(sessionId, runId, execution, stopFlag, stepRef, buildResumeFn());
     },
-    resume: (response, sessionId, interruptId) => {
+    resume: (response, sessionId, interruptId, resources) => {
       if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
       interruptPendingSessions.delete(sessionId);
       inFlightSessions.add(sessionId);
-      return makeAgentResumeHandle(response, sessionId, interruptId);
+      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);
     },
-    status: (sessionId) => querySessionPhase(capturedStore, sessionId),
+    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 {
+  LoopNotDefinedError,
   NoInterruptError,
   REQUIRED_TAG,
   RUNTIME_TAG,
   SessionInFlightError,
   SessionPendingInterruptError,
   StoreLoadError,
+  composeObservers,
   createAgent,
   createHarness,
   field,