@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/web-react/chat-composer.d.ts

@@ -0,0 +1,174 @@
+/**
+ * ChatComposer — the shared message input every agent app used to hand-roll:
+ * an auto-resizing textarea (Enter sends, Shift+Enter inserts a newline), an
+ * opt-in attach + drag-and-drop surface with pending-file chips, a streaming
+ * Stop/Send toggle, a slot for inline controls (model picker, reasoning
+ * effort), and a Cmd/Ctrl+L focus shortcut.
+ *
+ * A REJECTED send never destroys the draft. The input clears optimistically —
+ * the composer stays editable while a turn streams precisely so the next
+ * message can be typed against a live answer, and holding the sent text in the
+ * box until the server confirms would put the clear on a collision course with
+ * that typing. So the clear happens immediately and the draft is held until the
+ * send is known to have landed: a handler that throws, rejects, or returns
+ * `{ ok: false }` puts the exact bytes back with the caret where it was, names
+ * the reason, and reports `onSendFailed` so the host can restore the
+ * attachments it consumed. If the user has already typed a replacement, the
+ * unsent text is shown in the notice with its own Retry instead of overwriting
+ * what they typed — neither draft is ever destroyed.
+ *
+ * Styling contract matches the rest of `web-react`: Tailwind over the shared
+ * design tokens (`bg-card`, `border-border`, `text-foreground`, `bg-primary`, …)
+ * and inline-SVG glyphs. It defines NO `--chat-*` / `--brand-*` custom
+ * properties, so it themes correctly in any shell that provides the standard
+ * tokens — the input renders on-palette instead of collapsing to unstyled
+ * fallbacks when a host hasn't defined a private chat-token set.
+ */
+import { type ReactNode } from 'react';
+/** Prompt-part descriptor an uploaded file carries (the upload route's
+ *  `UploadedChatFile.part`), echoed back in the turn body on send. Mirrors
+ *  `/chat-routes`' wire shape structurally — no server import here. */
+export interface ComposerFilePart {
+    type: 'image' | 'file';
+    filename?: string;
+    mediaType?: string;
+    url?: string;
+    path?: string;
+    content?: string;
+}
+export interface ComposerFile {
+    id: string;
+    name: string;
+    size?: number;
+    kind: 'file' | 'folder';
+    /** Number of files inside, for a folder chip. */
+    fileCount?: number;
+    status: 'pending' | 'uploading' | 'ready' | 'error';
+    /** Uploaded part descriptor; set once the upload route returns. Only
+     *  `status: 'ready'` files with a part travel on a parts-aware send. */
+    part?: ComposerFilePart;
+}
+/** A send the host refused. `error` is shown verbatim in the composer's notice;
+ *  omit it for the generic copy. */
+export interface ComposerSendRejected {
+    ok: false;
+    error?: string;
+}
+/**
+ * What a send handler reports back. `void` — what every handler returned before
+ * this existed — reads as accepted, so wiring stays unchanged; a thrown error, a
+ * rejected promise, or `{ ok: false }` is the rejection that restores the draft.
+ * A handler that resolves only when the whole turn finishes still reports
+ * correctly: the input already cleared on dispatch, so the answer only decides
+ * whether the draft comes back.
+ */
+export type ComposerSendOutcome = void | {
+    ok: true;
+} | ComposerSendRejected;
+export type ComposerSendResult = ComposerSendOutcome | Promise<ComposerSendOutcome>;
+/**
+ * A send handler, typed as a UNION with the legacy `=> void` signature rather
+ * than as `(…) => ComposerSendResult` alone.
+ *
+ * TypeScript's return-type-`void` rule accepts a function returning ANYTHING
+ * where a `=> void` is expected, and that rule fires only when the target's
+ * return type is exactly `void` — not when it is a union that contains `void`.
+ * So narrowing this prop to `ComposerSendResult` would reject handler shapes
+ * that compiled against the shipped `onSend?: (message: string) => void`:
+ * `onSend={(m) => rows.push(m)}` (returns `number`) and
+ * `onSend={(m) => append({ role: 'user', content: m })}` (an ai-sdk append
+ * returns `Promise<string | null | undefined>`) both stop compiling, on a
+ * package whose pinned consumers must never need a source edit to take a minor.
+ *
+ * The union keeps both: a legacy handler lands on the first member, and a
+ * handler that reports an outcome lands on the second. A call through it
+ * resolves to `void | ComposerSendResult`, which IS `ComposerSendResult`, so
+ * the composer reads the outcome exactly as before.
+ */
+export type ComposerSendHandler = ((message: string) => void) | ((message: string) => ComposerSendResult);
+/** @see ComposerSendHandler — the parts-aware arity, same union for the same reason. */
+export type ComposerSendPartsHandler = ((message: string, parts: ComposerFilePart[]) => void) | ((message: string, parts: ComposerFilePart[]) => ComposerSendResult);
+/** The rejected send, handed to `onSendFailed` so the host can undo whatever it
+ *  cleared optimistically — most importantly the staged attachments, which the
+ *  composer does not own (`pendingFiles` is a prop). */
+export interface ComposerSendFailure {
+    /** The reason as the composer renders it. */
+    message: string;
+    /** The user's exact draft, untrimmed. */
+    text: string;
+    /** The parts the rejected send carried. */
+    parts: ComposerFilePart[];
+    /** Whatever the handler threw / rejected with, or the `{ ok: false }` value. */
+    error: unknown;
+    /** True when the draft was put back in the textarea (the box was empty).
+     *  False means the user had typed a replacement, so the unsent text is held in
+     *  the notice instead. */
+    restored: boolean;
+}
+export interface ChatComposerProps {
+    /** Send the trimmed, non-empty message. Attached files travel separately via
+     *  `onAttach` + `pendingFiles` (the host consumes and clears them on send).
+     *  Optional when `onSendParts` is wired.
+     *
+     *  Report a refused send by throwing, rejecting, or returning `{ ok: false }`
+     *  — the composer restores the draft rather than losing it. */
+    onSend?: ComposerSendHandler;
+    /** Parts-aware send: receives the trimmed message plus the `part`
+     *  descriptors of every `ready` pending file. Takes precedence over
+     *  `onSend`; enables file-only sends (empty text, ≥1 ready part).
+     *
+     *  Same rejection contract as `onSend`. */
+    onSendParts?: ComposerSendPartsHandler;
+    /** Notified when a send is rejected, after the composer has restored what it
+     *  owns. The host uses it to put back the `pendingFiles` it consumed. */
+    onSendFailed?: (failure: ComposerSendFailure) => void;
+    /** Notice copy when the handler names no reason of its own. */
+    sendFailureMessage?: string;
+    /** Stop the in-flight turn; shown in place of Send while `isStreaming`. */
+    onCancel?: () => void;
+    isStreaming?: boolean;
+    /** Block input + send (e.g. while restoring). Distinct from `isStreaming`,
+     *  which keeps the textarea editable so the next turn can be composed. */
+    disabled?: boolean;
+    placeholder?: string;
+    /** Controlled value. Omit for self-managed internal state (cleared on send). */
+    value?: string;
+    onValueChange?: (value: string) => void;
+    /** Initial text in uncontrolled mode; ignored when `value` is provided. */
+    initialValue?: string;
+    /** One-shot external prefill: when this becomes a non-null string the
+     *  composer adopts it as the draft (replacing any current draft), focuses the
+     *  input with the caret at the end, and reports consumption via
+     *  `onSeedApplied` so the host can clear its seed state. */
+    seed?: string | null;
+    onSeedApplied?: () => void;
+    /** Inline controls (e.g. `<ModelPicker/>` + `<EffortPicker/>` or
+     *  `<AgentSessionControls/>`). */
+    controls?: ReactNode;
+    /**
+     * Where {@link controls} sit. `inline` (default) puts them on the card's own
+     * action row, beside attach and Send — the model a turn will use reads as
+     * part of the input rather than as a separate widget floating above it.
+     * `above` keeps them outside the card, for a host that wants the input to be
+     * nothing but the input.
+     */
+    controlsPlacement?: 'above' | 'inline';
+    /** Attachments are opt-in: pass `onAttach` to show the attach button, accept
+     *  drag-and-drop onto the input, and render `pendingFiles` chips. */
+    onAttach?: (files: FileList) => void;
+    onAttachFolder?: (files: FileList) => void;
+    pendingFiles?: ComposerFile[];
+    onRemoveFile?: (id: string) => void;
+    accept?: string;
+    dropTitle?: string;
+    dropDescription?: string;
+    /** Cmd/Ctrl+L focuses the input and shows the hint. Default true. */
+    focusShortcut?: boolean;
+    /** Float the card on a soft two-layer foreground-tinted shadow (opt-in).
+     *  Elevation only — radius, ring, and control layout are unchanged. */
+    floating?: boolean;
+    /** Send button label. Default "Send". */
+    sendLabel?: string;
+    className?: string;
+}
+export declare function ChatComposer({ onSend, onSendParts, onSendFailed, sendFailureMessage, onCancel, isStreaming, disabled, placeholder, value, onValueChange, initialValue, seed, onSeedApplied, controls, controlsPlacement, onAttach, onAttachFolder, pendingFiles, onRemoveFile, accept, dropTitle, dropDescription, focusShortcut, floating, sendLabel, className, }: ChatComposerProps): import("react").JSX.Element;

package/dist/web-react/chat-interactions.d.ts

@@ -0,0 +1 @@
+export * from '../interactions/contract';

package/dist/web-react/chat-mentions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Transcript-side counterpart to the composer's `@`-mention primitive
+ * (sandbox-ui#184). The composer serializes a picked file into the message
+ * text as `@<path>`; this module is the exact inverse — it finds those tokens
+ * again in a PERSISTED message and splits the text so a renderer can draw a
+ * pill where the user typed one and leave the rest as prose.
+ *
+ * Pure and product-agnostic: no React, no fetch, no DOM. The only input beyond
+ * the text is the message's OWN mention parts, so one message can never render
+ * a pill for a path another message mentioned.
+ *
+ * `ChatMentionPart` and the runtime helpers `mentionInputToPart` /
+ * `mentionPartsFromMessageParts` are re-exported here from `../chat-store/parts`
+ * directly (not the `/chat-store` barrel), so a browser bundle gets the mention
+ * vocabulary and its converters without importing `/chat-store`, whose barrel
+ * pulls the drizzle peer.
+ */
+import { mentionInputToPart, mentionPartsFromMessageParts, type ChatMentionKind, type ChatMentionPart } from '../chat-store/parts';
+export type { ChatMentionKind, ChatMentionPart };
+export { mentionInputToPart, mentionPartsFromMessageParts };
+/** One run of a segmented message: literal prose, or a matched mention with
+ *  the part that produced it. `text` for a mention segment is the token as it
+ *  appears in the message (`@<path>`), so a renderer that ignores `part` still
+ *  reproduces the original string exactly. */
+export interface MentionTextSegment {
+    type: 'text' | 'mention';
+    text: string;
+    part?: ChatMentionPart;
+}
+/**
+ * Split a message's text into plain-text and mention segments by matching
+ * `@<path>` runs against that message's own mention parts.
+ *
+ * Only a part whose exact `@<path>` token appears in `content`, at a token
+ * boundary on both sides, counts as a match; everything else — including
+ * unrelated `@` text — passes through as plain text untouched. When two parts'
+ * tokens both match at the same position (one path a prefix of another), the
+ * LONGEST token wins, so nested-looking paths split at the right boundary.
+ *
+ * Returns the matched parts alongside the segments: a caller that also renders
+ * a fallback chip row can drop the chip for anything now shown inline and keep
+ * it only for mentions the text does not actually contain (a restored draft, a
+ * queued message whose text was edited).
+ */
+export declare function segmentMentionContent(content: string, parts: ReadonlyArray<ChatMentionPart>): {
+    segments: MentionTextSegment[];
+    matched: Set<ChatMentionPart>;
+};

package/dist/web-react/chat-stream.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Client-side chat-stream consumption — the NDJSON parse loop every agent
+ * app's chat UI hand-rolls (and breaks). Normalizes the three line shapes the
+ * agent-app chat routes emit:
+ *
+ *   {kind:'event', event:{type:'text'|'reasoning'|'tool_call'|'usage'|'notice'|'error', ...}}
+ *   {kind:'tool_result', toolCallId, toolName, label, outcome}
+ *   {type:'turn'|'metadata'|'error'|'turn_status', ...}          (route-level)
+ *   {type:'interaction', data:{request}}                         (sidecar ask)
+ *
+ * Replayed lines carry an extra `seq` — transparently ignored. Works for
+ * router-backed and sandbox-backed chats alike: anything producing these
+ * lines (live pump, queued follow, resume replay) feeds the same callbacks.
+ */
+import { type ChatInteraction, type InteractionCancelData } from './chat-interactions';
+import { type ChatPlan } from '../plans/index';
+export { chatTurnRequestInit, type ChatTurnFilePartInput, type ChatTurnPartInput, type ChatTurnRequestPayload, type ProducerTextEvent, type ProducerReasoningEvent, type ProducerToolCallEvent, type ProducerToolResultEvent, type ProducerUsageEvent, type ProducerNoticeEvent, type ProducerErrorEvent, type ProducerPassthroughEventType, type ProducerPassthroughEvent, type ProducerWireEvent, type FileMention, fileMentionsToParts, buildMentionPromptBlock, mediaTypeForMentionPath, mentionKindForPath, type ChatAttachmentKind, type ChatAttachmentInput, DISPATCH_REQUEST_MAX_BYTES, DISPATCH_STRUCTURAL_RESERVE_BYTES, DISPATCH_MAX_PARTS, DISPATCH_MAX_MEDIA_PARTS, base64WireLen, } from '../chat-routes/wire';
+export { type FileIndexResponse, type FileIndexReadyResponse, type FileIndexWarmingResponse, } from '../chat-routes/file-index';
+/** Define the structure for a chat tool call including optional ID, name, and arguments object */
+export interface ChatStreamToolCall {
+    toolCallId?: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+/** Describe the result of a chat stream tool including its outcome and optional metadata fields */
+export interface ChatStreamToolResult {
+    toolCallId?: string;
+    toolName?: string;
+    label?: string;
+    outcome: {
+        ok: boolean;
+        result?: unknown;
+        code?: string;
+        message?: string;
+    };
+}
+/** Define callbacks to handle events and data during a chat streaming session */
+export interface ChatStreamCallbacks {
+    onTurnId?: (turnId: string) => void;
+    onText?: (delta: string) => void;
+    onReasoning?: (delta: string) => void;
+    onToolCall?: (call: ChatStreamToolCall) => void;
+    onToolResult?: (result: ChatStreamToolResult) => void;
+    onUsage?: (usage: {
+        promptTokens: number;
+        completionTokens: number;
+    }) => void;
+    onNotice?: (notice: {
+        id: string;
+        noticeKind: 'warning' | 'auto-declined';
+        text: string;
+    }) => void;
+    onMetadata?: (data: Record<string, unknown>) => void;
+    /** Structured detail from a loop-level error event. Fired alongside the
+     *  legacy string-only `onErrorEvent` callback. */
+    onErrorEventDetail?: (detail: {
+        message: string;
+        code?: string;
+        details?: Record<string, unknown>;
+    }) => void;
+    /** A loop-level error event (the turn failed server-side). Optional, but the
+     *  error never vanishes: when omitted, the message is synthesized into the
+     *  transcript via `onText` (rendered by ChatMessages as a text segment) and
+     *  logged with `console.error`. */
+    onErrorEvent?: (message: string) => void;
+    /** A sidecar interaction ask (kind: "question"/"plan"/…). The run is BLOCKED
+     *  in the broker until the user answers; a pending ask is "waiting on the
+     *  user", not "model working". Optional — a consumer that doesn't wire it
+     *  parses the same stream unchanged. */
+    onInteraction?: (interaction: ChatInteraction) => void;
+    /** A terminal withdrawal/timeout for a previously emitted interaction. */
+    onInteractionCancel?: (cancel: InteractionCancelData) => void;
+    /** A durable-plan snapshot from any plan lifecycle event. */
+    onPlan?: (plan: ChatPlan) => void;
+}
+/** Represent the result of consuming a chat stream including turn ID and content reception status */
+export interface ConsumeChatStreamResult {
+    turnId: string | null;
+    /** True when any text/reasoning/tool activity was received. */
+    receivedContent: boolean;
+}
+/** Parse one NDJSON line into the callbacks. Exposed for tests. */
+export declare function dispatchChatStreamLine(line: string, cb: ChatStreamCallbacks): {
+    turnId?: string;
+    receivedContent: boolean;
+};
+/** Drain one NDJSON body into the callbacks. Throws on transport failure
+ *  (caller decides whether to resume). */
+export declare function consumeChatStream(body: ReadableStream<Uint8Array>, cb: ChatStreamCallbacks): Promise<ConsumeChatStreamResult>;
+/** Define options for managing and resuming streaming chat interactions with callbacks */
+export interface StreamChatOptions {
+    /** Start the turn (POST the chat request); must return a streaming Response. */
+    start: () => Promise<Response>;
+    /** Re-attach to a turn after a transport drop (GET the resume route). */
+    resume?: (turnId: string, fromSeq: number) => Promise<Response>;
+    callbacks: ChatStreamCallbacks;
+    /** Called before a resume replays from 0 so the UI can reset accumulated
+     *  turn state (text, reasoning, tool chips). */
+    onResetForResume?: () => void;
+}
+/**
+ * Run one chat turn with automatic single-shot resume: if the transport drops
+ * mid-turn and the server announced a turnId, reset and replay the buffered
+ * turn. Server-side the turn keeps running either way (queued runner).
+ */
+export declare function streamChatTurn(opts: StreamChatOptions): Promise<ConsumeChatStreamResult>;

package/dist/web-react/class-names.d.ts

@@ -0,0 +1,10 @@
+/**
+ * One class-attribute join for this subpath.
+ *
+ * The pattern it replaces is `` `base ${className ?? ''}` ``, which emits
+ * `class="base "` for every caller that passes nothing: a trailing separator in
+ * the DOM, in every snapshot, and in every assertion that compares the attribute
+ * instead of searching it. Interpolating an absent value is the defect — the
+ * fix is to never build the attribute by interpolation.
+ */
+export declare function joinClasses(...parts: ReadonlyArray<string | false | null | undefined>): string;

package/dist/web-react/controls.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Shared chat-shell control primitives — the LEAF that both the web-react barrel
+ * (`./index`) and the composer children (`./agent-session-controls`,
+ * `./seat-paywall`) import directly, so neither child has to reach back through
+ * the barrel (which would re-create an import cycle). The barrel re-exports the
+ * public names (`usePopover`, `usePending`, `ModelPicker`, `EffortPicker`, …)
+ * unchanged, so the published export surface is identical.
+ *
+ * Styling contract matches the rest of `web-react`: Tailwind classes against the
+ * shared design tokens; the glyphs are inline SVGs, no icon-library dependency.
+ */
+import { type ReactNode, type RefObject } from 'react';
+import type { CatalogModel } from '../runtime/model-catalog';
+export declare function ChevronDown({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/** lucide `check` — the selected-row mark in the picker menus. */
+export declare function CheckGlyph({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * Keyboard + pointer model for a trigger-and-popover pair, dependency-free.
+ * Outside-mousedown and Escape both close; Escape also returns focus to the
+ * trigger so keyboard users aren't dropped at the top of the document. The
+ * returned `triggerProps` carry the ARIA contract (`aria-haspopup`/
+ * `aria-expanded`); spread them onto the trigger button.
+ *
+ * `panelRef` belongs to the popover panel and MUST be wired when the panel is
+ * rendered through {@link PopoverSurface}: a portaled panel is not inside
+ * `containerRef`, so a container-only outside test reads every click on the
+ * menu's own rows as an outside click and closes before the row's handler runs.
+ */
+export declare function usePopover(open: boolean, setOpen: (open: boolean) => void): {
+    containerRef: RefObject<HTMLDivElement | null>;
+    triggerRef: RefObject<HTMLButtonElement | null>;
+    panelRef: RefObject<HTMLDivElement | null>;
+    triggerProps: {
+        ref: RefObject<HTMLButtonElement | null>;
+        'aria-haspopup': true;
+        'aria-expanded': boolean;
+    };
+};
+/**
+ * Marks the portaled panel in the DOM. Products and audits (see
+ * `playground/scripts/popover-hit-test.mjs`) select on this rather than on a
+ * Tailwind class, which is presentation and free to change.
+ *
+ * Its VALUE is the surface's ancestor path (`outer/inner`), which is what
+ * restores "is this click inside my popover" after the portal flattens two
+ * nested panels into two siblings of `<body>`.
+ */
+export declare const POPOVER_SURFACE_ATTR = "data-agent-app-popover";
+export interface PopoverSurfaceProps {
+    open: boolean;
+    /** The trigger the panel anchors to — `usePopover`'s `triggerRef`. */
+    triggerRef: RefObject<HTMLElement | null>;
+    /** `usePopover`'s `panelRef`; also what the outside-click test consults. */
+    panelRef: RefObject<HTMLDivElement | null>;
+    /** Presentation classes. Placement and elevation are owned here — a caller
+     *  must not pass `absolute`/`fixed`/`top-*`/`bottom-*`/`z-*`. */
+    className?: string;
+    role?: string;
+    id?: string;
+    /** Make the panel at least as wide as its trigger. A portaled panel has no
+     *  `w-full` to inherit — the trigger is no longer its offset parent — so a
+     *  menu that used to stretch to a full-width trigger declares it here. */
+    matchTriggerWidth?: boolean;
+    children: ReactNode;
+}
+/**
+ * The floating panel every canonical picker opens.
+ *
+ * It renders through a PORTAL to `document.body` and anchors itself to the
+ * trigger in viewport coordinates, because an in-place `absolute` panel's
+ * visibility is decided by markup this package does not own. Measured in
+ * production: the shipped chat composer docks these controls inside a
+ * horizontally scrolling rail (`overflow-x-auto`), and a scroll container
+ * clips every positioned descendant whose containing block sits inside it —
+ * so a correct 420x457 menu with correct coordinates painted zero pixels and
+ * could not be clicked. An ancestor `transform`/`filter`/`contain` would trap
+ * it the same way through the stacking context instead of the clip. Leaving
+ * the DOM subtree is the only placement a host cannot re-break.
+ *
+ * Placement prefers ABOVE the trigger (these controls dock at the bottom of a
+ * composer), flips below when there is more room there, clamps horizontally
+ * into the viewport, and caps its own height to the space on the chosen side.
+ * The panel is `visibility: hidden` for the measure pass so it never paints at
+ * the pre-placement origin.
+ */
+export declare function PopoverSurface({ open, triggerRef, panelRef, className, role, id, matchTriggerWidth, children, }: PopoverSurfaceProps): import("react").ReactPortal | null;
+/**
+ * Focus treatment for a row inside a popover panel.
+ *
+ * The ring itself now comes from the `:focus-visible` floor in tokens.css, so
+ * this no longer restates a width or a colour. What it still has to say is
+ * WHERE the ring is drawn: a popover option is a full-width row inside a panel
+ * that clips its own corners (`overflow-hidden rounded-xl`), and an outward
+ * ring on the first or last row is clipped away by that panel. Pulling the
+ * offset negative draws the same ring just inside the row instead.
+ */
+export declare const POPOVER_OPTION_FOCUS = "focus-visible:[outline-offset:-2px]";
+/**
+ * The one overlay elevation for floating surfaces — picker menus, popovers,
+ * drawers, modals. Reads the theme's `--shadow-overlay` token, so every overlay
+ * lifts with the same shadow and re-themes from one source. The floating
+ * composer uses the quieter `shadow-raised` rung instead.
+ *
+ * Written as an arbitrary value rather than the preset's `shadow-overlay`
+ * utility, because that utility only exists where the preset is part of the
+ * Tailwind build. A host that gets its tokens through a precompiled bundle —
+ * `@tangle-network/sandbox-ui` ships brand's tokens inlined, with no `@theme`
+ * block surviving the compile — receives `--shadow-overlay` as a plain custom
+ * property, from which no `shadow-overlay` utility can be generated, and these
+ * surfaces render flat. The arbitrary form emits from the class alone and works
+ * either way.
+ */
+export declare const OVERLAY_SHADOW = "shadow-[var(--shadow-overlay)]";
+/**
+ * Root geometry for a picker — the box that holds the trigger — in one place
+ * because every picker in this family has to agree on it.
+ *
+ * Shrink-wrapping (`inline-flex`) is the default: these controls dock on a
+ * composer row where an expanding pill shoves its neighbours around. A STACKED
+ * panel wants the opposite — the compact `AgentSessionControls` gear popover
+ * lays its controls out in a column, and a shrink-wrapped root there makes a
+ * trigger's own `w-full` a no-op, since it fills a box the trigger itself
+ * sized. That is what left Agent backend short of the panel edge and Thinking
+ * narrower still.
+ *
+ * The panel is portaled ({@link PopoverSurface}), so widening the root widens
+ * the TRIGGER only. A menu that should follow it declares `matchTriggerWidth`.
+ */
+export declare function pickerRootClass(fullWidth: boolean): string;
+/**
+ * Guard an async action against double-submit. `run` ignores re-entrant calls
+ * while a promise is in flight and flips `pending` so the caller can disable
+ * the control — the fix for double-charge / double-approve on a slow network.
+ * Settles (success or throw) before clearing, and no-ops state updates after
+ * unmount.
+ */
+export declare function usePending(): {
+    pending: boolean;
+    run: (action: () => void | Promise<void>) => void;
+};
+export interface ModelPickerProps {
+    value: string;
+    onChange: (id: string) => void;
+    /** Catalogue models — from `GET`ing the app's catalogue route (see
+     *  `runtime/model-catalog`), plus any product-specific entries appended. */
+    models: CatalogModel[];
+    loading?: boolean;
+    /** Render a provider logo/badge; default is a generic sparkle. */
+    renderProviderBadge?: (provider: string) => ReactNode;
+    /** Section label for `featured` models. */
+    recommendedLabel?: string;
+    /** Pin a labeled section to the TOP of the list (above Recommended) for the
+     *  models a product wants surfaced first — e.g. a tuner app's own fine-tuned
+     *  models (`{ label: 'Your Fine-Tuned Models', match: (m) => m.provider === 'tuner' }`).
+     *  Matching models are shown only in this section, not duplicated below. */
+    priorityGroup?: {
+        label: string;
+        match: (model: CatalogModel) => boolean;
+    };
+}
+/**
+ * Searchable model picker pill + popover: a featured/recommended section
+ * first, then per-provider groups in catalogue order (the server already
+ * sorts providers by tier).
+ *
+ * This is the CANONICAL ecosystem model picker (see "UI chrome ownership
+ * (picker canon)" in AGENTS.md). sandbox-ui's `dashboard/ModelPicker` is
+ * legacy — deprecated, frozen, removed at sandbox-ui's next major; new code
+ * belongs here.
+ */
+export declare function ModelPicker({ value, onChange, models, loading, renderProviderBadge, recommendedLabel, priorityGroup }: ModelPickerProps): import("react").JSX.Element;
+/** One reasoning-budget level: the engine `id` is unchanged (the value the
+ *  product sends to the loop); only the user-facing `label` is renamed to the
+ *  plainer "how hard should it think" vocabulary from docs/product-surfaces.md.
+ *  `low`→Quick, `medium`→Standard, `high`→Extended. The mapping is overridable
+ *  via `EffortPickerProps.levels`, so a product can relabel without losing the
+ *  ids the runtime expects. */
+export interface EffortLevel {
+    id: string;
+    label: string;
+}
+export declare const DEFAULT_EFFORT_LEVELS: readonly EffortLevel[];
+/**
+ * The user-facing label for an engine level id: the canonical vocabulary when
+ * the id is one this package names, otherwise the id itself made readable
+ * (`auto` -> "Auto", `ultra-code` -> "Ultra code"). Never invents a depth word,
+ * so an id nobody declared a label for still reads as ITSELF and never as some
+ * other level.
+ */
+export declare function effortLevelLabel(id: string): string;
+/**
+ * Build a levels list from the engine ids a backend applies — the shape the
+ * removed `ComposerAgentControls` took as `reasoning.available`, so a product
+ * migrating that list has one call to make instead of a hand-written label map
+ * per product (which is how "Quick" and "Low" drift apart across surfaces).
+ */
+export declare function effortLevelsFromIds(ids: readonly string[]): readonly EffortLevel[];
+/**
+ * The list {@link EffortPicker} RENDERS for `value` — the declared levels, plus
+ * `value` itself when the declaration omits it.
+ *
+ * A picker cannot honestly resolve a selected value it was not given, and the
+ * failure it used to take instead — fall back to the middle entry — renders the
+ * session's real depth as a DIFFERENT level's name. That is exactly the defect
+ * `levels` was added to prevent: the legacy adapter's `available` list excluded
+ * the `auto` sentinel because the old picker injected it, so a product mapping
+ * that list straight across ships a session running on `auto` labelled
+ * "Extended". Admitting the value is not offering a new choice — it is
+ * reporting the state the session is already in, and it disappears from the
+ * list as soon as the user picks a declared level.
+ *
+ * A blank value is not admitted (there is no honest label for it); the picker
+ * renders no selection instead.
+ */
+export declare function reconcileEffortLevels(value: string, levels?: readonly EffortLevel[]): readonly EffortLevel[];
+/** Segments the meter draws — fixed geometry so the ladder stays tabular
+ *  across levels (and across the trigger and its menu rows). */
+export declare const EFFORT_METER_SEGMENTS = 4;
+/**
+ * Filled-segment count for a level: 0 for off/none (or an id the levels list
+ * does not carry); otherwise the level's position among the non-off choices
+ * scaled onto the meter, so the ladder reads low < medium < high and the top
+ * level fills the whole scale. The canonical four levels land 0 / 1 / 2 / 4.
+ */
+export declare function effortMeterFill(levelId: string, levels?: readonly EffortLevel[]): number;
+/**
+ * The thinking-strength meter: four 12px bars, filled count = level, filled
+ * opacity ramping 25→100% left to right (unfilled at a faint ghost). Purely
+ * decorative — the level name is always rendered as text beside it, so the
+ * meter is `aria-hidden` and adds no second accessible name.
+ */
+export declare function EffortMeter({ fill, className }: {
+    fill: number;
+    className?: string;
+}): import("react").JSX.Element;
+export interface EffortPickerProps {
+    value: string;
+    onChange: (id: string) => void;
+    /** Selectable levels (engine id + user-facing label). Defaults to the plain
+     *  "Thinking" vocabulary; override to relabel without changing the ids the
+     *  runtime receives.
+     *
+     *  A list that omits the current `value` is not a rendering error the picker
+     *  papers over: `value` is reconciled INTO the rendered list under its own
+     *  name (see {@link reconcileEffortLevels}), because a control must report
+     *  the depth the session is running at and never some other list entry. */
+    levels?: readonly EffortLevel[];
+    /** Prefix shown before the active level on the pill — the "what is this"
+     *  context the bare value lacked. Default "Thinking". Pass '' to hide it. */
+    label?: string;
+    /** Fill the container instead of shrink-wrapping — opt-in, default `false`;
+     *  see {@link pickerRootClass} for when and why. */
+    fullWidth?: boolean;
+}
+/** Thinking-budget selector pill, styled to match {@link ModelPicker}. Show
+ *  it only when the selected model `supportsReasoning`. "Thinking" is the
+ *  plain-English name for what was internally called "effort".
+ *
+ *  The CANONICAL ecosystem effort picker — sandbox-ui's reasoning menu (inside
+ *  its `chat/AgentSessionControls`) is legacy and frozen. */
+export declare function EffortPicker({ value, onChange, levels, label, fullWidth }: EffortPickerProps): import("react").JSX.Element;

package/dist/web-react/durable-chat-cards.d.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+import { type ChatInteraction, type InteractionAnswers } from './chat-interactions';
+import { type ChatPlan } from '../plans/index';
+import type { DurablePlanDecision, DurablePlanDecisionResult } from './durable-plan-flow';
+import type { SubmitInteractionAnswer } from './interaction-card-support';
+export type DurableChatCard = {
+    kind: 'plan';
+    key: string;
+    plan: ChatPlan;
+} | {
+    kind: 'interaction';
+    key: string;
+    interaction: ChatInteraction;
+};
+/** Converts persisted/live parts to canonical cards. Legacy interaction-plan
+ * cards are suppressed only when their raw part carries an explicit planId and
+ * revision matching a durable plan. Identical markdown alone is never proof. */
+export declare function durableChatCardsFromParts(parts: Array<Record<string, unknown>>): DurableChatCard[];
+export interface DurableChatCardsProps {
+    parts: Array<Record<string, unknown>>;
+    canWrite: boolean;
+    submitInteraction: SubmitInteractionAnswer;
+    decidePlan: (plan: ChatPlan, decision: DurablePlanDecision, feedback?: string) => Promise<DurablePlanDecisionResult | null>;
+    decidingPlan?: (plan: ChatPlan) => DurablePlanDecision | null;
+    planError?: (plan: ChatPlan) => string | null;
+    onInteractionResolved?: (id: string, status: Exclude<ChatInteraction['status'], 'pending'>, answers?: InteractionAnswers) => void;
+    onLateAnswer?: (message: string) => boolean | void | Promise<boolean | void>;
+    /** Fired when the user asks the agent to re-submit an expired/withdrawn
+     *  plan card as a new chat turn; receives that card's interaction. Omit to
+     *  hide the affordance entirely. */
+    onReRequest?: (interaction: ChatInteraction) => boolean | void | Promise<boolean | void>;
+    /** Overrides the default re-request button label. */
+    reRequestLabel?: string;
+    renderMarkdown?: (markdown: string) => ReactNode;
+    className?: string;
+}
+/** Ready-to-embed canonical question/plan card lane for persisted assistant
+ * parts. Apps inject transport and styling callbacks instead of rebuilding the
+ * lifecycle/render switch. */
+export declare function DurableChatCards({ parts, canWrite, submitInteraction, decidePlan, decidingPlan, planError, onInteractionResolved, onLateAnswer, onReRequest, reRequestLabel, renderMarkdown, className, }: DurableChatCardsProps): import("react").JSX.Element | null;