ai-sdk-harness-sessions 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # ai-sdk-harness-sessions
 
+## 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

@@ -41,7 +41,7 @@ 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        |
@@ -226,6 +226,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`:
@@ -313,6 +338,7 @@ Keep one manager per store: at its start, a manager takes the sessions the store
 | `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 +348,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                                                                                    |
@@ -350,7 +377,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> {
     /**
@@ -32,6 +32,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;
     /**
@@ -118,6 +130,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/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-manager.js

@@ -5,6 +5,7 @@ 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 { 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';
@@ -16,18 +17,33 @@ 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;
-/** The answers `continue()` was given: read from `useChat`'s message, and given as they are. */
+/** How many approvals `approve` answers in one turn, at most, before leaving them to a person. */
+const MAX_ANSWERED_PER_TURN = 200;
+/**
+ * The answers `continue()` was given, read from `useChat`'s message and given as they are, and
+ * the answers `approve` gave already: they stand, whatever the message says.
+ */
 function responsesOf(pending, { message, ...given }) {
-    const read = message === undefined ? undefined : responsesFrom(message, pending);
+    const decided = decidedResponses(pending.approvals);
+    const open = {
+        ...pending,
+        approvals: pending.approvals.filter(({ decision }) => decision === undefined),
+    };
+    const read = message === undefined ? undefined : responsesFrom(message, open);
+    const approvals = [
+        ...(read?.toolApprovalContinuations ?? []),
+        ...(given.toolApprovalContinuations ?? []),
+    ].filter(({ approvalId }) => !decided.some((response) => response.approvalId === approvalId));
+    const results = [
+        ...(read?.toolResultContinuations ?? []),
+        ...(given.toolResultContinuations ?? []),
+    ];
     return {
-        toolApprovalContinuations: [
-            ...(read?.toolApprovalContinuations ?? []),
-            ...(given.toolApprovalContinuations ?? []),
-        ],
-        toolResultContinuations: [
-            ...(read?.toolResultContinuations ?? []),
-            ...(given.toolResultContinuations ?? []),
-        ],
+        responses: {
+            toolApprovalContinuations: [...decided, ...approvals],
+            toolResultContinuations: results,
+        },
+        answered: approvals.length + results.length,
     };
 }
 /**
@@ -149,9 +165,8 @@ class HarnessSessionManager {
         this.claim(session, 'awaiting-input');
         const { record } = session;
         const pending = record.pendingInput ?? pendingInputOf(record.messages);
-        const responses = responsesOf(pending, answers);
-        if (responses.toolApprovalContinuations.length + responses.toolResultContinuations.length ===
-            0) {
+        const { responses, answered } = responsesOf(pending, answers);
+        if (answered === 0) {
             throw this.conflict(record, 'continue() carries no answer to what the session waits for.');
         }
         record.messages = withResponses(record.messages, responses);
@@ -167,6 +182,25 @@ class HarnessSessionManager {
             })
             : session.agent.stream({ session: session.handle, prompt, abortSignal: signal }), abortSignal);
     };
+    update = async (id, { metadata }) => {
+        await this.ready();
+        const change = (current) => typeof metadata === 'function'
+            ? metadata(current)
+            : metadata;
+        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);
+    };
     interrupt = async (id) => {
         await this.recovered;
         const session = this.live.get(id);
@@ -203,12 +237,8 @@ class HarnessSessionManager {
         const session = this.live.get(id);
         await session?.ready.catch(() => undefined);
         if (session !== undefined && this.live.get(id) === session) {
-            this.live.delete(id);
-            session.turn?.abort.abort(new Error('The session was closed.'));
-            await session.turn?.done;
-            await this.teardown(session);
-            delete session.record.pendingInput;
-            await this.transition(session, 'closed');
+            session.ending = this.end(session);
+            await session.ending;
             return summaryOf(session.record);
         }
         const kept = await this.store.get(id);
@@ -262,6 +292,13 @@ class HarnessSessionManager {
         this.journal.updated(record);
         return persist ? this.journal.write(record, resumeState) : Promise.resolve();
     }
+    /** Writes new metadata, without counting it as activity: `updatedAt` stays. */
+    async changeMetadata(record, metadata, resumeState) {
+        record.metadata = metadata;
+        this.journal.updated(record);
+        await this.journal.write(record, resumeState);
+        return summaryOf(record);
+    }
     conflict(record, message) {
         const said = message ?? `The session is ${record.status}${record.error ? `: ${record.error}` : ''}.`;
         return new SessionConflictError(record.id, record.status, said);
@@ -459,21 +496,24 @@ class HarnessSessionManager {
             throw error;
         }
         const { record } = session;
+        const answered = { last: new Set(), count: 0, abortSignal: abort.signal };
         const { stream, settled } = streamTurn(result, {
             originalMessages: record.messages,
             generateMessageId: generateId,
             errorMessage,
+            next: (messages) => this.answerPause(session, messages, answered),
             onSettled: async ({ messages, failure, usage }) => {
                 if (messages !== undefined)
                     record.messages = messages;
                 record.turns += 1;
-                record.usage.inputTokens += usage?.inputTokens ?? 0;
-                record.usage.outputTokens += usage?.outputTokens ?? 0;
-                record.usage.totalTokens += usage?.totalTokens ?? 0;
+                record.usage.inputTokens += usage.inputTokens ?? 0;
+                record.usage.outputTokens += usage.outputTokens ?? 0;
+                record.usage.totalTokens += usage.totalTokens ?? 0;
                 await settle(failure);
             },
         });
-        const done = settled.then(() => summaryOf(record));
+        // A turn cut short by a close or a shutdown is over once they wrote the session.
+        const done = settled.then(() => session.ending).then(() => summaryOf(record));
         done.catch(() => undefined);
         return {
             stream,
@@ -481,6 +521,61 @@ class HarnessSessionManager {
             done,
         };
     }
+    /**
+     * What `approve` makes of the approvals a turn paused on: all answered, the turn goes on; some
+     * left to a person, it stops there, `continue()` sending the answers given with theirs.
+     */
+    async answerPause(session, messages, answered) {
+        session.paused = undefined;
+        const pending = pendingInputOf(messages);
+        if (this.options.approve === undefined ||
+            pending.approvals.length === 0 ||
+            !session.handle.hasUnfinishedTurn()) {
+            return undefined;
+        }
+        const approvals = await Promise.all(pending.approvals.map((approval) => this.decide(session, approval, answered)));
+        const responses = decidedResponses(approvals);
+        if (responses.length === 0)
+            return undefined;
+        answered.last = new Set(approvals.filter(({ decision }) => decision).map(signatureOf));
+        answered.count += responses.length;
+        const step = {
+            chunks: decidedChunks(approvals),
+            messages: withResponses(messages, {
+                toolApprovalContinuations: responses,
+                toolResultContinuations: [],
+            }),
+        };
+        if (responses.length < approvals.length || pending.toolCalls.length > 0) {
+            session.paused = { ...pending, approvals };
+            return step;
+        }
+        const result = await session.agent.continueStream({
+            session: session.handle,
+            toolApprovalContinuations: responses,
+            abortSignal: answered.abortSignal,
+        });
+        return { ...step, result };
+    }
+    /** The approval with the verdict of `approve`, unless it is to be left to a person. */
+    async decide(session, approval, answered) {
+        const { approve } = this.options;
+        // Asked again right after it was answered: the harness did not take the answer.
+        if (approve === undefined ||
+            answered.last.has(signatureOf(approval)) ||
+            answered.count >= MAX_ANSWERED_PER_TURN) {
+            return approval;
+        }
+        let decision;
+        try {
+            decision = await approve(approval, { session: summaryOf(session.record) });
+        }
+        catch (error) {
+            // Left to a person: they decide, as without approve.
+            this.report('approve', session.record.id)(error);
+        }
+        return decision === undefined ? approval : { ...approval, decision: verdictOf(decision) };
+    }
     /** After a turn: awaiting input if it paused, idle otherwise. */
     async settleTurn(session, handle, failure) {
         session.turn = undefined;
@@ -490,9 +585,10 @@ class HarnessSessionManager {
             return;
         const unfinished = handle.hasUnfinishedTurn();
         if (unfinished)
-            record.pendingInput = pendingInputOf(record.messages);
+            record.pendingInput = session.paused ?? pendingInputOf(record.messages);
         else
             delete record.pendingInput;
+        session.paused = undefined;
         await this.transition(session, unfinished ? 'awaiting-input' : 'idle', {
             ...(failure !== undefined && { error: failure }),
         });
@@ -520,8 +616,21 @@ class HarnessSessionManager {
                 await this.closeKept(kept);
         }
     }
+    /** Closes a live session, cutting its turn short. */
+    async end(session) {
+        this.live.delete(session.record.id);
+        session.turn?.abort.abort(new Error('The session was closed.'));
+        await session.turn?.done;
+        await this.teardown(session);
+        delete session.record.pendingInput;
+        await this.transition(session, 'closed');
+    }
+    shutdownSession(session) {
+        session.ending = this.windDown(session);
+        return session.ending;
+    }
     /** Suspends a live session for the shutdown, cutting its turn short. */
-    async shutdownSession(session) {
+    async windDown(session) {
         const { record } = session;
         if (record.status === 'preparing') {
             // Its start finds it gone and cleans up after itself; a resume parks it again.

package/dist/turns/approval-answers.d.ts

@@ -0,0 +1,10 @@
+import type { ToolApprovalResponse, UIMessageChunk } from 'ai';
+import type { ApprovalVerdict, PendingApproval } from '../definitions/session.js';
+/** An approval request as a repeat of another is recognised: the same tool, the same input. */
+export declare const signatureOf: ({ toolName, input }: PendingApproval) => string;
+/** A verdict with only what an approval response carries. */
+export declare const verdictOf: ({ approved, reason }: ApprovalVerdict) => ApprovalVerdict;
+/** The approval responses of the approvals decided already. */
+export declare function decidedResponses(approvals: readonly PendingApproval[]): ToolApprovalResponse[];
+/** The chunks that show a client the approvals decided already, as answered. */
+export declare function decidedChunks(approvals: readonly PendingApproval[]): UIMessageChunk[];

package/dist/turns/approval-answers.js

@@ -0,0 +1,22 @@
+/** An approval request as a repeat of another is recognised: the same tool, the same input. */
+export const signatureOf = ({ toolName, input }) => `${toolName}\u0000${JSON.stringify(input)}`;
+/** A verdict with only what an approval response carries. */
+export const verdictOf = ({ approved, reason }) => ({
+    approved,
+    ...(reason !== undefined && { reason }),
+});
+/** The approval responses of the approvals decided already. */
+export function decidedResponses(approvals) {
+    return approvals.flatMap(({ approvalId, decision }) => decision === undefined
+        ? []
+        : [{ type: 'tool-approval-response', approvalId, ...verdictOf(decision) }]);
+}
+/** The chunks that show a client the approvals decided already, as answered. */
+export function decidedChunks(approvals) {
+    return decidedResponses(approvals).map(({ approvalId, approved, reason }) => ({
+        type: 'tool-approval-response',
+        approvalId,
+        approved,
+        ...(reason !== undefined && { reason }),
+    }));
+}

package/dist/turns/pending-input.js

@@ -115,6 +115,27 @@ export function withResponses(messages, responses) {
             }),
         });
 }
+const isQuestions = (input) => Array.isArray(input?.questions);
+const isAnswers = (output) => typeof output?.action === 'string';
+/**
+ * The answers to the agent's questions, `askUserQuestions`, in words: the labels of the options
+ * picked rather than their ids, which the agent no longer sees once its turn was lost.
+ */
+function answersOf(input, output) {
+    if (!isQuestions(input) || !isAnswers(output))
+        return undefined;
+    if (output.answers === undefined)
+        return `- I ${output.action} your questions.`;
+    const { answers } = output;
+    return input.questions
+        .map(({ id, question, options = [] }) => {
+        const answer = answers[id];
+        const picked = (answer?.optionIds ?? []).map((optionId) => options.find((option) => option.id === optionId)?.label ?? optionId);
+        const said = [...picked, ...(answer?.freeform ? [answer.freeform] : [])].join('; ');
+        return `- ${question} — ${said || 'no answer'}`;
+    })
+        .join('\n');
+}
 /** A short form of a tool call's input, for a message. */
 const inputOf = (input) => {
     const text = typeof input === 'string' ? input : JSON.stringify(input);
@@ -134,6 +155,9 @@ export function describeResponses(pending, responses) {
     const results = responses.toolResultContinuations.map(({ toolCallId, toolName, output }) => {
         const call = pending.toolCalls.find((toolCall) => toolCall.toolCallId === toolCallId);
         const shown = shownOutput(output);
+        const answers = shown.error === undefined ? answersOf(call?.input, shown.value) : undefined;
+        if (answers !== undefined)
+            return answers;
         const value = shown.error === undefined ? inputOf(shown.value) : `error: ${shown.error}`;
         return `- ${call?.toolName ?? toolName}: ${value}`;
     });

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

@@ -1,12 +1,23 @@
 import type { LanguageModelUsage, UIMessage, UIMessageChunk } from 'ai';
 import type { SessionStreamResult } from '../definitions/agent.js';
+/** The tokens a turn used, added up over its streams. */
+export type TurnUsage = Pick<LanguageModelUsage, 'inputTokens' | 'outputTokens' | 'totalTokens'>;
 /** How a turn ended. */
 export interface TurnOutcome {
     /** The conversation with the turn's answer, when the stream got far enough to give it. */
     messages: UIMessage[] | undefined;
     /** What went wrong, when the turn failed or was cut short. */
     failure: string | undefined;
-    usage: LanguageModelUsage | undefined;
+    usage: TurnUsage;
+}
+/**
+ * What a turn does once one of its streams ends: answers given in between, sent to the client and
+ * written into the conversation, and the stream that continues the turn, if it goes on.
+ */
+export interface TurnStep {
+    chunks: UIMessageChunk[];
+    messages: UIMessage[];
+    result?: SessionStreamResult;
 }
 export interface TurnStreamOptions {
     /** The conversation the turn adds to: its last message is the one the turn answers. */
@@ -14,14 +25,17 @@ export interface TurnStreamOptions {
     generateMessageId: () => string;
     /** What the client is told of an error; the outcome keeps its real message. */
     errorMessage: (error: unknown) => string;
-    /** Runs once, when the turn is over, before the client's stream closes when it can. */
+    /** What follows a stream of the turn that ended with its conversation. Default: the turn ends. */
+    next?: (messages: UIMessage[]) => Promise<TurnStep | undefined>;
+    /** Runs once, when the turn is over, before the client's stream closes. */
     onSettled: (outcome: TurnOutcome) => Promise<void>;
 }
 /**
- * The turn as a UI message stream, for the client, while this side reads it to its end as well: a
- * client that goes away does not leave the turn hanging, and the outcome is settled either way.
+ * The turn as a UI message stream for the client, read to its end on this side whether the client
+ * reads it or not: a client that goes away does not leave the turn hanging, and the outcome is
+ * settled either way. A turn may run several streams, one after the other, `next` deciding.
  */
-export declare function streamTurn(result: SessionStreamResult, options: TurnStreamOptions): {
+export declare function streamTurn(first: SessionStreamResult, options: TurnStreamOptions): {
     stream: ReadableStream<UIMessageChunk>;
     settled: Promise<void>;
 };

package/dist/turns/turn-stream.js

@@ -1,48 +1,140 @@
 const messageOf = (error) => error instanceof Error ? error.message : String(error);
-/**
- * The turn as a UI message stream, for the client, while this side reads it to its end as well: a
- * client that goes away does not leave the turn hanging, and the outcome is settled either way.
- */
-export function streamTurn(result, options) {
-    let messages;
-    let failure;
-    let settled;
-    const settle = () => {
-        settled ??= (async () => {
-            const usage = await Promise.resolve(result.totalUsage).catch(() => undefined);
-            await options.onSettled({ messages, failure, usage });
-        })();
-        return settled;
+/** Reads one stream of the turn to its end, sending its chunks on. */
+async function readSegment(result, originalMessages, { first, send, options, }) {
+    const outcome = {
+        messages: undefined,
+        failure: undefined,
+        finish: undefined,
+        requests: [],
     };
-    const [toClient, toServer] = result
+    const holding = options.next !== undefined;
+    const reader = result
         .toUIMessageStream({
-        originalMessages: options.originalMessages,
+        originalMessages,
         // Without it, a turn that continues a message the client cannot tell apart from the others.
         generateMessageId: options.generateMessageId,
-        // Awaited before the stream closes: the client reads the session once it is settled.
-        onFinish: async ({ messages: finished }) => {
-            messages = finished;
-            await settle();
+        onFinish: ({ messages }) => {
+            outcome.messages = messages;
         },
         // Called again with the text it returned, as the error chunk is read: the first is the one.
         onError: (error) => {
-            failure ??= messageOf(error);
+            outcome.failure ??= messageOf(error);
             return options.errorMessage(error);
         },
     })
-        .tee();
-    const drained = (async () => {
-        const reader = toServer.getReader();
-        try {
-            while (!(await reader.read()).done)
-                ;
+        .getReader();
+    try {
+        for (let read = await reader.read(); !read.done; read = await reader.read()) {
+            const chunk = read.value;
+            if (chunk.type === 'finish')
+                outcome.finish = chunk;
+            else if (holding && chunk.type === 'tool-approval-request')
+                outcome.requests.push(chunk);
+            // A stream that continues the turn continues the client's message: it is already open.
+            else if (first || chunk.type !== 'start')
+                send(chunk);
+        }
+    }
+    catch (error) {
+        outcome.failure ??= messageOf(error);
+    }
+    return outcome;
+}
+/** 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);
+    for (const key of ['inputTokens', 'outputTokens', 'totalTokens']) {
+        usage[key] = (usage[key] ?? 0) + (spent?.[key] ?? 0);
+    }
+}
+/** Runs a turn's streams one after the other, sending their chunks to the client. */
+class TurnRun {
+    options;
+    send;
+    usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    messages;
+    failure;
+    finish;
+    constructor(options, send) {
+        this.options = options;
+        this.send = send;
+    }
+    async run(first) {
+        let result = first;
+        let originalMessages = this.options.originalMessages;
+        for (let index = 0; result !== undefined; index += 1) {
+            const outcome = await readSegment(result, originalMessages, {
+                first: index === 0,
+                send: this.send,
+                options: this.options,
+            });
+            await addUsage(this.usage, result);
+            this.failure ??= outcome.failure;
+            this.finish = outcome.finish;
+            this.messages = outcome.messages ?? this.messages;
+            const step = await this.next(outcome.messages, outcome.requests);
+            result = step?.result;
+            if (step)
+                originalMessages = this.messages = step.messages;
+        }
+        if (this.finish !== undefined)
+            this.send(this.finish);
+        return { messages: this.messages, failure: this.failure, usage: this.usage };
+    }
+    /**
+     * What follows a stream that ended well, its approval requests sent first, with the answers
+     * `next` gave them; nothing after a failure.
+     */
+    async next(messages, requests) {
+        let step;
+        let failed;
+        if (this.failure === undefined && messages !== undefined && this.options.next) {
+            try {
+                step = await this.options.next(messages);
+            }
+            catch (error) {
+                failed = error;
+            }
+        }
+        for (const chunk of [...requests, ...(step?.chunks ?? [])])
+            this.send(chunk);
+        if (failed !== undefined) {
+            this.failure = messageOf(failed);
+            this.send({ type: 'error', errorText: this.options.errorMessage(failed) });
         }
-        catch (error) {
-            failure ??= messageOf(error);
+        return step;
+    }
+}
+/**
+ * The turn as a UI message stream for the client, read to its end on this side whether the client
+ * reads it or not: a client that goes away does not leave the turn hanging, and the outcome is
+ * settled either way. A turn may run several streams, one after the other, `next` deciding.
+ */
+export function streamTurn(first, options) {
+    let controller;
+    let reading = true;
+    const stream = new ReadableStream({
+        start: (opened) => {
+            controller = opened;
+        },
+        cancel: () => {
+            reading = false;
+        },
+    });
+    const send = (chunk) => {
+        if (reading)
+            controller.enqueue(chunk);
+    };
+    const settled = (async () => {
+        try {
+            const outcome = await new TurnRun(options, send).run(first);
+            // Settled before the stream closes: the client reads the session once it is written.
+            await options.onSettled(outcome);
         }
         finally {
-            await settle();
+            if (reading)
+                controller.close();
         }
     })();
-    return { stream: toClient, settled: drained };
+    return { stream, settled };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-sdk-harness-sessions",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -55,12 +55,12 @@
     "ai": "^7.0.127",
     "typescript": "^6.0.3",
     "vitest": "^5.0.3",
-    "@repo/build": "0.0.0",
+    "@repo/eslint-config": "0.0.0",
     "@repo/prettier-config": "0.0.0",
     "@repo/typescript-config": "0.0.0",
-    "@repo/eslint-config": "0.0.0",
     "@repo/vitest-config": "0.0.0",
-    "ai-sdk-sandbox-sbx": "0.1.1"
+    "ai-sdk-sandbox-sbx": "0.1.1",
+    "@repo/build": "0.0.0"
   },
   "author": {
     "name": "Fabien Pasquet",