@theoremjs/web 0.0.0-stage → 0.3.4-next.375.ga2d1878

package/client/chat.d.ts

@@ -0,0 +1,144 @@
+import { type AttachmentValidationIssue, type ComposerMenuAction, type ComposerPendingMessage, type ComposerProfileInterface, type ComposerRunPhase, type InterfaceTurnSession, type TranscriptBlock } from '@theoremjs/agents/interface';
+import { type ClientFailure } from './failure.ts';
+import { type PageTools } from './live/live-page-tool.ts';
+import type { AnsweringGate, ToolDecisionAction } from './tool-resume.ts';
+import type { ConversationView, TheoremTransport, TurnEventSink } from './transport.ts';
+export type ChatOptions = {
+    transport: TheoremTransport;
+    /** The profile's composer interface, as `transport.describe()` returns it. `null` while it loads. */
+    iface: ComposerProfileInterface | null;
+    /**
+     * The ref of a conversation to resume, as `onConversationChange` reported it. Read once, when
+     * the chat is created: the chat draws the conversation as the host keeps it. A stateless profile
+     * keeps no conversation, so it has no ref.
+     */
+    conversation?: string;
+    /**
+     * The conversation under `conversation` as the host showed it with the ref, as
+     * `startConversation` returns it. Read once, when the chat is created: the chat draws it at
+     * once, and does not read it from the host again.
+     */
+    conversationView?: ConversationView;
+    /** The text the composer starts with. Read once, when the chat is created. */
+    initialText?: string;
+    /**
+     * Each new ref the host issues for the conversation: once the message posts, and again as the
+     * reply's runs are saved. Keep the latest to resume the chat later.
+     */
+    onConversationChange?: (ref: string) => void;
+    /**
+     * The value chosen for each of the profile's `inputs.slots`. Sent with every turn. A slot you
+     * name here is fixed to that value; one you leave out is chosen with `pickSlot`, starting at
+     * its first allowed value.
+     */
+    slots?: Record<string, string>;
+    /** Told each time the visitor picks a slot, with every slot's value. */
+    onSlotsChange?: (slots: Record<string, string>) => void;
+    /** What the page wants the agent to know: any JSON. The latest value goes with every turn. */
+    context?: unknown;
+    /** The page's tools, by name: each answers a tool the profile declares with `answeredBy: 'page'`. */
+    pageTools?: PageTools;
+    /**
+     * Every event of every turn, as it arrives and before the transcript takes it: the ones the
+     * transcript shows, and the ones it does not (a stage, a session, a guardrail decision).
+     */
+    onTurnEvent?: TurnEventSink;
+};
+/**
+ * How far the latest message has got: posted (`sending`), taken by the server
+ * (`sent`), reached the model (`delivered`), answered (`read`).
+ */
+export type MessageDelivery = 'sending' | 'sent' | 'delivered' | 'read';
+/** The slots the profile declares, and the value of each: the page's, else the picked one, else the first allowed. */
+export type ChatSlots = {
+    declared: Record<string, string[]>;
+    values: Record<string, string>;
+};
+/** Everything a chat shows. A new object on each change, the same one between changes. */
+export type ChatState = {
+    iface: ComposerProfileInterface | null;
+    /** The transcript. */
+    blocks: TranscriptBlock[];
+    /** The reply as it streams, or the reply that waits on a gate. */
+    streamBlocks: TranscriptBlock[];
+    chatStarted: boolean;
+    draftText: string;
+    pendingFiles: File[];
+    pendingVoice: File[];
+    /** Steered, queued, and stashed messages. */
+    pendingMessages: ComposerPendingMessage[];
+    issues: AttachmentValidationIssue[];
+    /** The failure the composer shows. */
+    failure: ClientFailure | null;
+    /** The answer on its way to a gate, shown on it until the answer settles or fails. */
+    answering: AnsweringGate | null;
+    phase: ComposerRunPhase;
+    session: InterfaceTurnSession;
+    /** The latest message's delivery; `null` before the first and once its turn failed. */
+    delivery: MessageDelivery | null;
+    streaming: boolean;
+    /** `undefined` when the profile declares no slots. */
+    slots: ChatSlots | undefined;
+};
+/** What `sendText` hands back: the blocks the turn added, its user message, and the reply. */
+export type SentTurn = {
+    blocks: TranscriptBlock[];
+};
+/** A new value, or a function of the current one. */
+export type ChatUpdate<T> = T | ((prev: T) => T);
+/**
+ * A chat with no UI framework: transcript, streaming, the composer's draft, the pending
+ * steer / queue / stash, gates, branching, and resuming a conversation. Read it with `getState`,
+ * follow it with `subscribe`, and act through its methods. Every method is bound, so pass them
+ * as callbacks as they are.
+ */
+export type ChatController = {
+    getState(): ChatState;
+    /** Called after each change, once per batch of changes. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** The latest options. `conversation`, `conversationView` and `initialText` are read only at creation. */
+    update(options: ChatOptions): void;
+    setDraftText(value: ChatUpdate<string>): void;
+    setPendingFiles(value: ChatUpdate<File[]>): void;
+    setPendingVoice(value: ChatUpdate<File[]>): void;
+    setPendingMessages(value: ChatUpdate<ComposerPendingMessage[]>): void;
+    setIssues(value: ChatUpdate<AttachmentValidationIssue[]>): void;
+    /** Sends the composer's draft when idle; queues it while a reply streams or waits on a gate. */
+    submit(): Promise<void>;
+    /** Stops the reply that is streaming. */
+    stop(): void;
+    /** Steers, queues, or stashes the composer's draft. A steer goes to the running turn. */
+    enqueue(kind: 'queue' | 'steer' | 'stash'): Promise<void>;
+    /**
+     * Sends a pending message, or the composer's draft, now: a streaming reply stops first, and a
+     * reply that waits on gates is walked away from.
+     */
+    sendNow(source?: ComposerPendingMessage): Promise<void>;
+    menuAction(action: ComposerMenuAction): void;
+    /** Puts a pending message back in the composer. What the composer holds is stashed first. */
+    restorePending(id: string): Promise<void>;
+    /** Moves a stashed message into the queue. At idle, the queue starts sending. */
+    queuePending(id: string): void;
+    /** Answers the gate the reply waits on. */
+    decide(action: ToolDecisionAction): Promise<void>;
+    /** The visitor signed in for the gated call, or gave its secret. */
+    authenticate(secret?: string): Promise<void>;
+    /**
+     * Cuts the conversation after transcript block `index`. A host that keeps the conversation
+     * cuts it (walking away from a reply that waits on gates); a stateless chat cuts its own.
+     */
+    branch(index: number): Promise<void>;
+    /** The model, and its effort (its default when left out), for the next turn. */
+    setGeneration(next: {
+        modelId: string;
+        effort?: string;
+    }): void;
+    pickSlot(name: string, value: string): void;
+    /**
+     * Sends `text` and optional files as the composer would, and resolves once the reply is done;
+     * `null` when it can't go now (a reply is streaming, or waits on a gate).
+     */
+    sendText(text: string, files?: readonly File[]): Promise<SentTurn | null>;
+};
+/** A chat for `options`. Framework-free: see `ChatController`. */
+export declare function createChatController(options: ChatOptions): ChatController;