@teaflask/assistant 0.6.0 → 0.7.0

package/dist/core/connection-epoch.d.ts

@@ -13,23 +13,86 @@ import { type ToolCallSchemas } from "./tool-schema-anchors.js";
 import { type AnchoredTurnFailReceipts } from "./turn-failed-anchors.js";
 import { type TurnUsage } from "./turn-usage-anchors.js";
 import { type UserTurnLedger } from "./user-turn-ledger.js";
-export interface MarkerAnchorsSnapshot {
+/**
+ * Lookup tables of extra facts the stream reports alongside the messages, keyed
+ * by message id, tool call id or memory id. transcriptRowsOf joins them into
+ * rows; read them directly only for custom rendering.
+ */
+export interface TranscriptMarkers {
+    /**
+     * Ids of messages where an interrupted response was retried. Calls left
+     * unfinished before that point in the same turn show as superseded; the
+     * values are internal and can be ignored.
+     */
     resumeAnchors: ReadonlyMap<string, unknown>;
+    /**
+     * Failure sentences for turns that failed outside any single tool call,
+     * keyed by the id of the message they are shown next to.
+     */
     turnFailedAnchors: ReadonlyMap<string, AnchoredTurnFailReceipts>;
+    /**
+     * Finished sub-agent results reported by a turn the assistant started on
+     * its own, keyed by the id of that turn's first message.
+     */
     subagentDeliveryAnchors: ReadonlyMap<string, DeliveredResult[]>;
+    /**
+     * Error text for tool calls that failed, keyed by tool call id; an empty
+     * string means the failure is described by the call's result text.
+     */
     toolErrorAnchors: ReadonlyMap<string, string>;
+    /**
+     * Ids of tool calls cancelled before they ran, for example because the user
+     * stopped the response.
+     */
     toolCancelAnchors: ReadonlySet<string>;
+    /**
+     * The tool's explanation for each call it declined, keyed by tool call id.
+     */
     toolRefusalAnchors: ReadonlyMap<string, string>;
+    /**
+     * Ids of tool calls whose output was too large and was replaced by a
+     * shortened stand-in.
+     */
     toolOffloadAnchors: ReadonlySet<string>;
+    /**
+     * Ids of tool calls the user was asked to approve or answer a question for.
+     * Treat a missing set as empty.
+     */
     toolDecisionAnchors?: ReadonlySet<string>;
+    /**
+     * Ids of tool calls whose approval the user declined. Treat a missing set
+     * as empty.
+     */
     toolDenialAnchors?: ReadonlySet<string>;
+    /**
+     * Server-supplied captions, status text, icons and tool view references,
+     * keyed by tool call id.
+     */
     toolCallDisplayAnchors: ReadonlyMap<string, ToolCallDisplay>;
+    /**
+     * The JSON Schemas declared for each call's arguments and result, keyed by
+     * tool call id; a call with no entry declared none.
+     */
     toolSchemaAnchors: ReadonlyMap<string, ToolCallSchemas>;
+    /**
+     * Server timestamps for each message and tool call, keyed by message id or
+     * tool call id; a missing entry means the timing is unknown.
+     */
     blockTimingAnchors: ReadonlyMap<string, BlockTiming>;
-    turnUsageAnchors: ReadonlyMap<string, TurnUsage>;
+    /**
+     * Every memory the assistant saved in this conversation, keyed by memory
+     * id, in the order saved.
+     */
     memoryProvenanceAnchors: ReadonlyMap<string, MemoryUpdated>;
+    /**
+     * For each saved memory id, the id of the assistant message it is shown
+     * under; a memory with no entry is shown under no message.
+     */
     memoryAttributionAnchors: ReadonlyMap<string, string>;
 }
+export interface MarkerAnchorsSnapshot extends TranscriptMarkers {
+    turnUsageAnchors: ReadonlyMap<string, TurnUsage>;
+}
 export declare function markerAnchorsOf(resume: StreamResumeStore): MarkerAnchorsSnapshot;
 export interface ConnectionEpochDeps {
     epochId: number;

package/dist/core/conversation-adoption.js

@@ -1,5 +1,6 @@
 import { clearStoredThread, readStoredThread, readStoredThreadFor, writeStoredThread, } from "../persistence/stored-thread.js";
 import { getAssistantThread, listAssistantThreads, } from "../transport/serving-api.js";
+import { noteThreadRead } from "./dispatch-poll.js";
 import { ServingApiError } from "../transport/serving-error.js";
 import { StreamResumeStore } from "../transport/stream-resume.js";
 import { ApprovalInbox, SERVING_APPROVAL_CAPABILITIES, } from "./approval-inbox.js";
@@ -134,6 +135,7 @@ function _finishAdoption(store, detail) {
     if (!_someTurnIsLive(detail.turns)) {
         store._stopping = false;
     }
+    noteThreadRead(store, detail.thread.id);
     publishStore(store);
 }
 function adoptCoworkerRequests(store, turns) {
@@ -177,6 +179,7 @@ export function adoptRefreshedDetail(store, detail) {
     if (!_someTurnIsLive(detail.turns)) {
         store._stopping = false;
     }
+    noteThreadRead(store, detail.thread.id);
     publishStore(store);
 }
 function _adoptWireModelPick(store, thread, { evenWhenDirty }) {

package/dist/core/conversation-contract.d.ts

@@ -1,4 +1,4 @@
-import type { ServedThinkingEffort } from "../contract/assistant-config.js";
+import type { ServedAttachmentPolicy, ServedThinkingEffort } from "../contract/assistant-config.js";
 import type { AssistantTelemetryEvent } from "../contract/telemetry.js";
 import type { ServingAssistantThread, ServingAssistantTurn, TurnAttachment } from "../contract/threads.js";
 import type { ServingReplayStreamAgent } from "../transport/replay-stream-agent.js";
@@ -18,34 +18,143 @@ export interface ActiveConversation {
     approvalInbox: ApprovalInbox;
     coworkerRequestTurns: readonly ServingAssistantTurn[];
 }
+/**
+ * State and controls for writing and sending messages in the open conversation,
+ * returned by useConversation() (inside <TeaflaskAssistantProvider>) and as
+ * AssistantConversation.composerContract.
+ */
 export interface ComposerContract {
+    /**
+     * True while a message is being sent or the assistant is replying; disable
+     * sending and offer a Stop button. False once the agent has stopped
+     * actively waiting on an unanswered approval or question (the card reads
+     * parked).
+     */
     busy: boolean;
+    /**
+     * True while a message is on its way to the server, before it is accepted.
+     * There is no reply to stop yet, so hide Stop during this window.
+     */
     pendingSend: boolean;
+    /**
+     * Sends a message (with the ids of already-uploaded attachments and their
+     * display details for the instant echo), starting a new conversation if
+     * none is open. Resolves true once the server accepts it, or false if it
+     * was refused (sendError explains why); it does not clear the draft, so
+     * clear and restore it yourself.
+     */
     sendMessage: (message: string, attachmentIds?: string[], optimisticAttachments?: TurnAttachment[]) => Promise<boolean>;
+    /**
+     * The message just sent, to show immediately until the transcript includes
+     * it; null otherwise. useTranscript().displayRows already includes it, so
+     * don't draw it again if you render those.
+     */
     pendingEcho: {
         messageId: string;
         text: string;
         attachments: TurnAttachment[];
     } | null;
+    /**
+     * True after a send or stop has gone through and before your input takes
+     * focus back. When it is true and busy is false, focus your input and call
+     * markComposerRefocusHandled.
+     */
     composerRefocusPending: boolean;
+    /**
+     * Call once you have handled composerRefocusPending, to reset it to false.
+     */
     markComposerRefocusHandled: () => void;
+    /**
+     * True from a Stop press until the reply has stopped (or the wait gives
+     * up); show a "Stopping" state and don't offer Stop again.
+     */
     stopping: boolean;
+    /**
+     * Stops the reply in progress. Does nothing when nothing is running, a send
+     * is still in flight, or a stop is already under way; if the stop fails,
+     * sendError says so.
+     */
     stopTurn: () => Promise<void>;
+    /**
+     * The model and reasoning effort the next reply will use, as chosen for
+     * this conversation. Null means the assistant's configured model and
+     * effort.
+     */
     modelPick: ComposerModelPick | null;
+    /**
+     * Chooses the model and effort for this conversation's replies. It goes out
+     * with the next message and is then saved on the conversation; starting a
+     * new conversation resets it.
+     */
     setModelPick: (pick: ComposerModelPick) => void;
+    /**
+     * The unsaved draft and staged attachments, as a separate observable so
+     * typing doesn't re-render everything else; read it with useCell. It
+     * survives reconnects and remounts, and is cleared when the visitor
+     * switches to or starts another conversation.
+     */
     composerInput: ReadonlyCell<ComposerInput>;
+    /**
+     * Replaces the draft text, with a value or an updater function like React's
+     * setState.
+     */
     setDraft: (next: string | ((current: string) => string)) => void;
+    /**
+     * Replaces the staged attachments, with a value or an updater function like
+     * React's setState.
+     */
     setAttachments: (next: readonly AttachmentDraft[] | ((current: readonly AttachmentDraft[]) => readonly AttachmentDraft[])) => void;
+    /**
+     * Uploads files and stages them on the draft: each appears in
+     * composerInput's attachments as uploading, then ready (carrying the id to
+     * pass to sendMessage) or failed with a sentence for the visitor. A file
+     * over its kind's size limit or past the per-message count never shows as
+     * uploading and appears as failed from the start, and if the assistant is
+     * configured without attachments, or its configuration could not be loaded,
+     * every file in the call fails that way. Resolves once every file has
+     * settled. A pick may wait for the assistant's configuration to load, and
+     * if the visitor switches or starts another conversation during that wait
+     * the pick is dropped rather than staged on the new one.
+     */
+    addFiles: (files: Iterable<File>) => Promise<void>;
+    /**
+     * Tells the assistant which of your inputs has keyboard focus (a name you
+     * choose for that surface), or null on blur. Used to put the caret back
+     * after an automatic reconnect remounts the input.
+     */
     noteComposerFocus: (owner: string | null) => void;
+    /**
+     * Call when your input mounts, with the same surface name; returns true
+     * (once) if that input had focus when a reconnect remounted it, meaning you
+     * should focus it again.
+     */
     takeComposerCaretReturn: (surface: string) => boolean;
 }
+/** The composer's unsaved input, as read from composerInput. */
 export interface ComposerInput {
+    /**
+     * An opaque token naming the conversation this input belongs to; it changes
+     * whenever the visitor switches or starts a conversation. Compare it before
+     * and after an awaited send so you only restore a refused draft into the
+     * conversation it was typed in.
+     */
     scope: string;
+    /** The text typed but not yet sent. */
     draft: string;
+    /** Files staged for the next message, in the order they were added. */
     attachments: readonly AttachmentDraft[];
 }
+/** A model and reasoning-effort choice for the conversation's replies. */
 export interface ComposerModelPick {
+    /**
+     * Id of one of the models the assistant offers, or null to keep the
+     * assistant's configured model.
+     */
     modelId: string | null;
+    /**
+     * How much reasoning the model spends per reply (low, medium, high, xhigh
+     * or max), or null for the assistant's configured setting.
+     */
     effort: ServedThinkingEffort | null;
 }
 export type { AttachmentDraft } from "./composer-policy.js";
@@ -74,6 +183,8 @@ export interface ConversationStoreDeps {
     onTelemetry: (event: AssistantTelemetryEvent) => void;
     onGateRefusal: (error: ServingApiError) => void;
     onTurnSettled: () => void;
+    attachmentPolicy: ReadonlyCell<ServedAttachmentPolicy | null>;
+    ensureAttachmentPolicy: () => Promise<ServedAttachmentPolicy | null>;
 }
 export interface ConnectionSnapshot {
     epochId: number;

package/dist/core/conversation-publish.js

@@ -76,6 +76,7 @@ export function composerSnapshotOf(store) {
         composerInput: store._composerInput,
         setDraft: store.setComposerDraft,
         setAttachments: store.setComposerAttachments,
+        addFiles: store.addComposerFiles,
         noteComposerFocus: store.noteComposerFocus,
         takeComposerCaretReturn: store.takeComposerCaretReturn,
     };

package/dist/core/conversation-store.d.ts

@@ -61,6 +61,7 @@ export declare class AssistantConversationStore {
     _modelPickDirty: boolean;
     readonly _composerInput: ObservableCell<ComposerInput>;
     _nextUnboundScope: number;
+    _composerInputResets: number;
     _composerFocusOwned: string | null;
     _composerCaretReturnPending: string | null;
     _tier: VisitorTier | null;
@@ -78,6 +79,7 @@ export declare class AssistantConversationStore {
     _deliveryProbeRearm: boolean;
     _idleRecheckTimer: ReturnType<typeof setInterval> | null;
     _idleRecheckInFlight: boolean;
+    _disarmDispatchPoll: (() => void) | null;
     _disposed: boolean;
     _epoch: ConnectionEpoch | null;
     _epochResume: StreamResumeStore | null;
@@ -102,6 +104,7 @@ export declare class AssistantConversationStore {
     noteComposerFocus: (owner: string | null) => void;
     takeComposerCaretReturn: (surface: string) => boolean;
     uploadAttachment: (file: File) => Promise<ServingAttachment>;
+    addComposerFiles: (files: Iterable<File>) => Promise<void>;
     mintAttachmentDownloadUrl: (attachmentId: string) => Promise<MintedDownloadUrl>;
     acquireTranscriptLease: (surface: string) => (() => void);
     submitApprovalDecision: (card: ApprovalCardModel, decision: ApprovalDecisionInput) => Promise<void>;

package/dist/core/conversation-store.js

@@ -1,6 +1,7 @@
 import { IDLE_ACTIVITY, } from "./activity.js";
 import { noteDispatchSettledFromStore, refreshConversationFromStore, } from "./conversation-refresh.js";
 import { mintAttachmentDownloadUrlFromStore, uploadAttachmentFromStore, } from "./attachment-uploads.js";
+import { addComposerFilesFromStore } from "./composer-attachments.js";
 import { handleUserMessageInjectedFromStore, markComposerRefocusHandledFromStore, sendMessageFromStore, stopTurnFromStore, } from "./conversation-send.js";
 import { noteComposerFocusFromStore, setComposerAttachmentsFromStore, setComposerDraftFromStore, setModelPickFromStore, takeComposerCaretReturnFromStore, } from "./composer-input-state.js";
 import { submitApprovalDecisionFromStore } from "./approval-decision.js";
@@ -12,6 +13,7 @@ import { SettleRefreshScheduler } from "./settle-refresh.js";
 import { handleStreamClosedQuietlyFromStore, handleStreamErrorFromStore, handleWorkflowRestartedFromStore, retryStreamFromStore, } from "./stream-trouble.js";
 import { acquireTranscriptLeaseFromStore } from "./transcript-lease.js";
 import { clearIdleRecheck, syncIdleRecheck } from "./idle-recheck.js";
+import { armDispatchPoll, disarmDispatchPoll } from "./dispatch-poll.js";
 import { ConsumedInterruptFold } from "./consumed-interrupts.js";
 import { composerSnapshotOf, conversationSnapshotOf, publishStore, } from "./conversation-publish.js";
 import { retireEpoch } from "./epoch-sync.js";
@@ -82,6 +84,7 @@ export class AssistantConversationStore {
         attachments: [],
     });
     _nextUnboundScope = 1;
+    _composerInputResets = 0;
     _composerFocusOwned = null;
     _composerCaretReturnPending = null;
     _tier = null;
@@ -103,6 +106,7 @@ export class AssistantConversationStore {
     _deliveryProbeRearm = false;
     _idleRecheckTimer = null;
     _idleRecheckInFlight = false;
+    _disarmDispatchPoll = null;
     _disposed = false;
     _epoch = null;
     _epochResume = null;
@@ -157,6 +161,7 @@ export class AssistantConversationStore {
         this.resumeStoredThread();
         loadHistoryOnceExpected(this);
         syncIdleRecheck(this);
+        armDispatchPoll(this);
     }
     setTier(tier) {
         if (this._tier === tier) {
@@ -172,6 +177,7 @@ export class AssistantConversationStore {
         this._settleScheduler.dispose();
         this._gapGate.dispose();
         clearIdleRecheck(this);
+        disarmDispatchPoll(this);
         retireEpoch(this);
     }
     resumeStoredThread = () => {
@@ -196,6 +202,7 @@ export class AssistantConversationStore {
     };
     takeComposerCaretReturn = (surface) => takeComposerCaretReturnFromStore(this, surface);
     uploadAttachment = async (file) => uploadAttachmentFromStore(this, file);
+    addComposerFiles = async (files) => addComposerFilesFromStore(this, files);
     mintAttachmentDownloadUrl = async (attachmentId) => mintAttachmentDownloadUrlFromStore(this, attachmentId);
     acquireTranscriptLease = (surface) => acquireTranscriptLeaseFromStore(this, surface);
     submitApprovalDecision = async (card, decision) => submitApprovalDecisionFromStore(this, card, decision);

package/dist/core/dispatch-poll.js

@@ -0,0 +1,81 @@
+import { demandInputOfMessages, dispatchDemandOf, dispatchJoinKeyOf, RESUME_SUBAGENT_TOOL_NAME, staleDeliveredOrdinalsKeyOf, } from "./subagent-ledger-join.js";
+import { DISPATCH_SUBAGENT_TOOL_NAME } from "./subagent-rows.js";
+import { EMPTY_THREAD_DISPATCHES, threadDispatchLedgerFor, } from "./thread-dispatch-ledger.js";
+export function armDispatchPoll(store) {
+    if (store._disarmDispatchPoll !== null) {
+        return;
+    }
+    const ledger = threadDispatchLedgerFor(store.deps.session);
+    ledger.setSettleListener(store, store.noteDispatchSettled);
+    ledger.setPauseListener(store, store.noteDispatchPaused);
+    let queued = false;
+    let lastTapKey = "";
+    const judge = () => {
+        queued = false;
+        if (store._disposed || store._disarmDispatchPoll === null) {
+            return;
+        }
+        lastTapKey = _judgeDemand(store, ledger, lastTapKey);
+    };
+    const schedule = () => {
+        if (queued) {
+            return;
+        }
+        queued = true;
+        queueMicrotask(judge);
+    };
+    const unsubscribes = [
+        store.messages.subscribe(schedule),
+        store.markerAnchors.subscribe(schedule),
+        store.connection.subscribe(schedule),
+        ledger.cell.subscribe(schedule),
+    ];
+    store._disarmDispatchPoll = () => {
+        for (const unsubscribe of unsubscribes) {
+            unsubscribe();
+        }
+        ledger.setDemand(store, null);
+        ledger.setSettleListener(store, null);
+        ledger.setPauseListener(store, null);
+    };
+    schedule();
+}
+export function disarmDispatchPoll(store) {
+    const disarm = store._disarmDispatchPoll;
+    if (disarm === null) {
+        return;
+    }
+    store._disarmDispatchPoll = null;
+    disarm();
+}
+export function noteThreadRead(store, threadId) {
+    threadDispatchLedgerFor(store.deps.session).noteThreadAnswered(threadId);
+}
+function _judgeDemand(store, ledger, lastTapKey) {
+    const threadId = store.connection.get()?.threadId ?? null;
+    const messages = store.messages.get();
+    if (threadId === null || !_delegates(messages)) {
+        ledger.setDemand(store, null);
+        return "";
+    }
+    const input = demandInputOfMessages(messages, store.markerAnchors.get());
+    const read = ledger.cell.get();
+    const map = read !== null && read.threadId === threadId
+        ? read.map
+        : EMPTY_THREAD_DISPATCHES;
+    ledger.setDemand(store, {
+        threadId,
+        ...dispatchDemandOf(input, map),
+        joinKey: dispatchJoinKeyOf(input),
+    });
+    const tapKey = staleDeliveredOrdinalsKeyOf(input, map);
+    if (tapKey !== "" && tapKey !== lastTapKey) {
+        void ledger.refresh(threadId);
+    }
+    return tapKey;
+}
+function _delegates(messages) {
+    return messages.some((message) => message.role === "assistant" &&
+        (message.toolCalls ?? []).some((call) => call.function.name === DISPATCH_SUBAGENT_TOOL_NAME ||
+            call.function.name === RESUME_SUBAGENT_TOOL_NAME));
+}

package/dist/core/elicitation-answers.js

@@ -14,6 +14,7 @@ async function _deliverQuestionSetReport(store, card, result, answered) {
     const epoch = store._epoch;
     const active = store._active;
     if (epoch === null || active === null) {
+        _stampAnswerNotSent(store, card);
         return;
     }
     const inbox = epoch.executionInbox;
@@ -57,6 +58,17 @@ async function _deliverQuestionSetReport(store, card, result, answered) {
         publishIfCurrent();
     }
 }
+function _stampAnswerNotSent(store, card) {
+    store._elicitationErrors.set(card.interruptId, ANSWER_NOT_SENT_SENTENCE);
+    const cards = store._elicitationsCell.get();
+    const next = cards.map((item) => item.interruptId === card.interruptId &&
+        item.errorSentence !== ANSWER_NOT_SENT_SENTENCE
+        ? { ...item, errorSentence: ANSWER_NOT_SENT_SENTENCE }
+        : item);
+    if (next.some((item, index) => item !== cards[index])) {
+        store._elicitationsCell.set(next);
+    }
+}
 function _turnNoLongerAwaitingToolResults(error) {
     return (error instanceof ServingApiError &&
         error.code === "ASSISTANT_TURN_NOT_AWAITING_TOOL_RESULTS");

package/dist/core/elicitation-cards.d.ts

@@ -10,8 +10,18 @@ interface ElicitationCardBase {
     status: ElicitationCardStatus;
     errorSentence: string | null;
 }
+/**
+ * A set of up to five questions the agent asked the visitor, answered together
+ * in one submission or dismissed together.
+ */
 export interface QuestionSetCardModel extends ElicitationCardBase {
+    /** The questions, in the order the visitor should see them. */
     questions: readonly QuestionModel[];
+    /**
+     * What this page submitted, either the answers or a cancellation. Null
+     * before it submits, and for sets answered elsewhere or earlier in the
+     * conversation, where the transcript's tool row shows the outcome.
+     */
     answered: AnsweredQuestions | null;
 }
 export type AnsweredQuestions = {
@@ -23,6 +33,10 @@ export type AnsweredQuestions = {
 } | {
     kind: "cancelled";
 };
+/**
+ * A request from the agent for the visitor to answer questions; currently
+ * always a question set.
+ */
 export type ElicitationCardModel = QuestionSetCardModel;
 export declare function elicitationCardsOf(entries: readonly ExecutionEntryModel[], errorSentences: ReadonlyMap<string, string>, questionAnswers?: ReadonlyMap<string, AnsweredQuestions>): ElicitationCardModel[];
 export declare function sameElicitationCards(a: readonly ElicitationCardModel[], b: readonly ElicitationCardModel[]): boolean;

package/dist/core/elicitation-pickers.d.ts

@@ -1,11 +1,27 @@
+/** One suggested answer to a question. */
 export interface QuestionOptionModel {
+    /**
+     * The suggestion as the visitor reads it; if they pick it, submit this
+     * exact text as their answer.
+     */
     text: string;
+    /** A one-line explanation of the suggestion, or null when there is none. */
     description: string | null;
 }
+/** One question in a question set. */
 export interface QuestionModel {
+    /**
+     * The question's id, unique within its set; use it as the id of its answer.
+     */
     id: string;
+    /** A short label for the question, a few words long. */
     heading: string;
+    /** The question, exactly as the visitor should read it. */
     prompt: string;
+    /**
+     * Suggested answers, up to eight; empty for an open question. Always let
+     * the visitor write their own answer as well.
+     */
     options: readonly QuestionOptionModel[];
 }
 export declare function askQuestionsActionOf(action: Record<string, unknown> | null): {

package/dist/core/memory-provenance-anchors.d.ts

@@ -1,7 +1,23 @@
 import type { AgentSubscriber } from "@ag-ui/client";
+/**
+ * A notice that the assistant saved a memory. It never contains the memory's
+ * content.
+ */
 export interface MemoryUpdated {
+    /**
+     * The saved memory's id; a repeated report of the same save carries the
+     * same id, so use it to de-duplicate.
+     */
     memoryId: string;
+    /**
+     * Who the memory is for: "org" is shared across all your users, "user" is
+     * private to the current user. Show any other value generically.
+     */
     scope: string;
+    /**
+     * A short sentence for the user saying a memory was saved, not the memory
+     * itself.
+     */
     summary: string;
 }
 export declare const EMPTY_MEMORY_PROVENANCE_ANCHORS: ReadonlyMap<string, MemoryUpdated>;

package/dist/core/observable-cell.d.ts

@@ -1,5 +1,17 @@
+/**
+ * An observable value from the assistant, readable without React (use useCell
+ * inside React).
+ */
 export interface ReadonlyCell<T> {
+    /**
+     * Returns the current value. The returned object only changes identity when
+     * the value changes, so you can compare by reference.
+     */
     get: () => T;
+    /**
+     * Calls the listener after every change and returns a function that
+     * unsubscribes it.
+     */
     subscribe: (listener: () => void) => () => void;
 }
 export declare class ObservableCell<T> implements ReadonlyCell<T> {

package/dist/core/pending-decision-gap.d.ts

@@ -9,8 +9,17 @@ export interface GapJudgeableTurn {
 interface InterruptHolder {
     interruptId: string;
 }
+/**
+ * The agent is waiting on requests that nothing on this page can show or
+ * answer, which usually means the conversation needs reloading.
+ */
 export interface PendingDecisionGap {
+    /** The id of the waiting turn. */
     turnId: string;
+    /**
+     * The ids of the waiting requests (approvals, questions or page actions)
+     * that have nothing on this page to answer them.
+     */
     missingInterruptIds: readonly string[];
 }
 export declare function pendingDecisionGapOf(turn: GapJudgeableTurn | null, approvalCards: readonly InterruptHolder[], elicitationCards: readonly InterruptHolder[], executionEntries: readonly InterruptHolder[], consumedInterruptIds?: ReadonlySet<string>): PendingDecisionGap | null;

package/dist/core/question-drafts.d.ts

@@ -4,29 +4,88 @@ type ActiveChoice = {
 } | {
     kind: "custom";
 } | null;
+/** The visitor's unsent answer to one question. */
 export interface QuestionAnswerDraft {
+    /**
+     * The selected answer, either { kind: "option", text } for a suggestion, {
+     * kind: "custom" } for the visitor's own text, or null when nothing is
+     * selected yet.
+     */
     active: ActiveChoice;
+    /**
+     * The visitor's own typed answer. Kept when they select a suggestion
+     * instead, so they can switch back.
+     */
     customText: string;
 }
+/** The visitor's unsent answers to one question set. */
 export interface QuestionSetDraft {
+    /** Index of the question the visitor is on, starting at 0. */
     cursor: number;
+    /**
+     * Unsent answers keyed by question id; questions the visitor hasn't touched
+     * are absent.
+     */
     answers: ReadonlyMap<string, QuestionAnswerDraft>;
 }
 export interface QuestionLike {
     id: string;
 }
 export declare const MAX_ANSWER_TEXT_CHARS = 1900;
+/**
+ * Holds the visitor's unsent answers to question sets, keyed by the card's
+ * interruptId then the question's id. Subscribe to it (for example with React's
+ * useSyncExternalStore and get) to re-render as answers change.
+ */
 export declare class QuestionDraftStore {
     private readonly drafts;
     private readonly listeners;
+    /**
+     * Returns the unsent answers for one question set, or an empty draft
+     * (cursor 0, no answers) if nothing has been entered. The same object is
+     * returned until that draft changes.
+     */
     get: (interruptId: string) => QuestionSetDraft;
+    /**
+     * Calls the listener after any draft changes and returns a function that
+     * unsubscribes it.
+     */
     subscribe: (listener: () => void) => (() => void);
+    /**
+     * True when the visitor has selected or typed anything for this question
+     * set; use it to confirm before discarding on cancel.
+     */
     hasContent(interruptId: string): boolean;
+    /**
+     * Selects the suggestion with this text as the answer to one question,
+     * keeping any text the visitor typed.
+     */
     selectOption(interruptId: string, questionId: string, text: string): void;
+    /**
+     * Selects the visitor's own typed answer for one question, without changing
+     * its text.
+     */
     selectCustom(interruptId: string, questionId: string): void;
+    /**
+     * Sets the visitor's own answer to one question and selects it. Control
+     * characters are removed, except that vertical tabs and form feeds become
+     * line breaks.
+     */
     setCustomText(interruptId: string, questionId: string, text: string): void;
+    /**
+     * Records which question the visitor is on (an index into the set's
+     * questions), so returning to the set shows the same question.
+     */
     setCursor(interruptId: string, cursor: number): void;
+    /**
+     * Discards the unsent answers for one question set. Answers are already
+     * cleared after a successful submit or cancel.
+     */
     clear(interruptId: string): void;
+    /**
+     * Discards the unsent answers for every question set. Already done when the
+     * visitor switches or starts a conversation.
+     */
     clearAll(): void;
     private updateAnswer;
     private notify;