@teaflask/assistant 0.6.0 → 0.7.0

package/dist/components/use-transcript.d.ts

@@ -1,19 +1,72 @@
 import type { Message } from "@ag-ui/core";
 import { type AssistantActivitySnapshot } from "../core/activity.js";
-import type { MarkerAnchorsSnapshot } from "../core/connection-epoch.js";
+import type { TranscriptMarkers } from "../core/connection-epoch.js";
 import { type TranscriptRow } from "../core/transcript-rows.js";
 import type { UserTurnMeta } from "../core/user-turn-ledger.js";
+/**
+ * The transcript as useTranscript returns it: ready-to-render rows, whether the
+ * assistant is working, and the raw inputs the rows were built from.
+ */
 export interface TranscriptSurface {
+    /**
+     * The conversation as an ordered list of rows, without the message the user
+     * has just sent and that is still on its way.
+     */
     rows: readonly TranscriptRow[];
+    /**
+     * The rows to render: `rows` plus the user's just-sent message while it is
+     * still being delivered. Don't also draw your own bubble for a sent
+     * message, or it will appear twice.
+     */
     displayRows: readonly TranscriptRow[];
+    /**
+     * True while the assistant is working: its turn is queued or running, or
+     * paused with nothing waiting on the user. False while a send is still in
+     * flight, so a working indicator should also check pendingSend from
+     * useConversation().
+     */
     running: boolean;
+    /**
+     * True while the newest turn has not finished, including while it is paused
+     * waiting for the user's approval or answer.
+     */
     turnOpen: boolean;
+    /**
+     * True while the turn is waiting on the user: an approval or question
+     * awaits their answer, or the server reports one this client has nothing to
+     * show for.
+     */
     decisionsPending: boolean;
+    /**
+     * The raw message list behind the rows (user messages, assistant text,
+     * reasoning, tool calls and tool results). Use it with markerAnchors,
+     * running and turnMeta to call transcriptRowsOf yourself.
+     */
     messages: readonly Message[];
-    markerAnchors: MarkerAnchorsSnapshot;
+    /**
+     * Extra facts the stream reports about messages and tool calls (failures,
+     * timing, schemas, memory saves), already joined into the rows; read it
+     * directly only for custom rendering.
+     */
+    markerAnchors: TranscriptMarkers;
+    /**
+     * The conversation's current run state, such as the newest turn's status
+     * and how many approvals are waiting.
+     */
     activity: AssistantActivitySnapshot;
+    /**
+     * The send time and attachments of each user message, keyed by that
+     * message's id.
+     */
     turnMeta: ReadonlyMap<string, UserTurnMeta>;
 }
+/**
+ * Returns everything needed to render the conversation's transcript yourself,
+ * as rows plus run state. Call it inside TeaflaskAssistantProvider (it throws
+ * otherwise); keep it mounted while the transcript is on screen, because that
+ * is what makes the assistant connect and load an existing conversation's
+ * history.
+ */
 export declare function useTranscript(options?: {
     surface?: string;
 }): TranscriptSurface;

package/dist/components/use-transcript.js

@@ -2,14 +2,18 @@
 import { useEffect, useMemo } from "react";
 import { isTerminalTurnStatus, } from "../core/activity.js";
 import { runReadsAsWorking } from "../core/run-status.js";
+import { withDispatchLedger } from "../core/subagent-ledger-join.js";
 import { approvalAwaitsMember, elicitationAwaitsMember, } from "../core/suspension-queue.js";
 import { transcriptRowsOf, withPendingUserEcho, } from "../core/transcript-rows.js";
 import { useConversation } from "./conversation-context.js";
 import { useAssistantSession } from "./teaflask-assistant-provider.js";
 import { useCell } from "./use-store-cell.js";
+import { useThreadDispatches } from "./use-thread-dispatches.js";
 export function useTranscript(options) {
-    const { store } = useAssistantSession();
+    const { session, store } = useAssistantSession();
     const { pendingEcho } = useConversation();
+    const connection = useCell(store.connection);
+    const dispatches = useThreadDispatches(session, connection?.threadId ?? null);
     const messages = useCell(store.messages);
     const markerAnchors = useCell(store.markerAnchors);
     const approvalCards = useCell(store.approvals);
@@ -24,7 +28,8 @@ export function useTranscript(options) {
     const running = runReadsAsWorking(activity.newestTurnStatus, decisionsPending);
     const turnOpen = activity.newestTurnStatus !== null &&
         !isTerminalTurnStatus(activity.newestTurnStatus);
-    const rows = useMemo(() => transcriptRowsOf(messages, markerAnchors, running, turnMeta), [messages, markerAnchors, running, turnMeta]);
+    const wireRows = useMemo(() => transcriptRowsOf(messages, markerAnchors, running, turnMeta), [messages, markerAnchors, running, turnMeta]);
+    const rows = useMemo(() => withDispatchLedger(wireRows, dispatches), [wireRows, dispatches]);
     const displayRows = useMemo(() => withPendingUserEcho(rows, pendingEcho), [pendingEcho, rows]);
     return {
         rows,

package/dist/contract/actions-adapter.d.ts

@@ -1,26 +1,104 @@
+/** The catalog entry an action request comes from. */
 export interface ActionIntentAction {
+    /**
+     * The action's identifier in your catalog; the agent calls it as the tool
+     * action__<slug>.
+     */
     slug: string;
+    /** The action's human-readable title from your catalog. */
     title: string;
 }
+/**
+ * One action request the assistant asks your page to perform, built by Teaflask
+ * from your actions catalog with arguments already validated against the
+ * action's schemas. Your actions adapter receives it.
+ */
 export interface ActionIntent {
+    /** Which catalog action this request is for. */
     action: ActionIntentAction;
+    /**
+     * The HTTP method, in upper case - GET, HEAD, POST, PUT, PATCH or DELETE.
+     */
     method: string;
+    /**
+     * The path relative to your API, with {name} placeholders, for example
+     * "/subscriptions/{subscription_id}". It never includes an origin, so the
+     * request always goes where your adapter sends it.
+     */
     pathTemplate: string;
+    /**
+     * Values for the placeholders in pathTemplate, keyed by name. The cookies
+     * and headers adapters substitute them URL-encoded.
+     */
     pathParams: Record<string, unknown>;
+    /**
+     * Query-string parameters, keyed by name; empty when there are none. The
+     * cookies and headers adapters drop null or undefined values and
+     * JSON-encode non-scalar ones.
+     */
     query: Record<string, unknown>;
+    /**
+     * The JSON request body; absent when the action sends none. The cookies and
+     * headers adapters send it with Content-Type application/json.
+     */
     body?: unknown;
 }
+/**
+ * For APIs authenticated by session cookies. The package fetches baseUrl plus
+ * the action's path with credentials included, so each request runs in the
+ * user's own session; an API on another origin must allow credentialed CORS
+ * from your page.
+ */
 export interface CookiesActionsAdapter {
+    /** Selects the cookies adapter. */
     kind: "cookies";
+    /**
+     * The URL your action paths are appended to, such as
+     * "https://app.example.com/api"; a trailing slash is ignored.
+     */
     baseUrl: string;
 }
+/**
+ * For APIs authenticated by a token or other headers. The package builds the
+ * URL the same way as the cookies adapter and adds the headers getHeaders
+ * returns.
+ */
 export interface HeadersActionsAdapter {
+    /** Selects the headers adapter. */
     kind: "headers";
+    /**
+     * The URL your action paths are appended to, such as
+     * "https://api.example.com/v1"; a trailing slash is ignored.
+     */
     baseUrl: string;
+    /**
+     * Called before every action request with that request; return the headers
+     * to send, such as Authorization. It may be async to fetch or refresh a
+     * token, its headers override the package's Content-Type, and throwing
+     * reports the action as failed.
+     */
     getHeaders: (intent: ActionIntent) => Record<string, string> | Promise<Record<string, string>>;
 }
+/**
+ * Full control - you perform the HTTP request yourself, for example through
+ * your existing API client.
+ */
 export interface RequestActionsAdapter {
+    /** Selects the request adapter. */
     kind: "request";
+    /**
+     * Performs the request and resolves with your API's response body, which
+     * the agent receives with status 200. Reject (for example by throwing on a
+     * non-2xx response) to report the action as failed.
+     */
     execute: (intent: ActionIntent) => Promise<unknown>;
 }
+/**
+ * How the assistant calls your API as the signed-in user, passed as the
+ * provider's actionsAdapter prop; without one the assistant cannot perform
+ * actions and tells the user to do them. The response's status and body (parsed
+ * as JSON, otherwise text) go back to the agent; a non-2xx status counts as
+ * your API's answer, not a failure, and bodies over about 16,000 characters are
+ * truncated.
+ */
 export type ActionsAdapter = CookiesActionsAdapter | HeadersActionsAdapter | RequestActionsAdapter;

package/dist/contract/errors.d.ts

@@ -1,7 +1,12 @@
 export type { ServingErrorCode } from "../generated/models/index.js";
 import type { ServingErrorCode } from "../generated/models/index.js";
+/**
+ * An error code: one of the known ServingErrorCode values, or any other string,
+ * since new codes may be added. Handle unknown codes by showing the error's
+ * message.
+ */
 export type ServingErrorCodeOnTheWire = ServingErrorCode | (string & {});
-export interface ServingErrorBody {
+interface ServingErrorBody {
     code: ServingErrorCodeOnTheWire;
     message: string;
     details?: unknown;

package/dist/contract/events.d.ts

@@ -1,7 +1,5 @@
-import type { ApprovalRequestedMarker, ApprovalResolvedMarker, InterruptAnswerConsumedMarker, RunResumedMarker, SubagentResultsDeliveredMarker, ToolExecutionRequestedMarker } from "../generated/models/index.js";
-export type AssistantStreamEventType = "TEXT_MESSAGE_START" | "TEXT_MESSAGE_CONTENT" | "TEXT_MESSAGE_END" | "REASONING_START" | "REASONING_END" | "REASONING_MESSAGE_START" | "REASONING_MESSAGE_CONTENT" | "REASONING_MESSAGE_END" | "TOOL_CALL_START" | "TOOL_CALL_ARGS" | "TOOL_CALL_END" | "TOOL_CALL_RESULT" | "RUN_STARTED" | "RUN_FINISHED" | "RUN_ERROR" | "CUSTOM";
+import type { ApprovalRequestedMarker, ApprovalResolvedMarker, InterruptAnswerConsumedMarker, SubagentResultsDeliveredMarker, ToolExecutionRequestedMarker } from "../generated/models/index.js";
 export declare const RUN_RESUMED_EVENT_NAME: "run_resumed";
-export type RunResumedPayload = RunResumedMarker;
 export declare const APPROVAL_REQUESTED_EVENT_NAME: "approval_requested";
 export type ApprovalRequestedPayload = ApprovalRequestedMarker & Required<Pick<ApprovalRequestedMarker, "tool_args" | "tool_input_schema" | "tool_output_schema" | "round" | "gated" | "trust_available">>;
 export declare const APPROVAL_RESOLVED_EVENT_NAME: "approval_resolved";

package/dist/contract/identity.d.ts

@@ -1 +1 @@
-export type { CurrentVisitorResponse as WhoamiResponse, EndUserIdentity, MintVisitorTokenRequest, MintVisitorTokenResponse, PublishableKeyMode, VisitorTier, } from "../generated/models/index.js";
+export type { MintVisitorTokenRequest, MintVisitorTokenResponse, VisitorTier, } from "../generated/models/index.js";

package/dist/contract/subscriptions.d.ts

@@ -1,6 +1,6 @@
 import type { SubscriptionProvider } from "../generated/models/index.js";
-export type { BeginSubscriptionAuthorizationResponse as SubscriptionAuthorization, CompleteSubscriptionAuthorizationRequest as SubscriptionAuthorizationCompletionRequest, CompleteSubscriptionAuthorizationResponse as SubscriptionAuthorizationCompletion, ServingSubscriptionStatus as SubscriptionStatus, SubscriptionCredentialState, SubscriptionProvider, } from "../generated/models/index.js";
-export declare const SUBSCRIPTION_CONNECT_MESSAGE_TYPE = "teaflask.subscription_connect";
+export type { BeginSubscriptionAuthorizationResponse as SubscriptionAuthorization, CompleteSubscriptionAuthorizationRequest as SubscriptionAuthorizationCompletionRequest, CompleteSubscriptionAuthorizationResponse as SubscriptionAuthorizationCompletion, ServingSubscriptionStatus as SubscriptionStatus, SubscriptionProvider, } from "../generated/models/index.js";
+declare const SUBSCRIPTION_CONNECT_MESSAGE_TYPE = "teaflask.subscription_connect";
 export type SubscriptionConnectMessage = {
     type: typeof SUBSCRIPTION_CONNECT_MESSAGE_TYPE;
     provider: SubscriptionProvider;

package/dist/contract/subscriptions.js

@@ -1,4 +1,4 @@
-export const SUBSCRIPTION_CONNECT_MESSAGE_TYPE = "teaflask.subscription_connect";
+const SUBSCRIPTION_CONNECT_MESSAGE_TYPE = "teaflask.subscription_connect";
 export function subscriptionConnectMessageOf(event, serverOrigin, provider) {
     if (event.origin !== serverOrigin || event.source === null) {
         return null;

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;