@teaflask/assistant 0.6.0 → 0.7.1

package/dist/contract/telemetry.d.ts

@@ -1,7 +1,30 @@
+/**
+ * Why clicking approve or deny sent nothing. "no_active_thread" means no
+ * conversation was open; "card_missing" means the request was no longer shown;
+ * "already_submitting" is a repeat click while the first answer is sending;
+ * "not_actionable_answered" and "not_actionable_stale" mean the request had
+ * already been answered or was no longer open; "no_turn_id" means no turn could
+ * be found to answer.
+ */
 export type ApprovalSubmitDropReason = "no_active_thread" | "card_missing" | "already_submitting" | "not_actionable_answered" | "not_actionable_stale" | "no_turn_id";
 type ApprovalCardStatusKind = "actionable" | "submitting" | "answered" | "stale";
+/**
+ * Reported to onTelemetry as the user answers an approval, so you can spot
+ * answers that never reached the server.
+ */
 export interface ApprovalSubmitTelemetryEvent {
+    /**
+     * "approval_submit_attempted" when the user clicks approve or deny,
+     * "approval_submit_sent" when the answer is posted, and
+     * "approval_submit_dropped" when nothing was posted (see drop_reason).
+     */
     name: "approval_submit_attempted" | "approval_submit_sent" | "approval_submit_dropped";
+    /**
+     * The request's interrupt_id, the conversation's thread_id, whether it was
+     * approved and trusted, the request's on-screen status (actionable,
+     * submitting, answered or stale), whether its turn had parked, and the
+     * drop_reason for a dropped answer.
+     */
     properties: {
         interrupt_id: string;
         thread_id: string | null;
@@ -12,9 +35,27 @@ export interface ApprovalSubmitTelemetryEvent {
         drop_reason?: ApprovalSubmitDropReason;
     };
 }
+/**
+ * Where a stream connection failed. "network_rejected" means no response
+ * arrived (offline, DNS, CORS); "http_error" is a non-2xx response; "no_body"
+ * is a 2xx with no readable body; "mid_stream" means the connection dropped
+ * after events had arrived; "parse_or_validation" means an event could not be
+ * read; "client_abort" is a cancellation by the widget and is not reported.
+ */
 export type StreamFailureClass = "network_rejected" | "http_error" | "no_body" | "mid_stream" | "parse_or_validation" | "client_abort";
+/**
+ * Reported to onTelemetry when the conversation's live stream connection fails.
+ * Cancellations made by the widget itself are not reported.
+ */
 export interface StreamFailedTelemetryEvent {
+    /** Always "assistant_stream_failed". */
     name: "assistant_stream_failed";
+    /**
+     * Where the connection failed (failure_class), the HTTP status or null when
+     * no response arrived, the conversation's thread_id, and two stream
+     * positions, resume_cursor and last_committed_sse_id, that locate the
+     * failure in the conversation's event stream.
+     */
     properties: {
         failure_class: StreamFailureClass;
         status: number | null;
@@ -23,6 +64,10 @@ export interface StreamFailedTelemetryEvent {
         last_committed_sse_id: string | null;
     };
 }
+/**
+ * Any event passed to the provider's onTelemetry callback, for forwarding to
+ * your own analytics. None carry message text, tool arguments or prompts.
+ */
 export type AssistantTelemetryEvent = ApprovalSubmitTelemetryEvent | StreamFailedTelemetryEvent;
 export declare function streamFailureClassOf(error: Error, context: {
     sawBodyBytes: boolean;

package/dist/contract/threads.d.ts

@@ -1,3 +1,7 @@
-export type { CreateServingAttachmentUploadResponse as AttachmentUploadIntent, HighlightResult, NavigateResult, PrefillFormResult, ReadPageResult, ResolveServingTurnApprovalRequest as ResolveTurnApprovalRequest, ResolveServingTurnApprovalResponse as ResolveTurnApprovalResponse, ResolveServingTurnToolResultsRequest as ResolveTurnToolResultsRequest, ResolveServingTurnToolResultsResponse as ResolveTurnToolResultsResponse, SendServingAssistantMessageRequest as SendAssistantMessageRequest, SendServingAssistantMessageResponse as SendAssistantMessageResponse, ServingApprovalDelivery as ApprovalDelivery, ServingAssistantThreadDetailResponse as AssistantThreadDetailResponse, ServingAssistantThreadResponse as ServingAssistantThread, ServingAssistantTurnResponse as ServingAssistantTurn, ServingAttachmentResponse as ServingAttachment, ServingTurnApprovalDecision as TurnApprovalDecision, ServingTurnAttachmentResponse as TurnAttachment, StopServingTurnResponse as StopTurnResponse, ThreadModelPickResponse as ThreadModelPick, AssistantTurnStatus as TurnStatus, } from "../generated/models/index.js";
+export type { CreateServingAttachmentUploadResponse as AttachmentUploadIntent, HighlightResult, NavigateResult, PrefillFormResult, ReadPageResult, ResolveServingTurnApprovalRequest as ResolveTurnApprovalRequest, ResolveServingTurnApprovalResponse as ResolveTurnApprovalResponse, ResolveServingTurnToolResultsRequest as ResolveTurnToolResultsRequest, ResolveServingTurnToolResultsResponse as ResolveTurnToolResultsResponse, SendServingAssistantMessageRequest as SendAssistantMessageRequest, SendServingAssistantMessageResponse as SendAssistantMessageResponse, ServingAssistantThreadDetailResponse as AssistantThreadDetailResponse, ServingAssistantThreadResponse as ServingAssistantThread, ServingAssistantTurnResponse as ServingAssistantTurn, ServingAttachmentResponse as ServingAttachment, ServingTurnAttachmentResponse as TurnAttachment, StopServingTurnResponse as StopTurnResponse, ThreadModelPickResponse as ThreadModelPick, AssistantTurnStatus as TurnStatus, } from "../generated/models/index.js";
+/**
+ * The longest message a user can send, in characters; the composer stops input
+ * at this length and the server rejects longer messages.
+ */
 export declare const ASSISTANT_MESSAGE_MAX_CHARS = 4000;
 export declare const ASSISTANT_MAX_ATTACHMENTS = 10;

package/dist/core/activity.d.ts

@@ -1,17 +1,61 @@
 import type { ServingAssistantTurn, TurnStatus } from "../contract/threads.js";
 import type { ApprovalCardModel } from "./approval-inbox.js";
 import type { PendingDecisionGap } from "./pending-decision-gap.js";
+/** How the most recent finished turn of the conversation ended. */
 export interface AssistantActivityResult {
+    /**
+     * The id of that turn, which tells apart two identical outcomes in a row.
+     */
     turnId: string;
+    /**
+     * The final status. It is one of `succeeded`, `failed`, `stopped` (the user
+     * pressed Stop) or `superseded` (the user sent a new message instead of
+     * answering what the turn was waiting on).
+     */
     status: TurnStatus;
+    /**
+     * The error message recorded for a failed turn. Null when the turn did not
+     * fail or no message was recorded.
+     */
     failureSentence: string | null;
 }
+/**
+ * What the assistant is doing right now, for the open conversation. When no
+ * conversation is open, every field holds its idle value (false, 0 or null).
+ */
 export interface AssistantActivitySnapshot {
+    /**
+     * True while a message is being sent or the agent is working on a reply.
+     */
     busy: boolean;
+    /**
+     * The status of the latest turn (one message and the agent's work on it),
+     * or null when there is none. `queued` and `working` mean in progress.
+     * `awaiting_input` means it is waiting on the user. `parked` means an
+     * approval went unanswered long enough for the run to pause, and answering
+     * still resumes it. The other values mean it has finished.
+     */
     newestTurnStatus: TurnStatus | null;
+    /**
+     * The id of the latest turn, or null. Use it to dismiss a notification for
+     * one turn without hiding later ones.
+     */
     newestTurnId: string | null;
+    /**
+     * How many approvals are waiting for the user to approve or deny, including
+     * ones being submitted.
+     */
     pendingApprovalCount: number;
+    /**
+     * Set when the agent is waiting on the user for something this page has no
+     * prompt for, so nothing on screen lets them respond. Null otherwise. The
+     * built-in UI then shows an alert with a reload button.
+     */
     pendingDecisionGap: PendingDecisionGap | null;
+    /**
+     * How the most recent finished turn ended. It stays until another turn
+     * finishes, and is null until one has or when you switch conversations.
+     */
     lastResult: AssistantActivityResult | null;
 }
 export declare const IDLE_ACTIVITY: AssistantActivitySnapshot;

package/dist/core/approval-inbox.d.ts

@@ -22,27 +22,96 @@ export type ApprovalAsker = {
     ordinal: number;
     label: string;
 };
+/**
+ * One request for the visitor to approve or deny a tool or action call before
+ * it runs.
+ */
 export interface ApprovalCardModel {
+    /** Unique id of this request; use it as the React key. */
     interruptId: string;
+    /**
+     * Name of the tool waiting for approval (an action's is action__<slug>), or
+     * null when the request is not tied to a tool call.
+     */
     toolName: string | null;
+    /**
+     * What the agent passed to the call, without its short step caption. For an
+     * action, an object with path_params, query and body.
+     */
     toolArgs: Record<string, unknown>;
+    /** JSON Schema of the tool's input, or null when the tool declares none. */
     toolInputSchema: Record<string, unknown> | null;
+    /**
+     * JSON Schema of the tool's output, or null when the tool declares none.
+     */
     toolOutputSchema: Record<string, unknown> | null;
+    /**
+     * The reason approval is needed, from the approval rules that raised it.
+     * May be empty; show a generic line such as "This tool needs your approval"
+     * then.
+     */
     prompt: string;
+    /**
+     * Id of the tool call waiting for approval, matching its row in the
+     * transcript, or null when there is none.
+     */
     toolCallId: string | null;
+    /**
+     * True when the waiting tool call has already appeared in the transcript on
+     * this connection, so the request can be shown beside that row.
+     */
     anchored: boolean;
+    /** Which step of the agent's run paused for this request. */
     round: number;
+    /** Id of the agent run that paused for this request. */
     runId: string;
+    /**
+     * True when the agent has stopped actively waiting for an answer. The
+     * request can still be answered, and answering resumes the reply.
+     */
     parked: boolean;
+    /**
+     * True when this action is set to ask for approval on every call; trust
+     * cannot skip it, so don't offer "don't ask again".
+     */
     gated: boolean;
+    /**
+     * True when you may offer "approve and don't ask again" for this tool (send
+     * trust with the approval).
+     */
     trustAvailable: boolean;
+    /**
+     * Where the request stands. actionable means waiting for a decision (with
+     * the last failed submit's error sentence, or null), submitting means
+     * sending, answered carries the decision, and stale means it can no longer
+     * be answered (expired or answered elsewhere).
+     */
     status: ApprovalCardStatus;
+    /**
+     * Who is asking, the assistant itself or one of its sub-agents (with its
+     * number and a label taken from its task), so the card can name it.
+     */
     asker: ApprovalAsker;
+    /**
+     * For a sub-agent's request, the turn the decision is sent to; null for the
+     * assistant's own requests.
+     */
     turnId: string | null;
 }
+/** The visitor's answer to one approval request, passed to submitDecision. */
 export interface ApprovalDecisionInput {
+    /** True to let the call run, false to deny it. */
     approved: boolean;
+    /**
+     * With an approval, also stop asking about this tool for the rest of the
+     * conversation (or, for a sub-agent's request, the rest of its task). Only
+     * honored when the card's trustAvailable is true and gated is false.
+     */
     trust?: boolean;
+    /**
+     * For a denial, optional text telling the agent why; it is passed to the
+     * agent along with the refusal.
+     */
     feedback?: string;
 }
 export interface ApprovalInboxCapabilities {

package/dist/core/assistant-session-registry.js

@@ -63,6 +63,19 @@ class SessionEntry {
         });
         return fetch;
     }
+    async _ensureAttachmentPolicy() {
+        this.ensureAssistantConfig();
+        let flight = this._assistantConfigFetch;
+        while (flight !== null) {
+            await flight;
+            const current = this._assistantConfigFetch;
+            if (current === null || current === flight) {
+                break;
+            }
+            flight = current;
+        }
+        return this._attachmentPolicyCell.get();
+    }
     ensureSubscriptions = () => {
         this._subscriptionsFetch ??= this._fetchSubscriptions();
     };
@@ -171,6 +184,8 @@ class SessionEntry {
                 }
             },
             onTurnSettled: this._onTurnSettled,
+            attachmentPolicy: this._attachmentPolicyCell,
+            ensureAttachmentPolicy: () => this._ensureAttachmentPolicy(),
         });
     }
     _resolveEndUserToken() {

package/dist/core/composer-attachments.js

@@ -0,0 +1,82 @@
+import { ASSISTANT_MAX_ATTACHMENTS } from "../contract/threads.js";
+import { humanFileSize } from "../components/human-file-size.js";
+import { capSlotsSpentBy, mintAttachmentDraftId, pickCapOf, } from "./composer-policy.js";
+const ATTACHMENTS_UNAVAILABLE_SENTENCE = "Attachments aren't available right now.";
+const UPLOAD_FAILED_SENTENCE = "The upload failed.";
+export function attachmentRoomOf(policy) {
+    return Math.min(policy.max_per_message, ASSISTANT_MAX_ATTACHMENTS);
+}
+function attachmentTooLargeSentence(cap) {
+    return `Too large — the limit for ${cap.label} is ${humanFileSize(cap.bytes)}.`;
+}
+function tooManyAttachmentsSentence(room) {
+    return `Too many files — the limit is ${String(room)} per message.`;
+}
+export async function addComposerFilesFromStore(store, files) {
+    const picked = [...files];
+    if (picked.length === 0) {
+        return;
+    }
+    const resets = store._composerInputResets;
+    const policy = store.deps.attachmentPolicy.get() ??
+        (await store.deps.ensureAttachmentPolicy());
+    if (store._composerInputResets !== resets) {
+        return;
+    }
+    if (policy === null) {
+        _appendDrafts(store, picked.map((file) => _failedDraft(_uploadingDraftFor(file), ATTACHMENTS_UNAVAILABLE_SENTENCE)));
+        return;
+    }
+    const room = attachmentRoomOf(policy);
+    let taken = capSlotsSpentBy(store._composerInput.get().attachments);
+    const settling = [];
+    for (const file of picked) {
+        const entry = _uploadingDraftFor(file);
+        if (taken >= room) {
+            _appendDrafts(store, [
+                _failedDraft(entry, tooManyAttachmentsSentence(room)),
+            ]);
+            continue;
+        }
+        const cap = pickCapOf(file, policy.max_bytes_by_kind);
+        if (file.size > cap.bytes) {
+            _appendDrafts(store, [
+                _failedDraft(entry, attachmentTooLargeSentence(cap)),
+            ]);
+            continue;
+        }
+        taken += 1;
+        _appendDrafts(store, [entry]);
+        settling.push(_uploadDraft(store, file, entry.localId));
+    }
+    await Promise.all(settling);
+}
+function _uploadingDraftFor(file) {
+    return {
+        localId: mintAttachmentDraftId(),
+        filename: file.name !== "" ? file.name : "attachment",
+        byteSize: file.size,
+        status: "uploading",
+    };
+}
+function _failedDraft(entry, error) {
+    return { ...entry, status: "failed", error };
+}
+function _appendDrafts(store, drafts) {
+    store.setComposerAttachments((current) => [...current, ...drafts]);
+}
+async function _uploadDraft(store, file, localId) {
+    try {
+        const settled = await store.uploadAttachment(file);
+        _settleDraft(store, localId, { status: "ready", attachment: settled });
+    }
+    catch (error) {
+        _settleDraft(store, localId, {
+            status: "failed",
+            error: error instanceof Error ? error.message : UPLOAD_FAILED_SENTENCE,
+        });
+    }
+}
+function _settleDraft(store, localId, patch) {
+    store.setComposerAttachments((current) => current.map((item) => item.localId === localId ? { ...item, ...patch } : item));
+}

package/dist/core/composer-input-state.js

@@ -20,6 +20,7 @@ export function setComposerAttachmentsFromStore(store, next) {
 }
 export function resetComposerInput(store, threadId) {
     store._composerCaretReturnPending = null;
+    store._composerInputResets += 1;
     store._composerInput.set({
         scope: threadId !== null
             ? `t:${threadId}`

package/dist/core/composer-policy.d.ts

@@ -1,12 +1,32 @@
 import { type ServingAttachment } from "../contract/threads.js";
 import type { AttachmentKind } from "../generated/models/index.js";
 export declare const CHARACTER_COUNT_VISIBLE_FROM: number;
+/** One file staged in the composer for the next message. */
 export interface AttachmentDraft<A = ServingAttachment> {
+    /**
+     * An id for this file that is unique within the page, for React keys and
+     * for updating or removing it.
+     */
     localId: number;
+    /** The file's name as shown to the visitor. */
     filename: string;
+    /** The file's size in bytes. */
     byteSize: number;
+    /**
+     * uploading while the file is being uploaded, ready once it can be sent,
+     * failed if it was rejected or the upload failed. The package composer
+     * won't send while any file is uploading or failed.
+     */
     status: "uploading" | "ready" | "failed";
+    /**
+     * The uploaded attachment, set once status is ready; pass its id to
+     * sendMessage.
+     */
     attachment?: A;
+    /**
+     * Why the file failed, as a sentence for the visitor; set only when status
+     * is failed.
+     */
     error?: string;
 }
 export declare function mintAttachmentDraftId(): number;

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,
     };