@noetaris/harness 0.7.0 → 0.9.0

package/README.md

@@ -156,6 +156,13 @@ const resumed = run.resume(response, interruptId)
 const resumed = agent.resume(response, sessionId, interruptId)
 ```
 
+`agent.resume()` takes an optional fourth argument with these reserved resources (a subset of
+`run()`'s): `observer`, `onObserverError`, `events: { onStoreError }`, and `parentRunId` (the caller's run id,
+for a sub agent resumed from a step). `parentRunId` applies to that resumed run only: calling
+`resume()` again on the handle it returns keeps the other resources but not `parentRunId`, which
+is stale by then. With a store, both `agent.resume()` and `run.resume()` record the agent's
+`instanceId` in the resumed run's `metadata`.
+
 **Resume replays the interrupted step from the top.** On resume, the step that called
 `ctx.interrupt()` runs again from its first line; each `ctx.interrupt()` call it reaches
 returns the stored response instead of pausing. State updates from the paused attempt are
@@ -255,7 +262,7 @@ throws on an adapter event never fails a step. Every hook is optional.
 | Hook | Fires |
 |---|---|
 | `onRunStart(ctx)` | once when a run starts |
-| `onRunEnd(ctx, { signal, durationMs })` | once when a run settles — completed, stopped (`$stopped`), paused, or rejected by a thrown error (`$error`) |
+| `onRunEnd(ctx, { signal, durationMs, error? })` | once when a run settles — completed, stopped (`$stopped`), paused, or rejected by a thrown error (`$error`). `error` is set when the run ends with `$error` because of an error no `onError` step handled (paused) or a rejection; a route that returns `'$error'` itself gives no `error`, so test for `error`, not the signal |
 | `onStepStart(ctx)` | before each step |
 | `onStepEnd(ctx, { durationMs })` | after a step's `run` succeeds, before its `route` |
 | `onStepError(ctx, { error, durationMs })` | when a step's `run` throws |
@@ -263,6 +270,7 @@ throws on an adapter event never fails a step. Every hook is optional.
 | `onEvent(ctx, type, payload)` | on `ctx.emit()` and adapter events such as `llm.response` |
 | `onStepSettled(ctx, event)` | once per step, when its outcome and destination are final |
 | `wrap(ctx, scope, fn)` | around a step's `run`, and around calls made with `ctx.within` |
+| `carry(ctx)` | once per top-level run, right after `onRunStart`; returns a string map to keep on the run's record (see [Linking runs](#linking-runs)) |
 
 Step hooks receive a `StepContext`: `agentId`, `sessionId`, `runId`, `stepName` and, inside a
 fork branch, `branchPath`. `runId` is the same value as `RunContext.runId`. Steps inside a branch
@@ -314,6 +322,27 @@ await createAgent('demo', h, {}).run({}, { observer: logger })
 // decide: ok end (signal done)
 ```
 
+### Linking runs
+
+Some runs continue an earlier one. Their `RunContext` says which, so an observer can link them:
+
+| The run is | `RunContext` field |
+|---|---|
+| the next run on a session that paused — on an interrupt, a stop, or an unhandled error — whether started by `agent.resume()`, `run.resume()` (with or without a store), or `agent.run()` on that session | `resumedFrom: { runId, carrier? }` — the run that paused |
+| the first run of a session created by `SessionStore.branch()` | `branchedFrom: { sessionId, runId, carrier? }` — the run it was branched from, in the source session |
+
+A run has at most one of the two, only on its top-level context (never on a fork branch's), and a
+session that already completed runs nothing, so it has neither.
+
+`carrier` is what the earlier run's observer returned from `carry(ctx)`: core calls `carry` once,
+right after `onRunStart`, keeps its string values, and saves them as `StoredRun.carrier` (or on the
+handle, for `run.resume()` without a store). It describes that run only — when the earlier run had
+no observer with `carry`, `carrier` is absent rather than taken from an older run.
+`@noetaris/harness-otel` uses this to link each run's root span to the one before it.
+`composeObservers` merges the maps its observers return (on a shared key the later observer wins);
+a `carry` that throws is reported to `onObserverError` with hook name `'carry'` and counts as
+returning nothing.
+
 ### Running code inside a span
 
 Hooks are notifications: they return before the step runs, so they cannot make a span the
@@ -387,14 +416,16 @@ The harness never trusts a wrapper. `fn` always runs exactly once, and the calle
 | `runtime()` | Marks a provider slot as required at `agent.run()`. |
 | `composeObservers([a, b], onObserverError?)` | Merges multiple `Observer` instances into one fan-out observer; a throwing observer is isolated and reported to `onObserverError`. |
 | `SessionStore` | Interface for session persistence backends. |
-| `StoredRun` | Type for a persisted run snapshot. Includes `agentId`, `runId`, `sessionId`, `phase`, and state. |
+| `StoredRun` | Type for a persisted run snapshot. Includes `agentId`, `runId`, `sessionId`, `phase`, state, and optionally `carrier` (the run's `carry` result) and `branchedFrom` (on a branch seed). |
+| `RunRef` | `{ runId, carrier? }` — points at an earlier run; used by `RunContext.resumedFrom` and `branchedFrom` (which adds `sessionId`). |
+| `RunCarrier` | `Readonly<Record<string, string>>` — the opaque map an observer's `carry` returns. |
 | `Observer` | Interface for telemetry hooks on run and step lifecycle events (see [Observers](#observers)). |
 | `StepSettledEvent` | Payload of `Observer.onStepSettled` — outcome, duration, update, signal, next, error, interrupt, fork. |
 | `StepSettledNext` | Where the run goes after a step settles: `step`, `end`, `pause`, or `throw`. |
 | `ObserverAware` | Interface for provider objects that want per-step telemetry: the harness calls `withTelemetry(telemetry)` once per step and installs the returned view on `ctx`. |
 | `TelemetryContext` | What `withTelemetry` receives: `observer` (the run's observer, fault-isolated), `stepContext`, and `within(type, payload, fn)` bound to that step. |
 | `WrapScope` | What `Observer.wrap` is asked to enclose: `{ kind: 'step' }` or `{ kind: 'event', type, payload }`. |
-| `RunContext` | Context passed to run-level observer hooks — `agentId`, `sessionId`, `runId`, `parentRunId?`, `instanceId?`, `branchPath?`. |
+| `RunContext` | Context passed to run-level observer hooks — `agentId`, `sessionId`, `runId`, `parentRunId?`, `instanceId?`, `branchPath?`, `resumedFrom?`, `branchedFrom?` (see [Linking runs](#linking-runs)). |
 | `StepContext` | Context passed to step-level observer hooks — `agentId`, `sessionId`, `runId`, `stepName`, `branchPath?`. |
 | `NoInterruptError` | Thrown when `resume()` is called but the session is not paused on a matching interrupt. |
 | `SessionInFlightError` | Thrown when a session is already running. |
@@ -424,6 +455,7 @@ See [LIMITATIONS.md](LIMITATIONS.md) for known limitations.
 - [`@noetaris/harness-openai`](https://github.com/noetaris-lab/harness-openai) — OpenAI adapter
 - [`@noetaris/harness-google`](https://github.com/noetaris-lab/harness-google) — Google Gemini adapter
 - [`@noetaris/harness-otel`](https://github.com/noetaris-lab/harness-otel) — OpenTelemetry observer bridge
+- [`@noetaris/harness-otel-genai`](https://github.com/noetaris-lab/harness-otel-genai) — GenAI semantic-conventions extension for the bridge
 
 ## License
 

package/dist/index.d.ts

@@ -130,6 +130,19 @@ interface RunContext {
      * from the real top-level pair. Absent for the top-level run.
      */
     readonly branchPath?: readonly string[];
+    /**
+     * The run this one continues: the run that paused the session (on an interrupt, a stop or
+     * an unhandled error), with the carrier its observer produced. Present on a resumed
+     * top-level run only — never on a fork branch's context, never together with `branchedFrom`.
+     */
+    readonly resumedFrom?: RunRef;
+    /**
+     * The run this session was branched from (`SessionStore.branch`), in the source session.
+     * Present on the branched session's first top-level run only.
+     */
+    readonly branchedFrom?: RunRef & {
+        readonly sessionId: string;
+    };
 }
 /**
  * Identifies the agent, session, and current step for step-level observer callbacks.
@@ -247,12 +260,19 @@ interface Observer {
     onRunStart?: (ctx: RunContext) => void;
     /**
      * Called once when a run settles — completed, stopped, paused, or rejected by a thrown error
-     * (a graph-definition error or a throwing callback). On a rejection `signal` is `'$error'` and
-     * the run rejects right after, with the original error.
+     * (a graph-definition error or a throwing callback).
+     *
+     * When the run ends because of an error, `signal` is `'$error'` and `error` holds it: the error
+     * a step's `run` or `route` threw, or a failed fork's branch error, when no `onError` step
+     * handled it (the run resolves paused); or the original thrown value when the run rejects (it
+     * rejects right after). `error` is absent on every other ending. A route may also return
+     * `'$error'` as an ordinary signal; that ending has no `error` key, so test for `error`, not
+     * for the signal.
      */
     onRunEnd?: (ctx: RunContext, event: {
         signal: string;
         durationMs: number;
+        error?: unknown;
     }) => void;
     /** Called immediately before each step's `run` function is invoked. */
     onStepStart?: (ctx: StepContext) => void;
@@ -297,6 +317,15 @@ interface Observer {
      * Not guarded: a wrapper that never settles hangs the step it encloses.
      */
     wrap?: <T>(ctx: StepContext, scope: WrapScope, fn: () => Promise<T>) => Promise<T>;
+    /**
+     * Called once per top-level run, right after `onRunStart` (never for a fork branch). Return
+     * an opaque string map that lets a later run refer back to this one — e.g. the run's trace
+     * context. Core saves it on the run's record and hands it back as `RunContext.resumedFrom.carrier`
+     * (or `branchedFrom.carrier`) to the run that continues or branches from it. Return
+     * `undefined` for nothing. Only string values are kept; a throw is reported via
+     * `onObserverError` (hook name `'carry'`) and counts as `undefined`.
+     */
+    carry?: (ctx: RunContext) => Record<string, string> | undefined;
 }
 /**
  * The telemetry a resource needs to attribute an `invoke()` call to the correct
@@ -455,6 +484,18 @@ interface StoredRunMetadata {
     /** Open extension point — domain-specific fields. */
     [key: string]: unknown;
 }
+/**
+ * Opaque string map an observer's `carry` hook returns for a run (e.g. a trace
+ * context). Core stores it on the run's record and hands it back to later runs; it never
+ * reads it.
+ */
+type RunCarrier = Readonly<Record<string, string>>;
+/** Points at one earlier run, with the carrier that run's observer produced (if any). */
+interface RunRef {
+    readonly runId: string;
+    /** Absent when that run had no observer that carries, or its `carry` returned nothing. */
+    readonly carrier?: RunCarrier;
+}
 /**
  * Persistence contract for agent sessions.
  *
@@ -492,6 +533,12 @@ interface SessionStore {
      * whose initial state equals the forked run's `finalState`.
      * Optional — omit if your store does not support branching.
      *
+     * Save the new session's version-0 record as a seed the next run continues: `phase: 'paused'`,
+     * no `step`, both states equal to the source run's `finalState`, and `branchedFrom` set to the
+     * source session, `runId` and the source run's `carrier` (when it has one). When the source is
+     * itself such a seed, copy its `branchedFrom` instead (or leave it out if it has none): a seed's
+     * own `runId` never ran. The seed has no `carrier` of its own.
+     *
      * @throws {@link BranchNotFoundError} when `runId` is not found in history.
      */
     branch?(agentId: string, sessionId: string, runId: string): Promise<string>;
@@ -560,6 +607,19 @@ interface StoredRun {
      * domain-defined. Absent for runs produced before this field was added.
      */
     readonly metadata?: StoredRunMetadata;
+    /**
+     * What the run's observer returned from `carry` (e.g. its trace context). Describes this
+     * run only. Absent when no observer carried anything.
+     */
+    readonly carrier?: RunCarrier;
+    /**
+     * Set by `SessionStore.branch` on the seed record of a branched session: the run it was
+     * branched from, in the source session. The branched session's first run reports it as
+     * `RunContext.branchedFrom`.
+     */
+    readonly branchedFrom?: RunRef & {
+        readonly sessionId: string;
+    };
 }
 /**
  * Discriminated union returned by {@link Agent.status} describing the lifecycle
@@ -999,6 +1059,8 @@ interface Agent {
      *
      * The optional fourth argument `resources` accepts:
      * - `observer?: Observer` — structured telemetry for the resumed run (see Observability)
+     * - `parentRunId?: string` — the caller's run id, as for `run()`; set on this resumed run's
+     *   `RunContext` only (a later `handle.resume()` on the returned handle does not inherit it)
      * - `events?.onStoreError?` — raw store-error callback (unchanged from prior shape)
      */
     resume(response: unknown, sessionId: string, interruptId: string, resources?: Record<string, unknown>): RunHandle;
@@ -1103,4 +1165,4 @@ declare class LeaseExpiredError extends Error {
     constructor(sessionId: string);
 }
 
-export { type Agent, type BranchCursor, type BranchDef, type ClaimOptions, type Cursor, type DeepWithMarkers, type FieldDefinition, type ForkCursor, type ForkDef, type FrameworkState, type Harness, type Lease, LeaseExpiredError, type LoopDefinition, type LoopNode, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, type ObserverErrorContext, type ObserverErrorSink, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunContext, type RunFn, type RuntimeMarker, SessionBusyError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SignalTransition, type StateFromSchema, type StepContext, type StepDef, type StepSettledEvent, type StepSettledNext, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TelemetryContext, type TransitionTarget, type WrapScope, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };
+export { type Agent, type BranchCursor, type BranchDef, type ClaimOptions, type Cursor, type DeepWithMarkers, type FieldDefinition, type ForkCursor, type ForkDef, type FrameworkState, type Harness, type Lease, LeaseExpiredError, type LoopDefinition, type LoopNode, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, type ObserverErrorContext, type ObserverErrorSink, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunCarrier, type RunContext, type RunFn, type RunRef, type RuntimeMarker, SessionBusyError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SignalTransition, type StateFromSchema, type StepContext, type StepDef, type StepSettledEvent, type StepSettledNext, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TelemetryContext, type TransitionTarget, type WrapScope, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };

package/dist/index.js

@@ -510,6 +510,14 @@ function safeInvoke(hookName, call, sink) {
     reportObserverError(error, { hookName }, sink);
   }
 }
+function safeCall(hookName, call, sink) {
+  try {
+    return call();
+  } catch (error) {
+    reportObserverError(error, { hookName }, sink);
+    return void 0;
+  }
+}
 async function runWrapped(wrap, fn, onObserverError) {
   let p;
   const inner = () => {
@@ -556,6 +564,16 @@ function composeObservers(observers, onObserverError) {
     onStepSettled: (ctx, event) => {
       for (const o of observers) safeInvoke("onStepSettled", () => o.onStepSettled?.(ctx, event), onObserverError);
     },
+    // Each observer isolated on its own; later keys win.
+    carry: (ctx) => {
+      let merged;
+      for (const o of observers) {
+        const carried = safeCall("carry", () => o.carry?.(ctx), onObserverError);
+        if (typeof carried !== "object" || carried === null || Array.isArray(carried)) continue;
+        merged = Object.assign(merged ?? {}, carried);
+      }
+      return merged;
+    },
     // First observer outermost; each layer isolated on its own by runWrapped.
     wrap: (ctx, scope, fn) => {
       const layer = (i) => i === wrappers.length ? fn() : runWrapped((inner) => wrappers[i].wrap(ctx, scope, inner), () => layer(i + 1), onObserverError);
@@ -706,6 +724,11 @@ function stepContextOf(runCtx, stepName) {
 function asError(e) {
   return e instanceof Error ? e : new Error(String(e));
 }
+function normalizeCarrier(carried) {
+  if (typeof carried !== "object" || carried === null || Array.isArray(carried)) return void 0;
+  const entries = Object.entries(carried).filter(([, v]) => typeof v === "string");
+  return entries.length > 0 ? Object.freeze(Object.fromEntries(entries)) : void 0;
+}
 async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callbacks) {
   const { onBeforeStep, onAfterStep, onError, onComplete, onInterrupt } = callbacks ?? {};
   const obs = callbacks?.observer;
@@ -715,19 +738,27 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
   if (!("$interrupt" in state)) state.$interrupt = null;
   if (!("$interruptResponses" in state)) state.$interruptResponses = {};
   const runStart = Date.now();
+  const branchPath = callbacks?.branchPath;
+  const isBranch = branchPath !== void 0 && branchPath.length > 0;
   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 } : {},
-    ...callbacks?.branchPath !== void 0 && callbacks.branchPath.length > 0 ? { branchPath: callbacks.branchPath } : {}
+    ...isBranch ? { branchPath } : {},
+    // Branch runLoops receive the outer callbacks by spread, so the refs are dropped here.
+    ...!isBranch && callbacks?.resumedFrom !== void 0 ? { resumedFrom: callbacks.resumedFrom } : {},
+    ...!isBranch && callbacks?.branchedFrom !== void 0 ? { branchedFrom: callbacks.branchedFrom } : {}
   };
   safeInvoke("onRunStart", () => obs?.onRunStart?.(runCtx), onObserverError);
+  const carrier = isBranch ? void 0 : normalizeCarrier(safeCall("carry", () => obs?.carry?.(runCtx), onObserverError));
+  const withCarrier = (result) => carrier !== void 0 ? { ...result, carrier } : result;
   let runEnded = false;
-  const endRun = (signal) => {
+  const endRun = (signal, failure) => {
     runEnded = true;
-    safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal, durationMs: Date.now() - runStart }), onObserverError);
+    const event = { signal, durationMs: Date.now() - runStart, ...failure !== void 0 ? { error: failure.error } : {} };
+    safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, event), onObserverError);
   };
   const callCountRef = { current: 0 };
   const stepCtxRef = { current: null };
@@ -740,7 +771,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
     while (true) {
       if (shouldStop?.()) {
         endRun("$stopped");
-        return { state, signal: null, cursor, paused: true };
+        return withCarrier({ state, signal: null, cursor, paused: true });
       }
       if (isForkCursor(cursor)) {
         const forkCursor = cursor;
@@ -764,7 +795,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
           graph
         );
         if (outcome.done) {
-          return outcome.result;
+          return withCarrier(outcome.result);
         }
         cursor = outcome.nextCursor;
         continue;
@@ -787,7 +818,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
           graph
         );
         if (outcome.done) {
-          return outcome.result;
+          return withCarrier(outcome.result);
         }
         cursor = outcome.nextCursor;
         continue;
@@ -833,7 +864,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
             safeInvoke("onInterrupt", () => obs?.onInterrupt?.(stepCtx, { prompt: e.prompt, interruptId: e.interruptId }), onObserverError);
             settle({ outcome: "interrupt", interrupt: { interruptId: e.interruptId, prompt: e.prompt }, next: { kind: "pause" } });
             endRun("$interrupt");
-            return { state, signal: "$interrupt", cursor, paused: true };
+            return withCarrier({ state, signal: "$interrupt", cursor, paused: true });
           }
           state.$error = e instanceof Error ? e : new Error(String(e));
           onError?.(state.$error, cursor);
@@ -854,8 +885,8 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
         } catch (e) {
           state.$error = e instanceof Error ? e : new Error(String(e));
           settle({ outcome: "error", error: state.$error, next: { kind: "pause" } });
-          endRun("$error");
-          return { state, signal: "$error", cursor, paused: true };
+          endRun("$error", { error: state.$error });
+          return withCarrier({ state, signal: "$error", cursor, paused: true });
         }
         const routed = runSucceeded || step.run === void 0 ? { outcome: "ok", signal } : { outcome: "error", signal, error: state.$error };
         const transition = step.transitions.find((t) => t.signal === signal);
@@ -868,7 +899,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
           settle({ ...routed, next: { kind: "end" } });
           onComplete?.(state, signal);
           endRun(signal);
-          return { state, signal, cursor: null, paused: false };
+          return withCarrier({ state, signal, cursor: null, paused: false });
         }
         settle({ ...routed, next: { kind: "step", name: transition.target.name } });
         cursor = transition.target.name;
@@ -878,8 +909,8 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
           cursor = graph.onError;
         } else {
           settle({ outcome: "error", error: state.$error, next: { kind: "pause" } });
-          endRun("$error");
-          return { state, signal: "$error", cursor, paused: true };
+          endRun("$error", { error: state.$error });
+          return withCarrier({ state, signal: "$error", cursor, paused: true });
         }
       } else {
         const next = step.next ?? implicitNextMap.get(cursor) ?? null;
@@ -893,7 +924,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
       }
     }
   } catch (e) {
-    if (!runEnded) endRun("$error");
+    if (!runEnded) endRun("$error", { error: e });
     throw e;
   }
 }
@@ -1036,7 +1067,7 @@ async function handleFork(forkNode, priorBranches, state, ctx, schema, shouldSto
       return { done: false, nextCursor: graph.onError };
     }
     fireSettled(obs, stepCtx, stepStart, { outcome: "error", error: state.$error, next: { kind: "pause" } }, onObserverError);
-    endRun("$error");
+    endRun("$error", { error: state.$error });
     return { done: true, result: { state, signal: "$error", cursor: forkNode.name, paused: true } };
   }
   state.$error = null;
@@ -1248,6 +1279,13 @@ async function querySessionPhase(store, agentId, sessionId) {
   const loaded = await store.load(agentId, sessionId);
   return storedSessionToPhase(loaded);
 }
+function runRefsOf(loaded) {
+  if (loaded === null || loaded.phase !== "paused") return {};
+  if (loaded.step !== void 0) {
+    return { resumedFrom: { runId: loaded.runId, ...loaded.carrier !== void 0 ? { carrier: loaded.carrier } : {} } };
+  }
+  return loaded.branchedFrom !== void 0 ? { branchedFrom: loaded.branchedFrom } : {};
+}
 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);
@@ -1299,7 +1337,8 @@ async function runWithSession(store, agentId, sessionId, runId, graph, initialSt
   const result = await runLoop(graph, state, ctx, schema, composedShouldStop, loaded?.step, {
     ...options,
     runId,
-    ...options?.parentRunId !== void 0 ? { parentRunId: options.parentRunId } : {}
+    ...options?.parentRunId !== void 0 ? { parentRunId: options.parentRunId } : {},
+    ...runRefsOf(loaded)
   });
   if (leaseExpired) {
     const expiredError = new LeaseExpiredError(sessionId);
@@ -1323,7 +1362,8 @@ async function runWithSession(store, agentId, sessionId, runId, graph, initialSt
         finalState: result.state,
         step: result.cursor,
         ...result.signal !== null ? { signal: result.signal } : {},
-        ...metadata !== void 0 ? { metadata } : {}
+        ...metadata !== void 0 ? { metadata } : {},
+        ...result.carrier !== void 0 ? { carrier: result.carrier } : {}
       };
       await store.save(agentId, sessionId, saved);
     } else {
@@ -1338,7 +1378,8 @@ async function runWithSession(store, agentId, sessionId, runId, graph, initialSt
         initialState: initialStateSnapshot,
         finalState: result.state,
         ...result.signal !== null ? { signal: result.signal } : {},
-        ...metadata !== void 0 ? { metadata } : {}
+        ...metadata !== void 0 ? { metadata } : {},
+        ...result.carrier !== void 0 ? { carrier: result.carrier } : {}
       };
       await store.save(agentId, sessionId, saved);
     }
@@ -1415,7 +1456,10 @@ async function injectInterruptResponse(store, agentId, sessionId, interruptId, r
     initialState: loaded.initialState,
     finalState: result.state,
     ...result.cursor !== void 0 ? { step: result.cursor } : {},
-    ...loaded.signal !== void 0 ? { signal: loaded.signal } : {}
+    ...loaded.signal !== void 0 ? { signal: loaded.signal } : {},
+    ...loaded.metadata !== void 0 ? { metadata: loaded.metadata } : {},
+    ...loaded.carrier !== void 0 ? { carrier: loaded.carrier } : {},
+    ...loaded.branchedFrom !== void 0 ? { branchedFrom: loaded.branchedFrom } : {}
   };
   await store.save(agentId, sessionId, updated);
 }
@@ -1660,7 +1704,8 @@ function createAgent(id, h, slots, agentOptions) {
   const reservedRunKeys = /* @__PURE__ */ new Set(["sessionId", "signal", "events", "listeners", "observer", "onObserverError", "claimOptions", "parentRunId"]);
   const inFlightSessions = /* @__PURE__ */ new Set();
   const interruptPendingSessions = /* @__PURE__ */ new Set();
-  const makeAgentResumeHandle = (resp, sId, iId, resumeOpts, observer, onObserverError, telemetrySlots) => {
+  const makeAgentResumeHandle = (resp, sId, iId, resumeResources = {}) => {
+    const { onStoreError, observer, onObserverError, telemetrySlots, parentRunId } = resumeResources;
     let _stopped = false;
     const abortController = new AbortController();
     const flag = {
@@ -1685,14 +1730,14 @@ function createAgent(id, h, slots, agentOptions) {
             lease = await capturedStore.claim(id, sId, claimOptions);
           } catch (claimError) {
             const loadError = new StoreLoadError(claimError);
-            resumeOpts?.onStoreError?.(loadError, "claim");
+            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");
+            onStoreError?.(busyError, "claim");
             const failState = initializeState(null, {}, agentInternals.stateSchema);
             failState["$error"] = busyError;
             return { state: failState, signal: "$error" };
@@ -1706,7 +1751,7 @@ function createAgent(id, h, slots, agentOptions) {
           } catch (injectError) {
             if (injectError instanceof NoInterruptError) throw injectError;
             const storeError = new StoreLoadError(injectError);
-            resumeOpts?.onStoreError?.(storeError, "claim");
+            onStoreError?.(storeError, "claim");
             const failState = initializeState(null, {}, agentInternals.stateSchema);
             failState["$error"] = storeError;
             return { state: failState, signal: "$error" };
@@ -1716,7 +1761,8 @@ function createAgent(id, h, slots, agentOptions) {
             agentId: id,
             sessionId: sId,
             runId: rId,
-            signal: abortController.signal
+            signal: abortController.signal,
+            ...agentOptions?.instanceId !== void 0 ? { instanceId: agentOptions.instanceId } : {}
           };
           const r = await runWithSession(
             capturedStore,
@@ -1732,11 +1778,13 @@ function createAgent(id, h, slots, agentOptions) {
               onBeforeStep: (n) => {
                 ref.current = n;
               },
-              ...resumeOpts?.onStoreError !== void 0 ? { onStoreError: resumeOpts.onStoreError } : {},
+              ...onStoreError !== void 0 ? { onStoreError } : {},
               ...leaseRef !== void 0 ? { leaseRef, claimTtlMs: claimOptions.ttlMs } : {},
               ...observer !== void 0 ? { observer } : {},
               ...onObserverError !== void 0 ? { onObserverError } : {},
-              ...telemetrySlots !== void 0 && telemetrySlots.length > 0 ? { telemetrySlots } : {}
+              ...telemetrySlots !== void 0 && telemetrySlots.length > 0 ? { telemetrySlots } : {},
+              ...agentOptions?.instanceId !== void 0 ? { instanceId: agentOptions.instanceId } : {},
+              ...parentRunId !== void 0 ? { parentRunId } : {}
             }
           );
           if (r.signal === "$interrupt") interruptPendingSessions.add(sId);
@@ -1764,7 +1812,8 @@ function createAgent(id, h, slots, agentOptions) {
       if (inFlightSessions.has(sId)) throw new SessionInFlightError(sId);
       interruptPendingSessions.delete(sId);
       inFlightSessions.add(sId);
-      return makeAgentResumeHandle(r, sId, i);
+      const { parentRunId: _staleParentRunId, ...inherited } = resumeResources;
+      return makeAgentResumeHandle(r, sId, i, inherited);
     };
     return createRunHandle(sId, rId, exec, flag, ref, resumeFn);
   };
@@ -1900,7 +1949,7 @@ function createAgent(id, h, slots, agentOptions) {
               }
             );
             if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
-            lastResult = { state: r.state, cursor: r.cursor };
+            lastResult = { state: r.state, cursor: r.cursor, runId, ...r.carrier !== void 0 ? { carrier: r.carrier } : {} };
             return { state: r.state, signal: r.signal };
           } catch (error) {
             if (error instanceof LeaseExpiredError) {
@@ -1973,11 +2022,12 @@ function createAgent(id, h, slots, agentOptions) {
                     ...Object.keys(listeners).length > 0 ? { listeners } : {},
                     ...observer !== void 0 ? { observer } : {},
                     ...onObserverError !== void 0 ? { onObserverError } : {},
-                    ...telemetrySlots.length > 0 ? { telemetrySlots } : {}
+                    ...telemetrySlots.length > 0 ? { telemetrySlots } : {},
+                    ...agentOptions?.instanceId !== void 0 ? { instanceId: agentOptions.instanceId } : {}
                   }
                 );
                 if (r2.signal === "$interrupt") interruptPendingSessions.add(sessionId);
-                lastResult = { state: r2.state, cursor: r2.cursor };
+                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;
@@ -1995,6 +2045,7 @@ function createAgent(id, h, slots, agentOptions) {
                 cursor,
                 {
                   runId: resumeRunId,
+                  resumedFrom: { runId: prev.runId, ...prev.carrier !== void 0 ? { carrier: prev.carrier } : {} },
                   onBeforeStep: (n, s) => {
                     resumeStepRef.current = n;
                     events.onBeforeStep?.(n, s);
@@ -2010,7 +2061,7 @@ function createAgent(id, h, slots, agentOptions) {
                 }
               );
               if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
-              lastResult = { state: r.state, cursor: r.cursor };
+              lastResult = { state: r.state, cursor: r.cursor, runId: resumeRunId, ...r.carrier !== void 0 ? { carrier: r.carrier } : {} };
               return { state: r.state, signal: r.signal };
             } catch (error) {
               if (error instanceof LeaseExpiredError) {
@@ -2033,11 +2084,17 @@ function createAgent(id, h, slots, agentOptions) {
       interruptPendingSessions.delete(sessionId);
       inFlightSessions.add(sessionId);
       const events = extractRunEvents(resources ?? {});
-      const resumeOpts = events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : void 0;
       const observer = extractRunObserver(resources ?? {});
       const onObserverError = extractRunErrorSink(resources ?? {});
       const telemetrySlots = buildTelemetrySlots(agentInternals.resolvedProviders.entries());
-      return makeAgentResumeHandle(response, sessionId, interruptId, resumeOpts, observer ?? void 0, onObserverError ?? void 0, telemetrySlots.length > 0 ? telemetrySlots : void 0);
+      const parentRunId = resources?.["parentRunId"];
+      return makeAgentResumeHandle(response, sessionId, interruptId, {
+        ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
+        ...observer !== void 0 ? { observer } : {},
+        ...onObserverError !== void 0 ? { onObserverError } : {},
+        ...telemetrySlots.length > 0 ? { telemetrySlots } : {},
+        ...typeof parentRunId === "string" ? { parentRunId } : {}
+      });
     },
     status: (sessionId) => querySessionPhase(capturedStore, id, sessionId),
     [_agentInternals]: agentInternals