@theoremjs/react 0.3.0 → 0.3.1

package/client/transport.d.ts

@@ -1,3 +1,5 @@
+import { type GateReference, type ToolGate } from '@theoremjs/agents';
+import type { PageDispatchResult } from './page-dispatch.ts';
 /**
  * Transport contract between a Theorem chat UI and the host that runs turns.
  *
@@ -9,7 +11,9 @@
  * @module
  */
 import { type ErrorKind, type TurnEvent, type TurnHistoryMessage, type TurnToolSnapshot, z } from '@theoremjs/agents';
-import { type ProfileInterface } from '@theoremjs/agents/interface';
+import { type ErrorCopies } from '@theoremjs/agents/guardrails';
+import { type ProfileInterface, type TranscriptBlock } from '@theoremjs/agents/interface';
+import type { PagePart } from './tool-resume.ts';
 import type { TraceFeed } from './trace-feed.ts';
 import { type MalformedEvent, type UnsupportedEvent, type WireLines } from './wire-line.ts';
 export type { MalformedEvent, UnsupportedEvent, WireLines } from './wire-line.ts';
@@ -23,49 +27,55 @@ export type TheoremTurnInput = {
     text?: string;
     attachments?: EncodedBlob[];
     voice?: EncodedBlob[];
-    history?: TurnHistoryMessage[];
-    historyTokens?: number;
-    inputTokens?: number;
+    /** The value chosen for each of the profile's `inputs.slots`. */
+    slots?: Record<string, string>;
+    /** What the page wants the agent to know: any JSON. The host reads it as untrusted. */
+    context?: unknown;
 };
 /**
  * State only the client holds, for hosts whose profile also lives in the browser
- * (the playground). `createHttpTransport` never sends it: `createTheoremHandler`
+ * (the studio). `createHttpTransport` never sends it: `createTheoremHandler`
  * keeps permissions, paused calls, and tool snapshots in its own session.
  */
 export type TheoremReplay = {
+    gateKind?: ToolGate['kind'];
     sessionPermissions?: string[];
     name?: string;
     input?: unknown;
-    turnInput?: TheoremTurnInput;
     snapshot?: TurnToolSnapshot;
     promoted?: string[];
     model?: string;
     effort?: string;
-    path?: string;
 };
-/** For a host that reads the playground's client-held state. */
+/** For a host that reads the studio's client-held state. */
 export declare const theoremReplaySchema: z.ZodType<TheoremReplay>;
 /**
- * One text turn. The host resolves the profile; the client sends the conversation.
+ * One message. The host resolves the profile and owns the conversation: the
+ * client sends only the message and the ref of the conversation it continues.
  *
  * A message sent while the reply waits on gates walks away from them: `abandon`
- * names the waiting calls, and `input.history` ends on their step with those
- * calls open. The host settles each one cancelled, streams those events first,
- * and gives the model each call's answer before the message.
+ * names the waiting calls. The host settles each one cancelled, streams those
+ * events first, and gives the model each call's answer before the message.
  */
 export type TheoremTurnRequest = {
     input: TheoremTurnInput;
-    previousInteractionId?: string;
+    /** The ref of the conversation this message continues; none starts one. */
+    conversation?: string;
     model?: string;
     effort?: string;
     /** Client-generated id so mid-turn steers can find this turn's inbox. */
     turnId?: string;
-    /** Call ids of the paused calls this message walks away from. */
-    abandon?: string[];
-    replay?: Pick<TheoremReplay, 'sessionPermissions'> & {
-        /** Each walked-away call as the client holds it, by call id, for a host without a session. */
-        abandon?: Record<string, TheoremReplay>;
-    };
+    /** invariant: Both issued IDs identify each paused action that this message abandons. */
+    abandon?: GateReference[];
+    /** The tools the person allowed for the page, for a host without a session (the studio). */
+    replay?: Pick<TheoremReplay, 'sessionPermissions'>;
+    /**
+     * The page's transcript before this message, sent only after the host answered that it can no
+     * longer open `conversation` (`session.conversation_unknown`). A host that restores from it (the
+     * studio) goes on from it under a new ref; `createTheoremHandler` keeps the conversation its own
+     * and does not.
+     */
+    transcript?: TranscriptBlock[];
 };
 /** A `/turn` body as `createTheoremHandler` reads it. */
 export declare const theoremTurnRequestSchema: z.ZodType<TheoremTurnRequest>;
@@ -80,6 +90,7 @@ declare const INVOKE_DECISIONS: readonly ["approve", "deny"];
 export type TheoremInvokeRequest = {
     /** Call id of the paused tool call (`tool.callId` on its gate event). */
     gateId: string;
+    operationId: string;
     decision: (typeof INVOKE_DECISIONS)[number];
     /** The user's edit of the model's input; only with `approve`. */
     input?: unknown;
@@ -90,6 +101,12 @@ export type TheoremInvokeRequest = {
      * callback saved the token.
      */
     secret?: string;
+    /** The page's answer to a `page` gate, only with `approve`: the tool's output schema checks it. */
+    page?: PagePart;
+    /** The ref of the conversation whose reply waits on the gate. */
+    conversation?: string;
+    /** Client-generated id so steers sent while the reply goes on find its inbox. */
+    turnId?: string;
     replay?: TheoremReplay;
 };
 /** An `/invoke` body as `createTheoremHandler` reads it. */
@@ -103,40 +120,97 @@ export type TheoremSteerRequest = {
 };
 /** A `/steer` body as `createTheoremHandler` reads it. */
 export declare const theoremSteerRequestSchema: z.ZodType<TheoremSteerRequest>;
+/**
+ * The ref the store issued for the conversation a run wrote: the client sends
+ * it with its next request. It comes before the run's error, which ends the stream.
+ * `posted` marks the write that holds the person's new message: a run that
+ * fails before it leaves the message unsent.
+ */
+export type ConversationLine = {
+    type: 'conversation';
+    ref: string;
+    posted?: true;
+};
+/** The lines a chat's reply streams: turn events, and the conversation's ref. */
+export declare const CHAT_LINES: WireLines<TurnEvent | ConversationLine>;
+/** What the browser draws: the transcript, and the reply that waits on gates. */
+export type ConversationView = {
+    transcript: TranscriptBlock[];
+    /** The reply that waits on gates: its events, and its blocks as the transcript will keep them. */
+    paused?: {
+        events: TurnEvent[];
+        blocks: TranscriptBlock[];
+    };
+};
+/** Read a conversation: a `/conversation` body. */
+export type TheoremConversationRequest = {
+    conversation: string;
+};
+/** A `/conversation` body as `createTheoremHandler` reads it. */
+export declare const theoremConversationRequestSchema: z.ZodType<TheoremConversationRequest>;
+/**
+ * Cut the conversation after transcript block `at` (-1 empties it): a
+ * `/rewind` body. A reply waiting on gates is walked away from first.
+ */
+export type TheoremRewindRequest = {
+    conversation: string;
+    at: number;
+};
+/** A `/rewind` body as `createTheoremHandler` reads it. */
+export declare const theoremRewindRequestSchema: z.ZodType<TheoremRewindRequest>;
+/** A rewound conversation: its new ref, and what the browser draws. */
+export type TheoremRewound = {
+    conversation: string;
+    view: ConversationView;
+};
 /** A turn event, one of a kind this client does not know (`unsupported`), or one that failed its check (`malformed`). */
 export type ClientTurnEvent = TurnEvent | UnsupportedEvent | MalformedEvent;
 export type TurnEventSink = (event: ClientTurnEvent) => void;
+/** A line of a chat's reply: a turn event, or the ref of the conversation it wrote. */
+export type ChatLine = ClientTurnEvent | ConversationLine;
+export type ChatLineSink = (line: ChatLine) => void;
 export interface TheoremTransport {
     /** Client-safe interface for the host's profile (inputs, models, guardrail view). */
     describe(signal?: AbortSignal): Promise<ProfileInterface>;
-    turn(request: TheoremTurnRequest, onEvent: TurnEventSink, signal?: AbortSignal): Promise<void>;
-    invoke(request: TheoremInvokeRequest, onEvent: TurnEventSink, signal?: AbortSignal): Promise<void>;
+    turn(request: TheoremTurnRequest, onLine: ChatLineSink, signal?: AbortSignal): Promise<void>;
+    invoke(request: TheoremInvokeRequest, onLine: ChatLineSink, signal?: AbortSignal): Promise<void>;
     steer(request: TheoremSteerRequest): Promise<void>;
-    /** Trace records the host sends back, when it delivers them (the playground does). */
+    /** The conversation under `ref`, as the host shows it. */
+    conversation(request: TheoremConversationRequest, signal?: AbortSignal): Promise<ConversationView>;
+    /** The conversation cut after a transcript block, under the ref the host issued for it. */
+    rewind(request: TheoremRewindRequest, signal?: AbortSignal): Promise<TheoremRewound>;
+    pageResult?(result: PageDispatchResult, signal?: AbortSignal): Promise<void>;
+    /** Trace records the host sends back, when it delivers them (the studio does). */
     traces?: TraceFeed;
 }
 /**
  * A failure the host reported: its kind, the host's wording when it sent one
- * (the profile's lexicon, applied on the host), and raw detail when the host
+ * (the profile's labels, applied on the host), and raw detail when the host
  * exposes it. `clientFailure` words it for the user.
  */
 export declare class TheoremStreamError extends Error {
     readonly kind: ErrorKind;
     readonly publicMessage?: string;
     readonly internalMessage?: string;
-    constructor(kind: ErrorKind, publicMessage?: string, internalMessage?: string);
+    /** The labels key behind `publicMessage`, when the host gave one: what failed, more exactly than `kind`. */
+    readonly copy?: ErrorCopies;
+    constructor(kind: ErrorKind, publicMessage?: string, internalMessage?: string, copy?: ErrorCopies);
 }
 export declare function isTheoremStreamError(err: unknown): err is TheoremStreamError;
 /** A host error reply's body (JSON reply or `{ type: 'error' }` stream line). */
 export type HostErrorBody = {
     error?: string;
     errorKind?: ErrorKind;
+    /** The labels key behind `error`, when more specific than the kind's. */
+    errorCopy?: ErrorCopies;
     errorInternal?: string;
 };
 /** A host's error body, as the transport and the live client read it. */
 export declare const hostErrorBodySchema: z.ZodType<HostErrorBody>;
 /** A host's error body as a failure: its kind (else `fallbackKind`), wording, and detail. */
 export declare function hostError(body: HostErrorBody, fallbackKind: ErrorKind): TheoremStreamError;
+/** The host could not open the message's conversation (`session.conversation_unknown`). */
+export declare function isUnknownConversation(err: unknown): boolean;
 /**
  * Read an NDJSON reply, checking each line against `lines`: a kind it doesn't
  * list reaches `onLine` as `unsupported`, and a line that fails its check as
@@ -162,12 +236,26 @@ export declare function postNdjson<Line extends {
     signal?: AbortSignal;
 }): Promise<void>;
 /** POST JSON; a non-OK reply throws its failure. The OK reply's body is not read. */
-export declare function postJson(url: string, body: unknown, options?: HttpOptions): Promise<void>;
-/** GET, or POST `body` as JSON, and read the JSON reply; a non-OK reply throws its failure. */
+export declare function postJson(url: string, body: unknown, options?: HttpOptions & {
+    signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * GET, or POST `body` as JSON, and read the JSON reply; a non-OK reply throws its failure, after
+ * `failed` has read whatever else its JSON body carries.
+ */
 export declare function fetchJson(url: string, init: {
     body?: unknown;
     signal?: AbortSignal;
+    failed?: (body: unknown) => void;
 }, options?: HttpOptions): Promise<unknown>;
+/** POST a conversation's read to `url`, and check the view the host answers. */
+export declare function fetchConversation(url: string, body: unknown, options?: HttpOptions & {
+    signal?: AbortSignal;
+}): Promise<ConversationView>;
+/** POST a rewind to `url`, and check the rewound conversation the host answers. */
+export declare function fetchRewound(url: string, body: unknown, options?: HttpOptions & {
+    signal?: AbortSignal;
+}): Promise<TheoremRewound>;
 export type HttpTransportOptions = HttpOptions & {
     /** Base URL where `createTheoremHandler` is mounted. Default `/api/theorem`. */
     endpoint?: string;

package/client/transport.js

@@ -1,3 +1,4 @@
+import { gateReferenceSchema, TOOL_GATE_KINDS, } from '@theoremjs/agents';
 /**
  * Transport contract between a Theorem chat UI and the host that runs turns.
  *
@@ -8,59 +9,67 @@
  *
  * @module
  */
-import { describeError, errorKindSchema, isAbortError, TheoremError, TURN_EVENT_SCHEMAS, throwIfAborted, turnHistoryMessageSchema, turnToolSnapshotSchema, z, } from '@theoremjs/agents';
-import { kindOfHttpStatus } from '@theoremjs/agents/guardrails';
-import { profileInterfaceSchema } from '@theoremjs/agents/interface';
+import { describeError, errorKindSchema, isAbortError, TheoremError, TURN_EVENT_SCHEMAS, throwIfAborted, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, z, } from '@theoremjs/agents';
+import { errorCopiesSchema, kindOfHttpStatus, } from '@theoremjs/agents/guardrails';
+import { profileInterfaceSchema, } from '@theoremjs/agents/interface';
+import { transcriptBlockSchema } from "./transcript-schema.js";
 import { checkWire, parseWireJson, readWireLine, } from "./wire-line.js";
 const encodedBlob = z.object({ name: z.string(), mimeType: z.string(), data: z.string() });
 true;
 const theoremTurnInput = z.object({
+    slots: z.record(z.string(), z.string()).optional(),
+    context: z.unknown().optional(),
     text: z.string().optional(),
     attachments: z.array(encodedBlob).optional(),
     voice: z.array(encodedBlob).optional(),
-    history: z.array(turnHistoryMessageSchema).optional(),
-    historyTokens: z.number().optional(),
-    inputTokens: z.number().optional(),
 });
 true;
 const theoremReplay = z.object({
+    gateKind: z.enum(TOOL_GATE_KINDS).optional(),
     sessionPermissions: z.array(z.string()).optional(),
     name: z.string().optional(),
     input: z.unknown().optional(),
-    turnInput: theoremTurnInput.optional(),
     snapshot: turnToolSnapshotSchema.optional(),
     promoted: z.array(z.string()).optional(),
     model: z.string().optional(),
     effort: z.string().optional(),
-    path: z.string().optional(),
 });
 true;
-/** For a host that reads the playground's client-held state. */
+/** For a host that reads the studio's client-held state. */
 export const theoremReplaySchema = theoremReplay;
 /** An id the client made: trimmed, never blank. */
 const clientId = z.string().trim().min(1);
 const theoremTurnRequest = z.object({
     input: theoremTurnInput,
-    previousInteractionId: z.string().optional(),
+    conversation: z.string().min(1).optional(),
     model: z.string().optional(),
     effort: z.string().optional(),
     turnId: clientId.optional(),
-    abandon: z.array(z.string().min(1)).min(1).optional(),
-    replay: theoremReplay
-        .pick({ sessionPermissions: true })
-        .extend({ abandon: z.record(z.string(), theoremReplay).optional() })
-        .optional(),
+    abandon: z.array(gateReferenceSchema).min(1).optional(),
+    replay: theoremReplay.pick({ sessionPermissions: true }).optional(),
+    transcript: z.array(transcriptBlockSchema).optional(),
 });
 true;
 /** A `/turn` body as `createTheoremHandler` reads it. */
 export const theoremTurnRequestSchema = theoremTurnRequest;
 /** What the user answers a gate with; walking away rides on the next message (`TheoremTurnRequest.abandon`). */
 const INVOKE_DECISIONS = ['approve', 'deny'];
+const pagePart = z.union([
+    z.strictObject({ unanswered: z.literal(true) }),
+    z
+        .strictObject({ output: z.unknown() })
+        .refine((part) => 'output' in part)
+        .transform((part) => ({ output: part.output })),
+]);
 const theoremInvokeRequest = z.object({
     gateId: z.string().min(1),
+    operationId: z.string().min(1).max(256),
     decision: z.enum(INVOKE_DECISIONS),
     input: z.unknown().optional(),
     secret: z.string().optional(),
+    page: pagePart.optional(),
+    conversation: z.string().min(1).optional(),
+    turnId: clientId.optional(),
     replay: theoremReplay.optional(),
 });
 true;
@@ -74,16 +83,49 @@ const theoremSteerRequest = z.object({
 true;
 /** A `/steer` body as `createTheoremHandler` reads it. */
 export const theoremSteerRequestSchema = theoremSteerRequest;
+const conversationLine = z.object({
+    type: z.literal('conversation'),
+    ref: z.string().min(1),
+    posted: z.literal(true).optional(),
+});
+true;
+/** The lines a chat's reply streams: turn events, and the conversation's ref. */
+export const CHAT_LINES = {
+    ...TURN_EVENT_SCHEMAS,
+    conversation: conversationLine,
+};
+const conversationView = z.object({
+    transcript: z.array(transcriptBlockSchema),
+    paused: z
+        .object({ events: z.array(turnEventSchema), blocks: z.array(transcriptBlockSchema) })
+        .optional(),
+});
+true;
+const theoremConversationRequest = z.object({ conversation: z.string().min(1) });
+true;
+/** A `/conversation` body as `createTheoremHandler` reads it. */
+export const theoremConversationRequestSchema = theoremConversationRequest;
+const theoremRewindRequest = z.object({
+    conversation: z.string().min(1),
+    at: z.number().int().min(-1),
+});
+true;
+/** A `/rewind` body as `createTheoremHandler` reads it. */
+export const theoremRewindRequestSchema = theoremRewindRequest;
+const theoremRewound = z.object({ conversation: z.string().min(1), view: conversationView });
+true;
 /**
  * A failure the host reported: its kind, the host's wording when it sent one
- * (the profile's lexicon, applied on the host), and raw detail when the host
+ * (the profile's labels, applied on the host), and raw detail when the host
  * exposes it. `clientFailure` words it for the user.
  */
 export class TheoremStreamError extends Error {
     kind;
     publicMessage;
     internalMessage;
-    constructor(kind, publicMessage, internalMessage) {
+    /** The labels key behind `publicMessage`, when the host gave one: what failed, more exactly than `kind`. */
+    copy;
+    constructor(kind, publicMessage, internalMessage, copy) {
         super(internalMessage ?? publicMessage ?? kind);
         this.name = 'TheoremStreamError';
         this.kind = kind;
@@ -91,6 +133,8 @@ export class TheoremStreamError extends Error {
             this.publicMessage = publicMessage;
         if (internalMessage)
             this.internalMessage = internalMessage;
+        if (copy)
+            this.copy = copy;
     }
 }
 export function isTheoremStreamError(err) {
@@ -103,6 +147,7 @@ function textOf(value) {
 const hostErrorBody = z.object({
     error: z.string().optional(),
     errorKind: errorKindSchema.optional(),
+    errorCopy: errorCopiesSchema.optional(),
     errorInternal: z.string().optional(),
 });
 true;
@@ -112,12 +157,19 @@ export const hostErrorBodySchema = hostErrorBody;
 export function hostError(body, fallbackKind) {
     const publicMessage = textOf(body.error);
     const internal = textOf(body.errorInternal);
-    return new TheoremStreamError(body.errorKind ?? fallbackKind, publicMessage, internal && internal !== publicMessage ? internal : undefined);
+    return new TheoremStreamError(body.errorKind ?? fallbackKind, publicMessage, internal && internal !== publicMessage ? internal : undefined, body.errorCopy);
+}
+/** The host could not open the message's conversation (`session.conversation_unknown`). */
+export function isUnknownConversation(err) {
+    if (!isTheoremStreamError(err) || err.copy === undefined)
+        return false;
+    const copies = Array.isArray(err.copy) ? err.copy : [err.copy];
+    return copies.some((copy) => copy.key === 'session.conversation_unknown');
 }
 /** One NDJSON line checked against `lines`; an `error` line ends the stream as a {@link TheoremStreamError}. */
 function parseStreamLine(lines, text) {
     const line = readWireLine(lines, text);
-    // An `error` line passed the error event's schema, whose fields include the body's.
+    // why: An `error` line passed the error event's schema, whose fields include the body's.
     if (line.type === 'error')
         throw hostError(hostErrorBody.parse(line), 'internal');
     return line;
@@ -139,7 +191,7 @@ function flushNdjsonChunk(buffer, lines, onLine) {
  */
 export async function readNdjsonStream(response, lines, onLine, signal) {
     if (!response.body)
-        throw new TheoremError('bad_response', 'stream reply has no body'); // lexicon-exempt: internal diagnostic
+        throw new TheoremError('bad_response', 'stream reply has no body'); // labels-exempt: internal diagnostic
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
@@ -174,18 +226,19 @@ async function resolveHeaders(options) {
  * kind. A body that is not JSON (a proxy's page) leaves the status to speak; a
  * JSON body that fails the error body's schema is `bad_response`.
  */
-async function failureFromResponse(response) {
+async function failureFromResponse(response, failed) {
     const text = await response.text();
     let raw;
     try {
         raw = JSON.parse(text);
+        failed?.(raw);
     }
     catch {
         return hostError({ errorInternal: `HTTP ${String(response.status)}` }, kindOfHttpStatus(response.status));
     }
     const body = hostErrorBody.safeParse(raw);
     if (!body.success) {
-        // lexicon-exempt: internal diagnostic; the user reads error.bad_response
+        // labels-exempt: internal diagnostic; the user reads error.bad_response
         return new TheoremError('bad_response', `HTTP ${String(response.status)} error body failed its wire check`);
     }
     return hostError({ ...body.data, errorInternal: body.data.errorInternal ?? `HTTP ${String(response.status)}` }, kindOfHttpStatus(response.status));
@@ -210,25 +263,43 @@ async function request(url, init, options) {
  * events ({@link TURN_EVENT_SCHEMAS}), or a host's own schema beside them.
  */
 export async function postNdjson(url, body, lines, onLine, options = {}) {
+    const response = await jsonPostResponse(url, body, options);
+    await readNdjsonStream(response, lines, onLine, options.signal);
+}
+async function jsonPostResponse(url, body, options) {
     const response = await request(url, { method: 'POST', body: JSON.stringify(body), signal: options.signal }, options);
     if (!response.ok)
         throw await failureFromResponse(response);
-    await readNdjsonStream(response, lines, onLine, options.signal);
+    return response;
 }
 /** POST JSON; a non-OK reply throws its failure. The OK reply's body is not read. */
 export async function postJson(url, body, options = {}) {
-    const response = await request(url, { method: 'POST', body: JSON.stringify(body) }, options);
-    if (!response.ok)
-        throw await failureFromResponse(response);
+    await jsonPostResponse(url, body, options);
 }
-/** GET, or POST `body` as JSON, and read the JSON reply; a non-OK reply throws its failure. */
+/**
+ * GET, or POST `body` as JSON, and read the JSON reply; a non-OK reply throws its failure, after
+ * `failed` has read whatever else its JSON body carries.
+ */
 export async function fetchJson(url, init, options = {}) {
-    const method = init.body === undefined ? { method: 'GET' } : { method: 'POST', body: JSON.stringify(init.body) };
+    const method = init.body === undefined
+        ? { method: 'GET' }
+        : { method: 'POST', body: JSON.stringify(init.body) };
     const response = await request(url, { ...method, signal: init.signal }, options);
     if (!response.ok)
-        throw await failureFromResponse(response);
+        throw await failureFromResponse(response, init.failed);
     return parseWireJson(await response.text());
 }
+/** POST a conversation's read to `url`, and check the view the host answers. */
+export async function fetchConversation(url, body, options = {}) {
+    const { signal, ...http } = options;
+    // labels-exempt: internal diagnostic; the user reads error.bad_response
+    return checkWire(conversationView, await fetchJson(url, { body, signal }, http), 'the conversation');
+}
+/** POST a rewind to `url`, and check the rewound conversation the host answers. */
+export async function fetchRewound(url, body, options = {}) {
+    const { signal, ...http } = options;
+    return checkWire(theoremRewound, await fetchJson(url, { body, signal }, http), 'the rewound conversation');
+}
 /** Drops trailing '/'s by scanning back, not with a regex (a `/\/+$/` scan is quadratic on long runs of '/'). */
 function withoutTrailingSlashes(url) {
     let end = url.length;
@@ -246,11 +317,14 @@ export function createHttpTransport(options = {}) {
             const response = await request(base, { method: 'GET', signal }, options);
             if (!response.ok)
                 throw await failureFromResponse(response);
-            // lexicon-exempt: internal diagnostic; the user reads error.bad_response
+            // labels-exempt: internal diagnostic; the user reads error.bad_response
             return checkWire(describedSchema, parseWireJson(await response.text()), 'the profile description').interface;
         },
-        turn: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/turn`, body, TURN_EVENT_SCHEMAS, onEvent, { ...options, signal }),
-        invoke: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/invoke`, body, TURN_EVENT_SCHEMAS, onEvent, { ...options, signal }),
+        turn: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/turn`, body, CHAT_LINES, onEvent, { ...options, signal }),
+        invoke: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/invoke`, body, CHAT_LINES, onEvent, { ...options, signal }),
+        conversation: (body, signal) => fetchConversation(`${base}/conversation`, body, { ...options, signal }),
+        rewind: (body, signal) => fetchRewound(`${base}/rewind`, body, { ...options, signal }),
+        pageResult: (body, signal) => postJson(`${base}/page-result`, body, { ...options, signal }),
         steer: (body) => postJson(`${base}/steer`, body, options),
     };
 }

package/client/turn-client.d.ts

@@ -1,28 +1,37 @@
-import type { TurnEvent } from '@theoremjs/agents';
+import { type TurnEvent } from '@theoremjs/agents';
 import { type AttachmentValidationIssue, type ComposerProfileInterface, type GatedToolContext, type InterfaceTurnSession, type TranscriptBlock, type UserTurnDraft } from '@theoremjs/agents/interface';
-import type { TheoremInvokeRequest, TheoremTurnInput, TheoremTurnRequest } from './transport.ts';
-export declare function turnInputFromSession(session: InterfaceTurnSession, overrides?: TheoremTurnInput): TheoremTurnInput;
-/** A gated call as the client holds it, for a host without a session (the playground). */
+import type { PagePart } from './tool-resume.ts';
+import type { TheoremInvokeRequest, TheoremReplay, TheoremTurnInput, TheoremTurnRequest } from './transport.ts';
+export declare function issuedOperationId(call: {
+    operationId?: string;
+}): string;
+/** A gated call as the client holds it, for a host without a session (the studio). */
 export type HeldCall = {
     name: string;
     /** The model's input to the call. */
     input: unknown;
+    gateKind?: TheoremReplay['gateKind'];
     sessionPermissions?: string[];
 };
-/** A paused session, and the calls it waits on that a message walks away from. */
+/** The calls a paused reply waits on that a message walks away from. */
 export type WalkAway = {
-    paused: InterfaceTurnSession;
     calls: readonly GatedToolContext[];
 };
-export declare function buildTurnRequest(iface: ComposerProfileInterface, session: InterfaceTurnSession, input: TheoremTurnInput, options?: {
+/** Where a request goes on from: the ref of the conversation the host keeps, and the run's id for steers. */
+export type RunScope = {
+    conversation?: string;
     turnId?: string;
+};
+export declare function buildTurnRequest(iface: ComposerProfileInterface, session: InterfaceTurnSession, input: TheoremTurnInput, options?: RunScope & {
     walkAway?: WalkAway;
 }): TheoremTurnRequest;
 export declare function buildInvokeRequest(iface: ComposerProfileInterface, session: InterfaceTurnSession, args: HeldCall & {
     gateId: string;
+    operationId: string;
     decision: TheoremInvokeRequest['decision'];
     secret?: string;
-}): TheoremInvokeRequest;
+    page?: PagePart;
+}, scope?: RunScope): TheoremInvokeRequest;
 export declare function projectUserTurn(iface: ComposerProfileInterface, draft: UserTurnDraft): {
     ok: true;
     blocks: TranscriptBlock[];

package/client/turn-client.js

@@ -1,13 +1,11 @@
+import { labelText, TheoremError } from '@theoremjs/agents';
 import { foldTurnEvents, prepareUserTurn, streamThoughtsEnabled, } from '@theoremjs/agents/interface';
 import { filesToPending } from "./encode-files.js";
 import { defaultModel } from "./generation-selection.js";
-export function turnInputFromSession(session, overrides = {}) {
-    return {
-        ...overrides,
-        history: session.history,
-        ...(session.inputTokens !== undefined ? { inputTokens: session.inputTokens } : {}),
-        ...(session.historyTokens !== undefined ? { historyTokens: session.historyTokens } : {}),
-    };
+export function issuedOperationId(call) {
+    if (!call.operationId)
+        throw new TheoremError('request', labelText('session.gate_expired'));
+    return call.operationId;
 }
 function resolveModelId(iface, session) {
     return session.selectedModel ?? defaultModel(iface);
@@ -31,48 +29,45 @@ function gateReplay(iface, session, call) {
     return {
         name: call.name,
         input: call.input,
+        ...(call.gateKind ? { gateKind: call.gateKind } : {}),
         sessionPermissions: call.sessionPermissions ?? session.sessionPermissions,
-        turnInput: turnInputFromSession(session),
         ...(session.toolSnapshot ? { snapshot: session.toolSnapshot } : {}),
         ...(session.promotedToolIds.length ? { promoted: [...session.promotedToolIds] } : {}),
         ...generationFields(iface, session),
     };
 }
-/**
- * The paused calls a message walks away from: their ids, and each call as a
- * host without a session replays it, from the session as it paused.
- */
-function abandonFields(iface, walkAway) {
-    if (!walkAway.calls.length)
-        return undefined;
+function scopeFields(scope) {
     return {
-        abandon: walkAway.calls.map((call) => call.callId),
-        replays: Object.fromEntries(walkAway.calls.map((call) => [
-            call.callId,
-            gateReplay(iface, walkAway.paused, { name: call.name, input: call.arguments }),
-        ])),
+        ...(scope.conversation ? { conversation: scope.conversation } : {}),
+        ...(scope.turnId ? { turnId: scope.turnId } : {}),
     };
 }
 export function buildTurnRequest(iface, session, input, options = {}) {
-    const walked = options.walkAway ? abandonFields(iface, options.walkAway) : undefined;
+    const abandon = (options.walkAway?.calls ?? []).map((call) => ({
+        callId: call.callId,
+        operationId: issuedOperationId(call),
+    }));
     return {
-        previousInteractionId: session.previousInteractionId,
-        ...(options.turnId ? { turnId: options.turnId } : {}),
+        ...scopeFields(options),
         ...generationFields(iface, session),
         input,
-        ...(walked ? { abandon: walked.abandon } : {}),
-        replay: {
-            sessionPermissions: session.sessionPermissions,
-            ...(walked ? { abandon: walked.replays } : {}),
-        },
+        ...(abandon.length ? { abandon } : {}),
+        replay: { sessionPermissions: session.sessionPermissions },
     };
 }
-export function buildInvokeRequest(iface, session, args) {
+export function buildInvokeRequest(iface, session, args, scope = {}) {
     return {
+        ...scopeFields(scope),
         gateId: args.gateId,
+        operationId: args.operationId,
         decision: args.decision,
         ...(args.secret === undefined ? {} : { secret: args.secret }),
-        replay: gateReplay(iface, session, args),
+        ...(args.page === undefined ? {} : { page: args.page }),
+        replay: gateReplay(iface, session, {
+            ...args,
+            gateKind: args.gateKind ??
+                (session.gatedTool?.callId === args.gateId ? session.gatedTool.gateKind : undefined),
+        }),
     };
 }
 export function projectUserTurn(iface, draft) {
@@ -86,7 +81,7 @@ export function prepareComposerTurn(iface, text, pendingFiles, pendingVoice = []
     });
 }
 export function foldAssistantTurn(iface, events) {
-    // Its `turn-done` blocks stay: hidden in the view, they carry the reply's worked time.
+    // why: Its `turn-done` blocks stay: hidden in the view, they carry the reply's worked time.
     return foldTurnEvents(events, {
         showThoughts: streamThoughtsEnabled(iface.outputs),
     });