ai-sdk-harness-sessions 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # ai-sdk-harness-sessions
 
+## 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
+
+- 05ff36c: The `approve` option answers the approvals a turn asks for before anyone sees them — an approval policy, the grants of the session: a verdict is sent at once and the turn goes on in the same stream, the client seeing the answer; `undefined` leaves the approval to a person. When it answers part of a pause, `pendingInput.approvals` carries its answers in `decision`, and `continue()` sends them with the person's. An approval asked again right after it was answered, with the same input, is left to a person. `update(id, { metadata })` changes the metadata of a session, whatever its status. A session resumed without the turn it waited in tells the agent the answers to its questions in words.
+
 ## 0.1.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),
@@ -41,11 +42,12 @@ return turn.toUIMessageStreamResponse();
 | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | A first message                        | Opens a sandbox, or a view of a shared one, and a harness session, in the background: a message sent meanwhile waits |
 | A message while a turn runs            | Refuses it: one turn at a time per session (`SessionConflictError`, status `busy`)                                   |
-| The turn asks approval for a tool call | Keeps the session `awaiting-input` until `continue()` brings the answer, even after a suspension or a restart        |
+| The turn asks approval for a tool call | Asks your `approve` option first, then keeps the session `awaiting-input` until `continue()` brings the answer       |
 | Nobody writes for `idleTimeoutMs`      | Suspends the session: its harness session stops with its state, its sandbox is freed. The next message resumes it    |
 | 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.
 
@@ -226,6 +230,31 @@ const turn =
 
 A session suspended while it waited keeps what it waits for: `continue()` resumes the session, without its paused turn, whose harness bridge the suspension stopped, and tells the agent the answers in a message. With Claude Code, see [Limitations](#limitations).
 
+The agent's questions wait the same way: Claude Code's `AskUserQuestion` reaches you as a call of `askUserQuestions` in `pendingInput.toolCalls`, and its answers are the tool's output, `addToolOutput()` in `useChat`, `toolResultContinuations` otherwise. A session resumed without its turn tells the agent the answers in words, the labels of the options picked.
+
+### Answered by a policy
+
+The `approve` option answers the approvals before anyone sees them. A verdict is sent at once and the turn goes on, in the same stream: the client sees the request, then its answer, then what the agent did. `undefined` leaves the approval to a person. [`ai-sdk-harness-approval`](https://ai-sdk-harness.pages.dev/docs/packages/harness-approval) gives one from a policy, with the "always allow" of each session kept in its metadata:
+
+```ts
+import { type ApprovalGrant, defineApprovalPolicy } from 'ai-sdk-harness-approval';
+
+const policy = defineApprovalPolicy({
+  commands: { allow: ['ls', 'git status', 'pnpm test'], deny: ['git push', 'rm -rf'] },
+});
+
+const sessions = createSessionManager<{ grants?: ApprovalGrant[] }>({
+  agent: () => new HarnessAgent({ harness, ...policy.agentSettings(harness) }),
+  sandboxes,
+  approve: policy.approver({ grants: ({ session }) => session.metadata.grants }),
+});
+
+// "Always allow": kept with the session, read by the next approvals.
+await sessions.update(id, { metadata: (metadata) => ({ ...metadata, grants }) });
+```
+
+When a pause holds several approvals and `approve` answers some, the session waits for the others: `pendingInput.approvals` carries the answers given in `decision`, and `continue()` sends them with the person's, which cannot overturn them. An approval asked again right after `approve` answered it, with the same input, is left to a person: a harness that does not take the answer would otherwise ask forever.
+
 ## Sandboxes
 
 Where each session runs is up to `sandboxes`:
@@ -236,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';
@@ -251,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.
@@ -298,7 +369,51 @@ 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`.
+
+### 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
 
@@ -308,11 +423,14 @@ 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                                                                    |
 | `suspendIdleWhenFull`   | `true`                   | When every sandbox slot is taken, suspend the session idle the longest rather than refuse a new one |
+| `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           |
 | `onError`               | `console.error`          | Called with what fails in the background: a start, a suspension, a write to the store               |
@@ -322,6 +440,7 @@ Keep one manager per store: at its start, a manager takes the sessions the store
 | `create({ id, metadata })` | Opens a session, and returns it `preparing`                                                                |
 | `send(id, options)`        | Starts a turn in reply to a message (`message`, `prompt`, `abortSignal`): a `SessionTurn`                  |
 | `continue(id, options)`    | Resumes a paused turn with its answers (`message`, `toolApprovalContinuations`, `toolResultContinuations`) |
+| `update(id, { metadata })` | Changes the metadata of a session, whatever its status: a value, or a function of the current one          |
 | `interrupt(id)`            | Cuts the turn under way short                                                                              |
 | `suspend(id)`              | Suspends an idle session now                                                                               |
 | `close(id)`                | Ends a session for good                                                                                    |
@@ -338,11 +457,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`.
@@ -350,7 +470,7 @@ Each has an `isInstance()` that recognizes it whichever copy of the package thre
 
 ## Development
 
-`pnpm --filter ai-sdk-harness-sessions test:e2e` runs real Claude Code sessions in a Docker Sandbox: two side by side, suspended and resumed, across a restart, and waiting for an approval; it needs `sbx` signed in and a Claude credential. See [CONTRIBUTING.md](https://github.com/fpasquet/ai-sdk-harness/blob/main/CONTRIBUTING.md).
+`pnpm --filter ai-sdk-harness-sessions test:e2e` runs real Claude Code sessions in a Docker Sandbox: two side by side, suspended and resumed, across a restart, and waiting for an approval; it needs `sbx` signed in and a Claude credential. `ai-sdk-harness-approval`'s end-to-end tests cover `approve`. See [CONTRIBUTING.md](https://github.com/fpasquet/ai-sdk-harness/blob/main/CONTRIBUTING.md).
 
 ## License
 

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 { SessionRecord, SessionSummary } from './session.js';
+import type { ApprovalVerdict, PendingApproval, SessionRecord, SessionSummary } 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:
@@ -32,6 +49,18 @@ export interface SessionManagerOptions<METADATA> {
      * one, or a resume, rather than refusing it with `SessionCapacityError`. Default: `true`.
      */
     suspendIdleWhenFull?: boolean;
+    /**
+     * Answers the approvals a turn asks for before anyone sees them: an approval policy, the grants
+     * of the session. A verdict is sent at once and the turn goes on, in the same stream, the client
+     * seeing the answer; `undefined` leaves the approval to a person, the session `awaiting-input`.
+     * Default: every approval waits for a person.
+     *
+     * An approval asked again right after it was answered, with the same input, is left to a
+     * person: a harness that does not take the answer (see the README) would ask forever.
+     */
+    approve?: (approval: PendingApproval, context: {
+        session: SessionSummary<METADATA>;
+    }) => ApprovalVerdict | PromiseLike<ApprovalVerdict | undefined> | undefined;
     /** The ids of new sessions and of the messages of their turns. Default: `crypto.randomUUID`. */
     generateId?: () => string;
     /**
@@ -93,6 +122,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
@@ -118,6 +149,14 @@ export interface SessionManager<METADATA = unknown> {
      * resumed first, its turn with it.
      */
     continue(id: string, options: ContinueOptions): Promise<SessionTurn<METADATA>>;
+    /**
+     * Changes what your application keeps with a session, its metadata, whatever its status: a
+     * title, the grants of an approval policy… Given a function, it is called with the metadata as
+     * they stand.
+     */
+    update(id: string, changes: {
+        metadata: ((metadata: METADATA) => METADATA) | METADATA;
+    }): Promise<SessionSummary<METADATA>>;
     /** Cuts the turn under way short, and resolves once the session is written. */
     interrupt(id: string): Promise<void>;
     /** Suspends a session idle or awaiting input, as idleness would. */

package/dist/definitions/session.d.ts

@@ -29,6 +29,12 @@ export interface SessionUsage {
     outputTokens: number;
     totalTokens: number;
 }
+/** An answer to an approval request, as `ToolApprovalResponse` carries it. */
+export interface ApprovalVerdict {
+    approved: boolean;
+    /** Why: what the agent is told of a denial, what a person reads of an automatic approval. */
+    reason?: string;
+}
 /** A tool call the agent asked approval for, waiting for your answer. */
 export interface PendingApproval {
     /** What the answer refers to: `ToolApprovalResponse.approvalId`. */
@@ -36,6 +42,11 @@ export interface PendingApproval {
     toolCallId: string;
     toolName: string;
     input: unknown;
+    /**
+     * The answer the manager's `approve` option gave already, when it gave one: the turn waits for
+     * the answers to the other approvals, and `continue()` sends this one with them.
+     */
+    decision?: ApprovalVerdict;
 }
 /** A tool call whose result your application gives, waiting for it. */
 export interface PendingToolCall {

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

@@ -3,10 +3,11 @@ export type { ContinueOptions, SendOptions, SessionEvent, SessionManager, Sessio
 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 { 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/live-session.d.ts

@@ -2,7 +2,7 @@ import type { HarnessAgentSession } from '@ai-sdk/harness/agent';
 import type { UIMessage } from 'ai';
 import type { SessionAgent } from '../definitions/agent.js';
 import type { SessionSandboxLease } from '../definitions/sandboxes.js';
-import type { SessionRecord, SessionStatus, SessionSummary } from '../definitions/session.js';
+import type { PendingInput, SessionRecord, SessionStatus, SessionSummary } from '../definitions/session.js';
 /** A session held in memory, with its harness session and its sandbox once it started. */
 export interface LiveSession<METADATA> {
     record: SessionRecord<METADATA>;
@@ -18,10 +18,17 @@ export interface LiveSession<METADATA> {
      * agent the answers in a message.
      */
     lostTurn?: boolean;
+    /**
+     * What the turn paused on, when the manager's `approve` answered part of it: the approvals with
+     * the verdicts it gave, for the record.
+     */
+    paused?: PendingInput;
     turn?: {
         abort: AbortController;
         done: Promise<void>;
     };
+    /** Settles once a close, or a shutdown, that took the session over has written it. */
+    ending?: Promise<void>;
     idleTimer?: NodeJS.Timeout;
 }
 /** A live session that started: its agent and harness session are there. */

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);
+    }
+}