@makinbakin/sdk 0.0.1-rc.2 → 0.0.1-rc.21

package/README.md

@@ -86,6 +86,7 @@ component for a slot via `registerPlugin({ slots: { 'slot-name': Component } })`
 | `task-assets`         | Task drawer, asset attachments section                   |
 | `task-sidebar`        | Task drawer sidebar (custom panels for a plugin's tasks) |
 | `home-widget`         | Dashboard home widget grid                               |
+| `nav-badge-providers` | Background hook runners (render `null`) that drive `setNavBadge` |
 | `page:/<route>`       | Full-page mount at `<route>`                             |
 
 ## Sub-path imports

package/_internal/app/components/agent-select.d.ts

@@ -1,6 +1,18 @@
-interface AgentSelectProps {
+import type { AriaAttributes } from 'react';
+/** Prefix marking a team selection in the select's string value (#189).
+ * Task surfaces split it back into {agent} vs {team} before talking to the
+ * API; workflow STEP definitions store the token verbatim (#611 — the step's
+ * team target, resolved sticky at dispatch). */
+export declare const TEAM_VALUE_PREFIX = "team:";
+export declare function isTeamValue(value: string): boolean;
+export declare function teamIdFromValue(value: string): string;
+interface AgentSelectProps extends Pick<AriaAttributes, 'aria-describedby' | 'aria-invalid'> {
+    id?: string;
     value: string;
     onValueChange: (value: string) => void;
+    /** Include the workflow/task runtime assignee token (`$assigned`) */
+    includeAssigned?: boolean;
+    assignedLabel?: string;
     /** Show a "None" / "Unassigned" option at the top (default: false) */
     allowNone?: boolean;
     /** Label for the none option (default: "Unassigned") */
@@ -9,7 +21,9 @@ interface AgentSelectProps {
     placeholder?: string;
     /** Restrict to a subset of agent IDs */
     agentIds?: string[];
+    /** Offer teams as assignment targets (`team:<id>` values, #189) */
+    includeTeams?: boolean;
     className?: string;
 }
-export declare function AgentSelect({ value, onValueChange, allowNone, noneLabel, placeholder, agentIds, className, }: AgentSelectProps): import("react/jsx-runtime").JSX.Element;
+export declare function AgentSelect({ value, onValueChange, includeAssigned, assignedLabel, allowNone, noneLabel, placeholder, agentIds, includeTeams, className, id, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }: AgentSelectProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/_internal/app/components/asset-picker.d.ts

@@ -0,0 +1,25 @@
+export interface AssetPickerAsset {
+    assetId: string;
+    description: string;
+    type: string;
+    hasThumb: boolean;
+}
+export interface AssetPickerProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Called with the chosen (or freshly uploaded) assetId; the dialog closes itself after. */
+    onPick: (assetId: string) => void;
+    /** Dialog heading (default "Choose an asset"). */
+    title?: string;
+    /** One-liner under the heading (e.g. what the asset will be used for). */
+    description?: string;
+    /** Narrow the grid (e.g. only images). Applied client-side over the library listing. */
+    filter?: (asset: AssetPickerAsset) => boolean;
+}
+/**
+ * Modal asset chooser over the assets plugin's library: search, thumbnail
+ * grid, and drag/drop or button upload-new (which picks the fresh asset).
+ * THE way any surface references a managed asset — never a raw id `<select>`.
+ * Engine-unreachable renders an honest error state, never a blank grid.
+ */
+export declare function AssetPicker({ open, onOpenChange, onPick, title, description, filter }: AssetPickerProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/charts/bar-chart.d.ts

@@ -0,0 +1,16 @@
+import { type ChartDatum, type ChartSeries } from './chart-data-table';
+export interface BarChartProps {
+    data: ChartDatum[];
+    series: ChartSeries[];
+    label: string;
+    description?: string;
+    height?: number;
+    /** Stack series within each x-axis bucket instead of grouping them. */
+    stacked?: boolean;
+    formatValue?: (value: number) => string;
+    emptyLabel?: string;
+    /** Hide the built-in collapsible table when the consumer renders equivalent data beside the chart. */
+    showDataTable?: boolean;
+}
+/** Dependency-free grouped/stacked bar chart with keyboard-equivalent marks. */
+export declare function BarChart({ data, series, label, description, height, stacked, formatValue, emptyLabel, showDataTable, }: BarChartProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/charts/chart-data-table.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+export interface ChartDatum {
+    /** Stable x-axis key. */
+    x: string;
+    /** Human-readable x-axis label; defaults to `x`. */
+    xLabel?: string;
+    /** Values keyed by `ChartSeries.key`. */
+    values: Record<string, number>;
+    /** Per-series labels for intentionally absent cells. */
+    missingLabels?: Record<string, string>;
+}
+export interface ChartSeries {
+    key: string;
+    label: string;
+    /** CSS color. Defaults to the matching semantic `--chart-*` token. */
+    color?: string;
+}
+export interface ChartDataTableProps {
+    data: ChartDatum[];
+    series: ChartSeries[];
+    caption: string;
+    formatValue?: (value: number) => ReactNode;
+    /** Rendered when a series has no value for a bucket; defaults to formatted zero. */
+    missingValue?: ReactNode;
+    /** Visually hide the exact table when the chart is intentionally compact. */
+    visuallyHidden?: boolean;
+}
+export declare const CHART_TOKEN_COLORS: readonly ["var(--chart-1)", "var(--chart-2)", "var(--chart-3)", "var(--chart-4)", "var(--chart-5)"];
+export declare function chartSeriesColor(series: ChartSeries, index: number): string;
+/** Exact values for charts whose visual marks intentionally summarize data. */
+export declare function ChartDataTable({ data, series, caption, formatValue, missingValue, visuallyHidden, }: ChartDataTableProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/charts/chart-explainer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ChartExplainer (#385) — the one-line "what am I looking at / when should I
+ * worry" footer every supervision chart carries. Plain language for users
+ * who aren't AI experts; keep it to one or two sentences.
+ */
+import type { ReactNode } from 'react';
+export declare function ChartExplainer({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/charts/chart-tooltip.d.ts

@@ -0,0 +1,8 @@
+export interface ChartTooltipProps {
+    id: string;
+    text: string;
+    xPercent: number;
+    yPercent: number;
+}
+/** Shared non-animated tooltip used identically by pointer and keyboard focus. */
+export declare function ChartTooltip({ id, text, xPercent, yPercent }: ChartTooltipProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/charts/line-chart.d.ts

@@ -0,0 +1,13 @@
+import { type ChartDatum, type ChartSeries } from './chart-data-table';
+export interface LineChartProps {
+    data: ChartDatum[];
+    series: ChartSeries[];
+    label: string;
+    description?: string;
+    height?: number;
+    formatValue?: (value: number) => string;
+    emptyLabel?: string;
+}
+/** Dependency-free multi-series line chart with keyboard-equivalent marks. */
+export declare function LineChart({ data, series, label, description, height, formatValue, emptyLabel, }: LineChartProps): import("react/jsx-runtime").JSX.Element;
+export type { ChartDatum, ChartSeries } from './chart-data-table';

package/_internal/app/components/charts/palette.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Chart series palette (#385) — the SDK chart kit's single source of series
+ * color. Bakin renders dark-only (host index.html pins color-scheme: dark on
+ * a #0f0e0e surface), so this is the dark-surface categorical set, validated
+ * with the dataviz six-checks script (lightness band, chroma floor, adjacent
+ * CVD ΔE, ≥3:1 contrast on the dark surface).
+ *
+ * Rules baked in here (do not "fix" them):
+ * - The slot ORDER is the colorblind-safety mechanism — never reorder or
+ *   cycle. It maximizes worst-case adjacent CVD separation.
+ * - Color follows the entity: assign via assignSeriesColors over the full
+ *   entity set so a filter that drops series never repaints the survivors.
+ * - A 9th series is never a new hue — fold into "Other" (CHART_OTHER_COLOR).
+ */
+export declare const CHART_SERIES_COLORS: readonly ["#3987e5", "#199e70", "#c98500", "#008300", "#9085e9", "#e66767", "#d55181", "#d95926"];
+/** Muted, low-chroma gray for the folded "Other" series — never a hue slot. */
+export declare const CHART_OTHER_COLOR = "#6b6963";
+export declare const CHART_MAX_SERIES: 8;
+/**
+ * Deterministic entity → color map: entities sorted, slots assigned in fixed
+ * order. Pass the FULL entity set (not the filtered view) so colors are
+ * stable across filters and windows.
+ */
+export declare function assignSeriesColors(keys: string[]): Map<string, string>;

package/_internal/app/components/charts/sparkline.d.ts

@@ -0,0 +1,12 @@
+export interface SparklineProps {
+    values: number[];
+    width?: number;
+    height?: number;
+    stroke?: string;
+    /** Accessible description, e.g. "input tokens over the last 10 runs". */
+    label: string;
+    /** Optional human-readable labels for each value. */
+    labels?: string[];
+    formatValue?: (value: number) => string;
+}
+export declare function Sparkline({ values, width, height, stroke, label, labels, formatValue, }: SparklineProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/charts/stacked-column-chart.d.ts

@@ -0,0 +1,40 @@
+/**
+ * StackedColumnChart (#385) — hand-rolled div-based stacked columns for the
+ * SDK chart kit. One column per x bucket, segments stacked by series with a
+ * 2px surface gap between fills, legend with click-to-toggle when there are
+ * ≥2 series (a single series needs no legend), and a per-column pointer and
+ * keyboard tooltip carrying the full breakdown. Series beyond the palette
+ * fold into a gray "Other" — a 9th hue is never generated.
+ */
+import { type ReactNode } from 'react';
+export interface StackedColumnDatum {
+    /** Bucket key (e.g. a YYYY-MM-DD day). */
+    x: string;
+    /** Short display label for the bucket; defaults to x. */
+    xLabel?: string;
+    /** Per-series values for this bucket (missing series = 0). */
+    values: Record<string, number>;
+    /** Per-series labels for intentionally absent exact-table cells. */
+    missingLabels?: Record<string, string>;
+}
+export interface StackedColumnChartProps {
+    data: StackedColumnDatum[];
+    /** Series that should stay discoverable even when every value is missing. */
+    seriesKeys?: readonly string[];
+    /** Accessible name for the plot. */
+    label?: string;
+    /** Accessible name for the exact-values disclosure. */
+    dataLabel?: string;
+    /** Bucket keys that are still accumulating data. */
+    partialKeys?: readonly string[];
+    /** Plot height in px (columns area, excluding legend). */
+    height?: number;
+    formatValue?: (n: number) => string;
+    /** Exact-table label for a missing series value; defaults to formatted zero. */
+    missingValue?: ReactNode;
+    /** Plot/tooltip label for a bucket with no reported series values. */
+    missingBucketLabel?: string;
+    /** Shown when data is empty — honest empty state, never a fake chart. */
+    emptyLabel?: string;
+}
+export declare function StackedColumnChart({ data, seriesKeys, label, dataLabel, partialKeys, height, formatValue, missingValue, missingBucketLabel, emptyLabel, }: StackedColumnChartProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/confirm-dialog.d.ts

@@ -0,0 +1,54 @@
+import { type ReactNode } from 'react';
+export interface ConfirmDialogProps {
+    /** Whether the dialog is shown. Controlled by the caller (e.g. `open={!!target}`). */
+    open: boolean;
+    title: ReactNode;
+    /** Body copy. Rendered inside DialogDescription (a `<p>`) — pass inline content; use `<span className="block">` for secondary lines. */
+    description?: ReactNode;
+    /** Confirm button label (default "Delete"). */
+    confirmLabel?: string;
+    /** Confirm label while busy (default = confirmLabel); a spinner is prepended. */
+    busyLabel?: string;
+    /** Cancel button label (default "Cancel"). */
+    cancelLabel?: string;
+    /** Cancel button variant (default "outline"). */
+    cancelVariant?: 'outline' | 'ghost';
+    /**
+     * Confirm button variant (default "destructive"). Non-destructive
+     * confirm flows (repair, switch-with-preview) pass "default" so a
+     * healing action doesn't render as a red warning.
+     */
+    confirmVariant?: 'destructive' | 'default';
+    /** Disables both buttons and shows a spinner on confirm while the action is in flight. */
+    busy?: boolean;
+    /** Inline error shown above the footer. */
+    error?: string | null;
+    /** Test id forwarded to the confirm button. */
+    confirmTestId?: string;
+    /** DialogContent className override (default width is `sm:max-w-sm`). */
+    className?: string;
+    /**
+     * Typed confirmation: when set, an input is rendered and the confirm button
+     * stays disabled until the user types this exact value. For the truly
+     * destructive actions where one click is too easy.
+     */
+    confirmValue?: string;
+    /** Label above the typed-confirmation input (default: `Type "<confirmValue>" to confirm`). */
+    confirmPrompt?: ReactNode;
+    /**
+     * Optional body content between the description and the typed-confirmation
+     * input — for the options an action needs decided at confirm time
+     * (checkboxes, a preview trigger). Keeps action configuration IN the
+     * dialog instead of inline on the page.
+     */
+    children?: ReactNode;
+    onConfirm: () => void;
+    onCancel: () => void;
+}
+/**
+ * A controlled confirmation dialog for destructive actions — the consolidation of
+ * six near-identical hand-rolled delete dialogs. The caller owns visibility (`open`)
+ * and the busy/error state of the in-flight action; the dialog never closes itself
+ * while `busy` so an action can't be cancelled mid-flight.
+ */
+export declare function ConfirmDialog({ open, title, description, confirmLabel, busyLabel, cancelLabel, cancelVariant, confirmVariant, busy, error, confirmTestId, className, confirmValue, confirmPrompt, children, onConfirm, onCancel, }: ConfirmDialogProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/conversation/activity-group.d.ts

@@ -0,0 +1,15 @@
+import type { ConversationToolCall } from './fold';
+export declare function formatDuration(ms: number | undefined): string;
+export declare function humanizeActivity(calls: ConversationToolCall[]): string;
+export declare function ToolCallRow({ call, onOpen, }: {
+    call: ConversationToolCall;
+    onOpen?: (call: ConversationToolCall) => void;
+}): import("react/jsx-runtime").JSX.Element;
+export interface ActivityGroupProps {
+    calls: ConversationToolCall[];
+    /** Row click-through to the detail surface (ToolCallDrawer). */
+    onOpenCall?: (call: ConversationToolCall) => void;
+    /** Start expanded (default collapsed). */
+    defaultExpanded?: boolean;
+}
+export declare function ActivityGroup({ calls, onOpenCall, defaultExpanded }: ActivityGroupProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/conversation/agent-turn.d.ts

@@ -0,0 +1,36 @@
+import type { ConversationToolCall, ConversationTurn } from './fold';
+export declare function TurnTimestamp({ ts }: {
+    ts?: string;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function CopyButton({ text, label }: {
+    text: string;
+    label?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Standalone avatar + shimmer row for surfaces that render the indicator
+ * outside an AgentTurn. Inside a turn the shimmer renders under the header.
+ */
+export declare function ThinkingIndicator({ agentId, label }: {
+    agentId?: string;
+    label?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export interface AgentTurnProps {
+    turn: Extract<ConversationTurn, {
+        kind: 'agent';
+    }>;
+    /** Fallback author when the turn doesn't carry its own agentId. */
+    agentId?: string;
+    /** Re-send the last user message; renders "Try again" on error turns. */
+    onRetry?: () => void;
+    /** Tool-call row click-through (detail drawer). */
+    onOpenCall?: (call: ConversationToolCall) => void;
+    /**
+     * Hook for surfaces that post-process assistant text (e.g. the brainstorm
+     * proposal stripper). Returns the text to render plus optional extra nodes.
+     */
+    transformText?: (text: string) => {
+        text: string;
+        extras?: React.ReactNode;
+    };
+}
+export declare function AgentTurn({ turn, agentId, onRetry, onOpenCall, transformText }: AgentTurnProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/conversation/attention.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Conversation attention rules — ONE set of pure decisions for every
+ * conversational surface's badge provider (#703): what a turn's done/error
+ * means given where the user is looking. Providers execute the returned
+ * actions (toast/sound/OS notification/seen); this module never touches
+ * the DOM so the rules stay unit-testable. Generalized verbatim from the
+ * chat plugin's attention module (chat re-exports from here).
+ *
+ * Suppression rules (chat spec S6, now kit-wide):
+ * - Reply lands while the user is VIEWING that thread → no toast, no
+ *   sound, no OS notification (the conversation itself is the signal);
+ *   unread is cleared (the view fires seen).
+ * - Reply lands elsewhere in the app → toast + sound; the OS notification
+ *   is also requested — sendBrowserNotification suppresses itself when
+ *   the tab has focus, so it only fires when the user is in another app.
+ * - Aborted turns notify nothing — the user stopped it themselves.
+ */
+export interface ConversationDonePayload {
+    /** The thread key (chat: chatId; projects: projectId; …). */
+    key: string;
+    agentId: string;
+    preview?: string;
+    aborted?: boolean;
+}
+export interface ConversationAttentionContext {
+    /** The thread currently open in the UI, '' when none. */
+    visibleKey: string;
+    settings: {
+        sound: boolean;
+        toasts: boolean;
+    };
+}
+export interface AttentionActions {
+    toast: boolean;
+    sound: boolean;
+    /** Ask browser-notify (it self-suppresses while the tab is focused). */
+    browserNotification: boolean;
+    /** The user is looking at the thread — mark it seen instead of unread. */
+    markSeen: boolean;
+}
+export declare function attentionForDone(payload: ConversationDonePayload, ctx: ConversationAttentionContext): AttentionActions;
+/**
+ * The entity id the user is currently viewing, derived from a
+ * `<base>/<id>` URL path (list and excluded ids — e.g. a `/new` draft
+ * route — view no conversation, so they never suppress attention).
+ */
+export declare function visibleIdFromLocation(pathname: string, base: string, opts?: {
+    exclude?: readonly string[];
+}): string;
+/** Nav badge from unread totals + in-flight turns: count wins, dot while working. */
+export declare function badgeFor(totalUnread: number, inflightCount: number): {
+    count?: number;
+    tone: 'attention' | 'info';
+} | null;
+/** `(N) ` tab-title prefix management (idempotent). */
+export declare function withUnreadPrefix(title: string, totalUnread: number): string;

package/_internal/app/components/conversation/composer.d.ts

@@ -0,0 +1,35 @@
+export interface ComposerAttachmentItem {
+    id: string;
+    name: string;
+    previewUrl?: string;
+    /** 'uploading' renders a progress chip; absent/'ready' renders the thumbnail. */
+    status?: 'uploading' | 'ready';
+}
+export interface ComposerAttachments {
+    /** Whether this agent/model accepts image input (capability-gated by the caller). */
+    enabled: boolean;
+    /** Honest explanation shown on the disabled affordance. */
+    disabledReason?: string;
+    items: ComposerAttachmentItem[];
+    onAdd: (files: File[]) => void;
+    onRemove: (id: string) => void;
+}
+export interface ComposerProps {
+    /** Thread identity: keys drafts, history, and the resize persistence. */
+    storageKey: string;
+    onSend: (content: string) => void | Promise<void>;
+    /** A turn is streaming: send is held (typing stays live), stop shows. */
+    busy?: boolean;
+    onAbort?: () => void;
+    /** Hard-disabled surface (read-only/archived). */
+    disabled?: boolean;
+    placeholder?: string;
+    maxLength?: number;
+    attachments?: ComposerAttachments;
+    /** Rendered left of the textarea (e.g. an agent switcher). */
+    leadingSlot?: React.ReactNode;
+    autoFocus?: boolean;
+    minHeight?: number;
+    maxHeight?: number;
+}
+export declare function Composer({ storageKey, onSend, busy, onAbort, disabled, placeholder, maxLength, attachments, leadingSlot, autoFocus, minHeight, maxHeight, }: ComposerProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/conversation/conversation-empty-state.d.ts

@@ -0,0 +1,8 @@
+export interface ConversationEmptyStateProps {
+    icon?: React.ReactNode;
+    title: string;
+    description?: string;
+    suggestions?: string[];
+    onSuggestion?: (suggestion: string) => void;
+}
+export declare function ConversationEmptyState({ icon, title, description, suggestions, onSuggestion, }: ConversationEmptyStateProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/conversation/conversation-panel.d.ts

@@ -0,0 +1,33 @@
+import type { ChatChunk as RuntimeChatChunk } from '../../../core/adapters/runtime';
+import { type ComposerAttachments } from './composer';
+import { type ConversationMessage } from './fold';
+import type { AgentTurnProps } from './agent-turn';
+export interface ConversationPanelProps {
+    /** Persisted rows (the caller owns storage; map local shapes onto ConversationMessage). */
+    messages: ConversationMessage[];
+    /** In-flight turn chunks (from useConversationThread); null/undefined when idle. */
+    liveChunks?: RuntimeChatChunk[] | null;
+    streaming?: boolean;
+    agentId?: string;
+    /** Renders an agent switcher next to the composer. */
+    onAgentChange?: (agentId: string) => void;
+    onSend: (content: string) => void | Promise<void>;
+    onAbort?: () => void;
+    onRetry?: AgentTurnProps['onRetry'];
+    transformText?: AgentTurnProps['transformText'];
+    /** Keys drafts/history/resize persistence. */
+    storageKey: string;
+    title?: React.ReactNode;
+    /** Default true; embedded surfaces with their own chrome pass false. */
+    showHeader?: boolean;
+    /** Fill the host container instead of a fixed resizable height. */
+    fitParent?: boolean;
+    readOnly?: boolean;
+    readOnlyNotice?: React.ReactNode;
+    placeholder?: string;
+    emptyState?: React.ReactNode;
+    maxLength?: number;
+    attachments?: ComposerAttachments;
+    className?: string;
+}
+export declare function ConversationPanel({ messages, liveChunks, streaming, agentId, onAgentChange, onSend, onAbort, onRetry, transformText, storageKey, title, showHeader, fitParent, readOnly, readOnlyNotice, placeholder, emptyState, maxLength, attachments, className, }: ConversationPanelProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/conversation/conversation.d.ts

@@ -0,0 +1,14 @@
+import { type AgentTurnProps } from './agent-turn';
+import type { ConversationTurn } from './fold';
+export interface ConversationProps {
+    turns: ConversationTurn[];
+    /** Fallback author for agent turns that don't carry their own agentId. */
+    agentId?: string;
+    /** Rendered centered when there are no turns (use ConversationEmptyState). */
+    emptyState?: React.ReactNode;
+    onRetry?: AgentTurnProps['onRetry'];
+    onOpenCall?: AgentTurnProps['onOpenCall'];
+    transformText?: AgentTurnProps['transformText'];
+    className?: string;
+}
+export declare function Conversation({ turns, agentId, emptyState, onRetry, onOpenCall, transformText, className, }: ConversationProps): import("react/jsx-runtime").JSX.Element;

package/_internal/app/components/conversation/fold.d.ts

@@ -0,0 +1,129 @@
+/**
+ * foldConversation — THE single folding engine for conversation surfaces.
+ *
+ * Consumes persisted `ConversationMessage` rows plus the in-flight turn's
+ * raw `RuntimeChatChunk`s and produces the renderable turn model
+ * (`ConversationTurn[]`). Every conversational surface (chat plugin,
+ * embedded brainstorm panels, task/workflow turn output) folds through
+ * here — never hand-roll chunk heuristics in a component.
+ *
+ * Semantics (pinned by tests/sdk/conversation-fold.test.ts):
+ * - Item ORDER inside a turn is preserved: text and tool-activity items
+ *   interleave in arrival order. Consecutive tool chunks group into ONE
+ *   activity item; a text chunk closes the group and later tools start a
+ *   new one.
+ * - Tool call/result pairs match by callId ACROSS group boundaries (a
+ *   result settles its original call even if text arrived in between).
+ *   A callId-less result closes the most recent RUNNING call of the same
+ *   tool; an orphan result settles as its own call.
+ * - Consecutive same-format text chunks coalesce; a format change starts
+ *   a new text item.
+ * - The newest status chunk is the streaming label. `done` → complete,
+ *   `error` → error (with a typed error item). Aborted turns come from
+ *   persisted `aborted` rows — the stream itself ends aborts with a clean
+ *   `done` (runtime contract).
+ */
+import type { ChatChunk as RuntimeChatChunk, ChatTextFormat } from '../../../core/adapters/runtime';
+/** Attachment as displayed in a conversation (URL-addressed, not path). */
+export interface DisplayAttachment {
+    name: string;
+    mimeType: string;
+    url: string;
+}
+/**
+ * One persisted conversation row — the kit's storable message shape.
+ * The chat plugin's transcript rows serialize to exactly this (plus its
+ * own storage concerns); embedded surfaces map their local shapes onto it.
+ * `turnId` groups the rows of one agent turn; rows without it (legacy)
+ * group by adjacency between user rows.
+ */
+export type ConversationMessage = {
+    kind: 'user';
+    ts: string;
+    content: string;
+    attachments?: DisplayAttachment[];
+} | {
+    kind: 'assistant';
+    ts: string;
+    turnId?: string;
+    agentId?: string;
+    content: string;
+} | {
+    kind: 'tool';
+    ts: string;
+    turnId?: string;
+    agentId?: string;
+    callId?: string;
+    toolName: string;
+    status?: 'running' | 'completed' | 'failed' | string;
+    summary?: string;
+    inputPreview?: string;
+    outputPreview?: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+} | {
+    kind: 'error';
+    ts: string;
+    turnId?: string;
+    message: string;
+    errorKind?: string;
+} | {
+    kind: 'aborted';
+    ts: string;
+    turnId?: string;
+};
+/** One tool invocation inside an activity group. */
+export interface ConversationToolCall {
+    /** Stable render key (callId when present). */
+    key: string;
+    callId?: string;
+    toolName: string;
+    status: 'running' | 'completed' | 'failed';
+    summary?: string;
+    inputPreview?: string;
+    outputPreview?: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+export type TurnItem = {
+    type: 'text';
+    format: ChatTextFormat;
+    content: string;
+} | {
+    type: 'activity';
+    calls: ConversationToolCall[];
+} | {
+    type: 'error';
+    message: string;
+    errorKind?: string;
+};
+export type TurnStatus = 'streaming' | 'complete' | 'error' | 'aborted';
+export type ConversationTurn = {
+    kind: 'user';
+    key: string;
+    ts: string;
+    content: string;
+    attachments?: DisplayAttachment[];
+} | {
+    kind: 'agent';
+    key: string;
+    ts?: string;
+    /** Author agent, when known (multi-agent embedded threads switch mid-conversation). */
+    agentId?: string;
+    items: TurnItem[];
+    status: TurnStatus;
+    /** Latest runtime status label ('thinking', …) — meaningful while streaming. */
+    statusLabel?: string;
+};
+export interface FoldOptions {
+    /** Raw chunks of the in-flight turn; presence (even empty) appends a streaming turn. */
+    liveChunks?: readonly RuntimeChatChunk[];
+    /** Author of the live turn, when known. */
+    liveAgentId?: string;
+}
+/**
+ * Fold persisted rows + optional live chunks into the renderable turn list.
+ * Pure — same inputs, same output (keys are derived from row position, so
+ * they're stable across re-folds).
+ */
+export declare function foldConversation(messages: readonly ConversationMessage[], opts?: FoldOptions): ConversationTurn[];

package/_internal/app/components/conversation/notification-sound.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reply chime — a soft two-tone WebAudio blip shared by every
+ * conversational surface's attention provider (moved from the chat plugin
+ * in #703; chat re-exports from here). Generated, not an asset: zero
+ * bundle weight, no file to embed, and the volume stays deliberately low
+ * (this is a nudge, not an alarm).
+ */
+export declare function playReplyChime(): void;

package/_internal/app/components/conversation/relative-time.d.ts

@@ -0,0 +1,8 @@
+/** Compact relative timestamps for conversation surfaces ('now', '5m', '3h', '2d', then a date). */
+export declare function formatRelativeTime(iso: string, now?: number): string;
+/** Full timestamp for tooltips. */
+export declare function formatAbsoluteTime(iso: string): string;
+/** Day-separator label ('Jul 10, 2026'). */
+export declare function formatDayLabel(iso: string): string;
+/** Calendar-day bucket for separator comparisons (local time). */
+export declare function dayKey(iso: string | undefined): string;