@theoremjs/react 0.3.0 → 0.3.1

package/client/live-messages.js

@@ -1,3 +1,4 @@
+import { providerCheckpointSchema } from '@theoremjs/agents';
 /**
  * The live wire between the browser and a host's relay: the messages the live
  * client sends (a relay reads them with `parseLiveClientMessage`) and the envelopes it reads
@@ -5,48 +6,78 @@
  *
  * @module
  */
-import { GATE_DECISIONS, toolGateSchema, traceRecordSchema, TURN_EVENT_SCHEMAS, z, } from '@theoremjs/agents';
+import { GATE_DECISIONS, TURN_EVENT_SCHEMAS, toolGateSchema, traceRecordSchema, turnHistoryMessageSchema, z, } from '@theoremjs/agents';
 import { hostErrorBodySchema } from "./transport.js";
 import { readWireLine, readWireValue, } from "./wire-line.js";
-/** The longest context message a relay accepts. */
-const LIVE_CONTEXT_MAX_CHARS = 2000;
+const liveOpenMessage = z.object({
+    type: z.literal('open'),
+    history: z.array(turnHistoryMessageSchema).optional(),
+    slots: z.record(z.string(), z.string()).optional(),
+    context: z.unknown().optional(),
+    resume: z
+        .object({ providerState: providerCheckpointSchema, awayMs: z.number().nonnegative() })
+        .optional(),
+    host: z.record(z.string(), z.unknown()).optional(),
+});
+true;
+/** The live client's first message, as `parseLiveOpenMessage` checks it for a relay. */
+export const liveOpenMessageSchema = liveOpenMessage;
 const liveClientMessage = z.discriminatedUnion('type', [
     z.object({ type: z.literal('audio'), data: z.string() }),
-    z.object({ type: z.literal('video'), data: z.string(), mimeType: z.string(),
-    }),
+    z.object({ type: z.literal('video'), data: z.string(), mimeType: z.string() }),
     z.object({ type: z.literal('text'), text: z.string() }),
-    z.object({ type: z.literal('context'), text: z.string().max(LIVE_CONTEXT_MAX_CHARS) }),
+    z.object({ type: z.literal('context'), context: z.unknown() }),
     z.object({
         type: z.literal('executeTool'),
         callId: z.string().min(1),
+        operationId: z.string().min(1).max(256),
         decision: z.enum(GATE_DECISIONS).optional(),
         input: z.unknown().optional(),
         secret: z.string().optional(),
         output: z.unknown().optional(),
+        grantId: z.string().min(1).optional(),
+        unanswered: z.literal(true).optional(),
     }),
 ]);
 true;
 /** The live client's messages, as `parseLiveClientMessage` checks them for a relay. */
 export const liveClientMessageSchema = liveClientMessage;
 const liveServerEnvelopeKinds = {
-    ready: z.object({ type: z.literal('ready'), profile: z.string().optional(), sessionId: z.string().optional(),
+    ready: z.object({
+        type: z.literal('ready'),
+        profile: z.string().optional(),
+        sessionId: z.string().optional(),
     }),
     events: z.object({ type: z.literal('events'), events: z.array(z.unknown()) }),
     trace: z.object({ type: z.literal('trace'), record: traceRecordSchema }),
     error: z.object({ type: z.literal('error') }).and(hostErrorBodySchema),
     executeToolResult: z.discriminatedUnion('status', [
-        z.object({ type: z.literal('executeToolResult'), callId: z.string(), status: z.literal('settled'),
+        z.object({
+            type: z.literal('executeToolResult'),
+            callId: z.string().min(1),
+            operationId: z.string().min(1).max(256),
+            status: z.literal('dispatched'),
+            grantId: z.string().min(1),
+            arguments: z.record(z.string(), z.unknown()),
+        }),
+        z.object({
+            type: z.literal('executeToolResult'),
+            callId: z.string(),
+            status: z.literal('settled'),
+            operationId: z.string().min(1).max(256),
         }),
         z.object({
             type: z.literal('executeToolResult'),
             callId: z.string(),
             status: z.literal('gated'),
+            operationId: z.string().min(1).max(256),
             gate: toolGateSchema,
         }),
         z.object({
             type: z.literal('executeToolResult'),
             callId: z.string(),
             status: z.literal('refused'),
+            operationId: z.string().min(1).max(256),
             body: hostErrorBodySchema,
         }),
     ]),
@@ -62,6 +93,8 @@ export function parseLiveServerEnvelope(text) {
     const envelope = readWireLine(liveServerEnvelopeLines, text);
     if (envelope.type !== 'events')
         return envelope;
-    return { type: 'events', events: envelope.events.map((event) => readWireValue(TURN_EVENT_SCHEMAS, event)),
+    return {
+        type: 'events',
+        events: envelope.events.map((event) => readWireValue(TURN_EVENT_SCHEMAS, event)),
     };
 }

package/client/page-dispatch.d.ts

@@ -0,0 +1,15 @@
+import type { HostTransport } from './host-transport.ts';
+import type { PageTools } from './live/live-page-tool.ts';
+import type { TheoremTransport } from './transport.ts';
+export type PageDispatchResult = {
+    callId: string;
+    operationId: string;
+    grantId: string;
+    page: {
+        output: unknown;
+    } | {
+        unanswered: true;
+    };
+};
+export declare function withPageToolDispatch(transport: TheoremTransport, tools?: PageTools): TheoremTransport;
+export declare function withPageToolDispatch(transport: HostTransport, tools?: PageTools): HostTransport;

package/client/page-dispatch.js

@@ -0,0 +1,63 @@
+import { errorKind, publicError } from '@theoremjs/agents';
+export function withPageToolDispatch(transport, tools) {
+    const sink = (onEvent, signal) => {
+        const dispatched = new Set();
+        return (event) => {
+            onEvent(event);
+            if (event.type !== 'tool' || event.tool.phase !== 'dispatch')
+                return;
+            const { tool } = event;
+            if (!transport.pageResult || !tool.operationId || signal?.aborted)
+                return;
+            const key = JSON.stringify([tool.operationId, tool.grantId]);
+            if (dispatched.has(key))
+                return;
+            dispatched.add(key);
+            const callback = tools && Object.hasOwn(tools, tool.name) ? tools[tool.name] : undefined;
+            const reference = {
+                callId: tool.callId,
+                operationId: tool.operationId,
+                grantId: tool.grantId,
+            };
+            void Promise.resolve()
+                .then(async () => {
+                if (signal?.aborted)
+                    return;
+                const page = callback
+                    ? await Promise.resolve()
+                        .then(() => callback(tool.arguments, reference))
+                        .catch(() => ({ unanswered: true }))
+                    : { unanswered: true };
+                await transport.pageResult?.({ ...reference, page }, signal);
+            })
+                .catch((error) => {
+                if (!signal?.aborted)
+                    onEvent({ type: 'error', errorKind: errorKind(error), error: publicError(error) });
+            });
+        };
+    };
+    // why: A chat's stream also carries the conversation's ref, which no page tool reads.
+    const chatSink = (onLine, signal) => {
+        const events = sink(onLine, signal);
+        return (line) => (line.type === 'conversation' ? onLine(line) : events(line));
+    };
+    if ('call' in transport) {
+        const host = {
+            ...transport,
+            describe: transport.describe.bind(transport),
+            invoke: (request, onEvent, signal) => transport.invoke(request, sink(onEvent, signal), signal),
+            call: (request, onEvent, signal) => transport.call(request, sink(onEvent, signal), signal),
+        };
+        return host;
+    }
+    const chat = {
+        ...transport,
+        describe: transport.describe.bind(transport),
+        invoke: (request, onLine, signal) => transport.invoke(request, chatSink(onLine, signal), signal),
+        turn: (request, onLine, signal) => transport.turn(request, chatSink(onLine, signal), signal),
+        steer: transport.steer.bind(transport),
+        conversation: transport.conversation.bind(transport),
+        rewind: transport.rewind.bind(transport),
+    };
+    return chat;
+}

package/client/run-commit.d.ts

@@ -1,59 +1,32 @@
-import type { TheoremError, TurnBlob, TurnEvent } from '@theoremjs/agents';
-import { type ComposerProfileInterface, type InterfaceTurnSession, type TranscriptBlock, type UserTurnHistoryMedia } from '@theoremjs/agents/interface';
-import { type TurnFailure } from './failure.ts';
-import type { TheoremTransport, TurnEventSink } from './transport.ts';
-/** The turn is over: every event it streamed, gate resumes included, enters history once. */
-export declare function commitCompletedTurn(session: InterfaceTurnSession, events: TurnEvent[], media?: UserTurnHistoryMedia): InterfaceTurnSession;
-export declare function toTurnMedia(encodedAttachments?: TurnBlob[], encodedVoice?: TurnBlob[]): UserTurnHistoryMedia;
+import type { TheoremError, TurnEvent } from '@theoremjs/agents';
+import { type ComposerProfileInterface, type InterfaceTurnSession, type TranscriptBlock } from '@theoremjs/agents/interface';
+import type { ChatLineSink, ConversationLine } from './transport.ts';
+/**
+ * The session once a reply's events are in: a reply that waits on a gate
+ * keeps its events beside the transcript until the gate settles; any other is over.
+ */
+export declare function sessionAfter(session: InterfaceTurnSession, events: readonly TurnEvent[]): InterfaceTurnSession;
 /** Where a run shows itself as it streams: the reply so far, and each line the stream left out. */
 export type StreamView = {
     blocks(blocks: TranscriptBlock[]): void;
     /** A `malformed` line: left out, and the reply goes on. */
     skipped(error: TheoremError): void;
 };
-export declare function continueAfterTool(args: {
-    iface: ComposerProfileInterface;
-    transport: TheoremTransport;
-    session: InterfaceTurnSession;
-    view: StreamView;
-    seedEvents: TurnEvent[];
-}): Promise<{
-    ok: true;
-    session: InterfaceTurnSession;
-    assistantBlocks: TranscriptBlock[];
-} | TurnFailure>;
-/** A turn that failed partway, committed as far as it got. */
-export declare function failTurnStream(args: {
-    session: InterfaceTurnSession;
-    events: TurnEvent[];
-    media: UserTurnHistoryMedia;
-    failure: TurnFailure;
-}): TurnFailure;
 /**
- * An answer to `callId`'s gate that failed. Once the call settled, the reply
- * commits as far as it got, or waits on its next gate; before, the reply waits
- * on the gate as it did (the host puts the call back), and the answer can go again.
+ * Streams into `events`, which the caller owns, so a stream that fails still
+ * leaves what it delivered. A `conversation` line goes to `onConversation`. An
+ * `unsupported` line is the host's to read on its own transport, and a
+ * `malformed` one goes to `view.skipped`: neither enters the reply.
  */
-export declare function failGateAnswer(args: {
-    /** The paused session the answer went out from. */
-    session: InterfaceTurnSession;
-    callId: string;
-    /** The paused reply's events, then the answer's as far as they came. */
-    events: TurnEvent[];
-    failure: TurnFailure;
-}): TurnFailure;
-export declare function finalizeTurnStream(args: {
-    session: InterfaceTurnSession;
-    events: TurnEvent[];
-    media: UserTurnHistoryMedia;
-}): InterfaceTurnSession;
 export declare function streamFoldedTurn(args: {
     iface: ComposerProfileInterface;
     view: StreamView;
     /** Seeded by the caller, and filled as the stream delivers. */
     events: TurnEvent[];
-    stream: (onEvent: TurnEventSink) => Promise<void>;
-}): Promise<TurnEvent[]>;
+    /** The page adopts each ref from its transport; a run reads them only to know its message posted. */
+    onConversation?(line: ConversationLine): void;
+    stream: (onLine: ChatLineSink) => Promise<void>;
+}): Promise<void>;
 /** `blocks` with its last `turn-done` carrying the reply's work. */
 export declare function stampWorked(blocks: TranscriptBlock[], worked: {
     workedMs: number;

package/client/run-commit.js

@@ -1,17 +1,16 @@
-import { appendAssistantEventsToHistory, appendUserDraftToHistory, applyTurnEventsToSession, gatedToolFromEvents, settlesToolCall, } from '@theoremjs/agents/interface';
-import { turnFailure } from "./failure.js";
-import { buildTurnRequest, foldAssistantTurn, turnInputFromSession } from "./turn-client.js";
-/** The turn's history before its reply: a turn not yet started adds the user's message. */
-function turnBaseHistory(session, media) {
-    return session.pendingUserDraft
-        ? appendUserDraftToHistory(session.history, session.pendingUserDraft, media)
-        : session.history;
-}
-/** The turn is over: every event it streamed, gate resumes included, enters history once. */
-export function commitCompletedTurn(session, events, media = {}) {
+import { applyTurnEventsToSession, gatedToolFromEvents, } from '@theoremjs/agents/interface';
+import { foldAssistantTurn } from "./turn-client.js";
+/**
+ * The session once a reply's events are in: a reply that waits on a gate
+ * keeps its events beside the transcript until the gate settles; any other is over.
+ */
+export function sessionAfter(session, events) {
+    const applied = applyTurnEventsToSession(session, events);
+    const gatedTool = gatedToolFromEvents(events);
+    if (gatedTool)
+        return { ...applied, gatedTool, assistantEvents: [...events] };
     return {
-        ...applyTurnEventsToSession(session, events),
-        history: appendAssistantEventsToHistory(turnBaseHistory(session, media), events),
+        ...applied,
         gatedTool: null,
         assistantEvents: [],
         pendingUserDraft: null,
@@ -19,101 +18,27 @@ export function commitCompletedTurn(session, events, media = {}) {
         promotedToolIds: [],
     };
 }
-/**
- * The turn waits at a gate. History stops at the user's message and the events
- * wait in `assistantEvents`, so the gated step enters history whole once it settles.
- */
-function pauseTurn(session, events, media = {}) {
-    return {
-        ...applyTurnEventsToSession(session, events),
-        history: turnBaseHistory(session, media),
-        gatedTool: gatedToolFromEvents(events),
-        assistantEvents: [...events],
-        pendingUserDraft: null,
-    };
-}
-export function toTurnMedia(encodedAttachments, encodedVoice) {
-    return {
-        ...(encodedAttachments?.length ? { attachments: encodedAttachments } : {}),
-        ...(encodedVoice?.length ? { voice: encodedVoice } : {}),
-    };
-}
-/**
- * A failed turn with the conversation it leaves: the user's message and what the
- * reply got through (its text and the tool calls that settled), so the next turn
- * picks up from there. A stopped reply leaves the transcript, so only the message stays.
- */
-function withFailedTurnSession(failure, commit, events, seedEvents = []) {
-    return { ...failure, session: commit(failure.aborted ? seedEvents : events) };
-}
 /**
  * Streams into `events`, which the caller owns, so a stream that fails still
- * leaves what it delivered. An `unsupported` line is the host's to read on its
- * own transport, and a `malformed` one goes to `view.skipped`: neither enters
- * the turn, its history or its transcript.
+ * leaves what it delivered. A `conversation` line goes to `onConversation`. An
+ * `unsupported` line is the host's to read on its own transport, and a
+ * `malformed` one goes to `view.skipped`: neither enters the reply.
  */
-async function streamFoldedEvents(stream, view, iface, events) {
-    await stream((event) => {
-        if (event.type === 'unsupported')
+export function streamFoldedTurn(args) {
+    return args.stream((line) => {
+        if (line.type === 'conversation') {
+            args.onConversation?.(line);
+            return;
+        }
+        if (line.type === 'unsupported')
             return;
-        if (event.type === 'malformed') {
-            view.skipped(event.error);
+        if (line.type === 'malformed') {
+            args.view.skipped(line.error);
             return;
         }
-        events.push(event);
-        view.blocks(foldAssistantTurn(iface, events));
+        args.events.push(line);
+        args.view.blocks(foldAssistantTurn(args.iface, args.events));
     });
-    return events;
-}
-export async function continueAfterTool(args) {
-    const events = [...args.seedEvents];
-    // The model reads the turn so far: the settled gate and everything before it.
-    const sent = {
-        ...args.session,
-        history: appendAssistantEventsToHistory(args.session.history, args.seedEvents),
-    };
-    try {
-        await streamFoldedEvents((onEvent) => args.transport.turn(buildTurnRequest(args.iface, sent, turnInputFromSession(sent)), onEvent), args.view, args.iface, events);
-        if (gatedToolFromEvents(events)) {
-            return {
-                ok: true,
-                session: pauseTurn(args.session, events),
-                assistantBlocks: foldAssistantTurn(args.iface, events),
-            };
-        }
-        return {
-            ok: true,
-            session: commitCompletedTurn(args.session, events),
-            assistantBlocks: foldAssistantTurn(args.iface, events),
-        };
-    }
-    catch (err) {
-        return withFailedTurnSession(turnFailure(err, args.iface.lexicon), (kept) => commitCompletedTurn(args.session, kept), events, args.seedEvents);
-    }
-}
-/** A turn that failed partway, committed as far as it got. */
-export function failTurnStream(args) {
-    return withFailedTurnSession(args.failure, (kept) => commitCompletedTurn(args.session, kept, args.media), args.events);
-}
-/**
- * An answer to `callId`'s gate that failed. Once the call settled, the reply
- * commits as far as it got, or waits on its next gate; before, the reply waits
- * on the gate as it did (the host puts the call back), and the answer can go again.
- */
-export function failGateAnswer(args) {
-    const answered = args.events.slice(args.session.assistantEvents.length);
-    if (!answered.some((event) => settlesToolCall(event, args.callId)))
-        return args.failure;
-    return { ...args.failure, session: finalizeTurnStream({ session: args.session, events: args.events, media: {} }) };
-}
-export function finalizeTurnStream(args) {
-    if (gatedToolFromEvents(args.events)) {
-        return pauseTurn(args.session, args.events, args.media);
-    }
-    return commitCompletedTurn(args.session, args.events, args.media);
-}
-export function streamFoldedTurn(args) {
-    return streamFoldedEvents(args.stream, args.view, args.iface, args.events);
 }
 /** `blocks` with its last `turn-done` carrying the reply's work. */
 export function stampWorked(blocks, worked) {

package/client/run-session.d.ts

@@ -1,39 +1,56 @@
+import { type TurnEvent } from '@theoremjs/agents';
 import { type ComposerProfileInterface, type InterfaceTurnSession, type TranscriptBlock, type UserTurnDraft } from '@theoremjs/agents/interface';
 import { type TurnFailure } from './failure.ts';
 import { type StreamView } from './run-commit.ts';
-import type { TheoremTransport } from './transport.ts';
 import { type ToolGateResolution } from './tool-resume.ts';
+import { type TheoremTransport } from './transport.ts';
+import { type RunScope } from './turn-client.ts';
 export type { TurnFailure } from './failure.ts';
 export type { StreamView } from './run-commit.ts';
-export type StreamTurnSuccess = {
-    ok: true;
+/**
+ * Whether the host keeps this chat's conversation. A stateless profile keeps
+ * none: the page holds its transcript, and nothing goes on from a ref.
+ */
+export declare function keepsConversation(iface: ComposerProfileInterface): boolean;
+/**
+ * What one run left. A host that keeps the conversation is the truth for the
+ * rest: the page draws it again from the last ref the stream carried. A
+ * stateless chat keeps the reply as the run streamed it.
+ */
+export type RunOutcome = {
+    /** The session the run went out from, with any permission the answer granted. */
     session: InterfaceTurnSession;
-    userBlocks: TranscriptBlock[];
-    assistantBlocks: TranscriptBlock[];
+    /** The reply's events: a gate's answer starts from the paused reply's. */
+    events: TurnEvent[];
+    /** The message reached the conversation: the host's when it keeps one (the ref marked `posted`), else the page's. */
+    posted: boolean;
+    failure?: TurnFailure;
 };
 export type StreamInterfaceTurnBaseArgs = {
     iface: ComposerProfileInterface;
     transport: TheoremTransport;
     session: InterfaceTurnSession;
+    scope: RunScope;
     view: StreamView;
     /**
-     * Fires once the message posts, before its reply streams, with the blocks
-     * the transcript gains: a walked-away reply's settled blocks, then the
-     * message's own (with media preview data).
+     * Fires once the message posts, with the blocks the transcript gains: a
+     * walked-away reply's settled blocks, then the message's own (with media
+     * preview data). Walking away, it posts once the host has it.
      */
-    onUserBlocks?: (blocks: TranscriptBlock[]) => void;
+    onUserBlocks: (blocks: TranscriptBlock[]) => void;
     signal?: AbortSignal;
-    turnId?: string;
     /**
      * Send while the reply waits on gates: the message walks away from every
      * waiting call in its own request, and the host settles each one cancelled
-     * ahead of the reply. `workedMs` is the paused reply's work so far, which
-     * its settled blocks keep. Without it, a waiting session refuses the send
-     * (`session.gate_pending`).
+     * ahead of the reply. Without it, or in a chat the host keeps no
+     * conversation for, a waiting session refuses the send (`session.gate_pending`).
+     */
+    walkAway?: boolean;
+    /**
+     * The transcript before this message. Sent once, only when the host answers that it can no
+     * longer open the conversation, so a host that restores from it (the studio) goes on.
      */
-    walkAway?: {
-        workedMs: number;
-    };
+    transcript?: readonly TranscriptBlock[];
 };
 export type StreamInterfaceTurnArgs = StreamInterfaceTurnBaseArgs & {
     text: string;
@@ -43,38 +60,20 @@ export type StreamInterfaceTurnArgs = StreamInterfaceTurnBaseArgs & {
 export type StreamInterfaceDraftTurnArgs = StreamInterfaceTurnBaseArgs & {
     draft: UserTurnDraft;
 };
-export declare function streamInterfaceTurn(args: StreamInterfaceTurnArgs): Promise<StreamTurnSuccess | TurnFailure>;
+export declare function streamInterfaceTurn(args: StreamInterfaceTurnArgs): Promise<RunOutcome>;
 /** Send a turn from an already-encoded pending draft (queue drain / send now). */
-export declare function streamInterfaceDraftTurn(args: StreamInterfaceDraftTurnArgs): Promise<StreamTurnSuccess | TurnFailure>;
+export declare function streamInterfaceDraftTurn(args: StreamInterfaceDraftTurnArgs): Promise<RunOutcome>;
 /**
  * Send the user's answer to the gate the session waits on. The host settles
- * the call either way (an approval runs it; a refusal records it declined),
- * so the model and the trace read what the user chose.
+ * the call either way (an approval runs it; a refusal records it declined), so
+ * the model and the trace read what the user chose. A host that keeps the
+ * conversation goes on with the reply in the same stream once no call waits.
  */
 export declare function resumeInterfaceTool(args: {
     iface: ComposerProfileInterface;
     transport: TheoremTransport;
     session: InterfaceTurnSession;
+    scope: RunScope;
     resolution: ToolGateResolution;
     view: StreamView;
-}): Promise<{
-    ok: true;
-    session: InterfaceTurnSession;
-    assistantBlocks: TranscriptBlock[];
-} | TurnFailure>;
-export declare function applyTurnResultToTranscript(args: {
-    blocks: TranscriptBlock[];
-    streamBlocks: TranscriptBlock[];
-    session: InterfaceTurnSession;
-    userBlocks?: TranscriptBlock[];
-    assistantBlocks: TranscriptBlock[];
-    /** The reply's work so far, stamped on its latest `turn-done` so the time stays with the blocks. */
-    worked?: {
-        workedMs: number;
-        endedAt: number;
-    };
-}): {
-    blocks: TranscriptBlock[];
-    streamBlocks: TranscriptBlock[];
-    session: InterfaceTurnSession;
-};
+}): Promise<RunOutcome>;