ai-sdk-harness-sessions 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # ai-sdk-harness-sessions
 
+## 0.3.0
+
+### Minor Changes
+
+- 02b3ad7: `onTurn`, a new option of `createSessionManager()`, is called once each turn is over and the session written, with a `TurnReport`: the turn's tokens, cache reads and writes included, the model, tokens and tool calls of each step, and the raw events of its harness — Claude Code's `rate_limit_event`, for instance. An application can account for its sessions, and read the rate limits of a subscription. `SessionStreamResult` may give `steps` and `fullStream`, as a `StreamTextResult` does; an agent whose results give neither reports its tokens only.
+
+## 0.2.1
+
+### Patch Changes
+
+- d1448b3: Closing or deleting an `interrupted` session now discards its sandbox, as it does for a `suspended` one. A session the process left live when it stopped without suspending it kept its sandbox forever: with `sandboxPerSession()`, a session created again under the same id then failed, its sandbox's name already taken.
+- 116b98c: A resume that fails no longer closes the session's sandbox lease: it hands it back with `suspend()`, as a suspension does, so the sandbox and the files the next try resumes from are kept. With `sandboxPerSession()`, a failed resume destroyed the session's sandbox while the session stayed `suspended`, waiting to resume from it.
+- a1197a2: Several managers can share one store: the instances of an application behind a load balancer, scaled out, or a new version deployed beside the old one. A store that implements three more methods — `claimSession`, `renewLease` and `releaseSession`, the lease of each manager kept on the database's clock — lets each manager run the sessions it holds:
+  
+  - a starting manager no longer marks `interrupted` the live sessions of the others, only those of a manager whose lease expired;
+  - a request for a session another manager runs fails with `SessionOwnedElsewhereError` (a `SessionConflictError`), which names that manager (`owner`, the new `managerId` option) so that the application can route the request to it;
+  - a suspended session is resumed by whichever manager receives its next message;
+  - once the lease of a manager that crashed has expired, the others mark its live sessions `interrupted`.
+  
+  `leaseTtlMs` sets the lease (30 seconds by default). A store without these methods works as before, with one manager.
+- 32e5121: The message sent after a turn cut short is answered. Claude Code goes on with a turn for a moment after it is told to stop, and the harness session handed what it still said to the next turn: that turn failed with "Received text-delta for missing text part", or ended at once without its answer. A turn cut short by `interrupt()`, `turnTimeoutMs` or the caller's `abortSignal` now starts its harness session again, in the same sandbox and the same conversation, before the next turn.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -22,7 +22,8 @@ import { createSessionManager, sharedSandbox } from 'ai-sdk-harness-sessions';
 const sessions = createSessionManager({
   // The agent of a session, from what you keep with it.
   agent: ({ metadata }) => agents[metadata.agent],
-  // One sandbox for every session, each with a port of its own for its bridge.
+  // One sandbox for every session, each with a port of its own for its bridge. `openSandbox` is
+  // yours: it opens a sandbox of ai-sdk-sandbox-sbx, ai-sdk-sandbox-cloud-run… (see "Sandboxes").
   sandboxes: sharedSandbox({
     open: openSandbox,
     ports: Array.from({ length: 4 }, (_, i) => 4001 + i),
@@ -46,6 +47,7 @@ return turn.toUIMessageStreamResponse();
 | Every sandbox slot is taken            | Suspends the session idle the longest to make room                                                                   |
 | Your server stops (`shutdown()`)       | Cuts the turns under way short, and suspends every session: the next start resumes them on their next message        |
 | Your server crashes                    | Marks the sessions it held `interrupted` at the next start: their conversation can still be read                     |
+| Your server runs on several instances  | With a store that gives leases, each instance runs the sessions it holds, and takes over those of one that crashed   |
 | You want the conversation again        | `get(id)` gives it as `useChat` shows it, `list()` every session, `subscribe()` every change, for a list to follow   |
 
 ## Installation
@@ -134,6 +136,8 @@ export async function POST(request: Request) {
 
 The turn is read to its end on your server as well: a user who closes the tab does not leave the session hanging, and the session is written either way. `abortSignal: request.signal` lets the stop button of `useChat` cut the turn short; leave it out for turns that go on without the client. `interrupt(id)` cuts a turn short from anywhere.
 
+A turn cut short — by `interrupt(id)`, `turnTimeoutMs` or the caller's `abortSignal` — starts its harness session again, in the same sandbox, before the session takes another message. A runtime goes on with a turn for a moment after it is told to stop, and its harness session would hand what it still says to the next turn: that turn would end at once, its answer lost ([vercel/ai#23507](https://github.com/vercel/ai/issues/23507)). The conversation goes on where it stopped; starting again takes a few seconds. A harness session that cannot start again leaves the session `suspended`, resumed by the next message.
+
 ### Showing the conversations again
 
 ```ts
@@ -183,16 +187,16 @@ stateDiagram-v2
   busy --> interrupted: the server crashed
 ```
 
-| Status           | What it means                                                                                                      |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `preparing`      | Its sandbox and harness session are being opened, or brought back from `suspended`. A message sent meanwhile waits |
-| `idle`           | Ready for a message                                                                                                |
-| `busy`           | A turn is under way. Another message is refused until it ends                                                      |
-| `awaiting-input` | The turn paused on a tool call that waits for you: an approval, or the result of a tool your application runs      |
-| `suspended`      | Stopped, its state kept in the store and its sandbox freed. The next message, or `continue()`, brings it back      |
-| `closed`         | Ended for good. Its conversation can still be read                                                                 |
-| `failed`         | A new session that could not start: a sandbox that did not open, say. The next message tries again                 |
-| `interrupted`    | Cannot be brought back: the server stopped without suspending it. Its conversation can still be read               |
+| Status           | What it means                                                                                                                                   |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preparing`      | Its sandbox and harness session are being opened, or brought back from `suspended`. A message sent meanwhile waits                              |
+| `idle`           | Ready for a message                                                                                                                             |
+| `busy`           | A turn is under way. Another message is refused until it ends                                                                                   |
+| `awaiting-input` | The turn paused on a tool call that waits for you: an approval, or the result of a tool your application runs                                   |
+| `suspended`      | Stopped, its state kept in the store and its sandbox freed. The next message, or `continue()`, brings it back                                   |
+| `closed`         | Ended for good. Its conversation can still be read                                                                                              |
+| `failed`         | A new session that could not start: a sandbox that did not open, say. The next message tries again                                              |
+| `interrupted`    | Cannot be brought back: the server stopped without suspending it. Its conversation can still be read; `close()` or `delete()` frees its sandbox |
 
 A session that fails to resume stays `suspended`, with the reason in its `error`: the next message tries again from the same state.
 
@@ -261,7 +265,7 @@ Where each session runs is up to `sandboxes`:
 | `sandboxPerSession({ create, resume, maxSessions })` | A sandbox of its own, stopped when the session is suspended, destroyed when it is closed                    | Sessions that must not see each other: one per user or per repository |
 | Your own `SessionSandboxes`                          | What `acquire(sessionId, { resume })` returns                                                               | A pool, a sandbox per user shared by their sessions…                  |
 
-`sharedSandbox()` takes sandboxes that give views of themselves, `fork({ ports })`: those of `ai-sdk-sandbox-sbx` and `ai-sdk-sandbox-cloud-run`. A suspended session hands its port back and keeps its files in the sandbox. With `stopWhenUnused`, the sandbox itself is stopped once no session holds it, and opened again with the next one: on Cloud Run, a stopped sandbox costs its snapshot's storage alone.
+`sharedSandbox()` takes sandboxes that give views of themselves, `fork({ ports })`: those of `ai-sdk-sandbox-sbx`, `ai-sdk-sandbox-cloud-run` and `ai-sdk-sandbox-runtime`. A suspended session hands its port back and keeps its files in the sandbox. With `stopWhenUnused`, the sandbox itself is stopped once no session holds it, and opened again with the next one: on Cloud Run, a stopped sandbox costs its snapshot's storage alone.
 
 ```ts
 import { createSbxNetworkSandboxSession, resumeSbxNetworkSandboxSession } from 'ai-sdk-sandbox-sbx';
@@ -276,6 +280,48 @@ const sandboxes = sandboxPerSession({
 });
 ```
 
+### Opening the sandbox
+
+The package imports no sandbox package: the `open()` of `sharedSandbox()`, and the `create()` and `resume()` of `sandboxPerSession()`, are functions you write with the sandbox package of your choice. Throughout this documentation, `openSandbox` is the function of [The manager](#the-manager): it finds the sandbox again when it exists, and creates it otherwise. To run the sessions somewhere else, change that function and nothing else:
+
+| Sandbox package                                                                                      | Its functions                                                                            | `sharedSandbox()`      | `sandboxPerSession()` |
+| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------- | --------------------- |
+| [`ai-sdk-sandbox-sbx`](https://ai-sdk-harness.pages.dev/docs/packages/sandbox-sbx)                   | `createSbxNetworkSandboxSession()`, `resumeSbxNetworkSandboxSession()`                   | Yes                    | Yes                   |
+| [`ai-sdk-sandbox-cloud-run`](https://ai-sdk-harness.pages.dev/docs/packages/sandbox-cloud-run)       | `createCloudRunNetworkSandboxSession()`, `resumeCloudRunNetworkSandboxSession()`         | Yes                    | Yes                   |
+| [`ai-sdk-sandbox-runtime`](https://ai-sdk-harness.pages.dev/docs/packages/sandbox-runtime)           | `createSrtNetworkSandboxSession()`, `resumeSrtNetworkSandboxSession()`                   | Yes                    | Yes                   |
+| [`ai-sdk-sandbox-microsandbox`](https://ai-sdk-harness.pages.dev/docs/packages/sandbox-microsandbox) | `createMicrosandboxNetworkSandboxSession()`, `resumeMicrosandboxNetworkSandboxSession()` | No: it has no `fork()` | Yes                   |
+
+The same `openSandbox` on Cloud Run, through the sandbox service you deployed:
+
+```ts
+import {
+  CloudRunSandboxNotFoundError,
+  createCloudRunNetworkSandboxSession,
+  resumeCloudRunNetworkSandboxSession,
+} from 'ai-sdk-sandbox-cloud-run';
+
+async function openSandbox() {
+  const settings = {
+    url: process.env.CLOUD_RUN_SANDBOX_URL!,
+    sandboxId: 'my-app',
+    ports: [4000],
+    // The bridges install their dependencies from npm.
+    allowedHosts: ['registry.npmjs.org'],
+  };
+  try {
+    const sandbox = await resumeCloudRunNetworkSandboxSession(settings);
+    await sandbox.killAllProcesses();
+    return sandbox;
+  } catch (error) {
+    if (!(error instanceof CloudRunSandboxNotFoundError)) throw error;
+  }
+  const template = await createHarnessSandboxTemplate({ harnesses: [harness] });
+  return createCloudRunNetworkSandboxSession({ ...settings, template });
+}
+```
+
+The [Next.js example](https://github.com/fpasquet/ai-sdk-harness/tree/main/examples/next-chat) picks one of the four with an environment variable, `EXAMPLE_SANDBOX`: see its `lib/sandbox.ts`.
+
 ### How many sessions run at once
 
 Claude Code and Codex run behind a bridge: a process the harness starts in the sandbox for each session, listening on a port of the sandbox that your server reaches over a WebSocket (published on `127.0.0.1` by `sbx`, tunnelled by the Cloud Run service). The harness takes the first port of the sandbox session it is given, so two sessions handed the same sandbox would both listen on it. `sharedSandbox()` gives each session a view of the sandbox with a port of its own: the same microVM, the same installed tools, a working directory of its own, and a port of `ports` for its bridge.
@@ -323,7 +369,78 @@ const store: SessionStore<Metadata> = {
 
 A resume state holds secrets: the token of the harness bridge, the placeholders of the credentials. Keep it apart from what you show, as you would a session token. The [Next.js example](https://github.com/fpasquet/ai-sdk-harness/tree/main/examples/next-chat) keeps its sessions in JSON files (`lib/session-store.ts`).
 
-Keep one manager per store: at its start, a manager takes the sessions the store holds as live for those of a process that crashed, and marks them `interrupted`.
+Keep one manager per store, unless the store gives leases (below): at its start, a manager takes the sessions the store holds as live for those of a process that crashed, and marks them `interrupted`.
+
+### What a turn cost
+
+`onTurn` is called once each turn is over and the session written, with a `TurnReport`: the turn's tokens, cache reads and writes included, each of its steps — the model that answered, its tokens and the tools it called, with their input — and the raw events of its harness, in order. Keep them to account for your sessions, or to read the rate limits of a subscription, which Claude Code reports as `rate_limit_event`:
+
+```ts
+const sessions = createSessionManager<Metadata>({
+  // …
+  onTurn: async ({ sessionId, usage, steps, rawEvents }) => {
+    await db.turns.insert({
+      sessionId,
+      inputTokens: usage.inputTokens,
+      cacheReadTokens: usage.inputTokenDetails.cacheReadTokens,
+      outputTokens: usage.outputTokens,
+      models: [...new Set(steps.map(({ modelId }) => modelId))],
+    });
+    const limits = rawEvents.filter(
+      (event) => (event as { type?: string }).type === 'rate_limit_event',
+    );
+    if (limits.length > 0) await db.rateLimits.insert(sessionId, limits.at(-1));
+  },
+});
+```
+
+A `rate_limit_event` of Claude Code (signed in with a subscription) gives every window in `rate_limit_info.unifiedWindows`, such as `five_hour` and `seven_day`, each with its `utilization` (a fraction) and its `resetsAt` (in seconds). The harness names its tools in lower case: `bash`, not `Bash`.
+
+The steps and the raw events come from the agent's result, `steps` and `fullStream`: a `HarnessAgent` gives both; an agent of your own that gives neither reports its tokens only. What `onTurn` throws goes to `onError`; the turn is settled either way.
+
+### Several instances
+
+An application that runs on several instances — behind a load balancer, scaled out, or a new version deployed beside the old one — shares one store between their managers. The store tells them apart with leases: three more methods, on the same database, and the managers share it.
+
+- Each manager holds the sessions it runs, and renews its own lease three times within `leaseTtlMs` (30 seconds by default).
+- A request for a session another manager runs fails with `SessionOwnedElsewhereError`, which names it (`owner`, its `managerId`): send the request there, or answer 409 and let the client try again. Reading a session, `get()` and `list()`, works from any instance.
+- A suspended session is held by nobody: the next message resumes it on whichever instance receives it.
+- A manager that crashed stops renewing its lease. Once it expired, the others mark its live sessions `interrupted`, within a lease or so, and so does any manager that starts.
+
+```ts
+const store: SessionStore<Metadata> = {
+  // …the five methods above, and:
+  claimSession: async (id, owner) => {
+    // One statement, so that two managers never both win: take the session unless a manager
+    // whose lease has not expired holds it.
+    const row = await db.query(
+      `INSERT INTO session_owners (session_id, owner) VALUES ($1, $2)
+       ON CONFLICT (session_id) DO UPDATE SET owner = $2
+         WHERE session_owners.owner = $2
+            OR NOT EXISTS (SELECT 1 FROM manager_leases l
+                           WHERE l.owner = session_owners.owner AND l.expires_at > now())
+       RETURNING (SELECT owner FROM session_owners WHERE session_id = $1) AS previous_owner`,
+      [id, owner],
+    );
+    if (row) return { claimed: true, previousOwner: row.previous_owner };
+    const { owner: holder } = await db.query(
+      'SELECT owner FROM session_owners WHERE session_id = $1',
+      [id],
+    );
+    return { claimed: false, owner: holder };
+  },
+  renewLease: (owner, ttlMs) =>
+    db.query(
+      `INSERT INTO manager_leases (owner, expires_at) VALUES ($1, now() + $2 * interval '1 ms')
+       ON CONFLICT (owner) DO UPDATE SET expires_at = excluded.expires_at`,
+      [owner, ttlMs],
+    ),
+  releaseSession: (id, owner) =>
+    db.query('DELETE FROM session_owners WHERE session_id = $1 AND owner = $2', [id, owner]),
+};
+```
+
+The lease's expiry is read on the database's clock, the one clock all instances share. `delete()` forgets who holds the session too. Give each manager a `managerId` you can route by — the instance's address, a pod name — to send a request to the instance that runs the session; never two running managers the same.
 
 ## Reference
 
@@ -333,7 +450,9 @@ Keep one manager per store: at its start, a manager takes the sessions the store
 | ----------------------- | ------------------------ | --------------------------------------------------------------------------------------------------- |
 | `agent`                 | required                 | The agent of a session, from `{ id, metadata }`: called at each start and resume                    |
 | `sandboxes`             | required                 | `sharedSandbox()`, `sandboxPerSession()` or your own `SessionSandboxes`                             |
-| `store`                 | in memory                | Where sessions are kept: a `SessionStore`                                                           |
+| `store`                 | in memory                | Where sessions are kept: a `SessionStore`, shared by several managers when it gives leases          |
+| `managerId`             | `crypto.randomUUID()`    | This manager among those sharing the store, named by `SessionOwnedElsewhereError`                   |
+| `leaseTtlMs`            | 30 seconds               | How long this manager holds its sessions without renewing its lease, with a store that gives leases |
 | `idleTimeoutMs`         | never                    | Suspend a session idle, or awaiting input, for this long                                            |
 | `closeSuspendedAfterMs` | never                    | Close a session suspended for this long                                                             |
 | `turnTimeoutMs`         | never                    | Cut a turn short after this long                                                                    |
@@ -341,6 +460,7 @@ Keep one manager per store: at its start, a manager takes the sessions the store
 | `approve`               | none                     | Answers an approval before anyone sees it: `{ approved, reason }`, or `undefined` to ask a person   |
 | `generateId`            | `crypto.randomUUID`      | The ids of new sessions and of the messages of their turns                                          |
 | `errorMessage`          | `getHarnessErrorMessage` | What a client is told of an error in a turn; the session's `error` keeps the full message           |
+| `onTurn`                | none                     | Called once each turn is over, with its `TurnReport`: tokens in detail, steps, raw harness events   |
 | `onError`               | `console.error`          | Called with what fails in the background: a start, a suspension, a write to the store               |
 
 | Method                     | What it does                                                                                               |
@@ -365,11 +485,12 @@ Each has an `isInstance()` that recognizes it whichever copy of the package thre
 
 - `SessionNotFoundError` (404): no session has this id. Carries `sessionId`.
 - `SessionConflictError` (409): the session cannot do it in its status — a message while `busy` or `awaiting-input`, `continue()` with nothing to answer, anything once `closed` or `interrupted`. Carries `sessionId` and `status`.
+- `SessionOwnedElsewhereError` (409, or a redirect): another manager sharing the store runs the session. A `SessionConflictError` as well; carries `owner`, that manager's `managerId`.
 - `SessionCapacityError` (503): every sandbox slot is taken by a session that is not idle. Carries `capacity`.
 
 ## Limitations
 
-- **One process per store.** The live sessions are held in the memory of one process: run the manager on one instance, or give each instance its own sessions.
+- **One process per store, unless it gives leases.** Without `claimSession`, `renewLease` and `releaseSession`, the live sessions are held in the memory of one process: run the manager on one instance. With them, a turn under way is still read from the instance that runs it: a client whose request reaches another one gets `SessionOwnedElsewhereError`. And a manager stalled for longer than its lease — a process frozen, not crashed — may find its sessions taken over by another one when it wakes up.
 - **A turn does not survive a crash.** A session the process held when it crashed is `interrupted`; a clean `shutdown()` suspends it instead. Streams that reconnect after a page reload are not supported yet: a reload cuts the turn its request carried when it passed `abortSignal: request.signal`.
 - **Approvals after a resume, with Claude Code.** A resumed Claude Code session (`@ai-sdk/harness-claude-code` up to 1.0.152) sends "Continue." in place of the answers to the approvals it asks afterwards: the tool call is rejected, and asked again ([vercel/ai#22549](https://github.com/vercel/ai/issues/22549)). Approvals work in a session until it is suspended; a session that resumed asks again and again. A turn that was waiting for an approval when its session was suspended resumes without it: `continue()` tells the agent the answers in a message.
 - **No approvals of Codex's own tools.** `@ai-sdk/harness-codex` (up to 1.0.150) runs Codex with approvals turned off and refuses any `permissionMode` but `'allow-all'`, though Codex itself can ask before a command or a patch ([vercel/ai#22550](https://github.com/vercel/ai/issues/22550)). Your own tools can still ask, through `toolApproval`.

package/dist/definitions/agent.d.ts

@@ -3,8 +3,12 @@ import type { HarnessAgentResumeSessionState, HarnessAgentSession } from '@ai-sd
 import type { StreamTextResult, ToolApprovalResponse, ToolResultPart, ToolSet } from 'ai';
 /** A turn's result, whatever the agent's runtime context and output. */
 type AnyStreamTextResult = StreamTextResult<ToolSet, any, any>;
-/** What the manager reads of a turn: a `StreamTextResult` is one. */
-export type SessionStreamResult = Pick<AnyStreamTextResult, 'totalUsage' | 'toUIMessageStream'>;
+/**
+ * What the manager reads of a turn: a `StreamTextResult` is one. Its `steps` and `fullStream`, when
+ * it has them, give `onTurn` the model, the tokens and the tools of each step, and the raw events of
+ * the harness.
+ */
+export type SessionStreamResult = Partial<Pick<AnyStreamTextResult, 'fullStream' | 'steps'>> & Pick<AnyStreamTextResult, 'totalUsage' | 'toUIMessageStream'>;
 /**
  * What the manager needs of an agent: a `HarnessAgent` is one, whatever its harness, tools and
  * settings.

package/dist/definitions/manager.d.ts

@@ -1,7 +1,7 @@
 import type { ToolApprovalResponse, ToolResultPart, UIMessage, UIMessageChunk } from 'ai';
 import type { SessionAgent } from './agent.js';
 import type { SessionSandboxes } from './sandboxes.js';
-import type { ApprovalVerdict, PendingApproval, SessionRecord, SessionSummary } from './session.js';
+import type { ApprovalVerdict, PendingApproval, SessionRecord, SessionSummary, TurnReport } from './session.js';
 import type { SessionStore } from './store.js';
 export interface SessionManagerOptions<METADATA> {
     /**
@@ -15,8 +15,25 @@ export interface SessionManagerOptions<METADATA> {
     }) => Promise<SessionAgent> | SessionAgent;
     /** How sessions get a sandbox: `sharedSandbox()`, `sandboxPerSession()`, or your own. */
     sandboxes: SessionSandboxes;
-    /** Where sessions are kept. Default: in memory, `createMemorySessionStore()`. */
+    /**
+     * Where sessions are kept. Default: in memory, `createMemorySessionStore()`. A store that gives
+     * leases (`claimSession`, `renewLease`, `releaseSession`) is shared by several managers: the
+     * instances of an application.
+     */
     store?: SessionStore<METADATA>;
+    /**
+     * This manager, among those sharing the store: what `SessionOwnedElsewhereError.owner` names,
+     * to send a request to the instance that runs the session. Default: `crypto.randomUUID()`. Give
+     * an id of your own — the instance's address — to route by it; never two running managers the
+     * same.
+     */
+    managerId?: string;
+    /**
+     * How long this manager's hold on its sessions lasts without renewal, in milliseconds, with a
+     * store that gives leases: renewed three times within it, and what another manager waits, after
+     * a crash, before taking its sessions over. Default: 30 seconds.
+     */
+    leaseTtlMs?: number;
     /**
      * Suspend a session idle, or awaiting input, for this long, in milliseconds: its harness session
      * stops, its state is kept and its sandbox freed. The next message brings it back. Default:
@@ -51,6 +68,15 @@ export interface SessionManagerOptions<METADATA> {
      * `@ai-sdk/harness`. The session's `error` keeps the full message.
      */
     errorMessage?: (error: unknown) => string;
+    /**
+     * Called once each turn is over and the session written, with what the turn cost: its tokens,
+     * cache reads and writes included, the model, tokens and tool calls of each step, and the raw
+     * events of its harness — what an application needs to account for its sessions, or to read the
+     * rate limits of a subscription. What it throws goes to `onError`; the turn is settled either way.
+     */
+    onTurn?: (report: TurnReport, context: {
+        session: SessionSummary<METADATA>;
+    }) => PromiseLike<void> | void;
     /**
      * Called with what fails in the background: a start, a suspension, a write to the store. Default:
      * `console.error`.
@@ -105,6 +131,8 @@ export type SessionEvent<METADATA = unknown> = {
  * message to the last, across suspensions and restarts. See {@link createSessionManager}.
  */
 export interface SessionManager<METADATA = unknown> {
+    /** This manager, among those sharing the store. */
+    readonly managerId: string;
     /**
      * Opens a session and returns at once, `preparing`: its sandbox and its harness session are
      * opened in the background — minutes the very first time, when the harness is installed in the

package/dist/definitions/session.d.ts

@@ -1,4 +1,4 @@
-import type { UIMessage } from 'ai';
+import type { LanguageModelUsage, UIMessage } from 'ai';
 /**
  * Where a session stands in its lifecycle.
  *
@@ -29,6 +29,36 @@ export interface SessionUsage {
     outputTokens: number;
     totalTokens: number;
 }
+/** A step of a turn: the model that answered, the tokens it used, and the tools it called. */
+export interface TurnStepReport {
+    /** The model, as the harness names it: `claude-sonnet-4-5`, for instance. */
+    modelId: string | undefined;
+    usage: LanguageModelUsage;
+    /** The tools it called, with their input: the skill it loaded, the subagent it started… */
+    toolCalls: {
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    }[];
+}
+/**
+ * A turn once it is over, for accounting: its tokens, cache reads and writes included, each of its
+ * steps, and the raw events its harness sent — rate limits, for instance, which Claude Code reports
+ * as `rate_limit_event`.
+ */
+export interface TurnReport {
+    sessionId: string;
+    startedAt: Date;
+    endedAt: Date;
+    /** What went wrong, when the turn failed or was cut short. */
+    failure: string | undefined;
+    /** The tokens of the whole turn, over all its streams. */
+    usage: LanguageModelUsage;
+    /** Its steps, in order; empty when the agent's results do not give them. */
+    steps: TurnStepReport[];
+    /** The raw events of the harness, in order; empty when the agent's results do not stream them. */
+    rawEvents: unknown[];
+}
 /** An answer to an approval request, as `ToolApprovalResponse` carries it. */
 export interface ApprovalVerdict {
     approved: boolean;

package/dist/definitions/store.d.ts

@@ -21,6 +21,37 @@ export interface SessionStore<METADATA = unknown> {
     list(): Promise<SessionSummary<METADATA>[]>;
     /** What a suspended session needs to resume. */
     getResumeState(id: string): Promise<HarnessAgentResumeSessionState | undefined>;
-    /** Forgets the session and its resume state. */
+    /** Forgets the session and its resume state, and who holds it. */
     delete(id: string): Promise<void>;
+    /**
+     * Optional, with `renewLease` and `releaseSession`: lets several managers share the store — the
+     * instances of an application behind a load balancer, or a new version deployed beside the old
+     * one. A manager holds each session it runs, and keeps its lease alive while it runs: another
+     * manager leaves its sessions alone, and takes them over once its lease expired.
+     *
+     * Makes `owner` hold the session `id`, in one atomic step (a compare-and-set on a database row),
+     * unless another manager whose lease has not expired holds it. The session need not be saved
+     * yet: `create()` takes it before writing it.
+     */
+    claimSession?(id: string, owner: string): Promise<SessionClaim>;
+    /**
+     * Keeps the lease of the manager `owner` alive for `ttlMs` milliseconds from now, by the store's
+     * clock: what decides whether the sessions it holds may be taken over.
+     */
+    renewLease?(owner: string, ttlMs: number): Promise<void>;
+    /** Lets go of the session `id`, when `owner` holds it. */
+    releaseSession?(id: string, owner: string): Promise<void>;
 }
+/** What `claimSession` made of a claim. */
+export type SessionClaim = {
+    claimed: false;
+    /** The manager that holds the session, its lease alive. */
+    owner: string;
+} | {
+    claimed: true;
+    /**
+     * Who held the session before: `null` when nobody did, the claiming manager itself when it
+     * held it already, or a manager whose lease expired.
+     */
+    previousOwner: null | string;
+};

package/dist/errors/session-owned-elsewhere-error.d.ts

@@ -0,0 +1,19 @@
+import type { SessionStatus } from '../definitions/session.js';
+import { SessionConflictError } from './session-conflict-error.js';
+/** What `isInstance` looks for, shared by every copy of this package. */
+declare const MARKER: unique symbol;
+/**
+ * Another manager sharing the store runs the session: send the request to it — the instance
+ * `owner` names —, or answer 409 and let the client try again. A `SessionConflictError` as well.
+ */
+export declare class SessionOwnedElsewhereError extends SessionConflictError {
+    /** The manager that runs the session: its `managerId`. */
+    readonly owner: string;
+    private readonly [MARKER];
+    constructor(sessionId: string, status: SessionStatus, 
+    /** The manager that runs the session: its `managerId`. */
+    owner: string);
+    /** Whether `error` is one, whichever copy of the package threw it. */
+    static isInstance(error: unknown): error is SessionOwnedElsewhereError;
+}
+export {};

package/dist/errors/session-owned-elsewhere-error.js

@@ -0,0 +1,22 @@
+import { SessionConflictError } from './session-conflict-error.js';
+/** What `isInstance` looks for, shared by every copy of this package. */
+const MARKER = Symbol.for('ai-sdk-harness-sessions.SessionOwnedElsewhereError');
+/**
+ * Another manager sharing the store runs the session: send the request to it — the instance
+ * `owner` names —, or answer 409 and let the client try again. A `SessionConflictError` as well.
+ */
+export class SessionOwnedElsewhereError extends SessionConflictError {
+    owner;
+    [MARKER] = true;
+    constructor(sessionId, status, 
+    /** The manager that runs the session: its `managerId`. */
+    owner) {
+        super(sessionId, status, `The session ${sessionId} is run by another manager, ${owner}.`);
+        this.owner = owner;
+        this.name = 'SessionOwnedElsewhereError';
+    }
+    /** Whether `error` is one, whichever copy of the package threw it. */
+    static isInstance(error) {
+        return typeof error === 'object' && error !== null && MARKER in error;
+    }
+}

package/dist/index.d.ts

@@ -2,11 +2,12 @@ export type { SessionAgent, SessionStreamResult } from './definitions/agent.js';
 export type { ContinueOptions, SendOptions, SessionEvent, SessionManager, SessionManagerOptions, SessionTurn, } from './definitions/manager.js';
 export type { SessionSandboxes, SessionSandboxLease } from './definitions/sandboxes.js';
 export { LIVE_STATUSES, SESSION_STATUSES } from './definitions/session.js';
-export type { PendingApproval, PendingInput, PendingToolCall, SessionRecord, SessionStatus, SessionSummary, SessionUsage, } from './definitions/session.js';
-export type { SessionStore } from './definitions/store.js';
+export type { PendingApproval, PendingInput, PendingToolCall, SessionRecord, SessionStatus, SessionSummary, SessionUsage, TurnReport, TurnStepReport, } from './definitions/session.js';
+export type { SessionClaim, SessionStore } from './definitions/store.js';
 export { SessionCapacityError } from './errors/session-capacity-error.js';
 export { SessionConflictError } from './errors/session-conflict-error.js';
 export { SessionNotFoundError } from './errors/session-not-found-error.js';
+export { SessionOwnedElsewhereError } from './errors/session-owned-elsewhere-error.js';
 export { createSessionManager } from './manager/session-manager.js';
 export { sandboxPerSession } from './sandboxes/sandbox-per-session.js';
 export type { SandboxPerSessionOptions } from './sandboxes/sandbox-per-session.js';

package/dist/index.js

@@ -2,6 +2,7 @@ export { LIVE_STATUSES, SESSION_STATUSES } from './definitions/session.js';
 export { SessionCapacityError } from './errors/session-capacity-error.js';
 export { SessionConflictError } from './errors/session-conflict-error.js';
 export { SessionNotFoundError } from './errors/session-not-found-error.js';
+export { SessionOwnedElsewhereError } from './errors/session-owned-elsewhere-error.js';
 export { createSessionManager } from './manager/session-manager.js';
 export { sandboxPerSession } from './sandboxes/sandbox-per-session.js';
 export { sharedSandbox } from './sandboxes/shared-sandbox.js';

package/dist/manager/session-leases.d.ts

@@ -0,0 +1,38 @@
+import type { SessionClaim, SessionStore } from '../definitions/store.js';
+type Report = (action: string, sessionId?: string) => (error: unknown) => void;
+/** The methods of a store that shares its sessions between managers. */
+type LeasingStore = Pick<SessionStore<unknown>, 'claimSession' | 'releaseSession' | 'renewLease'>;
+export interface SessionLeasesOptions {
+    store: LeasingStore;
+    /** This manager. */
+    owner: string;
+    ttlMs: number;
+    report: Report;
+}
+/**
+ * The sessions a manager holds in a store it shares with other managers, and its lease that
+ * keeps them: renewed in the background, checked by the store when another manager claims one. A
+ * store without leases has one manager: every claim succeeds, and nothing is renewed.
+ */
+export declare class SessionLeases {
+    readonly owner: string;
+    /** Whether the store shares its sessions between managers. */
+    readonly shared: boolean;
+    private readonly store;
+    private readonly ttlMs;
+    private readonly report;
+    private renewal;
+    constructor({ store, owner, ttlMs, report }: SessionLeasesOptions);
+    /**
+     * Takes the lease, then keeps it alive until `stop()`; `onLeaseRenewed` runs once per lease,
+     * after a renewal.
+     */
+    start(onLeaseRenewed: () => void): Promise<void>;
+    stop(): void;
+    /** Makes this manager hold the session, unless another one does. */
+    claim(id: string): Promise<SessionClaim>;
+    /** Lets go of the session; a failure is reported, the lease expiring lets go of it anyway. */
+    release(id: string): Promise<void>;
+    private renew;
+}
+export {};

package/dist/manager/session-leases.js

@@ -0,0 +1,70 @@
+/** How often a manager renews its lease: three times within its life. */
+const RENEWALS_PER_LEASE = 3;
+/** Whether the store gives its lease methods: all three, or none. */
+function sharesSessions(store) {
+    const given = [
+        typeof store.claimSession,
+        typeof store.renewLease,
+        typeof store.releaseSession,
+    ].filter((type) => type === 'function').length;
+    if (given !== 0 && given !== 3) {
+        throw new TypeError('A session store shares its sessions with claimSession, renewLease and releaseSession, all three.');
+    }
+    return given === 3;
+}
+/**
+ * The sessions a manager holds in a store it shares with other managers, and its lease that
+ * keeps them: renewed in the background, checked by the store when another manager claims one. A
+ * store without leases has one manager: every claim succeeds, and nothing is renewed.
+ */
+export class SessionLeases {
+    owner;
+    /** Whether the store shares its sessions between managers. */
+    shared;
+    store;
+    ttlMs;
+    report;
+    renewal;
+    constructor({ store, owner, ttlMs, report }) {
+        this.shared = sharesSessions(store);
+        this.store = store;
+        this.owner = owner;
+        this.ttlMs = ttlMs;
+        this.report = report;
+    }
+    /**
+     * Takes the lease, then keeps it alive until `stop()`; `onLeaseRenewed` runs once per lease,
+     * after a renewal.
+     */
+    async start(onLeaseRenewed) {
+        if (!this.shared)
+            return;
+        await this.renew();
+        let renewals = 0;
+        this.renewal = setInterval(() => {
+            void this.renew().then(() => {
+                renewals += 1;
+                if (renewals % RENEWALS_PER_LEASE === 0)
+                    onLeaseRenewed();
+            }, this.report('lease'));
+        }, this.ttlMs / RENEWALS_PER_LEASE);
+        this.renewal.unref();
+    }
+    stop() {
+        clearInterval(this.renewal);
+    }
+    /** Makes this manager hold the session, unless another one does. */
+    claim(id) {
+        const claimed = this.shared ? this.store.claimSession?.(id, this.owner) : undefined;
+        return claimed ?? Promise.resolve({ claimed: true, previousOwner: this.owner });
+    }
+    /** Lets go of the session; a failure is reported, the lease expiring lets go of it anyway. */
+    async release(id) {
+        if (!this.shared)
+            return;
+        await this.store.releaseSession?.(id, this.owner)?.catch(this.report('release', id));
+    }
+    async renew() {
+        await this.store.renewLease?.(this.owner, this.ttlMs);
+    }
+}

package/dist/manager/session-manager.d.ts

@@ -12,7 +12,9 @@ import type { SessionManager, SessionManagerOptions } from '../definitions/manag
  *    a session the process left live without it is `interrupted` at the next start.
  * 6. `close()` ends a session for good.
  *
- * Every change is written to the store and sent to the subscribers. Keep one manager per store:
- * a second one would take the sessions of the first for those of a crashed process.
+ * Every change is written to the store and sent to the subscribers. Several managers share a store
+ * that gives them leases (`claimSession`, `renewLease`, `releaseSession`): each runs the sessions it
+ * holds. Without them, keep one manager per store: a second one would take the sessions of the
+ * first for those of a crashed process.
  */
 export declare function createSessionManager<METADATA = unknown>(options: SessionManagerOptions<METADATA>): SessionManager<METADATA>;

package/dist/manager/session-manager.js

@@ -4,12 +4,14 @@ import { randomUUID } from 'node:crypto';
 import { SessionCapacityError } from '../errors/session-capacity-error.js';
 import { SessionConflictError } from '../errors/session-conflict-error.js';
 import { SessionNotFoundError } from '../errors/session-not-found-error.js';
+import { SessionOwnedElsewhereError } from '../errors/session-owned-elsewhere-error.js';
 import { createMemorySessionStore } from '../store/memory-session-store.js';
 import { decidedChunks, decidedResponses, signatureOf, verdictOf, } from '../turns/approval-answers.js';
 import { describeResponses, pendingInputOf, responsesFrom, withResponses, } from '../turns/pending-input.js';
 import { streamTurn } from '../turns/turn-stream.js';
 import { isLive, isReady, liveSession, messageOf, newRecord, summaryOf, textOf, } from './live-session.js';
 import { SessionJournal } from './session-journal.js';
+import { SessionLeases } from './session-leases.js';
 const INTERRUPTED_BY_CRASH = 'The application stopped without suspending the session.';
 const CUT_BY_SHUTDOWN = 'The turn was cut short: the application stopped. Send the message again.';
 const FAILED_BY_SHUTDOWN = 'The application stopped before the session was ready.';
@@ -17,6 +19,8 @@ const NOT_STOPPED = 'The harness session could not be stopped cleanly.';
 const NOTHING_TO_RESUME = 'Nothing was kept to resume the session from.';
 /** How long a shutdown waits for a turn it cut short to wind down. */
 const WIND_DOWN_MS = 10_000;
+/** How long a manager's lease on its sessions lasts, unless renewed. */
+const LEASE_TTL_MS = 30_000;
 /** How many approvals `approve` answers in one turn, at most, before leaving them to a person. */
 const MAX_ANSWERED_PER_TURN = 200;
 /**
@@ -63,6 +67,17 @@ function withoutUnfinishedTurn(state) {
 const defaultReport = (error, { action, sessionId }) => 
 // eslint-disable-next-line no-console -- the default, until the application passes onError
 console.error(`ai-sdk-harness-sessions: ${action}${sessionId ? ` ${sessionId}` : ''}:`, error);
+function settingsOf(options) {
+    return {
+        idleTimeoutMs: options.idleTimeoutMs ?? 0,
+        closeSuspendedAfterMs: options.closeSuspendedAfterMs ?? 0,
+        turnTimeoutMs: options.turnTimeoutMs ?? 0,
+        suspendIdleWhenFull: options.suspendIdleWhenFull ?? true,
+        generateId: options.generateId ?? randomUUID,
+        errorMessage: options.errorMessage ?? getHarnessErrorMessage,
+        onError: options.onError ?? defaultReport,
+    };
+}
 /**
  * Manages the sessions of an application with its coding agents, `HarnessAgent`s of any harness:
  *
@@ -76,17 +91,23 @@ console.error(`ai-sdk-harness-sessions: ${action}${sessionId ? ` ${sessionId}` :
  *    a session the process left live without it is `interrupted` at the next start.
  * 6. `close()` ends a session for good.
  *
- * Every change is written to the store and sent to the subscribers. Keep one manager per store:
- * a second one would take the sessions of the first for those of a crashed process.
+ * Every change is written to the store and sent to the subscribers. Several managers share a store
+ * that gives them leases (`claimSession`, `renewLease`, `releaseSession`): each runs the sessions it
+ * holds. Without them, keep one manager per store: a second one would take the sessions of the
+ * first for those of a crashed process.
  */
 export function createSessionManager(options) {
     return new HarnessSessionManager(options);
 }
 class HarnessSessionManager {
     options;
+    get managerId() {
+        return this.leases.owner;
+    }
     store;
     settings;
     journal;
+    leases;
     live = new Map();
     /** Starts run one at a time: the first one installs the harness in the sandbox. */
     starting = Promise.resolve();
@@ -96,17 +117,18 @@ class HarnessSessionManager {
     constructor(options) {
         this.options = options;
         this.store = options.store ?? createMemorySessionStore();
-        this.settings = {
-            idleTimeoutMs: options.idleTimeoutMs ?? 0,
-            closeSuspendedAfterMs: options.closeSuspendedAfterMs ?? 0,
-            turnTimeoutMs: options.turnTimeoutMs ?? 0,
-            suspendIdleWhenFull: options.suspendIdleWhenFull ?? true,
-            generateId: options.generateId ?? randomUUID,
-            errorMessage: options.errorMessage ?? getHarnessErrorMessage,
-            onError: options.onError ?? defaultReport,
-        };
+        this.settings = settingsOf(options);
         this.journal = new SessionJournal(this.store, this.report);
-        this.recovered = this.recover().catch(this.report('recover'));
+        this.leases = new SessionLeases({
+            store: this.store,
+            owner: options.managerId ?? randomUUID(),
+            ttlMs: options.leaseTtlMs ?? LEASE_TTL_MS,
+            report: this.report,
+        });
+        this.recovered = this.leases
+            .start(() => void this.recoverOrphans().catch(this.report('recover')))
+            .then(() => this.recover())
+            .catch(this.report('recover'));
         const { closeSuspendedAfterMs } = this.settings;
         if (closeSuspendedAfterMs > 0) {
             this.sweeper = setInterval(() => void this.sweep().catch(this.report('sweep')), Math.min(closeSuspendedAfterMs, 60_000));
@@ -118,7 +140,13 @@ class HarnessSessionManager {
         const existing = this.live.get(id)?.record ?? (await this.store.get(id));
         if (existing !== undefined)
             throw this.conflict(existing, `A session ${id} already exists.`);
-        await this.makeRoom();
+        const claim = await this.leases.claim(id);
+        if (!claim.claimed)
+            throw new SessionOwnedElsewhereError(id, 'preparing', claim.owner);
+        await this.makeRoom().catch(async (error) => {
+            await this.leases.release(id);
+            throw error;
+        });
         const session = liveSession(newRecord(id, metadata));
         this.live.set(id, session);
         await this.transition(session, 'preparing');
@@ -190,23 +218,26 @@ class HarnessSessionManager {
         const live = this.live.get(id);
         if (live !== undefined)
             return this.changeMetadata(live.record, change(live.record.metadata));
-        const kept = await this.store.get(id);
-        if (kept === undefined)
-            throw new SessionNotFoundError(id);
-        const resumeState = kept.status === 'suspended' ? await this.store.getResumeState(id) : undefined;
-        const changed = change(kept.metadata);
-        // Brought back while the store was read: the live session is the one to change.
-        const racing = this.live.get(id);
-        if (racing !== undefined)
-            return this.changeMetadata(racing.record, changed);
-        return this.changeMetadata(kept, changed, resumeState);
+        const { record: kept, release } = await this.hold(id);
+        try {
+            const resumeState = kept.status === 'suspended' ? await this.store.getResumeState(id) : undefined;
+            const changed = change(kept.metadata);
+            // Brought back while the store was read: the live session is the one to change.
+            const racing = this.live.get(id);
+            if (racing !== undefined)
+                return await this.changeMetadata(racing.record, changed);
+            return await this.changeMetadata(kept, changed, resumeState);
+        }
+        finally {
+            await release();
+        }
     };
     interrupt = async (id) => {
         await this.recovered;
         const session = this.live.get(id);
-        if (session === undefined && (await this.store.get(id)) === undefined) {
-            throw new SessionNotFoundError(id);
-        }
+        // Run by another manager, it throws: the request is for that one.
+        if (session === undefined)
+            await (await this.hold(id)).release();
         const turn = session?.turn;
         if (turn === undefined)
             return;
@@ -217,9 +248,8 @@ class HarnessSessionManager {
         await this.ready();
         const session = this.live.get(id);
         if (session === undefined) {
-            const kept = await this.store.get(id);
-            if (kept === undefined)
-                throw new SessionNotFoundError(id);
+            const { record: kept, release } = await this.hold(id);
+            await release();
             if (kept.status === 'suspended')
                 return summaryOf(kept);
             throw this.conflict(kept);
@@ -241,10 +271,13 @@ class HarnessSessionManager {
             await session.ending;
             return summaryOf(session.record);
         }
-        const kept = await this.store.get(id);
-        if (kept === undefined)
-            throw new SessionNotFoundError(id);
-        return this.closeKept(kept);
+        const { record: kept, release } = await this.hold(id);
+        try {
+            return await this.closeKept(kept);
+        }
+        finally {
+            await release();
+        }
     };
     delete = async (id) => {
         await this.close(id);
@@ -256,10 +289,23 @@ class HarnessSessionManager {
             return;
         this.stopped = true;
         clearInterval(this.sweeper);
+        this.leases.stop();
         await Promise.all([...this.live.values()].map((session) => this.shutdownSession(session)));
         await this.options.sandboxes.shutdown?.().catch(this.report('shutdown'));
         await this.journal.flush();
     };
+    /** Hands a turn that is over to `onTurn`: what it throws goes to `onError`, the turn stays settled. */
+    async reportTurn(session, turn) {
+        if (this.options.onTurn === undefined)
+            return;
+        const report = { sessionId: session.record.id, ...turn, endedAt: new Date() };
+        try {
+            await this.options.onTurn(report, { session: summaryOf(session.record) });
+        }
+        catch (error) {
+            this.report('report turn', session.record.id)(error);
+        }
+    }
     report = (action, sessionId) => (error) => this.settings.onError(error, { action, ...(sessionId !== undefined && { sessionId }) });
     async ready() {
         if (this.stopped)
@@ -267,19 +313,69 @@ class HarnessSessionManager {
         await this.recovered;
     }
     /**
-     * A session still live in the store was live when the application last stopped without
-     * suspending it: it cannot be brought back.
+     * At the start: a session still live in the store, that no other manager runs, was live when
+     * its manager stopped without suspending it — this one, before, or one that crashed: it cannot
+     * be brought back.
      */
     async recover() {
         for (const { id, status } of await this.store.list()) {
             if (!isLive(status))
                 continue;
+            const claim = await this.leases.claim(id);
+            if (!claim.claimed)
+                continue;
             const record = await this.store.get(id);
-            if (record === undefined)
+            if (record === undefined || !isLive(record.status)) {
+                await this.leases.release(id);
                 continue;
-            await this.transition(liveSession(record), 'interrupted', { error: INTERRUPTED_BY_CRASH });
+            }
+            await this.interruptOrphan(record);
         }
     }
+    /**
+     * Then, once per lease: the sessions of the managers sharing the store whose lease expired —
+     * they crashed — are interrupted.
+     */
+    async recoverOrphans() {
+        if (this.stopped)
+            return;
+        for (const { id, status } of await this.store.list()) {
+            if (!isLive(status) || this.live.has(id))
+                continue;
+            await this.hold(id).then(({ release }) => release(), () => undefined);
+        }
+    }
+    /**
+     * The session `id` as the store keeps it, held by this manager until `release()`: what to read
+     * and change of a session no manager runs. Throws `SessionOwnedElsewhereError` when another
+     * manager runs it. A session the store keeps live although no manager runs it any more — its
+     * manager crashed — is `interrupted` first.
+     */
+    async hold(id) {
+        if ((await this.store.get(id)) === undefined)
+            throw new SessionNotFoundError(id);
+        const claim = await this.leases.claim(id);
+        // Read again once held: what the manager that held it last wrote.
+        const record = await this.store.get(id);
+        if (!claim.claimed) {
+            throw new SessionOwnedElsewhereError(id, record?.status ?? 'preparing', claim.owner);
+        }
+        const ours = claim.previousOwner === this.leases.owner;
+        const release = () => (ours ? Promise.resolve() : this.leases.release(id));
+        if (record === undefined) {
+            await release();
+            throw new SessionNotFoundError(id);
+        }
+        if (!ours && isLive(record.status))
+            return { record: await this.interruptOrphan(record), release };
+        return { record, release };
+    }
+    /** Interrupts a session left live by a manager that stopped without suspending it. */
+    async interruptOrphan(record) {
+        const session = liveSession(record);
+        await this.transition(session, 'interrupted', { error: INTERRUPTED_BY_CRASH });
+        return session.record;
+    }
     /** The one place a session changes status: it is written, unless told not to, and sent out. */
     transition(session, status, { error, persist = true, resumeState } = {}) {
         const { record } = session;
@@ -290,7 +386,9 @@ class HarnessSessionManager {
         else
             record.error = error;
         this.journal.updated(record);
-        return persist ? this.journal.write(record, resumeState) : Promise.resolve();
+        const written = persist ? this.journal.write(record, resumeState) : Promise.resolve();
+        // Once it is written: the manager that claims it next reads where it stopped.
+        return isLive(status) ? written : written.then(() => this.leases.release(record.id));
     }
     /** Writes new metadata, without counting it as activity: `updatedAt` stays. */
     async changeMetadata(record, metadata, resumeState) {
@@ -377,8 +475,9 @@ class HarnessSessionManager {
         this.report(resumeFrom === undefined ? 'start' : 'resume', id)(error);
         if (this.live.get(id) === session)
             this.live.delete(id);
-        await this.teardown(session);
-        // A resume that failed keeps what it resumes from: the next message tries again.
+        // A resume that failed keeps what it resumes from — its state, its sandbox and its files —:
+        // the next message tries again.
+        await (resumeFrom === undefined ? this.teardown(session) : this.release(session));
         await (resumeFrom === undefined
             ? this.transition(session, 'failed', { error: messageOf(error) })
             : this.transition(session, 'suspended', {
@@ -395,6 +494,13 @@ class HarnessSessionManager {
         await handle?.destroy().catch(this.report('destroy', record.id));
         await lease?.close().catch(this.report('close', record.id));
     }
+    /** Hands the sandbox of a session that never started back, keeping its files for a resume. */
+    async release(session) {
+        const { lease, record } = session;
+        session.lease = undefined;
+        clearTimeout(session.idleTimer);
+        await lease?.suspend().catch(this.report('suspend', record.id));
+    }
     /**
      * Suspends the session: its harness session stops, keeping what it needs to resume, and its
      * sandbox is freed.
@@ -423,12 +529,16 @@ class HarnessSessionManager {
     async openSession(id) {
         let session = this.live.get(id);
         if (session === undefined) {
-            const kept = await this.store.get(id);
-            if (kept === undefined)
-                throw new SessionNotFoundError(id);
-            if (kept.status !== 'suspended' && kept.status !== 'failed')
-                throw this.conflict(kept);
-            session = await this.revive(kept);
+            const { record: kept, release } = await this.hold(id);
+            try {
+                if (kept.status !== 'suspended' && kept.status !== 'failed')
+                    throw this.conflict(kept);
+                session = await this.revive(kept);
+            }
+            catch (error) {
+                await release();
+                throw error;
+            }
         }
         await session.ready.catch(() => undefined);
         if (this.live.get(id) !== session || !isReady(session))
@@ -481,9 +591,14 @@ class HarnessSessionManager {
             : undefined;
         let finish;
         session.turn = { abort, done: new Promise((resolve) => (finish = resolve)) };
+        const startedAt = new Date();
         await this.transition(session, 'busy');
         const settle = async (failure) => {
             clearTimeout(timer);
+            // Cut short by an interrupt, a timeout or the caller: before the turn is over, so that a
+            // close waits for it, and finds the harness session to destroy.
+            if (abort.signal.aborted || callerSignal?.aborted === true)
+                await this.renew(session, handle);
             await this.settleTurn(session, handle, failure);
             finish();
         };
@@ -502,7 +617,7 @@ class HarnessSessionManager {
             generateMessageId: generateId,
             errorMessage,
             next: (messages) => this.answerPause(session, messages, answered),
-            onSettled: async ({ messages, failure, usage }) => {
+            onSettled: async ({ messages, failure, usage, report }) => {
                 if (messages !== undefined)
                     record.messages = messages;
                 record.turns += 1;
@@ -510,6 +625,7 @@ class HarnessSessionManager {
                 record.usage.outputTokens += usage.outputTokens ?? 0;
                 record.usage.totalTokens += usage.totalTokens ?? 0;
                 await settle(failure);
+                await this.reportTurn(session, { startedAt, failure, ...report });
             },
         });
         // A turn cut short by a close or a shutdown is over once they wrote the session.
@@ -583,7 +699,7 @@ class HarnessSessionManager {
         // Closed, suspended or shut down meanwhile: whoever did it writes the session.
         if (this.live.get(record.id) !== session || record.status !== 'busy')
             return;
-        const unfinished = handle.hasUnfinishedTurn();
+        const unfinished = session.lostTurn === true || handle.hasUnfinishedTurn();
         if (unfinished)
             record.pendingInput = session.paused ?? pendingInputOf(record.messages);
         else
@@ -594,10 +710,58 @@ class HarnessSessionManager {
         });
         this.scheduleIdle(session);
     }
+    /**
+     * Starts the harness session of a turn cut short again, in the same sandbox, from where it
+     * stopped. The runtime goes on with the turn for a while after it is told to stop, and a harness
+     * session sends what it still says to the next turn: a stray `finish` ends that turn before it
+     * starts, and its answer is lost. A session that cannot start again is `suspended`, resumed by
+     * the next message, or `interrupted` when its harness session could not be stopped.
+     */
+    async renew(session, handle) {
+        const { id, status } = session.record;
+        // Closed, suspended or shut down meanwhile: whoever did it stops the harness session.
+        if (this.live.get(id) !== session || status !== 'busy')
+            return;
+        const { agent, lease } = session;
+        // Started again without the turn it paused in: `continue()` tells the agent the answers.
+        session.lostTurn = handle.hasUnfinishedTurn();
+        session.handle = undefined;
+        const stopped = await handle.stop().catch((error) => {
+            this.report('stop', id)(error);
+            return undefined;
+        });
+        if (stopped === undefined || agent === undefined || lease === undefined) {
+            if (this.live.get(id) === session)
+                this.live.delete(id);
+            await this.release(session);
+            await this.transition(session, 'interrupted', { error: NOT_STOPPED });
+            return;
+        }
+        const resumeFrom = withoutUnfinishedTurn(stopped);
+        try {
+            session.handle = await agent.createSession({
+                sessionId: id,
+                sandboxSession: lease.sandboxSession,
+                resumeFrom,
+            });
+        }
+        catch (error) {
+            this.report('resume', id)(error);
+            if (this.live.get(id) === session)
+                this.live.delete(id);
+            await this.release(session);
+            await this.transition(session, 'suspended', {
+                error: messageOf(error),
+                resumeState: resumeFrom,
+            });
+        }
+    }
     async closeKept(kept) {
         if (kept.status === 'closed')
             return summaryOf(kept);
-        if (kept.status === 'suspended') {
+        // A suspended session keeps its sandbox for its resume, an interrupted one because nothing freed it: the
+        // process stopped while the session held it, or its harness session could not be stopped.
+        if (kept.status === 'suspended' || kept.status === 'interrupted') {
             await this.options.sandboxes.discard?.(kept.id).catch(this.report('discard', kept.id));
         }
         const session = liveSession(kept);
@@ -611,9 +775,13 @@ class HarnessSessionManager {
         for (const { id, status, updatedAt } of await this.store.list()) {
             if (status !== 'suspended' || updatedAt >= cutoff || this.live.has(id))
                 continue;
-            const kept = await this.store.get(id);
-            if (kept?.status === 'suspended' && !this.live.has(id))
+            const held = await this.hold(id).catch(() => undefined);
+            if (held === undefined)
+                continue;
+            const { record: kept, release } = held;
+            if (kept.status === 'suspended' && !this.live.has(id))
                 await this.closeKept(kept);
+            await release();
         }
     }
     /** Closes a live session, cutting its turn short. */

package/dist/sandboxes/shared-sandbox.d.ts

@@ -5,8 +5,8 @@ export type SandboxView = HarnessV1NetworkSandboxSession & {
     release(): PromiseLike<void>;
 };
 /**
- * A sandbox that gives views of itself with ports of their own: `ai-sdk-sandbox-sbx` and
- * `ai-sdk-sandbox-cloud-run` sessions are.
+ * A sandbox that gives views of itself with ports of their own: `ai-sdk-sandbox-sbx`,
+ * `ai-sdk-sandbox-cloud-run` and `ai-sdk-sandbox-runtime` sessions are.
  */
 export type ForkableSandbox = HarnessV1NetworkSandboxSession & {
     fork(options: {

package/dist/turns/turn-stream.d.ts

@@ -1,5 +1,6 @@
 import type { LanguageModelUsage, UIMessage, UIMessageChunk } from 'ai';
 import type { SessionStreamResult } from '../definitions/agent.js';
+import type { TurnStepReport } from '../definitions/session.js';
 /** The tokens a turn used, added up over its streams. */
 export type TurnUsage = Pick<LanguageModelUsage, 'inputTokens' | 'outputTokens' | 'totalTokens'>;
 /** How a turn ended. */
@@ -9,6 +10,12 @@ export interface TurnOutcome {
     /** What went wrong, when the turn failed or was cut short. */
     failure: string | undefined;
     usage: TurnUsage;
+    /** The turn's tokens in detail, its steps and the raw events of its harness, for `onTurn`. */
+    report: {
+        usage: LanguageModelUsage;
+        steps: TurnStepReport[];
+        rawEvents: unknown[];
+    };
 }
 /**
  * What a turn does once one of its streams ends: answers given in between, sent to the client and

package/dist/turns/turn-stream.js

@@ -40,6 +40,68 @@ async function readSegment(result, originalMessages, { first, send, options, })
     }
     return outcome;
 }
+/** Tokens of nothing yet: what the turn's tokens are added to. */
+function emptyUsage() {
+    return {
+        inputTokens: 0,
+        inputTokenDetails: { noCacheTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },
+        outputTokens: 0,
+        outputTokenDetails: { textTokens: 0, reasoningTokens: 0 },
+        totalTokens: 0,
+    };
+}
+const add = (a, b) => a === undefined && b === undefined ? undefined : (a ?? 0) + (b ?? 0);
+/** `total` plus `spent`, detail by detail: a count neither of them knows stays unknown. */
+function addDetails(total, spent) {
+    if (spent === undefined)
+        return total;
+    return {
+        inputTokens: add(total.inputTokens, spent.inputTokens),
+        inputTokenDetails: {
+            noCacheTokens: add(total.inputTokenDetails.noCacheTokens, spent.inputTokenDetails?.noCacheTokens),
+            cacheReadTokens: add(total.inputTokenDetails.cacheReadTokens, spent.inputTokenDetails?.cacheReadTokens),
+            cacheWriteTokens: add(total.inputTokenDetails.cacheWriteTokens, spent.inputTokenDetails?.cacheWriteTokens),
+        },
+        outputTokens: add(total.outputTokens, spent.outputTokens),
+        outputTokenDetails: {
+            textTokens: add(total.outputTokenDetails.textTokens, spent.outputTokenDetails?.textTokens),
+            reasoningTokens: add(total.outputTokenDetails.reasoningTokens, spent.outputTokenDetails?.reasoningTokens),
+        },
+        totalTokens: add(total.totalTokens, spent.totalTokens),
+    };
+}
+/** The steps of a stream of the turn: their model, tokens and tool calls. */
+async function stepsOf(result) {
+    const steps = await Promise.resolve(result.steps).catch(() => undefined);
+    return (steps ?? []).map((step) => ({
+        modelId: step.response?.modelId,
+        usage: step.usage,
+        toolCalls: (step.toolCalls ?? []).map(({ toolCallId, toolName, input }) => ({
+            toolCallId,
+            toolName,
+            input: input,
+        })),
+    }));
+}
+/**
+ * The raw events a stream of the turn carries, read from its own copy of the stream, beside the
+ * client's: what the harness sends that no other part says.
+ */
+async function rawEventsOf(result) {
+    const events = [];
+    if (result.fullStream === undefined)
+        return events;
+    try {
+        for await (const part of result.fullStream) {
+            if (part.type === 'raw')
+                events.push(part.rawValue);
+        }
+    }
+    catch {
+        // The turn's failure is told by the client's stream: the events read so far are kept.
+    }
+    return events;
+}
 /** Adds the tokens a stream of the turn used, once it is over. */
 async function addUsage(usage, result) {
     const spent = await Promise.resolve(result.totalUsage).catch(() => undefined);
@@ -52,6 +114,9 @@ class TurnRun {
     options;
     send;
     usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    details = emptyUsage();
+    steps = [];
+    rawEvents = [];
     messages;
     failure;
     finish;
@@ -63,12 +128,19 @@ class TurnRun {
         let result = first;
         let originalMessages = this.options.originalMessages;
         for (let index = 0; result !== undefined; index += 1) {
+            const raw = rawEventsOf(result);
             const outcome = await readSegment(result, originalMessages, {
                 first: index === 0,
                 send: this.send,
                 options: this.options,
             });
             await addUsage(this.usage, result);
+            const spent = await Promise.resolve(result.totalUsage).catch(() => undefined);
+            this.details = addDetails(this.details, spent);
+            const steps = await stepsOf(result);
+            const events = await raw;
+            this.steps.push(...steps);
+            this.rawEvents.push(...events);
             this.failure ??= outcome.failure;
             this.finish = outcome.finish;
             this.messages = outcome.messages ?? this.messages;
@@ -79,7 +151,12 @@ class TurnRun {
         }
         if (this.finish !== undefined)
             this.send(this.finish);
-        return { messages: this.messages, failure: this.failure, usage: this.usage };
+        return {
+            messages: this.messages,
+            failure: this.failure,
+            usage: this.usage,
+            report: { usage: this.details, steps: this.steps, rawEvents: this.rawEvents },
+        };
     }
     /**
      * What follows a stream that ended well, its approval requests sent first, with the answers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-sdk-harness-sessions",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Sessions for AI SDK harness agents: the lifecycle of conversations with Claude Code, Codex and friends — one turn at a time, suspended when idle, resumed on the next message and after a restart, several of them sharing one sandbox.",
   "keywords": [
     "ai",
@@ -47,20 +47,20 @@
     "ai": "^7.0.0"
   },
   "devDependencies": {
-    "@ai-sdk/harness": "^1.0.138",
-    "@ai-sdk/harness-claude-code": "^1.0.142",
-    "@ai-sdk/harness-codex": "^1.0.140",
+    "@ai-sdk/harness": "^1.0.147",
+    "@ai-sdk/harness-claude-code": "^1.0.151",
+    "@ai-sdk/harness-codex": "^1.0.149",
     "@types/node": "^24.13.5",
     "@vitest/coverage-v8": "^5.0.3",
-    "ai": "^7.0.127",
+    "ai": "^7.0.136",
     "typescript": "^6.0.3",
     "vitest": "^5.0.3",
     "@repo/eslint-config": "0.0.0",
     "@repo/prettier-config": "0.0.0",
+    "@repo/build": "0.0.0",
     "@repo/typescript-config": "0.0.0",
     "@repo/vitest-config": "0.0.0",
-    "ai-sdk-sandbox-sbx": "0.1.1",
-    "@repo/build": "0.0.0"
+    "ai-sdk-sandbox-sbx": "0.1.3"
   },
   "author": {
     "name": "Fabien Pasquet",