@theoremjs/react 0.0.0-stage → 0.3.1

package/server/conversation.d.ts

@@ -0,0 +1,193 @@
+/**
+ * One reply, run against the conversation its host stores: the history goes
+ * to the model from the store, never from the browser, and what the reply
+ * leaves (its transcript, its history, a paused reply) is written back.
+ *
+ * Every host runs replies through here: `createTheoremHandler` with the
+ * kernel's `runTurn`, the studio with its own scope. Each run streams its
+ * events, then one `conversation` line with the ref the store issued, then
+ * the run's error when it failed.
+ *
+ * The conversation owns the transcript, the history, and the paused reply's
+ * events. Which paused calls may run, and with what input, stays the host's
+ * session store's: a call is answered there first, and its events settle it here.
+ *
+ * @module
+ */
+import { type GateReference, type LabelOverrides, type Profile, type ProviderCheckpoint, TheoremError, type TurnEvent, type TurnHistoryMessage, type TurnInput } from '@theoremjs/agents';
+import { type ClientTurnOptions } from '@theoremjs/agents/host';
+import { type ComposerProfileInterface, streamThoughtsEnabled, type TranscriptBlock, type UserTurnDraft, type UserTurnHistoryMedia } from '@theoremjs/agents/interface';
+import type { ConversationLine, ConversationView, TheoremTurnInput } from '../client/transport.ts';
+import { type StoredConversation, type TheoremConversationStore } from './conversation-store.ts';
+/** One walked-away call: its id, and the run that settles it (`invokeTool` with the abandoned resume). */
+export type WalkedAwayCall = {
+    callId: string;
+    events: AsyncIterable<TurnEvent>;
+};
+/** A walked-away call as the session issued it: the operation names the one call, since a model reuses call ids. */
+export type IssuedWalkAway = WalkedAwayCall & GateReference;
+/** A turn's failure, as a run ends on it. */
+export type ErrorEvent = Extract<TurnEvent, {
+    type: 'error';
+}>;
+/** What a run needs from the host that runs it. */
+export type ConversationHost = {
+    sessionId: string;
+    store: TheoremConversationStore;
+    /** Whether the profile shows the model's thoughts (`streamThoughtsEnabled`). */
+    showThoughts: boolean;
+    /** An event as the host's reader may have it (`forClient`). */
+    forReader(event: TurnEvent): TurnEvent;
+    /** A failure as the host's reader reads it: the profile's wording, by `forClient`'s rule. */
+    failureText(failure: ErrorEvent): string;
+};
+/**
+ * The conversation host for a profile as `forClient` shows it to `clientEvents`:
+ * its thoughts as its outputs allow, its failures in its own wording.
+ */
+export declare function readerConversationHost(args: {
+    sessionId: string;
+    store: TheoremConversationStore;
+    profile: {
+        outputs?: Parameters<typeof streamThoughtsEnabled>[0];
+        labels?: LabelOverrides;
+    };
+    clientEvents: ClientTurnOptions | undefined;
+}): ConversationHost;
+/** A conversation read for a request: its ref and revision, or neither for a new one. */
+export type OpenedConversation = {
+    ref: string | null;
+    revision: string | null;
+    conversation: StoredConversation;
+    /** What the guardrails decided reading a restored transcript, for the reply to stream first. */
+    events?: TurnEvent[];
+};
+/**
+ * What a request opens a conversation for, checked as it opens, before the host starts any run:
+ * - `read`: to draw it (`conversationView`).
+ * - `message`: to post a message (`messageReply`). A reply that waits on gates must be walked
+ *   away from: `abandon` names exactly the calls it waits on.
+ * - `answer`: to answer `call`, one the reply waits on (`answerReply`).
+ * - `rewind`: to cut it after transcript block `at`, which it must hold; -1 empties it
+ *   (`rewindConversation`).
+ */
+export type ConversationUse = {
+    kind: 'read';
+} | {
+    kind: 'message';
+    abandon?: readonly GateReference[];
+} | {
+    kind: 'answer';
+    call: GateReference;
+} | {
+    kind: 'rewind';
+    at: number;
+};
+/**
+ * The conversation under `ref`, or a new one when the browser has none, refused when it does not
+ * allow `use`.
+ */
+export declare function openConversation(host: ConversationHost, ref: string | undefined, use: ConversationUse, restore?: ConversationRestore): Promise<OpenedConversation>;
+/**
+ * The page's own transcript, for a conversation the host can no longer open (its key changed, or
+ * its store forgot it): the message goes on from it rather than failing. The host's copy is the
+ * truth while it opens; this is read only when it does not.
+ */
+export type ConversationRestore = {
+    profile: Profile;
+    blocks: readonly TranscriptBlock[];
+};
+/**
+ * Starts a conversation from blocks the host wrote, not ran: a chat that opens on an exchange
+ * already under way. The model reads them as history on the next turn, read first by the
+ * profile's guardrails at the `history` boundary, as every turn's history is. A match set to
+ * `block` refuses them, and nothing is stored. Returns the new conversation's ref, its view for
+ * the chat's `conversationView`, and the guardrail events for what matched.
+ */
+export declare function startConversation(host: Pick<ConversationHost, 'sessionId' | 'store'>, profile: Profile, blocks: readonly TranscriptBlock[]): Promise<{
+    ref: string;
+    view: ConversationView;
+    events: TurnEvent[];
+}>;
+/** The conversation as the browser draws it. */
+export declare function conversationView(host: ConversationHost, conversation: StoredConversation): ConversationView;
+/** One model run of a reply: the kernel's turn input, the checkpoint it continues, and the generation. */
+export type ReplyTurn = {
+    input: TurnInput;
+    providerState?: ProviderCheckpoint;
+    model?: string;
+    effort?: string;
+};
+/** What a reply's model run takes from the host. */
+export type ReplyRunner = {
+    /** The reply's events for one run (`runTurn` with the host's own options). */
+    run(turn: ReplyTurn): AsyncIterable<TurnEvent>;
+    /**
+     * Compacts history the profile says is due for it after a reply
+     * (`done.compaction.needed`): the compacted history, or undefined to keep it.
+     */
+    compact(history: TurnHistoryMessage[], tokens: number, model: string | undefined): Promise<TurnHistoryMessage[] | undefined>;
+    model?: string;
+    effort?: string;
+    signal: AbortSignal;
+};
+/** A line of a reply's stream: an event, or the ref of what the store wrote. */
+export type ReplyLine = TurnEvent | ConversationLine;
+/** The person's new message, as the host checked it: its blocks, its media, and the kernel's input. */
+export type PostedMessage = {
+    draft: UserTurnDraft;
+    /** The message's blocks (`prepareUserTurn`), with their media inline. */
+    blocks: TranscriptBlock[];
+    media: UserTurnHistoryMedia;
+    /** The kernel input without history: the message's text as the transcript shows it, its media, slots, and context. */
+    input: TurnInput;
+};
+/**
+ * The person's message as the profile accepts it: refused when its files break the profile's
+ * limits. `server` is the host's own context for the run (the handler's `context` option).
+ */
+export declare function postedMessage(iface: ComposerProfileInterface, input: TheoremTurnInput, server?: unknown): PostedMessage;
+/**
+ * The person sends a message. A reply that waits on gates is walked away
+ * from first: each call settles cancelled and the paused reply commits; then
+ * the message posts and its reply runs.
+ */
+export declare function messageReply(args: {
+    host: ConversationHost;
+    opened: OpenedConversation;
+    message: PostedMessage;
+    /** The paused reply's calls, each with the run that settles it: exactly the calls it waits on. */
+    walkAway?: readonly IssuedWalkAway[];
+    runner: ReplyRunner;
+}): AsyncGenerator<ReplyLine>;
+/**
+ * The person answers one call the reply waits on. `settling` streams the
+ * call's events; once no call waits, the reply goes on in the same stream.
+ */
+export declare function answerReply(args: {
+    host: ConversationHost;
+    opened: OpenedConversation;
+    /** The call answered, as the session issued it. */
+    call: GateReference;
+    settling: AsyncIterable<TurnEvent>;
+    runner: ReplyRunner;
+}): AsyncGenerator<ReplyLine>;
+/**
+ * The conversation cut after transcript block `at` (-1 empties it): the
+ * history is rebuilt from what is kept, and the model's checkpoint and meters
+ * start over. A paused reply is walked away from first, and commits before the cut.
+ */
+export declare function rewindConversation(args: {
+    host: ConversationHost;
+    opened: OpenedConversation;
+    at: number;
+    walkAway?: readonly IssuedWalkAway[];
+}): Promise<OpenedConversation>;
+/** A paused call's operation: every call a session issued carries one. */
+export declare function requiredOperationId(call: {
+    operationId?: string;
+}): string;
+/** The calls a paused reply waits on: the ones a message or a rewind walks away from. */
+export declare function waitingCalls(conversation: StoredConversation): GateReference[];
+/** Refuses what only a kept conversation answers, for a profile that keeps none. */
+export declare function statelessRefusal(what: string): TheoremError;