@tangle-network/agent-app 0.45.54 → 0.45.56

package/dist/web-react/session-history.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The rendered half of the session shell: the history view behind the rail's
+ * session list, and the rename/delete dialogs both surfaces drive.
+ *
+ * Storage is a seam, not a dependency. Every product keeps sessions somewhere
+ * different (gtm threads, tax sessions, legal matters), so this takes a
+ * `fetchPage` data port and injected mutations — the same shape
+ * `AgentActivityPanel` (`fetchActivity`) and `ReviewQueuePanel` (`fetchQueue`)
+ * already use, rather than a fifth pattern.
+ *
+ * sandbox-ui free on purpose: `/web-react` must not force the optional peer, so
+ * these render on the shared design tokens like the rest of the subpath. The
+ * pure logic (nav items, routing, cookies, merging) lives in `/session-shell`,
+ * which a server loader can import without pulling React.
+ */
+import { type ReactNode, type RefObject } from 'react';
+import { type SessionPage, type SessionRailAction, type SessionSort, type SessionSummary } from '../session-shell/index';
+export interface UseInfiniteScrollOptions {
+    /** Only fire `onLoadMore` while true (a next page exists, none in flight). */
+    enabled: boolean;
+    /** Scroll container the sentinel lives in. Defaults to the viewport. */
+    root?: RefObject<HTMLElement | null>;
+    /** Prefetch distance before the sentinel is actually reached. */
+    rootMargin?: string;
+}
+/**
+ * Fires `onLoadMore` when a sentinel element scrolls into view. Returns a ref
+ * callback for that sentinel (typically the last element in a list).
+ *
+ * The observer is re-created whenever `enabled` flips, so a short first page
+ * that leaves the sentinel on-screen keeps loading: when a load finishes and
+ * `enabled` returns to true, the fresh observer re-reads the current
+ * intersection state and fires again until the sentinel is pushed off-screen.
+ */
+export declare function useInfiniteScroll(onLoadMore: () => void, { enabled, root, rootMargin }: UseInfiniteScrollOptions): (node: HTMLElement | null) => void;
+export interface SessionPageQuery {
+    /** Trimmed search term; empty string means no filter. */
+    q: string;
+    sort: SessionSort;
+    /** `null` for the first page. */
+    cursor: string | null;
+    /** Aborted when the view changes or the component unmounts. */
+    signal: AbortSignal;
+}
+/** Data port — one page of sessions for the current view. */
+export type FetchSessionPage = (query: SessionPageQuery) => Promise<SessionPage>;
+export interface UseSessionHistoryOptions {
+    fetchPage: FetchSessionPage;
+    /** Trimmed search term driving the fetch. */
+    q: string;
+    sort: SessionSort;
+    /** SSR page 1 of the default view, so the first paint costs no request. */
+    initialPage: SessionPage;
+    /** The sort `initialPage` was rendered for. Default `'newest'`. */
+    defaultSort?: SessionSort;
+}
+export interface SessionHistoryState {
+    items: SessionSummary[];
+    hasMore: boolean;
+    isLoadingFirst: boolean;
+    isLoadingMore: boolean;
+    isError: boolean;
+    loadMore: () => void;
+    /** Re-run whichever load failed. */
+    retry: () => void;
+    /** Refetch page 1 — call after a client-side mutation (e.g. a delete). */
+    reload: () => void;
+}
+/**
+ * Infinite-scroll data source for the history view. Seeds from `initialPage`
+ * for the default view (no fetch) and otherwise fetches page 1 for the current
+ * search/sort; `loadMore` appends the next cursor page.
+ *
+ * Raw promises + `AbortController` rather than a router fetcher, so a filter
+ * change cancels in-flight requests, pages accumulate, and a late response from
+ * a superseded view is dropped by the monotonic `seq` guard.
+ */
+export declare function useSessionHistory({ fetchPage, q, sort, initialPage, defaultSort, }: UseSessionHistoryOptions): SessionHistoryState;
+export interface SessionActionsOptions {
+    /** Persist a new title. Reject to surface the error in the dialog. */
+    renameSession: (sessionId: string, title: string) => Promise<void>;
+    deleteSession: (sessionId: string) => Promise<void>;
+    /** Called after a successful rename/delete — revalidate the rail here. */
+    onChanged?: () => void;
+    /** Called after deleting the session the user is currently viewing, so the
+     *  product can navigate away from a route that no longer resolves. */
+    onDeletedCurrent?: () => void;
+    /** The open session, compared against the delete target. */
+    currentSessionId?: string | null;
+    /** Product toast/log seam. Errors also render inside the dialog. */
+    notify?: (level: 'success' | 'error', message: string) => void;
+    labels?: Partial<SessionActionLabels>;
+}
+export interface SessionActionLabels {
+    renameTitle: string;
+    renameField: string;
+    renameSubmit: string;
+    deleteTitle: string;
+    deleteBody: (title: string) => string;
+    deleteSubmit: string;
+    cancel: string;
+    renamed: string;
+    deleted: string;
+    renameFailed: string;
+    deleteFailed: string;
+}
+export interface SessionActions {
+    openRename: (session: SessionSummary) => void;
+    openDelete: (session: SessionSummary) => void;
+    /** Render once, anywhere that survives navigation (the layout). */
+    dialogs: ReactNode;
+    busy: boolean;
+}
+/**
+ * Rename + delete for one session, shared by the rail kebab and the history
+ * row menu so both drive the same dialogs and the same product mutations.
+ *
+ * Dialogs are owned here rather than returned as raw state: two surfaces
+ * needing the same confirm step is exactly how a product ends up with two
+ * subtly different delete confirmations.
+ */
+export declare function useSessionActions({ renameSession, deleteSession, onChanged, onDeletedCurrent, currentSessionId, notify, labels, }: SessionActionsOptions): SessionActions;
+export interface SessionHistoryPanelProps {
+    history: SessionHistoryState;
+    /** Whether the workspace has any sessions at all — decided by the SSR page,
+     *  independent of the active search, so filtering to zero shows "no matches"
+     *  rather than the first-run empty state. */
+    hasAnySessions: boolean;
+    query: string;
+    onQueryChange: (value: string) => void;
+    sort: SessionSort;
+    onSortChange: (value: SessionSort) => void;
+    /** Product route for one session row. */
+    hrefForSession: (sessionId: string) => string;
+    /** Rendered as the row link. Defaults to an `<a>`; pass a router Link to keep
+     *  client-side navigation. */
+    linkComponent?: LinkLikeComponent;
+    /** Ids currently mid-turn — renders the responding treatment. */
+    respondingSessionIds?: ReadonlySet<string>;
+    onRename?: (session: SessionSummary) => void;
+    onDelete?: (session: SessionSummary) => void;
+    /** Product-owned mutation for selected rows or a workspace-wide age range. */
+    onBulkAction?: (action: SessionBulkAction) => Promise<void>;
+    /** Menu wording, so this surface and the rail name the same act the same way
+     *  — a product whose delete is really an archive says so in both places. */
+    renameLabel?: string;
+    deleteLabel?: string;
+    /**
+     * Row actions this shell has no opinion about — pin, categorise, share.
+     * Same seam and same ordering as the rail's `SessionRowActions.extraActions`:
+     * evaluated per session, placed between rename and delete. This menu is
+     * text-only, so `icon` is ignored here and honoured on the rail.
+     */
+    extraActions?: (session: SessionSummary) => SessionRailAction[];
+    /** New-session destination for the header action. Omitted ⇒ no button. */
+    newSessionHref?: string;
+    title?: string;
+    untitledLabel?: string;
+    emptyTitle?: string;
+    emptyDescription?: string;
+    /** Absolute → relative timestamp. Defaults to a compact built-in. */
+    formatTimestamp?: (isoDate: string | null) => string;
+    /** Max width of the reading column. `'full'` opts out for a product whose
+     *  surface really is a wide table. Default keeps title and timestamp inside
+     *  one scannable line rather than at opposite edges of a 1440px viewport. */
+    contentWidth?: 'reading' | 'full';
+    className?: string;
+}
+export type SessionBulkAction = {
+    kind: 'selected';
+    ids: string[];
+} | {
+    kind: 'older-than';
+    days: number;
+} | {
+    kind: 'newer-than';
+    days: number;
+};
+export interface LinkLikeProps {
+    to: string;
+    className?: string;
+    children?: ReactNode;
+}
+export type LinkLikeComponent = (props: LinkLikeProps) => ReactNode;
+/** Compact relative time. Overridable — a product with its own i18n passes
+ *  `formatTimestamp` rather than this being the only option. */
+export declare function formatSessionTimestamp(isoDate: string | null): string;
+/**
+ * The full session history: search, sort, cursor-paged rows with per-row
+ * actions, and the states in between (first-run empty, loading, no matches,
+ * error + retry).
+ *
+ * This is the surface the rail's capped list overflows into — the reason the
+ * rail can stay short without hiding the user's work.
+ */
+export declare function SessionHistoryPanel({ history, hasAnySessions, query, onQueryChange, sort, onSortChange, hrefForSession, linkComponent: Link, respondingSessionIds, onRename, onDelete, onBulkAction, renameLabel, deleteLabel, extraActions, newSessionHref, title, untitledLabel, emptyTitle, emptyDescription, formatTimestamp, contentWidth, className, }: SessionHistoryPanelProps): import("react").JSX.Element;

package/dist/web-react/smooth-text.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Smooth text reveal — turns chunky network deltas into a continuous
+ * typewriter paint. Streamed turns arrive in 100-500ms slabs (model burst,
+ * flush windows, replay polls); revealing characters at an adaptive rate
+ * makes the same bytes read as top-tier streaming. The rate scales with the
+ * backlog so the reveal never falls behind the stream — it crawls when caught
+ * up and sprints when a burst lands (e.g. a reasoning summary arriving all at
+ * once still *types out* instead of popping in).
+ */
+/** Define configuration options for controlling smooth text reveal animation rates */
+export interface SmoothRevealOptions {
+    /** Baseline reveal rate when nearly caught up. Default 90 chars/s. */
+    baseCharsPerSecond?: number;
+    /** Extra chars/s per backlog character — the catch-up pressure. Default 5. */
+    catchUpPerChar?: number;
+    /** Hard ceiling so giant bursts still animate. Default 2400 chars/s. */
+    maxCharsPerSecond?: number;
+}
+/** Pure reveal step: how many characters should be visible after `dtMs`.
+ *  Exposed for tests; the hook is a thin rAF wrapper around it. */
+export declare function nextRevealCount(shown: number, targetLength: number, dtMs: number, opts?: SmoothRevealOptions): number;
+/**
+ * Animate `target` text into view. While `enabled`, the returned string grows
+ * smoothly toward `target` (which may itself keep growing); when `enabled` is
+ * false the full text returns immediately (history, completed turns). A
+ * target that is not an extension of the revealed prefix (new message) resets
+ * the reveal.
+ */
+export declare function useSmoothText(target: string, enabled: boolean, opts?: SmoothRevealOptions): string;

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

@@ -0,0 +1,150 @@
+/**
+ * `Sparkline` — the series behind a number, as inline SVG.
+ *
+ * `/spend`, `/missions` and the eval lanes all produce a number for today, and
+ * every product renders it as text. Text cannot separate "$41, up from $38"
+ * from "$41, up from $4" — the same sentence, two different situations — so the
+ * reader opens a second surface to find out which one they are in. The series
+ * next to the number answers it in one glance.
+ *
+ * No chart dependency: this subpath is react + `@tangle-network/ui` only, and a
+ * polyline is not worth a bundle. What a chart library would give us here is
+ * axes, ticks and a tooltip, none of which belong on a 96×24 glyph.
+ *
+ * The three shapes a hand-rolled sparkline gets wrong, each handled here rather
+ * than left to the caller:
+ *
+ *  - **no readings** renders an explicit empty label, never a line. A line
+ *    along the baseline is a claim — "this metric sat at zero" — and a series
+ *    nobody has measured yet did not sit anywhere.
+ *  - **one reading** renders a point. A line needs two coordinates; drawing one
+ *    from a single reading invents the segment before it.
+ *  - **equal readings** render flat at MID height. The obvious normalisation
+ *    divides by `max - min`, which is `0` for a perfectly stable metric, and
+ *    the resulting `NaN` lands in the `points` attribute — SVG drops the whole
+ *    polyline, so the metric that never moved is the one that disappears.
+ *  - **a missing reading renders as a GAP, and the accessible name says so.**
+ *    A `null` from a hole in a series and a `NaN` from a producer's unguarded
+ *    division are not smaller series — they are readings nobody has. Deleting
+ *    them closed the line straight across the hole and announced a count that
+ *    was short by the number deleted: measured on `[1, NaN, 3]`, one continuous
+ *    two-point line labelled "2 readings, rising from 1 to 3", with nothing
+ *    anywhere saying a reading was unreadable. The card's figure slot already
+ *    refuses to let a non-measurement look measured; the series one line below
+ *    it holds the same rule. The x axis is the SAMPLE index, so the hole keeps
+ *    its width, the line breaks at it, and the label carries "N not available".
+ *
+ * Accessibility: `role="img"` with an `aria-label` naming the metric, its range
+ * and its direction. A sparkline with no accessible name is decoration a screen
+ * reader cannot report, which would leave the shape — the entire reason the
+ * component exists — visible to exactly one kind of reader.
+ *
+ * Deliberately not animated. `docs/product-surfaces.md` Pattern 4 lists chart
+ * draw-on under what this package does not animate: the shape IS the answer,
+ * and easing it in taxes every read of a surface people sit in for hours. The
+ * card around it arrives (`.agent-arrive`); the line does not draw itself.
+ */
+import type { ReactElement } from 'react';
+/** Where a series ended relative to where it started. */
+export type SparklineDirection = 'rising' | 'falling' | 'flat';
+export interface SparklinePoint {
+    readonly x: number;
+    readonly y: number;
+}
+export interface SparklineGeometry {
+    /** The finite readings, in order — what was actually plotted. */
+    readonly readings: readonly number[];
+    /** Every plotted point, in order. Positions are on the SAMPLE axis, so a
+     *  missing reading leaves its width behind rather than closing up. */
+    readonly points: readonly SparklinePoint[];
+    /** The points split into runs of CONSECUTIVE samples. One run is one stroke:
+     *  a line drawn across a missing reading states a movement nobody measured. */
+    readonly segments: readonly (readonly SparklinePoint[])[];
+    /** Samples that carried no usable reading — a `null`, a `NaN`, an infinity.
+     *  Counted rather than discarded, because the accessible name has to state
+     *  them: a shorter series announced as a complete one is the silent loss. */
+    readonly gaps: number;
+    readonly min: number;
+    readonly max: number;
+    readonly first: number;
+    readonly last: number;
+    readonly direction: SparklineDirection;
+}
+export interface SparklineGeometryOptions {
+    width?: number;
+    height?: number;
+    /** Keeps the stroke and the end dot inside the viewBox instead of clipping
+     *  them at the extremes, where the interesting readings always are. */
+    inset?: number;
+}
+export declare const DEFAULT_SPARKLINE_WIDTH = 96;
+export declare const DEFAULT_SPARKLINE_HEIGHT = 24;
+/** Only a name, never a metric: it exists so the accessible label is never
+ *  empty. Every caller in this package passes the metric's own title. */
+export declare const DEFAULT_SPARKLINE_LABEL = "Trend";
+export declare const DEFAULT_SPARKLINE_EMPTY_LABEL = "No history yet";
+/** Nothing was measurable, which is not the same as nothing was measured yet —
+ *  and "No history yet" over a series that arrived full of `NaN` reads as the
+ *  metric being new when the producer is broken. */
+export declare const DEFAULT_SPARKLINE_UNAVAILABLE_LABEL = "No readings available";
+/** The package's default number rendering, pinned to `en-US` so a card and its
+ *  series read the same on every host — a series formatted by the server's
+ *  locale and a value formatted by the browser's is a defect nobody sees until
+ *  the decimal separators disagree. */
+export declare function formatSparklineValue(value: number): string;
+/**
+ * The readings that can be plotted.
+ *
+ * A `null` from a gap in a series, or a `NaN` from a division a producer did
+ * not guard, is not plotted rather than coerced to `0`: plotting a missing
+ * reading at the baseline draws a cliff that never happened.
+ *
+ * This returns the readings ALONE, so it cannot tell a caller how many are
+ * missing. That is what {@link SparklineGeometry.gaps} is for, and what the
+ * accessible name reports — dropping a sample and then announcing the shorter
+ * count as the whole series is the defect, not the filter.
+ */
+export declare function sparklineReadings(values: readonly number[]): number[];
+/**
+ * Plots the series into the viewBox.
+ *
+ * Pure and exported so the cases that produce a broken chart — nothing, one
+ * reading, a flat series, negatives — are unit-testable without a DOM.
+ */
+export declare function sparklineGeometry(values: readonly number[], { width, height, inset }?: SparklineGeometryOptions): SparklineGeometry;
+/** `"2,14 48,3 94,21"` — the `points` attribute of the polyline. */
+export declare function sparklinePointsAttribute(points: readonly SparklinePoint[]): string;
+export interface SparklineLabelOptions {
+    label?: string;
+    format?: (value: number) => string;
+}
+/**
+ * The accessible name: metric, how many readings, how many are missing, the
+ * range, and the direction.
+ *
+ * All of it is load-bearing. The range without the direction describes a shape
+ * that could have been walked in either order; the direction without the range
+ * says "rising" about a metric that moved by a rounding error; and the count
+ * without the gaps is the number of readings that SURVIVED announced as the
+ * number that were taken — the shape a reader cannot see is exactly the one
+ * this sentence exists to carry.
+ */
+export declare function sparklineLabel(values: readonly number[], { label, format }?: SparklineLabelOptions): string;
+export interface SparklineProps {
+    values: readonly number[];
+    /** Names the metric in the accessible label. */
+    label?: string;
+    /** Renders a reading in that label; defaults to the package number format. */
+    format?: (value: number) => string;
+    width?: number;
+    height?: number;
+    /** Shown instead of a line when the metric has no history yet. */
+    emptyLabel?: string;
+    /** Shown instead of a line when every sample arrived unreadable — a different
+     *  state from "no history yet", and one the reader has to be able to tell
+     *  apart, because one is a new metric and the other is a broken producer. */
+    unavailableLabel?: string;
+    className?: string;
+}
+/** The series glyph. Strokes in `currentColor`, so tone is the caller's. */
+export declare function Sparkline({ values, label, format, width, height, emptyLabel, unavailableLabel, className, }: SparklineProps): ReactElement;

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

@@ -1,92 +1 @@
-/** Define the connection details and status for a sandbox terminal session */
-interface SandboxTerminalConnection {
-    runtimeUrl: string | null;
-    sidecarUrl: string | null;
-    token: string | null;
-    expiresAt: string | null;
-    status: string;
-    error: string | null;
-    loading: boolean;
-    sandboxId?: string;
-    connectionId?: string;
-}
-/**
- * Define the response structure for a sandbox terminal connection including URLs, token, status, and errors
- *
- * The browser-direct scoped-token route (`createSandboxTerminalConnectionRoute`,
- * `src/sandbox/terminal-connection.ts`) returns `sidecarUrl`. The hook also
- * exposes that URL through the historical `runtimeUrl` state field so existing
- * terminal panels do not need transport-specific branching.
- *
- * `connectionId` is the id the route's minted token's `sid` is bound to
- * (echoed back from the `connectionId` the hook sent) — pass it straight
- * through as `TerminalView`'s `connectionId` prop, since any other value
- * fails the WS upgrade on the current platform.
- */
-interface SandboxTerminalConnectionResponse {
-    runtimeUrl?: string;
-    sidecarUrl?: string;
-    token?: string;
-    expiresAt?: string;
-    status?: string;
-    error?: string;
-    sandboxId?: string;
-    connectionId?: string;
-}
-/**
- * Define options for configuring a sandbox terminal connection including workspace ID and connection parameters
- *
- * `connectionId`, when set, is passed to
- * `createSandboxTerminalConnectionRoute` as the `connectionId` query
- * parameter — pass `tabTerminalConnectionId()` here so the route mints a
- * token whose `sid` is bound to the same id `TerminalView` will dial. Give
- * `TerminalView` the response's echoed `connectionId` (not this input
- * value) alongside `sidecarUrl` as `apiUrl` and `token`, since a product's
- * `resolveConnectionId` seam may rewrite it server-side.
- */
-interface UseSandboxTerminalConnectionOptions {
-    workspaceId: string;
-    connectionUrl?: string | ((workspaceId: string) => string);
-    connectionId?: string;
-    fetcher?: typeof fetch;
-    provisionPollIntervalMs?: number;
-    provisionPollTimeoutMs?: number;
-    tokenRefreshSkewMs?: number;
-}
-/** Resolve sandbox terminal connection status and provide a method to initiate the connection */
-interface UseSandboxTerminalConnectionResult extends SandboxTerminalConnection {
-    connect: () => Promise<void>;
-}
-/**
- * Manage and maintain a sandbox terminal connection with automatic polling and token refresh handling
- *
- * `connectionUrl` is backed by the browser-direct scoped-token route
- * (`createSandboxTerminalConnectionRoute`,
- * `src/sandbox/terminal-connection.ts`). The route returns `sidecarUrl`; the
- * hook normalizes it into both URL fields for compatibility with existing
- * terminal panels.
- *
- * Pass `tabTerminalConnectionId()` as `opts.connectionId` — the hook forwards
- * it as the `connectionId` query parameter the browser-direct route requires
- * to mint a token whose `sid` is bound to that exact id (the orchestrator's
- * terminal WS gate fails closed on any other value). Give `TerminalView` the
- * RESULT's echoed `connectionId` (not the input value — a product's
- * `resolveConnectionId` seam may rewrite it), the resolved `sidecarUrl`/
- * `runtimeUrl` as `apiUrl`, and `token` as its token prop.
- */
-declare function useSandboxTerminalConnection(opts: UseSandboxTerminalConnectionOptions): UseSandboxTerminalConnectionResult;
-/**
- * Stable-per-tab, unique-per-client terminal connection id.
- *
- * Persists in `sessionStorage` so a reload in the same tab reuses the id (the
- * sidecar restores the same PTY session via `TerminalView.connectionId`), while
- * separate tabs/windows each get a distinct id. Pass the result as
- * `TerminalView`'s `connectionId`. Without it (e.g. gtm-agent today) every tab
- * shares one connection id and their reconnects evict each other.
- *
- * Falls back to an ephemeral id when `sessionStorage` is unavailable (SSR,
- * privacy mode) — still unique per call, just not reload-stable.
- */
-declare function tabTerminalConnectionId(storageKey?: string): string;
-
-export { type SandboxTerminalConnection, type SandboxTerminalConnectionResponse, type UseSandboxTerminalConnectionOptions, type UseSandboxTerminalConnectionResult, tabTerminalConnectionId, useSandboxTerminalConnection };
+export * from './sandbox-terminal';

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

@@ -0,0 +1,78 @@
+/**
+ * useChatInteractions — the interaction-state wiring every consumer of
+ * `ChatStreamCallbacks.onInteraction` re-implements: an id-keyed,
+ * insertion-ordered list with
+ *
+ *   - forward-only status transitions (a replayed/stale `pending` never
+ *     resurrects a resolved card),
+ *   - pending-question content dedupe (a re-emitted duplicate ask never renders
+ *     a second card),
+ *   - cancel-event application (`interaction.cancel` → cancelled/expired),
+ *   - local resolution marking (the card's `onResolved`),
+ *   - reload restore from the answer route's GET list (sidecar registry is the
+ *     source of truth after a reload),
+ *   - turn-end settling (client mirror of the server's finalize pass: a turn
+ *     that completed without a cancel was answered; a failed turn can make no
+ *     such claim).
+ *
+ * The reducer functions are pure and exported for non-React consumers/tests;
+ * the hook is a thin `useState` shell over them.
+ */
+import { type ChatInteraction, type ChatInteractionStatus, type InteractionAnswers, type InteractionCancelData, type InteractionRequestWire } from './chat-interactions';
+/** Insert or update one interaction. A terminal existing entry wins over any
+ *  incoming state for the same id; a new pending ask that duplicates another
+ *  pending ask's content is dropped. Returns the same array when unchanged. */
+export declare function upsertChatInteraction(list: ChatInteraction[], interaction: ChatInteraction): ChatInteraction[];
+/** Applies an `interaction.cancel` event: only a pending ask moves, to
+ *  `expired` (reason:"timeout") or `cancelled`. */
+export declare function cancelChatInteraction(list: ChatInteraction[], cancel: InteractionCancelData): ChatInteraction[];
+/** Marks one ask resolved locally (the card's `onResolved`). Forward-only. */
+export declare function resolveChatInteraction(list: ChatInteraction[], id: string, status: Exclude<ChatInteractionStatus, 'pending'>, answers?: InteractionAnswers): ChatInteraction[];
+/** Settles every still-pending ask when the turn ends: `answered` for a turn
+ *  that completed cleanly, `expired` for one that failed. */
+export declare function terminalizePendingChatInteractions(list: ChatInteraction[], status: Extract<ChatInteractionStatus, 'answered' | 'expired'>): ChatInteraction[];
+/** Define modes for restoring chat interactions with legacy or durable strategies */
+export type ChatInteractionRestoreMode = 'legacy' | 'durable';
+/** Define options to control how chat interactions are restored during the restore process */
+export interface RestoreChatInteractionsOptions {
+    /**
+     * `legacy` settles pending asks absent from the sidecar list as answered,
+     * preserving the pre-durable restore contract. `durable` leaves them
+     * pending because absence is ambiguous until `hydrateChatInteractions`
+     * applies the durable projection.
+     */
+    mode?: ChatInteractionRestoreMode;
+}
+/** Reload restore from the answer route's GET list. Legacy consumers retain
+ * the historical absence→answered behavior; durable consumers opt into the
+ * ambiguity-preserving mode and apply terminal parts through `hydrate`. */
+export declare function restoreChatInteractions(list: ChatInteraction[], outstanding: InteractionRequestWire[], options?: RestoreChatInteractionsOptions): ChatInteraction[];
+/** Applies transcript/state-store projections after reload. Terminal state and
+ * acknowledged answer values enrich an existing pending card without relying
+ * on the sidecar's outstanding-list absence. */
+export declare function hydrateChatInteractions(list: ChatInteraction[], persisted: ChatInteraction[]): ChatInteraction[];
+/** Resolve and manage chat interactions with methods to update, cancel, mark resolved, and restore state */
+export interface UseChatInteractionsResult {
+    /** All known interactions, insertion-ordered. */
+    interactions: ChatInteraction[];
+    /** The asks currently blocking the run (waiting on the user). */
+    pending: ChatInteraction[];
+    /** Wire to `ChatStreamCallbacks.onInteraction` (and persisted-part replay). */
+    upsert: (interaction: ChatInteraction) => void;
+    /** Wire to `interaction.cancel` events. */
+    applyCancel: (cancel: InteractionCancelData) => void;
+    /** Wire to the cards' `onResolved`. */
+    markResolved: (id: string, status: Exclude<ChatInteractionStatus, 'pending'>, answers?: InteractionAnswers) => void;
+    /** Wire to the answer route's GET list after a reload/reconnect. */
+    restore: (outstanding: InteractionRequestWire[], options?: RestoreChatInteractionsOptions) => void;
+    /** Apply durable transcript/state projections after a reload. */
+    hydrate: (persisted: ChatInteraction[]) => void;
+    /** Settle still-pending asks when the turn ends. */
+    terminalizePending: (status: Extract<ChatInteractionStatus, 'answered' | 'expired'>) => void;
+    /** Drop everything (thread switch). */
+    reset: () => void;
+}
+/** Resolve options for restoring chat interactions from previous sessions */
+export type UseChatInteractionsOptions = RestoreChatInteractionsOptions;
+/** Manage chat interactions state with upsert, cancel, resolve, and restore capabilities */
+export declare function useChatInteractions(options?: UseChatInteractionsOptions): UseChatInteractionsResult;

package/dist/web-react/use-composer-attachments.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `useComposerAttachments` — the composer's staged-upload lifecycle: validate
+ * selected/dropped/pasted files against the shared limits (the SAME
+ * `sniffBinary`/`checkAttachmentType`/size-cap vocabulary the store-backed
+ * upload route enforces server-side, `../chat-routes/attachment-validation`
+ * + `../chat-routes/binary-sniff`), upload each accepted file with one POST
+ * request per file (so a single failure never poisons the batch), and track
+ * every file's status so a host composer can render chips and gate sending.
+ *
+ * Ported from gtm-agent's `src/components/composer-attachments.tsx`
+ * (gtm#584/#592/#593 hardened the sniff gate and batch semantics this leans
+ * on), de-gtm-ified:
+ *   - the hardcoded `/api/vault/upload?workspaceId=` URL becomes
+ *     `uploadUrl`/`buildUploadRequest` (the latter wins — it hands back both
+ *     the URL and a `RequestInit` override, e.g. an auth header);
+ *   - `sonner` toasts become `onReject` (client pre-validation, never hits the
+ *     network) and `onError` (a request that reached the server and failed);
+ *   - the sandbox-ui `validateComposerFiles` import becomes a small
+ *     accept-list matcher re-implemented locally (`isAcceptedFileType`,
+ *     mirroring its `accept`-string matching byte-for-byte) — this module
+ *     stays free of the sandbox-ui peer;
+ *   - the response is expected to be `{ files: ChatAttachmentInput[] }` (full
+ *     server-authoritative descriptors — size/mediaType/kind — not gtm's
+ *     `{path, name}`), so `references` is a verbatim pass-through with no
+ *     client recompute;
+ *   - `workspaceId`'s truthiness gate becomes `enabled` (default `true`).
+ *
+ * Import-free beyond React + the browser-safe `/chat-routes` validation core:
+ * this module ships through `/web-react` into client bundles
+ * (`tests/browser-safe-subpaths.test.ts` walks the graph), so nothing here
+ * may reach a Node builtin, `sandbox-ui`, or an engine package.
+ */
+import type { ChatAttachmentInput, ChatAttachmentKind } from './chat-stream';
+import type { ComposerFile } from './chat-composer';
+export { ATTACHMENT_ACCEPT } from '../chat-routes/attachment-validation';
+/** Define options for configuring file upload behavior and handling in a composer component */
+export interface UseComposerAttachmentsOptions {
+    /** Simple upload target: every file POSTs here. Ignored when
+     *  `buildUploadRequest` is provided. */
+    uploadUrl?: string;
+    /** Full request-building seam (auth headers, per-file routing, …) — wins
+     *  over `uploadUrl` when both are set. */
+    buildUploadRequest?: (args: {
+        file: File;
+        name: string;
+        form: FormData;
+    }) => {
+        url: string;
+        init?: Omit<RequestInit, 'body' | 'signal'>;
+    };
+    /** Client pre-validation rejections — a file that never reaches the
+     *  network (bad type, over a size cap, over count, disallowed kind). */
+    onReject?: (reason: string, file?: File) => void;
+    /** A file that reached the upload endpoint and failed (HTTP error,
+     *  transport error, malformed response). */
+    onError?: (reason: string) => void;
+    limits?: {
+        maxCount?: number;
+        maxBinaryBytes?: number;
+        maxTextBytes?: number;
+        maxTotalBytes?: number;
+    };
+    /** Attachment kinds accepted, checked against the sniffed content's
+     *  mime. Default: both (`['image', 'file']` — i.e. no restriction). */
+    allowedKinds?: ChatAttachmentKind[];
+    /** `<input accept>`-style gate for the file picker/drop/paste path.
+     *  Default {@link ATTACHMENT_ACCEPT}. */
+    accept?: string;
+    /** When `false`, `addFiles` rejects every call via `onReject` (and
+     *  `blockReason` explains why) instead of staging anything — the
+     *  replacement for gtm's `workspaceId`-truthiness gate (e.g. no workspace
+     *  loaded yet). Default `true`. */
+    enabled?: boolean;
+}
+/** Provide staged file chips, ready attachments, and methods to add, retry, or drop composer files */
+export interface UseComposerAttachmentsResult {
+    /** Chip models for `ChatComposer`'s `pendingFiles` prop, one per staged
+     *  file — `kind` is always `'file'` (agent-app's `ComposerFile.kind`
+     *  discriminates file-vs-folder chips, not attachment media type). */
+    composerFiles: ComposerFile[];
+    /** Ready-to-send attachment descriptors — only files whose upload
+     *  succeeded, straight from the server's response (no recompute). Feed
+     *  this into `ChatTurnRequestPayload.attachments`. */
+    references: ChatAttachmentInput[];
+    /** Validate + stage + upload the given files, one request per file. */
+    addFiles: (files: File[] | FileList) => Promise<void>;
+    /** Re-upload a failed entry using its retained `File`. */
+    retry: (id: string) => void;
+    /** Drop one staged entry, aborting its upload and revoking its preview. */
+    removeAttachment: (id: string) => void;
+    /** Forget every staged entry (call after a successful send). */
+    clear: () => void;
+    /** True while any file is still pending or uploading. */
+    hasPending: boolean;
+    /** True while any file failed to upload. */
+    hasError: boolean;
+    /** Why a send is blocked, or `null` when the queue is clean. */
+    blockReason: string | null;
+}
+/**
+ * Owns the composer's attachment lifecycle: validate selected/dropped/pasted
+ * files against the shared limits, upload each accepted file to the
+ * product's store (one request per file), and track every file's status so
+ * the composer can render chips and gate sending.
+ *
+ * Failures surface loud — a rejected file calls `onReject` and is never
+ * uploaded; a failed upload calls `onError` and leaves an error chip the user
+ * can retry or remove. `references` only ever contains files whose upload the
+ * server actually confirmed.
+ */
+export declare function useComposerAttachments(options: UseComposerAttachmentsOptions): UseComposerAttachmentsResult;