@kortix/ui 0.14.3 → 0.14.5

package/dist/session/composer/agent-selector.js

@@ -0,0 +1,149 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge } from '../../primitives/badge.js';
+import { Button } from '../../primitives/button.js';
+import { CommandGroup, CommandInput, CommandItem, CommandList, CommandPopover, CommandPopoverContent, CommandPopoverTrigger, CommandSeparator, } from '../../primitives/command.js';
+import Hint from '../../primitives/hint.js';
+import { useTranslations } from '../../i18n/index.js';
+import { useUiHostConfig } from '../../providers/ui-provider.js';
+import { cn } from '../../lib/utils.js';
+import { capitalizeWords, isMetaAgentName, META_AGENT_DISPLAY_NAME } from '../../_vendor/kortix-shared.js';
+import { CaretDownIcon, CheckIcon, SparkleIcon } from '@phosphor-icons/react';
+import { useEffect, useMemo, useState } from 'react';
+import { composerSelectableAgents } from './composer-agent-access.js';
+/**
+ * Agents on screen before the popover grows a search field.
+ *
+ * The list caps at 320px and a row is two lines (~48px), so roughly six fit
+ * without scrolling. Up to that point the whole set is readable in one glance
+ * and a search field is pure chrome — it costs a row of height and a focus
+ * stop to filter something the eye has already finished reading. Past it,
+ * scanning becomes scrolling and search starts paying for itself.
+ */
+const SEARCH_MIN_AGENTS = 7;
+/**
+ * The agent a selector shows: the selected one, even before the roster has it,
+ * else the first selectable agent. One rule for the trigger and the chat composer.
+ */
+function resolveDisplayedAgentName(primaryAgents, selectedAgent) {
+    const current = primaryAgents.find((a) => a.name === selectedAgent);
+    return current?.name ?? selectedAgent ?? primaryAgents[0]?.name;
+}
+/** The label `AgentSelector` shows for a selection (null = nothing picked). Other surfaces that name the agent reuse it. */
+export function agentDisplayLabel(agents, selectedAgent) {
+    const name = resolveDisplayedAgentName(composerSelectableAgents(agents), selectedAgent);
+    if (!name)
+        return 'Agent';
+    return isMetaAgentName(name) ? META_AGENT_DISPLAY_NAME : capitalizeWords(name);
+}
+export function AgentSelector({ agents, selectedAgent, onSelect, disabled = false, triggerLabelClassName, unavailableHint, open: controlledOpen, onOpenChange, }) {
+    const tHardcodedUi = useTranslations('hardcodedUi');
+    const t = useTranslations('threads');
+    const [internalOpen, setInternalOpen] = useState(false);
+    const open = controlledOpen ?? internalOpen;
+    const setOpen = onOpenChange ?? setInternalOpen;
+    const [search, setSearch] = useState('');
+    const { offeredAgents, agentLabels } = useUiHostConfig();
+    // A host that lists its agents (`offeredAgents`) offers only those; it names them with `agentLabels`.
+    const offered = useMemo(() => (offeredAgents ? agents.filter((a) => offeredAgents.includes(a.name)) : agents), [agents, offeredAgents]);
+    const primaryAgents = useMemo(() => composerSelectableAgents(offered), [offered]);
+    const label = (name) => agentLabels?.[name] ?? (isMetaAgentName(name) ? META_AGENT_DISPLAY_NAME : capitalizeWords(name));
+    // A `flash` state, a `prevAgentRef` feeding it, two effects and a 400ms
+    // timer used to live here. Nothing ever READ `flash` — it was written on
+    // every agent change and rendered nowhere, so the whole apparatus bought a
+    // re-render and a timer per selection and showed the user nothing.
+    useEffect(() => {
+        if (!open)
+            setSearch('');
+    }, [open]);
+    const filteredPrimary = useMemo(() => {
+        const q = search.toLowerCase().trim();
+        if (!q)
+            return primaryAgents;
+        return primaryAgents.filter((a) => a.name.toLowerCase().includes(q) ||
+            (agentLabels?.[a.name] ?? '').toLowerCase().includes(q) ||
+            (a.description || '').toLowerCase().includes(q));
+    }, [primaryAgents, search, agentLabels]);
+    const filteredMeta = useMemo(() => filteredPrimary.filter((a) => isMetaAgentName(a.name)), [filteredPrimary]);
+    const filteredProject = useMemo(() => filteredPrimary.filter((a) => !isMetaAgentName(a.name)), [filteredPrimary]);
+    // Keyed off the FULL list, never the filtered one: deriving it from
+    // `filteredPrimary` would make the field that is doing the filtering vanish
+    // the moment a query narrowed the list past the threshold, taking the
+    // user's own query with it.
+    const showSearch = primaryAgents.length >= SEARCH_MIN_AGENTS;
+    // The trigger names the agent that will RUN, which is `selectedAgent` even
+    // when the roster does not (yet) contain it: a session bound to `kortix`
+    // must read "Kortix" while the roster query is still in flight, not whatever
+    // happens to be first in someone else's list. The `primaryAgents[0]`
+    // fallback stays only for a truly unresolved selection (no name at all),
+    // matching the resolver's own first-accessible pre-selection.
+    const displayedName = resolveDisplayedAgentName(primaryAgents, selectedAgent);
+    const displayName = displayedName ? label(displayedName) : agentDisplayLabel(offered, selectedAgent);
+    const metaSelected = isMetaAgentName(displayedName);
+    /**
+     * One agent: name, its type, its description, and a check when it is the
+     * one in use.
+     *
+     * The type is a `Badge` on the row rather than a `CommandGroup` heading.
+     * Headings only earn their place when there is more than one section to
+     * tell apart, and there usually is not — most projects have no meta agents
+     * at all, so the list rendered a lone "Agents" label over a single group,
+     * captioning something that needed no caption. A badge says the same thing
+     * where it is actually useful (on the row that differs) and disappears
+     * entirely when every agent is the same kind.
+     *
+     * Selection is shown ONCE, by the check plus the tinted row. It used to be
+     * said three times — check, tinted row, AND a heavier font weight on the
+     * name — which made the selected row's title render at a different weight
+     * from every other title for no added information.
+     */
+    const renderAgentItem = (agent, meta) => {
+        const isSelected = selectedAgent === agent.name || (!selectedAgent && agent === primaryAgents[0]);
+        return (_jsxs(CommandItem, { value: `agent-${agent.name}`, 
+            // `items-start` is what pins the check to the top right: the row is
+            // two lines and a vertically-centred check floats between them,
+            // pointing at neither.
+            className: cn('items-start gap-2 py-2', isSelected && 'bg-primary/[0.06]'), onSelect: () => {
+                onSelect(agent.name);
+                setOpen(false);
+            }, children: [meta && (
+                // Meta is the platform agent that runs the others, so its row leads
+                // with its own mark instead of reading as one more peer in the list.
+                _jsx("span", { className: "bg-muted flex size-8 shrink-0 items-center justify-center rounded-md", children: _jsx(SparkleIcon, { weight: "fill", className: "text-foreground size-4" }) })), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-1.5", children: [_jsx("span", { className: "text-foreground truncate text-sm font-medium", children: label(agent.name) }), meta && (_jsx(Badge, { variant: "outline", size: "xs", className: "shrink-0 font-normal", children: tHardcodedUi.raw('i18nComplete.textc78ffe195710') }))] }), agent.description && (_jsx("p", { className: "text-muted-foreground mt-0.5 truncate text-xs", children: agent.description }))] }), isSelected && (
+                // `mt-0.5` optically centres the 16px check against the first line
+                // rather than the top edge of the text box.
+                _jsx(CheckIcon, { className: "text-foreground mt-0.5 size-4 shrink-0" }))] }, agent.name));
+    };
+    /**
+     * Nothing to pick from.
+     *
+     * The SAME trigger as the loaded state and as the model picker beside it —
+     * same variant, size, radius, label slot and caret — just inert and muted.
+     * It is deliberately not a wide pill, a banner, or an icon of its own: an
+     * empty picker is still a picker, and the composer's bottom rail is a row of
+     * sibling controls, not a place to put a notice. The reason lives in the
+     * tooltip, and on the send button's tooltip, which is where a user who wants
+     * it goes.
+     *
+     * The tooltip hangs off a `<span>` rather than the button: a disabled button
+     * takes no pointer events, so a `Hint` wrapped straight around it would never
+     * open — in exactly the state where its words matter.
+     */
+    if (primaryAgents.length === 0) {
+        const trigger = (_jsxs(Button, { type: "button", variant: "ghost", size: "sm", disabled: true, "aria-label": unavailableHint ?? undefined, className: "text-muted-foreground rounded-lg hit-area-y-3", children: [_jsx("span", { className: cn('max-w-[100px] truncate', triggerLabelClassName), children: displayName }), _jsx(CaretDownIcon, { className: "size-3" })] }));
+        if (!unavailableHint)
+            return trigger;
+        return (_jsx(Hint, { side: "top", label: unavailableHint, children: _jsx("span", { className: "inline-flex", children: trigger }) }));
+    }
+    /**
+     * An inert picker: this host offered the roster but the control is read-only
+     * (a settings form the caller cannot write). The trigger stays — the agent
+     * that would run must remain visible — but it stops pretending to be
+     * interactive: no caret (the one cue that read as "opens a menu"), the muted
+     * text every inert control on this rail wears, and the disabled attribute.
+     */
+    if (disabled) {
+        return (_jsxs(Button, { type: "button", variant: "ghost", size: "sm", disabled: true, className: "text-muted-foreground rounded-lg hit-area-y-3", children: [metaSelected && _jsx(SparkleIcon, { className: "size-3.5 shrink-0", weight: "fill" }), _jsx("span", { className: cn('max-w-[100px] truncate', triggerLabelClassName), children: displayName })] }));
+    }
+    return (_jsxs(CommandPopover, { open: open, onOpenChange: setOpen, children: [_jsx(CommandPopoverTrigger, { children: _jsxs(Button, { type: "button", variant: "ghost", size: "sm", "aria-label": t('selectAgent'), className: "text-foreground/70 rounded-lg hit-area-y-3", children: [metaSelected && _jsx(SparkleIcon, { className: "size-3.5 shrink-0", weight: "fill" }), _jsx("span", { className: cn('max-w-[100px] truncate', triggerLabelClassName), children: displayName }), _jsx(CaretDownIcon, { className: cn('size-3 transition-transform duration-200 ease-out', open && 'rotate-180') })] }) }), _jsxs(CommandPopoverContent, { side: "top", align: "start", sideOffset: 8, className: "w-[min(300px,calc(100vw-1.5rem))]", children: [_jsx("div", { className: showSearch ? undefined : 'sr-only', children: _jsx(CommandInput, { compact: true, placeholder: tHardcodedUi.raw('componentsSessionSessionChatInput.line231JsxAttrPlaceholderSearchAgents'), value: search, onValueChange: setSearch }) }), _jsxs(CommandList, { className: "max-h-[320px]", children: [filteredPrimary.length > 0 && (_jsxs(CommandGroup, { forceMount: true, children: [filteredMeta.map((agent) => renderAgentItem(agent, true)), filteredMeta.length > 0 && filteredProject.length > 0 && (_jsx(CommandSeparator, { className: "my-1" })), filteredProject.map((agent) => renderAgentItem(agent, false))] })), filteredPrimary.length === 0 && search.trim() && (_jsxs("div", { className: "text-muted-foreground/50 py-8 text-center text-xs", children: [tHardcodedUi.raw('componentsSessionSessionChatInput.line273JsxTextNoAgentsMatchLdquo'), search.trim(), tHardcodedUi.raw('componentsSessionSessionChatInput.line273JsxTextRdquo')] }))] })] })] }));
+}

package/dist/session/composer/animated-placeholder.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The rotating hint copy. Every line is pinned to a shortcut or feature that
+ * actually exists in THIS composer — the old list claimed "Up arrow to recall
+ * your last prompt", a textarea-era feature the TipTap rebuild dropped, so a
+ * new line only enters this list with its handler named:
+ *
+ *  - `/` and `@`      → editor/composer-editor.tsx suggestion extensions
+ *  - ⌘K / Ctrl+K      → workspace/command-palette.tsx, mounted by the host
+ *  - Tab              → `cycleAgent` in composer.tsx
+ *  - ⌘, / Ctrl+,      → the host's settings shortcut
+ *  - Shift+Enter      → hard break in editor/extensions.ts
+ *  - drag & drop      → `handleDropFiles` in composer.tsx
+ *
+ * The two host shortcuts show only when the host says it handles them
+ * (`UiHostConfig.commandPaletteShortcut` / `settingsShortcut`).
+ *
+ * `base` is always index 0. That is what makes the platform-aware shortcuts
+ * hydration-safe: the server renders index 0 (no `navigator`, no ⌘/Ctrl
+ * decision in it), and every shortcut variant appears only after the first
+ * client-side interval tick.
+ */
+export interface ComposerPlaceholderCopy {
+    skills: string;
+    mentions: string;
+    workspaceFile: string;
+    commandPalette: (modifier: string) => string;
+    switchAgents: string;
+    attachFiles: string;
+    changed: string;
+    newLine: string;
+    settings: (modifier: string) => string;
+    compact: string;
+}
+/** The shortcuts the host handles, not the composer. */
+export interface HostShortcuts {
+    commandPalette: boolean;
+    settings: boolean;
+}
+export declare function buildPlaceholderVariants(base: string, mac: boolean, copy?: ComposerPlaceholderCopy, host?: HostShortcuts): string[];
+export interface AnimatedComposerPlaceholderProps {
+    /** The caller's base placeholder — always the first (and SSR-rendered) frame. */
+    placeholder: string;
+    /**
+     * Empty draft, no lock, not disabled. While false the component renders
+     * nothing and the interval stops; the editor's own static placeholder
+     * takes over (locks and disabled states keep their functional copy).
+     */
+    active: boolean;
+}
+/**
+ * The rotating placeholder, drawn OVER the TipTap editor rather than in it.
+ *
+ * TipTap's Placeholder extension paints a `::before` pseudo-element
+ * (`content: attr(data-placeholder)` — styles/components.css), and pseudo-element
+ * content cannot animate between two strings. So while this overlay is
+ * active the composer passes `''` to the editor — the `::before` renders
+ * empty — and this absolutely-positioned sibling carries the visible text.
+ * `aria-hidden` + `pointer-events-none`: it is decoration over a live
+ * textbox whose `aria-label` already names it.
+ *
+ * `initial={false}`: no roll-in on mount, and none when the overlay comes
+ * back after a draft is deleted — a restored placeholder should read as
+ * state, not an event. Only the interval's rotation animates.
+ */
+export declare function AnimatedComposerPlaceholder({ placeholder, active, }: AnimatedComposerPlaceholderProps): import("react").JSX.Element | null;

package/dist/session/composer/animated-placeholder.js

@@ -0,0 +1,119 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+import { AnimatePresence, m, useReducedMotion } from 'motion/react';
+import { useTranslations } from '../../i18n/index.js';
+import { useUiHostConfig } from '../../providers/ui-provider.js';
+import { useEffect, useMemo, useState } from 'react';
+import { COMPOSER_TEXT_METRICS } from './composer-text-metrics.js';
+/** Same idiom as `project-sidebar.tsx` — module-level, SSR-safe (false on the server). */
+const isMac = typeof navigator !== 'undefined' && /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+/** How long each hint stays before rotating to the next. */
+const HOLD_MS = 6000;
+/**
+ * The swap animations, verbatim from `session-busy-indicator.tsx` so the two
+ * rotating-text surfaces in a session read as one system: the outgoing line
+ * rolls up and out while the incoming one rolls up from below (`popLayout`
+ * overlaps them — a ticker, not a crossfade). `translateY(±100%)` is
+ * self-relative, so the roll distance is exactly one line at any font size,
+ * and the full `transform` string keeps it hardware-accelerated.
+ */
+const ROLL_SWAP = {
+    initial: { transform: 'translateY(100%)', opacity: 0 },
+    animate: { transform: 'translateY(0%)', opacity: 1 },
+    exit: { transform: 'translateY(-100%)', opacity: 0 },
+    transition: { type: 'spring', duration: 0.4, bounce: 0 },
+};
+const FADE_SWAP = {
+    initial: { opacity: 0 },
+    animate: { opacity: 1 },
+    exit: { opacity: 0 },
+    transition: { duration: 0.2, ease: 'easeOut' },
+};
+const ENGLISH_PLACEHOLDER_COPY = {
+    skills: 'Type / for skills, commands, and files',
+    mentions: 'Type @ to mention files and agents',
+    workspaceFile: 'Ask about any file in your workspace',
+    commandPalette: (modifier) => `Press ${modifier}K to open the command palette`,
+    switchAgents: 'Press Tab to switch agents',
+    attachFiles: 'Drag and drop files to attach them',
+    changed: "Ask what's changed in your project",
+    newLine: 'Press Shift+Enter for a new line',
+    settings: (modifier) => `Press ${modifier}, to open settings`,
+    compact: 'Ask to compact the session when it gets long',
+};
+export function buildPlaceholderVariants(base, mac, copy = ENGLISH_PLACEHOLDER_COPY, host = { commandPalette: false, settings: false }) {
+    const mod = mac ? '⌘' : 'Ctrl+';
+    return [
+        base,
+        copy.skills,
+        copy.mentions,
+        copy.workspaceFile,
+        host.commandPalette && copy.commandPalette(mod),
+        copy.switchAgents,
+        copy.attachFiles,
+        copy.changed,
+        copy.newLine,
+        host.settings && copy.settings(mod),
+        copy.compact,
+    ].filter((line) => typeof line === 'string');
+}
+/**
+ * The rotating placeholder, drawn OVER the TipTap editor rather than in it.
+ *
+ * TipTap's Placeholder extension paints a `::before` pseudo-element
+ * (`content: attr(data-placeholder)` — styles/components.css), and pseudo-element
+ * content cannot animate between two strings. So while this overlay is
+ * active the composer passes `''` to the editor — the `::before` renders
+ * empty — and this absolutely-positioned sibling carries the visible text.
+ * `aria-hidden` + `pointer-events-none`: it is decoration over a live
+ * textbox whose `aria-label` already names it.
+ *
+ * `initial={false}`: no roll-in on mount, and none when the overlay comes
+ * back after a draft is deleted — a restored placeholder should read as
+ * state, not an event. Only the interval's rotation animates.
+ */
+export function AnimatedComposerPlaceholder({ placeholder, active, }) {
+    const t = useTranslations('threads');
+    const { commandPaletteShortcut, settingsShortcut } = useUiHostConfig();
+    const reduceMotion = useReducedMotion();
+    const variants = useMemo(() => buildPlaceholderVariants(placeholder, isMac, {
+        skills: t('hintSkills'),
+        mentions: t('hintMentions'),
+        workspaceFile: t('hintWorkspaceFile'),
+        commandPalette: (modifier) => t('hintCommandPalette', { modifier }),
+        switchAgents: t('hintSwitchAgents'),
+        attachFiles: t('hintAttachFiles'),
+        changed: t('hintChanged'),
+        newLine: t('hintNewLine'),
+        settings: (modifier) => t('hintSettings', { modifier }),
+        compact: t('hintCompact'),
+    }, { commandPalette: commandPaletteShortcut, settings: settingsShortcut }), [placeholder, t, commandPaletteShortcut, settingsShortcut]);
+    const [index, setIndex] = useState(0);
+    // The index survives deactivation on purpose: type, delete, and the
+    // rotation resumes where it was instead of restarting the same first hints.
+    useEffect(() => {
+        if (!active)
+            return;
+        const id = setInterval(() => {
+            setIndex((i) => (i + 1) % variants.length);
+        }, HOLD_MS);
+        return () => clearInterval(id);
+    }, [active, variants.length]);
+    if (!active)
+        return null;
+    const swap = reduceMotion ? FADE_SWAP : ROLL_SWAP;
+    return (_jsx("div", { "aria-hidden": true, 
+        // `inset-x-2` mirrors the wrapper's `px-2`; the font classes mirror
+        // `ComposerEditor`'s own, so the overlay sits exactly where the static
+        // placeholder would. `overflow-hidden` clips the roll to one line.
+        //
+        // `COMPOSER_TEXT_METRICS` is the rest of that mirror, and it is NOT
+        // optional: `inset-x-2` only reaches the wrapper's padding box, so any
+        // horizontal padding on the contenteditable inside it is invisible from
+        // out here. Without this the overlay draws its first glyph at the
+        // wrapper's edge while the caret underneath it sits one inset further
+        // in — the placeholder and the cursor stop agreeing on where the line
+        // starts. See composer-text-metrics.ts.
+        className: cn('text-muted-foreground pointer-events-none absolute inset-x-1 top-0 overflow-hidden text-sm', COMPOSER_TEXT_METRICS), children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, children: _jsx(m.span, { initial: swap.initial, animate: swap.animate, exit: swap.exit, transition: swap.transition, className: "block min-w-0 truncate", children: variants[index] }, `${index}:${variants[index]}`) }) }));
+}

package/dist/session/composer/attachment-submission.d.ts

@@ -0,0 +1,184 @@
+import type { PromptAttachmentItem, SessionPromptPart } from '@kortix/sdk';
+import type { AttachmentUploadStatus } from '../turn/user-message.js';
+import type { AttachedFile } from './types.js';
+/** The controller surface one Send uses. `usePromptAttachments` satisfies it. */
+export interface AttachmentSubmissionController {
+    readonly attachments: readonly PromptAttachmentItem[];
+    submit: (ids: readonly string[]) => void;
+    retry: (id: string) => void;
+    forget: (ids: readonly string[]) => void;
+    reclaim: (ids: readonly string[]) => void;
+    whenReady: (ids: readonly string[], options?: {
+        signal?: AbortSignal;
+    }) => Promise<SessionPromptPart[]>;
+}
+/**
+ * One Send's handed-off uploads. The host paints, then awaits `whenReady`
+ * before its POST, and releases the uploads once the POST is accepted.
+ */
+export interface AttachmentSubmission {
+    readonly submittedIds: readonly string[];
+    /** Every selected upload was ready at Send, so `whenReady` resolves at once. */
+    readonly readyAtSend: boolean;
+    whenReady: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<SessionPromptPart[]>;
+    /** Restart this send's failed uploads with the same File and `attachment_id`. */
+    retry: () => void;
+    /**
+     * Hand this send's uploads off again after `reclaim` returned them to the tray: a refused send
+     * that a later Retry delivers (the connector gate) needs them to outlive the composer.
+     */
+    resubmit: () => void;
+    /** Release this send's uploads after its prompt POST is accepted. */
+    release: () => void;
+}
+export interface StageComposerFilesDependencies {
+    addMany: (files: readonly File[]) => string[];
+    createObjectURL: (file: File) => string;
+    isImage: (file: File) => boolean;
+}
+/** The bytes of each tray file the controller lists: what a new drop is counted against. */
+export declare function heldTraySizes(files: readonly AttachedFile[]): number[];
+/** Why a file was left out of a drop or a pick. */
+export type RefusedFileReason = 'empty' | 'tooLarge' | 'tooMany' | 'totalTooLarge';
+/**
+ * Split a drop or a pick into the files that fit and the files that do not,
+ * against the message limits the SDK enforces (`@kortix/shared`). `held` is
+ * what the tray already holds. The SDK refuses a whole batch when one file is
+ * out of bounds, so every file that fits must be split off first (KRTX-2557).
+ */
+export declare function splitComposerFiles(files: readonly File[], held: {
+    count: number;
+    bytes: number;
+}): {
+    accepted: File[];
+    refused: {
+        file: File;
+        reason: RefusedFileReason;
+    }[];
+};
+/** The toast for the files a drop left out: how many, then each by name and why. */
+export declare function refusedFilesToast(refused: readonly {
+    file: File;
+    reason: RefusedFileReason;
+}[], t: (key: string, values?: Record<string, string | number>) => string): {
+    title: string;
+    description: string;
+};
+/** Validate and start every upload before creating preview URLs or React state. */
+export declare function stageComposerFiles(files: readonly File[], dependencies: StageComposerFilesDependencies): Extract<AttachedFile, {
+    kind: 'local';
+}>[];
+export declare function attachedFileUploadId(file: AttachedFile): string | undefined;
+/** Resources owned only by a replaced composer tray. Active submissions keep ownership. */
+export declare function planAttachmentReplacement(current: readonly AttachedFile[], next: readonly AttachedFile[], protectedIds: ReadonlySet<string>): {
+    idsToRemove: string[];
+    urlsToRevoke: string[];
+};
+/** A failed upload refuses Send. Pending, uploading, and processing uploads never do. */
+export declare function attachmentsBlockSend(items: readonly Pick<PromptAttachmentItem, 'status'>[]): boolean;
+/**
+ * Why an upload or a painted send failed, in the terms the UI words and acts on.
+ * `connection` is every failure the same File can recover from on Retry.
+ */
+export type AttachmentFailureReason = 'billing' | 'budget' | 'tooLarge' | 'expired' | 'connection';
+export declare function attachmentFailureReason(error: unknown): AttachmentFailureReason;
+/** Retry sends the same File again. A refusal (billing, budget, size, expiry) answers the same way. */
+export declare function attachmentFailureRetryable(reason: AttachmentFailureReason): boolean;
+/**
+ * The `hardcodedUi.composerAttachments` line under "Couldn't send" for each reason. A sent
+ * message never says "Upload failed": upload state belongs to the composer tile.
+ */
+export declare const SENT_FAILURE_COPY: {
+    readonly billing: "billingRequired";
+    readonly budget: "budgetExceeded";
+    readonly tooLarge: "tooLarge";
+    readonly expired: "expired";
+    readonly connection: "checkConnection";
+};
+/**
+ * The line under "Couldn't send" for a painted send's failure. A 4xx refusal with no copy of its
+ * own (400, 403, 409, 429) is not a connection problem: it says what the server said, or
+ * `ownMessage` when the caller already classified the error. Every other failure uses its copy.
+ */
+export declare function sentFailureMessage(error: unknown, words: (key: (typeof SENT_FAILURE_COPY)[AttachmentFailureReason]) => string, ownMessage?: string): string;
+/**
+ * Billing refusals among `items` that `seen` has not recorded yet. The composer opens the
+ * plan dialog for them once; a failed tile stays in later snapshots without a second dialog.
+ */
+export declare function takeNewBillingRefusals(items: readonly Pick<PromptAttachmentItem, 'status' | 'error'>[], seen: WeakSet<object>): Error[];
+/**
+ * Hand one Send's selected uploads to its host, synchronously.
+ *
+ * Send never waits for an upload: the selection is handed off and the host is
+ * called in the same tick. Returns `null`, handing nothing off, only when a
+ * selected upload failed. The Send control states that reason, so no toast.
+ */
+export declare function captureAttachmentSubmission(files: readonly AttachedFile[], controller: AttachmentSubmissionController, holdUnload?: <T>(work: Promise<T>) => Promise<T>): AttachmentSubmission | null;
+/**
+ * One composer Send after capture. The submitted ids stay protected from a
+ * tray replacement while the host takes the send. A host that throws refused
+ * the send before anything durable happened: the uploads return to the tray
+ * and `onFailed` restores the draft. A detached send (one with uploads, or one
+ * behind an earlier send of its session) never throws here (`deliverAfterPaint`).
+ */
+export declare function runComposerSend(input: {
+    submission: AttachmentSubmission;
+    controller: Pick<AttachmentSubmissionController, 'reclaim'>;
+    active: Set<string>;
+    send: () => unknown;
+    onSent: () => void;
+    onFailed: () => void;
+}): Promise<void>;
+/**
+ * Whether a painted send is delivered detached from the composer: it carries
+ * uploads, or an earlier send of the same session is still being delivered.
+ * A caller with no submission is not the composer, and it always waits.
+ */
+export declare function deliversDetached(sessionKey: string, submission: AttachmentSubmission | undefined): boolean;
+/**
+ * Deliver a send whose message is already painted, in its session's Send order.
+ *
+ * Every delivery takes its place in the session's chain (`deliverInOrder`), so
+ * POSTs leave in Enter order. A detached send (`deliversDetached`) returns
+ * `painted` at once: the composer's dispatch settles now, so the next Send
+ * paints at once instead of waiting behind an upload or an earlier POST.
+ * `deliver` then owns every failure and keeps the message on screen, marked
+ * failed with Retry. Any other send waits for `deliver`, so a refusal still
+ * returns its draft. `deliver` is told which of the two it is.
+ *
+ * `immediate` is the one exception, for a send with no uploads: it POSTs at
+ * once, outside the chain, takes no place in it, and waits for `deliver`. The
+ * inline edit's send uses it. It commits the rewind it staged, so it must not
+ * wait behind an earlier send that would commit that rewind first.
+ */
+export declare function deliverAfterPaint<T>(sessionKey: string, submission: AttachmentSubmission | undefined, deliver: (detached: boolean) => Promise<T>, painted: T, options?: {
+    immediate?: boolean;
+}): Promise<T>;
+/**
+ * Post a painted send once its uploads are ready, then release them.
+ *
+ * The wait and the POST take the session's next place in its delivery chain
+ * at this call, so the POST leaves after every earlier send of the session. A
+ * painted message is never taken back. When an upload or the POST fails,
+ * `onStatus` receives a failed status for the message, worded by `describe`,
+ * and the chain moves on. Its Retry restarts the failed uploads at once
+ * (finished uploads are not sent again) and posts again from the chain's tail.
+ */
+export declare function postWhenUploaded(sessionKey: string, submission: AttachmentSubmission, post: (parts: SessionPromptPart[]) => Promise<unknown>, onStatus: (status: AttachmentUploadStatus | undefined) => void, describe: (error: unknown) => string): Promise<void>;
+/**
+ * How one composer dispatch ended. `'sent'`: a host took the draft.
+ * `'answered'`: an open question took its text only. Nothing: refused before
+ * any host.
+ */
+export type DispatchOutcome = 'sent' | 'answered' | void;
+/**
+ * Run one latched dispatch. A stashed draft left the editor and handed its
+ * uploads off at Enter. When its dispatch does not reach a host, the uploads
+ * return to the tray and `restore` puts the draft back: text and files, or only
+ * the files when a question took the text.
+ */
+export declare function dispatchLatched<S extends {
+    attachmentSubmission: AttachmentSubmission;
+}>(stash: S | undefined, dispatch: (stash?: S) => Promise<DispatchOutcome>, controller: Pick<AttachmentSubmissionController, 'reclaim'>, restore: (stash: S, withText: boolean) => void): Promise<void>;