@kortix/ui 0.0.0-stage → 0.14.4

package/dist/session/composer/attachment-tiles.js

@@ -0,0 +1,201 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import { Button } from '../../primitives/button.js';
+import Hint from '../../primitives/hint.js';
+import { IconRefresh } from '../../primitives/kortix-icons.js';
+import { ProgressRing } from '../../primitives/progress-ring.js';
+import { useTranslations } from '../../i18n/index.js';
+import { cn } from '../../lib/utils.js';
+import { convertHeicBlobToJpeg, isHeicFile } from '../../internal/lib/utils/heic-convert.js';
+import { PastedTextModal } from './pasted-text.js';
+import { holdConvertedPreview } from './sent-attachment-previews.js';
+import { AttachmentRemoveButton, AttachmentTile, PASTE_PREVIEW_CHARS, isPreviewableImage, } from './attachment-tile.js';
+import { attachmentFailureReason, attachmentFailureRetryable, } from './attachment-submission.js';
+const REASON_COPY = {
+    billing: 'billingRequired',
+    budget: 'budgetExceeded',
+    tooLarge: 'tooLarge',
+    expired: 'expired',
+    connection: 'uploadFailed',
+};
+/** Resolve the failure reasons, the Retry label, and the failure announcement from the active locale. */
+export function attachmentTileCopy(t) {
+    return {
+        uploadFailed: t('uploadFailed'),
+        failureReason: (reason) => t(REASON_COPY[reason]),
+        retryNamed: (name) => t('retryNamed', { name }),
+        didNotUpload: (name) => t('didNotUpload', { name }),
+    };
+}
+/** The two shapes of `AttachedFile` disagree on where the name lives. */
+function attachmentName(af) {
+    return af.kind === 'local' ? af.file.name : af.filename;
+}
+function attachmentMime(af) {
+    return af.kind === 'local' ? af.file.type : af.mime;
+}
+/** The ring waits this long after attach, so a small file never flashes upload chrome. */
+const RING_DELAY_MS = 400;
+const browserTimers = {
+    now: () => Date.now(),
+    set: (callback, delayMs) => setTimeout(callback, delayMs),
+    clear: (handle) => clearTimeout(handle),
+};
+/**
+ * A `useSyncExternalStore` subscription that notifies once `due` has passed.
+ * A timer can fire a little before `due` against `Date.now()`; it then re-arms
+ * for the remainder, so the render at `due` is never skipped.
+ */
+export function subscribeWhenDue(due, timers = browserTimers) {
+    return (notify) => {
+        let handle;
+        const check = () => {
+            const remaining = due - timers.now();
+            if (remaining > 0)
+                handle = timers.set(check, remaining);
+            else
+                notify();
+        };
+        handle = timers.set(check, Math.max(0, due - timers.now()));
+        return () => timers.clear(handle);
+    };
+}
+/**
+ * Whether `due` has passed. Time is an external source, so it is read through
+ * `useSyncExternalStore`. While `waiting`, one timer re-renders at `due`.
+ */
+function useTimePassed(due, waiting) {
+    const subscribe = useCallback((notify) => (waiting ? subscribeWhenDue(due)(notify) : () => { }), [due, waiting]);
+    const passed = () => Date.now() >= due;
+    return useSyncExternalStore(subscribe, passed, passed);
+}
+/**
+ * The upload's corner mark: a determinate ring, shown only when the upload
+ * still runs 400 ms after attach. On ready it fades out in place.
+ */
+function UploadRing({ upload, attachedAt, name, }) {
+    const running = upload.status === 'pending' || upload.status === 'uploading' || upload.status === 'processing';
+    const shown = useTimePassed(attachedAt + RING_DELAY_MS, running);
+    if (!shown)
+        return null;
+    const percent = upload.status === 'pending'
+        ? 0
+        : upload.status === 'uploading'
+            ? Math.min(100, Math.floor((upload.receivedBytes / upload.size) * 100))
+            : 100;
+    return (_jsx("span", { "data-slot": "upload-ring", role: running ? 'progressbar' : undefined, "aria-label": running ? name : undefined, "aria-valuemin": running ? 0 : undefined, "aria-valuemax": running ? 100 : undefined, "aria-valuenow": running ? percent : undefined, "aria-hidden": running ? undefined : true, className: cn('flex transition-opacity duration-(--duration-moderate) ease-out', running ? 'opacity-100' : 'opacity-0'), children: _jsx(ProgressRing, { value: percent }) }));
+}
+/**
+ * A locally attached image.
+ *
+ * HEIC is decoded to JPEG first — browsers cannot render HEIC natively —
+ * carried over verbatim from the old `attachment-preview.tsx`. The decode is
+ * async, so until it resolves the tile falls back to the named treatment,
+ * matching how the sent message's own `AttachmentImage` handles a src that
+ * has not resolved yet (`turn/user-message.tsx`).
+ */
+function AttachmentImageTile({ af, name, corner, overlay, }) {
+    const isHeic = isHeicFile(name);
+    const [heicUrl, setHeicUrl] = useState(null);
+    // WHICH file failed, not merely "something failed". Storing the attachment
+    // itself makes the reset free: a new `af` no longer matches, so the flag
+    // clears by comparison instead of by a `setState` in the effect body (which
+    // is a cascading render, and what the React Compiler rule flags).
+    //
+    // Before this existed, a failed decode was indistinguishable from one still
+    // running — `.catch(() => {})` swallowed the rejection and the tile spun
+    // forever on a file that was never going to render.
+    const [failedFor, setFailedFor] = useState(null);
+    const failed = failedFor === af;
+    useEffect(() => {
+        if (!isHeic || af.kind !== 'local')
+            return;
+        let cancelled = false;
+        let letGo = null;
+        convertHeicBlobToJpeg(af.file)
+            .then((jpeg) => {
+            if (cancelled)
+                return;
+            const objectUrl = URL.createObjectURL(jpeg);
+            // A Send takes this JPEG as the sent message's picture.
+            letGo = af.uploadId
+                ? holdConvertedPreview(af.uploadId, objectUrl)
+                : () => URL.revokeObjectURL(objectUrl);
+            setHeicUrl(objectUrl);
+        })
+            .catch(() => {
+            if (!cancelled)
+                setFailedFor(af);
+        });
+        return () => {
+            cancelled = true;
+            letGo?.();
+        };
+        // `af` (not `af.file`) matches the dependency the original
+        // `attachment-preview.tsx` HEIC effect tracked.
+    }, [af, isHeic]);
+    // A restored upload (`uploaded`) has no picture in this tab: the named tile below.
+    const src = isHeic
+        ? heicUrl
+        : af.kind === 'local'
+            ? af.localUrl
+            : af.kind === 'remote'
+                ? af.url
+                : undefined;
+    // Fall back to the named tile — the file is still attached and still sends;
+    // only the thumbnail is unavailable.
+    if (failed || !src)
+        return (_jsx(AttachmentTile, { filename: name, mime: attachmentMime(af), corner: corner, overlay: overlay }));
+    return (_jsx(AttachmentTile, { filename: name, mime: attachmentMime(af), imageSrc: src, corner: corner, overlay: overlay }));
+}
+export function AttachmentTiles({ files, uploads = [], onRemove, onRetry, pastes = [], onRemovePaste, onOpenPaste, }) {
+    const t = useTranslations('hardcodedUi.composerAttachments');
+    const copy = attachmentTileCopy(t);
+    // A host with no side panel (project home) opens the paste in a modal instead.
+    const [modalText, setModalText] = useState(null);
+    if (files.length === 0 && pastes.length === 0)
+        return null;
+    // One row that scrolls sideways, never a second row: at 720×480 six wrapped
+    // tiles left the transcript ~60px. `pt-1.5 -mt-1.5` keeps the remove dots
+    // (`-top-1.5`) inside the scroll box, which clips both axes.
+    return (_jsxs("ul", { className: "scrollbar-hide -mt-1.5 flex gap-2 overflow-x-auto px-3 pt-1.5", children: [_jsx(PastedTextModal, { text: modalText, onClose: () => setModalText(null) }), pastes.map((paste) => (
+            // The same `contents` li + `relative` box split as the file tiles below.
+            _jsx("li", { className: "contents", children: _jsxs("div", { className: "group relative", children: [_jsx(AttachmentTile, { filename: "Pasted text", preview: paste.text.slice(0, PASTE_PREVIEW_CHARS), onOpen: () => (onOpenPaste ? onOpenPaste(paste) : setModalText(paste.text)) }), onRemovePaste && (_jsx(AttachmentRemoveButton, { filename: "pasted text", onRemove: () => onRemovePaste(paste.id) }))] }) }, `paste:${paste.id}`))), files.map((af, i) => {
+                const name = attachmentName(af);
+                const uploadId = af.kind === 'remote' ? undefined : af.uploadId;
+                const upload = uploadId ? uploads.find((item) => item.id === uploadId) : undefined;
+                // `submit` unlists an id: a send holds it now, so this tray cannot remove it.
+                const held = uploadId !== undefined && !upload;
+                const failed = upload?.status === 'error' || upload?.status === 'aborted';
+                const running = upload?.status === 'pending' ||
+                    upload?.status === 'uploading' ||
+                    upload?.status === 'processing';
+                const corner = upload && !failed ? (_jsx(UploadRing, { upload: upload, attachedAt: af.kind === 'local' ? (af.attachedAt ?? 0) : 0, name: name })) : undefined;
+                // A refusal (billing, budget, size, expiry) answers Retry the same way, so it
+                // offers only Remove. The reason is a tooltip on the whole tile and a line for
+                // screen readers.
+                const reason = failed ? attachmentFailureReason(upload?.error) : undefined;
+                const overlay = upload && reason ? (_jsx(Hint, { label: copy.failureReason(reason), side: "top", children: _jsxs("span", { className: "bg-background/70 absolute inset-0 flex items-center justify-center", children: [_jsx("span", { className: "sr-only", children: copy.failureReason(reason) }), onRetry && upload.file && attachmentFailureRetryable(reason) && (_jsx(Button, { type: "button", variant: "outline", size: "icon", "aria-label": copy.retryNamed(name), onClick: () => onRetry(upload.id), children: _jsx(IconRefresh, {}) }))] }) })) : undefined;
+                const tile = af.isImage && isPreviewableImage(name, attachmentMime(af)) ? (_jsx(AttachmentImageTile, { af: af, name: name, corner: corner, overlay: overlay })) : (_jsx(AttachmentTile, { filename: name, mime: attachmentMime(af), corner: corner, overlay: overlay }));
+                return (
+                // `li` stays `display: contents` (no box of its own — matches the
+                // pattern `turn/user-message.tsx` uses for its own `<li>`s), so it
+                // is transparent to the `ul`'s flex-wrap layout. Its child below is
+                // the REAL positioned box: `relative`, but deliberately NOT the
+                // `overflow-hidden` tile div itself — the remove button's negative
+                // corner offset needs to sit outside the tile's edge, and nesting
+                // it inside an `overflow-hidden` ancestor would clip that corner
+                // off. This is the same two-box split `attachment-preview.tsx` used
+                // (an outer plain `relative` wrapper, an inner `overflow-hidden`
+                // thumbnail box) — `relative` on a `contents` element is inert, so
+                // that split has to live one level in from the `<li>`, not on it.
+                _jsx("li", { className: "contents", children: _jsxs("div", { className: "group relative", "aria-busy": running || undefined, children: [tile, !held && _jsx(AttachmentRemoveButton, { filename: name, onRemove: () => onRemove(i) }), _jsx("span", { className: "sr-only", "aria-live": "polite", children: failed ? copy.didNotUpload(name) : '' })] }) }, uploadId
+                    ? `attachment:${uploadId}`
+                    : af.kind === 'remote'
+                        ? af.url
+                        : af.kind === 'local'
+                            ? af.localUrl
+                            : af.uploadId));
+            })] }));
+}

package/dist/session/composer/clipboard-files.d.ts

@@ -0,0 +1,16 @@
+export interface ClipboardItemLike {
+    readonly kind: string;
+    getAsFile(): File | null;
+}
+export interface ClipboardPayload {
+    readonly files: ArrayLike<File>;
+    readonly items: ArrayLike<ClipboardItemLike>;
+}
+/**
+ * Pull pasted files off a clipboard payload. Prefers the `files` list — which
+ * covers copied image files and most screenshot pastes — and falls back to
+ * `items` of kind `'file'` for browsers that only expose a pasted image there.
+ * Returns an empty array for a plain-text paste so callers can let the browser
+ * handle the text itself.
+ */
+export declare function extractClipboardFiles(data: ClipboardPayload | null | undefined): File[];

package/dist/session/composer/clipboard-files.js

@@ -0,0 +1,23 @@
+/**
+ * Pull pasted files off a clipboard payload. Prefers the `files` list — which
+ * covers copied image files and most screenshot pastes — and falls back to
+ * `items` of kind `'file'` for browsers that only expose a pasted image there.
+ * Returns an empty array for a plain-text paste so callers can let the browser
+ * handle the text itself.
+ */
+export function extractClipboardFiles(data) {
+    if (!data)
+        return [];
+    const fromFiles = Array.from(data.files);
+    if (fromFiles.length > 0)
+        return fromFiles;
+    const fromItems = [];
+    for (const item of Array.from(data.items)) {
+        if (item.kind !== 'file')
+            continue;
+        const file = item.getAsFile();
+        if (file !== null)
+            fromItems.push(file);
+    }
+    return fromItems;
+}

package/dist/session/composer/command-attachments.d.ts

@@ -0,0 +1,151 @@
+import type { UiTranslator } from '../../i18n/index.js';
+/**
+ * Whether a `/` command submission may carry the composer's attachments.
+ *
+ * It may not, and the honest answer is to say so.
+ *
+ * `handleSubmit`'s command branch used to ignore `attachedFiles` completely
+ * and then clear them — revoking every `blob:` URL on the way out. Attach a
+ * screenshot, run `/webapp`, and the screenshot was gone with nothing on
+ * screen to say it had ever existed. The queued command path introduced in
+ * `27279d2232` inherited the same hole: it passes `undefined` for files.
+ *
+ * ## Why refuse instead of carrying the files
+ *
+ * Carrying them is the better product outcome and it is not reachable from
+ * here. The wire call is `client.session.command(...)`, which opencode does
+ * accept a `parts` array for — but every layer between this composer and that
+ * call drops it: `useSession.runCommand(command, args, options)` takes no
+ * parts, `buildSessionCommandInput` builds `{sessionId, command, args, agent,
+ * model, variant}`, and `executeOpenCodeCommand` forwards exactly those six
+ * fields. All three live in `@kortix/sdk`, and a host must never reach past
+ * the SDK to the opencode client (see the repo's SDK rules). So the file parts
+ * cannot be delivered without a change to the published package.
+ *
+ * Refusing keeps the one property that matters: nothing the user attached is
+ * ever destroyed without being sent or reported. The composer disables submit,
+ * shows the reason inline, and keeps every file — so the user picks which of
+ * the two things they meant, with both still in front of them.
+ *
+ * Pure, and tested, because `composer.tsx` cannot be: `apps/web` has no DOM
+ * harness, and the composer sits behind a `React.lazy` boundary.
+ */
+/**
+ * The `data-*` attribute a mention chip renders its kind into, and the value a
+ * `/` command chip carries — see `editor/mention-node.ts`'s `addAttributes`.
+ *
+ * The composer needs to know a command chip is in the draft *while the user is
+ * typing*, not only at submit: the warning has to appear before anything can
+ * be lost. The editor's `onEmptyChange` fires only on the empty↔non-empty
+ * boundary (`trackEmptyBoundary`), so it cannot see a chip inserted into an
+ * already-non-empty draft. Querying the editor's DOM for the chip is what is
+ * available without changing the editor's props, and `command-attachments.test.ts`
+ * pins the selector against `MentionNode`'s real rendered output so a rename
+ * cannot silently switch the warning off.
+ */
+export declare const COMMAND_CHIP_ATTRIBUTE = "data-mention";
+export declare const COMMAND_CHIP_VALUE = "command";
+export declare const COMMAND_CHIP_SELECTOR = "[data-mention=\"command\"]";
+/** Where the chip keeps the command's name. See `MentionNode.addAttributes`. */
+export declare const COMMAND_CHIP_LABEL_ATTRIBUTE = "data-mention-label";
+/**
+ * The part of the editor element this read touches — an `HTMLElement`
+ * satisfies it structurally. Narrow on purpose: `apps/web` has no DOM harness,
+ * and a two-method interface is the difference between a tested read and five
+ * untestable lines inside a component.
+ */
+export interface CommandChipHost {
+    querySelector(selectors: string): {
+        getAttribute(name: string): string | null;
+    } | null;
+}
+/**
+ * The name on the first `/` command chip in the live draft, or `null`.
+ *
+ * First, matching `collectCommandName`'s rule — `querySelector` returns the
+ * first match in document order, which is the same chip the serializer picks.
+ */
+export declare function readCommandChipLabel(host: CommandChipHost | null): string | null;
+/**
+ * Whether a draft carrying this chip label will actually RUN a command.
+ *
+ * The same resolution `planDraftSubmission` performs at submit time, against
+ * the same live list — deliberately, so the warning shown while typing and the
+ * decision taken on submit can never disagree.
+ *
+ * The case that makes this necessary: a chip whose command is no longer in the
+ * list does not run anything. `planDraftSubmission` re-inlines it as `/name
+ * args` and sends it as an ordinary message, which carries attachments fine.
+ * Treating the chip alone as "this is a command" would disable the send button
+ * for a submission that was about to work.
+ */
+export declare function draftWillRunCommand(chipLabel: string | null | undefined, commands: readonly {
+    name: string;
+}[]): boolean;
+export type CommandAttachmentPlan = 
+/** Nothing is at risk — send, queue, or run it as usual. */
+{
+    kind: 'dispatch';
+}
+/** Do not send, do not clear, and put both strings in front of the user. */
+ | {
+    kind: 'refuse';
+    message: string;
+    description: string;
+};
+export interface CommandAttachmentInput {
+    /**
+     * Whether this submission runs a `/` command. At submit time that is
+     * `planDraftSubmission(...).kind === 'command'`; for the live warning it is
+     * `draftWillRunCommand(readCommandChipLabel(editor), commands)`.
+     *
+     * Both resolve the same chip name against the same live list, so the warning
+     * shown while typing and the decision taken on submit agree. They are still
+     * two separate checks because only one of them can gate the keyboard: a
+     * disabled send button does nothing to Enter.
+     */
+    isCommand: boolean;
+    /** `attachedFiles.length`. */
+    attachmentCount: number;
+}
+/**
+ * Whether this submission may proceed, and what to tell the user if not.
+ *
+ * Called twice with different sources for `isCommand` — once per render for
+ * the inline warning and the disabled send button, once inside `handleSubmit`
+ * for the keyboard path, which no disabled button can gate.
+ */
+export declare function planCommandAttachments({ isCommand, attachmentCount }: CommandAttachmentInput, tI18nComplete: UiTranslator): CommandAttachmentPlan;
+export interface UnresolvedCommandChipInput {
+    /** The `/` chip the draft carries, if any — `getContent().commandName`. */
+    commandName: string | undefined;
+    /**
+     * Whether the live command list has EVER resolved. The composer's `commands`
+     * prop is `[]` both while the list is loading and for a host that passes no
+     * list at all, so the loading state has to arrive as its own bit — the
+     * composer cannot recover it from the array.
+     */
+    commandsResolved: boolean;
+    /** `attachedFiles.length`. */
+    attachmentCount: number;
+}
+/**
+ * Whether a chip the live list cannot YET resolve may leave with attachments.
+ *
+ * It may not. This is the hole the `planCommandAttachments` refusal cannot
+ * see: that guard runs only on `plan.kind === 'command'`, and a chip whose
+ * lookup misses degrades `planDraftSubmission` to a MESSAGE — which carries
+ * attachments fine. So in the window where the list has never resolved (a
+ * first load, or the `resetRuntimeQueries` a session restart and a config
+ * apply both fire), chip + attachment + Enter left the composer as an
+ * ordinary prompt: exactly the loss the refusal exists to prevent,
+ * reproduced on a booted local stack (2026-10-15, issue KRTX-1903).
+ *
+ * Only the never-resolved list is refused. A list that HAS resolved and
+ * misses the chip keeps its documented behavior — the command is gone, the
+ * failure degrades to plain text, and `draftWillRunCommand`'s doc comment
+ * records why that is deliberate. Without attachments nothing is at risk:
+ * the plain-text fallback is visible, recoverable, and stays available even
+ * while the list is loading.
+ */
+export declare function planUnresolvedCommandChip({ commandName, commandsResolved, attachmentCount }: UnresolvedCommandChipInput, tI18nComplete: UiTranslator): CommandAttachmentPlan;

package/dist/session/composer/command-attachments.js

@@ -0,0 +1,128 @@
+/**
+ * Whether a `/` command submission may carry the composer's attachments.
+ *
+ * It may not, and the honest answer is to say so.
+ *
+ * `handleSubmit`'s command branch used to ignore `attachedFiles` completely
+ * and then clear them — revoking every `blob:` URL on the way out. Attach a
+ * screenshot, run `/webapp`, and the screenshot was gone with nothing on
+ * screen to say it had ever existed. The queued command path introduced in
+ * `27279d2232` inherited the same hole: it passes `undefined` for files.
+ *
+ * ## Why refuse instead of carrying the files
+ *
+ * Carrying them is the better product outcome and it is not reachable from
+ * here. The wire call is `client.session.command(...)`, which opencode does
+ * accept a `parts` array for — but every layer between this composer and that
+ * call drops it: `useSession.runCommand(command, args, options)` takes no
+ * parts, `buildSessionCommandInput` builds `{sessionId, command, args, agent,
+ * model, variant}`, and `executeOpenCodeCommand` forwards exactly those six
+ * fields. All three live in `@kortix/sdk`, and a host must never reach past
+ * the SDK to the opencode client (see the repo's SDK rules). So the file parts
+ * cannot be delivered without a change to the published package.
+ *
+ * Refusing keeps the one property that matters: nothing the user attached is
+ * ever destroyed without being sent or reported. The composer disables submit,
+ * shows the reason inline, and keeps every file — so the user picks which of
+ * the two things they meant, with both still in front of them.
+ *
+ * Pure, and tested, because `composer.tsx` cannot be: `apps/web` has no DOM
+ * harness, and the composer sits behind a `React.lazy` boundary.
+ */
+/**
+ * The `data-*` attribute a mention chip renders its kind into, and the value a
+ * `/` command chip carries — see `editor/mention-node.ts`'s `addAttributes`.
+ *
+ * The composer needs to know a command chip is in the draft *while the user is
+ * typing*, not only at submit: the warning has to appear before anything can
+ * be lost. The editor's `onEmptyChange` fires only on the empty↔non-empty
+ * boundary (`trackEmptyBoundary`), so it cannot see a chip inserted into an
+ * already-non-empty draft. Querying the editor's DOM for the chip is what is
+ * available without changing the editor's props, and `command-attachments.test.ts`
+ * pins the selector against `MentionNode`'s real rendered output so a rename
+ * cannot silently switch the warning off.
+ */
+export const COMMAND_CHIP_ATTRIBUTE = 'data-mention';
+export const COMMAND_CHIP_VALUE = 'command';
+export const COMMAND_CHIP_SELECTOR = `[${COMMAND_CHIP_ATTRIBUTE}="${COMMAND_CHIP_VALUE}"]`;
+/** Where the chip keeps the command's name. See `MentionNode.addAttributes`. */
+export const COMMAND_CHIP_LABEL_ATTRIBUTE = 'data-mention-label';
+/**
+ * The name on the first `/` command chip in the live draft, or `null`.
+ *
+ * First, matching `collectCommandName`'s rule — `querySelector` returns the
+ * first match in document order, which is the same chip the serializer picks.
+ */
+export function readCommandChipLabel(host) {
+    if (!host)
+        return null;
+    const label = host
+        .querySelector(COMMAND_CHIP_SELECTOR)
+        ?.getAttribute(COMMAND_CHIP_LABEL_ATTRIBUTE);
+    return label || null;
+}
+/**
+ * Whether a draft carrying this chip label will actually RUN a command.
+ *
+ * The same resolution `planDraftSubmission` performs at submit time, against
+ * the same live list — deliberately, so the warning shown while typing and the
+ * decision taken on submit can never disagree.
+ *
+ * The case that makes this necessary: a chip whose command is no longer in the
+ * list does not run anything. `planDraftSubmission` re-inlines it as `/name
+ * args` and sends it as an ordinary message, which carries attachments fine.
+ * Treating the chip alone as "this is a command" would disable the send button
+ * for a submission that was about to work.
+ */
+export function draftWillRunCommand(chipLabel, commands) {
+    if (!chipLabel)
+        return false;
+    return commands.some((candidate) => candidate.name === chipLabel);
+}
+/**
+ * Whether this submission may proceed, and what to tell the user if not.
+ *
+ * Called twice with different sources for `isCommand` — once per render for
+ * the inline warning and the disabled send button, once inside `handleSubmit`
+ * for the keyboard path, which no disabled button can gate.
+ */
+export function planCommandAttachments({ isCommand, attachmentCount }, tI18nComplete) {
+    if (!isCommand || attachmentCount < 1)
+        return { kind: 'dispatch' };
+    const one = attachmentCount === 1;
+    return {
+        kind: 'refuse',
+        message: tI18nComplete.raw('text01ec8eaf8ffa'),
+        description: one
+            ? tI18nComplete.raw('text2eb91a6f88aa')
+            : tI18nComplete('text807f9beb34b1', { count: attachmentCount }),
+    };
+}
+/**
+ * Whether a chip the live list cannot YET resolve may leave with attachments.
+ *
+ * It may not. This is the hole the `planCommandAttachments` refusal cannot
+ * see: that guard runs only on `plan.kind === 'command'`, and a chip whose
+ * lookup misses degrades `planDraftSubmission` to a MESSAGE — which carries
+ * attachments fine. So in the window where the list has never resolved (a
+ * first load, or the `resetRuntimeQueries` a session restart and a config
+ * apply both fire), chip + attachment + Enter left the composer as an
+ * ordinary prompt: exactly the loss the refusal exists to prevent,
+ * reproduced on a booted local stack (2026-10-15, issue KRTX-1903).
+ *
+ * Only the never-resolved list is refused. A list that HAS resolved and
+ * misses the chip keeps its documented behavior — the command is gone, the
+ * failure degrades to plain text, and `draftWillRunCommand`'s doc comment
+ * records why that is deliberate. Without attachments nothing is at risk:
+ * the plain-text fallback is visible, recoverable, and stays available even
+ * while the list is loading.
+ */
+export function planUnresolvedCommandChip({ commandName, commandsResolved, attachmentCount }, tI18nComplete) {
+    if (!commandName || commandsResolved || attachmentCount < 1)
+        return { kind: 'dispatch' };
+    return {
+        kind: 'refuse',
+        message: tI18nComplete.raw('textdffd02b805cb'),
+        description: tI18nComplete.raw('textd943cb31f962'),
+    };
+}

package/dist/session/composer/composer-agent-access.d.ts

@@ -0,0 +1,83 @@
+import type { Agent } from '@kortix/sdk/react';
+/**
+ * Which agent the composer will actually run, given the roster the server is
+ * willing to hand this user.
+ *
+ * Project agents are deny-by-default for a `member`: the roster only contains
+ * agents an explicit `iam_resource_grant` names them (or one of their groups)
+ * on. Two consequences the composer has to render honestly, and used not to:
+ *
+ *   - The roster can be legitimately EMPTY. The picker was hidden entirely in
+ *     that case (`agents.length > 0` in `ComposerUnderbar`), the send button
+ *     stayed live, and the prompt went out with no `agent` option — so the
+ *     server silently fell back to the manifest `default_agent` (`kortix`) and
+ *     the user watched a run they never picked an agent for. For a member with
+ *     no grant that same send is a 403.
+ *   - The project's `default_agent` may not be in it. The picker then showed
+ *     nothing rather than the agent that would run.
+ *
+ * This resolver is the single answer to "what is selected, and can we send" —
+ * pure, so both hosts (`ComposerChatInput` and `session-chat.tsx`) get the same
+ * answer and it is testable without a DOM or a network.
+ */
+/** The refusal, as a toast title. */
+export declare const NO_AGENT_ACCESS_LABEL = "No agents available to you";
+/** The secondary line: what the user can do about it. */
+export declare const NO_AGENT_ACCESS_HINT = "Ask a manager for access";
+/**
+ * The one-line form, for the tooltip on the picker and on the send button.
+ *
+ * The state itself is carried by the controls looking disabled — a muted
+ * trigger beside a dead send button — not by a banner or a coloured pill
+ * shouting it across the composer. The words live in the tooltip, where the
+ * user goes when they want to know why.
+ */
+export declare const NO_AGENT_ACCESS_MESSAGE = "No agents available to you \u2014 ask a manager for access";
+export type ComposerAgentReason = 
+/** The roster has not loaded yet — nothing is refused on a pending query. */
+'loading'
+/** The caller's own pick is accessible and stands. */
+ | 'selected'
+/** No pick; the agent the session was created with stands. */
+ | 'bound'
+/** No pick (or an inaccessible one); the project default is accessible. */
+ | 'default'
+/** Neither the pick nor the default is accessible; first grant wins. */
+ | 'first_accessible'
+/** Nothing is accessible. The composer must refuse the send. */
+ | 'no_access';
+export interface ComposerAgentResolution {
+    /** The agent name to display AND to send. `null` only when nothing runs. */
+    selected: string | null;
+    /** No agent can run: disable the picker and the send control. */
+    disabled: boolean;
+    reason: ComposerAgentReason;
+}
+/**
+ * The agents a composer may offer: the SDK's `isSelectableAgent` rule, the
+ * same rule every agent picker on web and mobile applies.
+ *
+ * Subagents are dispatched BY an agent, never picked as the one to prompt, and
+ * `AgentSelector` has always filtered them out of the list. They are filtered
+ * here too so "the roster is empty" means the same thing to the resolver as it
+ * does to the control that renders it — a roster of nothing but subagents is an
+ * empty picker, and must not read as "we have an agent to run".
+ */
+export declare function composerSelectableAgents(agents: Agent[] | undefined): Agent[];
+export declare function resolveComposerAgent(input: {
+    /** The accessible roster. `undefined` means the query is still in flight. */
+    agents: Agent[] | undefined;
+    /**
+     * The agent the session was created with, when this composer belongs to an
+     * existing project session. It is the picker's starting value with no
+     * explicit pick — the truth to display then, never `selectable[0]`, which is
+     * somebody else's first grant. A pick made in the picker outranks it: agent
+     * switching stays available in a started session (KRTX-1290), and the send
+     * carries the picked name for the server to authorize and re-scope.
+     */
+    boundAgent?: string | null;
+    /** The project's declared default agent, accessible or not. */
+    defaultAgent?: string | null;
+    /** The caller's current pick (session slot, last-used, …), if any. */
+    selectedAgent?: string | null;
+}): ComposerAgentResolution;