@flamingo-stack/openframe-frontend-core 0.0.488 → 0.0.490-1506.3944.1

package/dist/components/chat/stream/chat-dialog-store.d.ts

@@ -0,0 +1,184 @@
+/**
+ * createChatDialogStore — framework-free registry of `ChatStreamReducer`
+ * instances keyed by `(dialogId, side)`. Reducer state PERSISTS across
+ * component unmounts (the store outlives React), and the store is the
+ * `useSyncExternalStore` source for the `useChatStreamReducer` wrapper.
+ *
+ * CROSS-SIDE PROJECTION: exactly two operations fan out across sides of the
+ * same dialogId —
+ *   1. approval RESOLUTION by requestId (`approval-resolved` events), and
+ *   2. tool-execution MERGE by execId (`tool-execution` events)
+ * — implemented as idempotent pure projections over the other side's state
+ * (recomputed from state, never re-injected into the other side's seq
+ * stream; per-side seq gates stay untouched). Everything else — text,
+ * thinking, participant rows — is strictly per-side.
+ *
+ * LIFECYCLE / MEMORY: the reducer map is LRU-capped (`maxReducers`, default
+ * `DEFAULT_MAX_REDUCERS`) and evicted through the same path as `remove()`.
+ * Without a cap an agent cycling hundreds of dialogs would retain a reducer
+ * (thread + accumulator) per dialog for the process's lifetime; under SSR,
+ * where the store is module-scoped, that growth is shared across every
+ * request. `getSnapshot` is PURE — it never creates an entry — and
+ * `getServerSnapshot` always returns the shared frozen `EMPTY_STATE`.
+ *
+ * EVICTION SAFETY (LRU recency alone is NOT liveness):
+ *   1. RETAINED keys are never evicted. `retain(dialogId, side)` returns a
+ *      release fn; the `useChatStreamReducer` hook calls it for as long as it
+ *      is mounted, so a quiet-but-visible panel can't be dropped just because
+ *      ten other keys were touched. NON-React hosts must call it too.
+ *      Because the hook retains in an EFFECT but takes its reducer during
+ *      RENDER, a key created by a public `getReducer` is protected from
+ *      creation until its FIRST `retain()` (bounded by
+ *      `MAX_PENDING_RETAIN_KEYS`) — see `pendingRetain`.
+ *   2. A reducer whose `streamingPhase !== 'idle'` is never evicted — dropping
+ *      mid-turn would recreate an EMPTY reducer on the next `getReducer`
+ *      while the host's seq cursor still says "caught up", i.e. the thread
+ *      visually vanishes with no path back.
+ *   3. Eviction hands the host the dropped instance's PARKED state
+ *      (`onEvict(..., { messages, approvalStatuses, lastAppliedSeq,
+ *      pendingEchoes })`). A recreated reducer is pristine, so re-seeding
+ *      messages alone would
+ *      resurrect resolved approvals as actionable and reset the seq gate to
+ *      `-Infinity`; the parked payload is what makes the round-trip lossless.
+ *   4. Eviction NEVER notifies synchronously. `getReducer` is called during
+ *      render (by the hook), and notifying there means updating other
+ *      components mid-render. The notify is deferred to a microtask.
+ */
+import { type ChatReducerState, type ChatStreamReducer, type ChatStreamReducerOptions, type PendingEcho } from './chat-stream-reducer';
+import type { ChatStreamEvent } from '../../../chat-protocol/events';
+export type ChatDialogSide = string;
+/** Factory for a key's reducer options, consulted ONCE at creation. A plain
+ *  `() => options` thunk remains assignable. */
+export type CreateReducerOptionsFn = (dialogId: string, side: ChatDialogSide) => ChatStreamReducerOptions;
+export interface ChatDialogStore {
+    /** Create-or-get the reducer for `(dialogId, side)`. `createOptions` is
+     *  consulted ONLY when the instance is first created. */
+    getReducer(dialogId: string, side?: ChatDialogSide, createOptions?: CreateReducerOptionsFn): ChatStreamReducer;
+    /** Apply one event to a side, then fan out the cross-side projections to
+     *  the other sides of the same dialog. */
+    apply(dialogId: string, side: ChatDialogSide, event: ChatStreamEvent): void;
+    /** Run adapter commands against a reducer; subscribers are notified. */
+    mutate<T>(dialogId: string, side: ChatDialogSide, fn: (reducer: ChatStreamReducer) => T): T;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Referentially-stable snapshot for `useSyncExternalStore`. PURE — an
+     * unknown key returns the shared frozen `EMPTY_STATE` rather than
+     * creating a reducer (a create-on-read would let SSR renders accumulate
+     * reducers in a process-global map, and would make React's snapshot read
+     * a mutation).
+     */
+    getSnapshot(dialogId: string, side?: ChatDialogSide): ChatReducerState;
+    /** `useSyncExternalStore`'s server getter — always `EMPTY_STATE`. There is
+     *  no per-request store on the server, so a live thread cannot be rendered
+     *  server-side; the client hydrates from the real reducer. */
+    getServerSnapshot(): ChatReducerState;
+    /** Drop a side's reducer (or every side of the dialog when omitted). */
+    remove(dialogId: string, side?: ChatDialogSide): void;
+    /**
+     * PIN `(dialogId, side)` against LRU eviction while a consumer is live.
+     * Returns the release fn (idempotent; refcounted, so nested retains are
+     * safe). Creation is NOT implied — retaining an absent key simply means the
+     * key is protected once it exists.
+     */
+    retain(dialogId: string, side?: ChatDialogSide): () => void;
+    /**
+     * POLICY retain: keep exactly `keys` pinned by this store-level set and
+     * release every key the set previously pinned. Independent of the refcounted
+     * `retain()` handles a host's components hold — the two compose.
+     *
+     * Exists because "retain this set, release the rest" is generic store
+     * policy that every multi-panel host otherwise re-derives (diffing its own
+     * key list against a map of release fns). Retains BEFORE releasing, so a key
+     * present in both the old and the new set never momentarily drops to zero
+     * retains and becomes evictable mid-swap.
+     */
+    setRetained(keys: Array<{
+        dialogId: string;
+        side?: ChatDialogSide;
+    }>): void;
+}
+export declare const DEFAULT_DIALOG_SIDE: ChatDialogSide;
+/** Most-recently-used reducer keys retained before eviction. Ten covers
+ *  every realistic multi-panel / dialog-switching session while bounding an
+ *  agent that cycles hundreds of dialogs. */
+export declare const DEFAULT_MAX_REDUCERS = 10;
+/**
+ * Hard cap on keys held in the "created by `getReducer`, `retain()` still
+ * pending" protection set — the ONLY thing bounding the map while retains are
+ * outstanding, since that protection ends at the retain rather than on a timer.
+ *
+ * Deliberately far above `maxReducers`: a host may legitimately mount MORE
+ * panels than the LRU cap (once their effects run, retained keys already let
+ * the map exceed it), so capping the pending set at `maxReducers` would blank
+ * exactly the panels round 10 fixed. It is a backstop against a caller that
+ * reads a reducer once and drops it — or a concurrent render React discards
+ * before any effect runs — not a per-commit budget. Past it, the oldest pending
+ * key falls through to ordinary LRU.
+ */
+export declare const MAX_PENDING_RETAIN_KEYS = 256;
+export interface CreateChatDialogStoreOptions {
+    /** LRU cap on retained reducers (keys are `(dialogId, side)` pairs).
+     *  Values < 1 are clamped to 1. Default `DEFAULT_MAX_REDUCERS`. */
+    maxReducers?: number;
+    /**
+     * Options applied to any reducer this store creates WITHOUT an explicit
+     * per-call `createOptions` — i.e. every reducer first materialized by
+     * `apply()` or `mutate()`. Hosts with non-default reducer semantics
+     * (`ownEchoIncludesAdmin`, `selfUserId`, approve/reject `callbacks`, …)
+     * MUST set this: creation options are consulted once, so a bare
+     * apply-created instance would keep those semantics missing for its whole
+     * lifetime, including for a later `getReducer(..., options)` caller.
+     */
+    defaultCreateOptions?: CreateReducerOptionsFn;
+    /**
+     * Called when LRU eviction actually DROPS a key. The store knows this
+     * exactly; without publishing it, hosts are left inferring eviction by
+     * comparing reducer OBJECT IDENTITY across `getReducer` calls and then
+     * suppressing the "pristine empty" snapshot that a silently-recreated
+     * reducer returns — archaeology about a fact this callback states outright.
+     *
+     * Fires only for LRU eviction. Host-initiated `remove()` needs no
+     * notification: the caller already knows which key it dropped.
+     *
+     * Called AFTER the key is gone, from `getReducer` (i.e. potentially during a
+     * React render) — treat it as a "schedule a refetch/rehydrate" signal, not a
+     * place to set state synchronously.
+     *
+     * `parked` carries the dropped reducer's non-refetchable state so the host
+     * can restore it on the recreated instance (`initializeWithState(messages,
+     * { approvalStatuses, lastAppliedSeq, pendingEchoes })`). Refetching
+     * messages alone is NOT
+     * equivalent: a recreated reducer starts with `approvalStatuses = {}` and
+     * `lastAppliedSeq = -Infinity`, so a resolved approval whose APPROVAL_RESULT
+     * row is not in the refetched history page re-renders as ACTIONABLE (the
+     * exact hazard `resetForDialogSwitch` preserves that map to avoid), and a
+     * replay from the host's own cursor re-applies events the dropped instance
+     * had already consumed.
+     */
+    onEvict?: (dialogId: string, side: ChatDialogSide, parked: EvictedReducerState) => void;
+}
+/**
+ * Snapshot of an LRU-evicted reducer's state, captured just before the
+ * instance is dropped. Everything here either cannot be refetched
+ * (`lastAppliedSeq`) or is not reliably present in a refetched history page
+ * (`approvalStatuses`); `messages` rides along so a host that keeps its own
+ * copy does not have to.
+ */
+export interface EvictedReducerState {
+    messages: ChatReducerState['messages'];
+    approvalStatuses: ChatReducerState['approvalStatuses'];
+    /** `-Infinity` when the instance never applied a seq-carrying event. */
+    lastAppliedSeq: number;
+    /**
+     * Optimistic-echo entries still armed at eviction time. A key dropped
+     * between `pushOptimisticSend` and its `MESSAGE_REQUEST` echo would
+     * otherwise leave the recreated reducer with nothing armed, and the echo
+     * renders a DUPLICATE user bubble. Replay via
+     * `initializeWithState(messages, { pendingEchoes })`; the reducer drops
+     * entries already past `OWN_ECHO_AUTHOR_TTL_MS`. Empty for a key with no
+     * send in flight (the common case).
+     */
+    pendingEchoes: readonly PendingEcho[];
+}
+export declare function createChatDialogStore(options?: CreateChatDialogStoreOptions): ChatDialogStore;
+//# sourceMappingURL=chat-dialog-store.d.ts.map

package/dist/components/chat/stream/chat-dialog-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-dialog-store.d.ts","sourceRoot":"","sources":["../../../../src/components/chat/stream/chat-dialog-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAEpE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAA;AAEnC;gDACgD;AAChD,MAAM,MAAM,sBAAsB,GAAG,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,KACjB,wBAAwB,CAAA;AAE7B,MAAM,WAAW,eAAe;IAC9B;6DACyD;IACzD,UAAU,CACR,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,cAAc,EACrB,aAAa,CAAC,EAAE,sBAAsB,GACrC,iBAAiB,CAAA;IACpB;8CAC0C;IAC1C,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;IAC3E,wEAAwE;IACxE,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,CAAC,GAAG,CAAC,CAAA;IAC3F,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,gBAAgB,CAAA;IACtE;;kEAE8D;IAC9D,iBAAiB,IAAI,gBAAgB,CAAA;IACrC,wEAAwE;IACxE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;IACrD;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,MAAM,IAAI,CAAA;IAC3D;;;;;;;;;;OAUG;IACH,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,cAAc,CAAA;KAAE,CAAC,GAAG,IAAI,CAAA;CAC5E;AAED,eAAO,MAAM,mBAAmB,EAAE,cAAuB,CAAA;AAEzD;;6CAE6C;AAC7C,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAE1C,MAAM,WAAW,4BAA4B;IAC3C;uEACmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,sBAAsB,CAAA;IAC7C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,EAAE,CACR,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,mBAAmB,KACxB,IAAI,CAAA;CACV;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAA;IACtC,gBAAgB,EAAE,gBAAgB,CAAC,kBAAkB,CAAC,CAAA;IACtD,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAA;IACtB;;;;;;;;OAQG;IACH,aAAa,EAAE,SAAS,WAAW,EAAE,CAAA;CACtC;AAyBD,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,eAAe,CAgTjB"}

package/dist/components/chat/stream/chat-stream-reducer.d.ts

@@ -0,0 +1,367 @@
+/**
+ * createChatStreamReducer — THE master chat-stream reader (Phase 3 of the
+ * chat unification). One accumulation path for every event source:
+ *
+ *   SSE bytes  → createSseFrameDecoder ─┐
+ *   NATS chunk → decodeNatsChunk       ─┼→ ChatStreamEvent → reducer.apply()
+ *   history    → decodeHistoricalMessageData (per-item vocabulary) →
+ *                envelope grouping → reducer.initializeWithState()
+ *
+ * The reducer absorbs, verbatim, the semantics that used to be spread over
+ * three layers:
+ *   - `MessageSegmentAccumulator` stays as the internal per-turn segment
+ *     kernel (instantiated here — its goldens remain valid);
+ *   - the deleted `useRealtimeChunkProcessor`'s switch (in-stream vs post-END
+ *     routing, agent-busy outside a message window, escalated approvals,
+ *     compaction upsert, direct-mode barrier) — surfaced as
+ *     `ChatReducerEffect`s for consumers that want the callback contract;
+ *   - `useNatsChatAdapter`'s message-mutation callbacks (trailing-assistant
+ *     replace/append, compaction upsert, cross-message tool merge, approval
+ *     flip, participant dedup) — now the reducer's own state transitions via
+ *     `./message-mutations`;
+ *   - `useSseChatAdapter`/`useChat`'s SSE turn kernel (cumulative text
+ *     replace, front-inserted thinking, approval card, `decision_resolved`
+ *     receipt + cardRef stamping, sendIdx-keyed sources/refs/meta maps).
+ *
+ * Idempotency:
+ *   - events whose `seq` ≤ the last applied seq are dropped (per instance);
+ *   - participant rows additionally dedup via a one-shot optimistic-echo
+ *     list and a short same-author content window (seq-less transports);
+ *   - value-level no-op merges return prior references (see
+ *     `message-mutations.ts`).
+ *
+ * TRANSPORT ORDERING ASSUMPTION (the seq gate, see `apply()`): every
+ * transport feeding this reducer is AT-LEAST-ONCE and IN-ORDER. JetStream
+ * redelivers (hence the gate) but never reorders within a stream, and the
+ * catchup back-fill replays a monotonically increasing range. So `seq <=
+ * lastAppliedSeq` means "already applied", and dropping is correct.
+ * A genuinely out-of-order arrival (seq 5 then 4) would be discarded
+ * PERMANENTLY — accepted deliberately: no transport here reorders, and an
+ * out-of-order buffer would add latency + unbounded state to guard against
+ * a case that cannot occur. If a reordering transport is ever added, this
+ * gate is the place that must change (do not paper over it downstream).
+ *
+ * `resolvePendingApprovalForExecution` (the accumulator's implicit
+ * approve-on-execution) is reachable ONLY on `transport: 'nats'` — the SSE
+ * kernel never routes tool executions through the accumulator.
+ *
+ * PURE + framework-free: no React, no timers, no network. Side effects the
+ * UI needs (approve/reject POSTs) enter as opaque callbacks stamped onto
+ * approval segments.
+ */
+import { type AccumulatorCallbacks } from '../utils/message-segment-accumulator';
+import { type ScrollAnchor } from '../utils/scroll-anchor';
+import type { ChatApprovalStatus, MessageSegment, PendingToolCallData, ToolExecutionSegment, ExecutingToolState } from '../types';
+import type { PendingApproval } from '../types/processing.types';
+import type { DialogTokenUsage, StreamingPhase, UnifiedChatMessage, UnifiedUsageBreakdown } from '../types/unified-chat-state.types';
+import { type ChatStreamEvent } from '../../../chat-protocol/events';
+import type { ChatRef } from '../chat-ref.types';
+/** Per-turn metadata extracted from the streamed metadata/usage frames
+ *  (SSE transport). Canonical home — `use-sse-chat-adapter` re-exports it. */
+export interface ChatTurnMeta {
+    provider: string | null;
+    modelLabel: string | null;
+    contextWindowMaxTokens: number | null;
+    /** Input tokens (from usage:start). Includes cached tokens. */
+    inputTokens: number | null;
+    /** Output tokens (from the trailing usage frame). */
+    outputTokens: number | null;
+    /** Cache hit % (read / total-input × 100). Only known after stream end. */
+    cacheHitRatePct: number | null;
+    /** Cross-call usage breakdown extracted from the trailing usage frame. */
+    breakdown: UnifiedUsageBreakdown | null;
+    /** Per-message viewport-positioning hint. */
+    scrollAnchor: ScrollAnchor | null;
+    routedComplexity: string | null;
+    routedThinkingBudget: number | null;
+}
+/** Single source of truth for a fresh `ChatTurnMeta` row. */
+export declare function createEmptyTurnMeta(): ChatTurnMeta;
+/** SSE per-send maps, keyed by the send counter (`sendIdx`). Each user send
+ *  produces ONE server-side refs/sources entry but can fan out to MULTIPLE
+ *  assistant messages client-side — the adapter maps every following
+ *  assistant message back to its send's entry. */
+export interface ChatTurnMetaState {
+    meta: Map<number, ChatTurnMeta>;
+    sources: Map<number, unknown[]>;
+    refs: Map<number, Record<string, ChatRef>>;
+    sendCount: number;
+}
+export interface ChatReducerState {
+    messages: UnifiedChatMessage[];
+    streamingPhase: StreamingPhase;
+    turnMeta: ChatTurnMetaState;
+    dialogTokenUsage?: DialogTokenUsage | null;
+    liveModel?: {
+        provider: string | null;
+        modelLabel: string | null;
+        contextWindowMaxTokens: number | null;
+    } | null;
+    approvalStatuses: Record<string, ChatApprovalStatus>;
+}
+/** Escalated-approval bookkeeping entry (mirrors the legacy processor). */
+export interface EscalatedApprovalData {
+    command: string;
+    explanation?: string;
+    approvalType: string;
+    toolCalls?: PendingToolCallData[];
+}
+/**
+ * Callback-visible effect produced by `apply()`. Names + args mirror the
+ * legacy `RealtimeChunkCallbacks` contract 1:1 — the contract the deleted
+ * `useRealtimeChunkProcessor` wrapper exposed, now pinned directly by
+ * `__tests__/chat-stream-reducer-golden.test.ts`.
+ *
+ * `segments-after-approval-result` is the one conditional emission: the
+ * legacy processor emitted a cumulative `onSegmentsUpdate` for a
+ * non-escalated APPROVAL_RESULT only when the consumer had NOT wired
+ * `onApprovalResolved` — the effect sink resolves that at dispatch time.
+ */
+export interface ChatReducerEffect {
+    name: 'onStreamStart' | 'onStreamEnd' | 'onMetadata' | 'onSegmentsUpdate' | 'onError' | 'onUserMessage' | 'onTokenUsage' | 'onDirectMessage' | 'onSystemMessage' | 'onEscalatedApproval' | 'onEscalatedApprovalResult' | 'onApprovalResolved' | 'onToolExecuted' | 'onAgentBusy' | 'onDialogClosed' | 'segments-after-approval-result';
+    args: unknown[];
+}
+export interface ChatStreamReducerOptions {
+    /** Which transport's turn kernel drives `apply()`. Default `'nats'`. */
+    transport?: 'sse' | 'nats';
+    /** Seed for the approval-status map (request-id → status). */
+    approvalStatuses?: Record<string, ChatApprovalStatus>;
+    /** Batch APPROVAL_REQUESTs render as one card (default true) or unfold. */
+    batchApprovalsEnabled?: boolean;
+    /** Approval types displayed inline; others escalate. Default ['CLIENT']. */
+    displayApprovalTypes?: string[];
+    /** Opaque approve/reject handlers stamped onto approval segments. */
+    callbacks?: AccumulatorCallbacks;
+    /** Engage the direct-mode barrier optimistically (host-known takeover). */
+    isDirectMode?: boolean;
+    /**
+     * Legacy-processor parity knob: post-MESSAGE_END tool chunks route
+     * cross-message (`onToolExecuted` effect + `applyToolExecutionToMessages`)
+     * only when the consumer wired the cross-message updater; otherwise they
+     * fall through the accumulator like the pre-callback code path. Default
+     * true (both first-party adapters wire it).
+     */
+    crossMessageToolRouting?: boolean;
+    /** Effect sink for callback-contract consumers (compat wrapper). */
+    onEffect?: (effect: ChatReducerEffect) => void;
+    /** Notified after every state mutation (the dialog store wires this). */
+    onChange?: () => void;
+    /**
+     * Whether an ADMIN-authored `MESSAGE_REQUEST` may be consumed as OUR OWN
+     * optimistic echo (see `pushOptimisticSend`). Default `false`.
+     *
+     * Who the local operator is decides this, and it differs per host:
+     *  - Hub website chat / ticket CLIENT side: the local user is NEVER the
+     *    admin, so an ADMIN-authored inbound row is a technician's reply and
+     *    must ALWAYS render. Consuming it as an echo would silently delete a
+     *    real message whenever its text happened to match ours. → `false`.
+     *  - OpenFrame product app (Mingo + ticket ADMIN side): the operator IS
+     *    the admin, so their own sends echo back as ADMIN and MUST be
+     *    deduped, or every message renders twice. → `true`.
+     *
+     * Only ever applies to text the host itself registered via
+     * `pushOptimisticSend`, so enabling it cannot drop a message the host
+     * did not just send.
+     */
+    ownEchoIncludesAdmin?: boolean;
+    /**
+     * The LOCAL user's id, either as a value or as a GETTER resolved at event
+     * time. When it resolves to a value, an inbound `MESSAGE_REQUEST` that
+     * DECLARES a different author (`event.userId !== selfUserId`) may not be
+     * consumed as our own optimistic echo.
+     *
+     * Without it the echo list matches on RAW TEXT alone, which on a shared
+     * ADMIN side (two technicians in one ticket, `ownEchoIncludesAdmin: true`)
+     * can silently delete a colleague's message: if OUR send never echoes back,
+     * its entry stays armed and the next identical text from anyone — canned
+     * replies like "ok" / "done" / "on it" make this routine — is swallowed.
+     *
+     * The guard FAILS OPEN, deliberately: a row that carries NO `userId` is not
+     * "someone else's", it is UNATTRIBUTED, and rejecting it would disable
+     * dedup entirely (→ every send rendered twice) on any transport whose
+     * decoder does not surface the author id. Such a row falls back to the
+     * text + `OWN_ECHO_TTL_MS` behaviour instead, and a one-shot `console.warn`
+     * makes the missing id observable.
+     *
+     * Pass a FUNCTION whenever the id can change or arrive late (auth
+     * rehydration, logout / login-as-another-user without a reload): reducers
+     * are retained for the store's lifetime, so a value captured at creation
+     * time can go stale and silently disable the guard.
+     */
+    selfUserId?: string | (() => string | undefined);
+}
+/**
+ * How long an un-consumed optimistic-echo entry stays armed **on the
+ * UNATTRIBUTED path**. Long enough to cover any realistic send → server-echo
+ * round trip, short enough that a send whose echo never lands cannot swallow
+ * an unrelated identical message later in the conversation.
+ *
+ * A row that is DECLARED ours (`selfUserId` set and `event.userId ===
+ * selfUserId`) gets the LONGER `OWN_ECHO_AUTHOR_TTL_MS` instead — see there.
+ */
+export declare const OWN_ECHO_TTL_MS = 30000;
+/**
+ * How long an un-consumed entry stays armed on the AUTHOR-MATCHED path
+ * (`selfUserId` set, inbound row declares the same author).
+ *
+ * The author check rules out CROSS-technician theft, but NOT the same user on
+ * a second tab or device: a row THIS tab did not originate looks exactly like
+ * an author-matched echo. So the entry still needs an upper bound — without
+ * one, a send whose echo never lands (dropped frame, backend text
+ * normalization, reconnect gap) leaves the entry armed for the reducer's
+ * whole lifetime, and the next identical text from the same user on ANOTHER
+ * tab is silently swallowed. With `MAX_PENDING_ECHOES` armed slots and canned
+ * replies ("ok", "done", "on it") being exactly the recurring strings, that is
+ * a routine message-LOSS bug, strictly worse than the duplicate row it trades
+ * against.
+ *
+ * Ten minutes is the bound: generously longer than the slow echo the author
+ * path exists to protect (a JetStream catch-up replay after a network gap
+ * arrives long after the send, and its rows carry `seq`, so the seq-less
+ * content-dedup fallback cannot rescue it), and far shorter than the
+ * "same text again an hour later" window in which a stale entry does damage.
+ *
+ * It is a BACKSTOP, not the usual bound: `turn-end` disarms entries much
+ * sooner (see `purgeEchoesAtTurnEnd`). The ten minutes only ever apply to a
+ * dialog that never reports a turn boundary at all.
+ */
+export declare const OWN_ECHO_AUTHOR_TTL_MS: number;
+/** One armed optimistic-echo entry: the sent text and the wall-clock ms it was
+ *  armed at. Exported because the LRU-eviction round trip PARKS these (see
+ *  `getPendingEchoes` / `InitializeExtras.pendingEchoes`). */
+export interface PendingEcho {
+    text: string;
+    at: number;
+}
+export interface InitializeExtras {
+    existingSegments?: MessageSegment[];
+    pendingApprovals?: Map<string, PendingApproval>;
+    executingTools?: Map<string, ExecutingToolState>;
+    escalatedApprovals?: Map<string, EscalatedApprovalData>;
+    /**
+     * Approval statuses PARKED from a previous instance of this key (LRU
+     * eviction hands them to `onEvict`). Merged with the same state-monotonic
+     * precedence as `mergeApprovalStatuses` — a resolved approval must not come
+     * back as actionable, which is exactly why `resetForDialogSwitch` preserves
+     * this map rather than clearing it.
+     */
+    approvalStatuses?: Record<string, ChatApprovalStatus>;
+    /**
+     * Seq cursor PARKED from a previous instance of this key. A recreated
+     * reducer starts at `-Infinity`, so a host that replays from its own cursor
+     * would re-apply already-applied events; restoring the parked value keeps
+     * `apply()`'s idempotency gate intact across an eviction. Only ever moves
+     * the gate FORWARD (a lower value is ignored).
+     */
+    lastAppliedSeq?: number;
+    /**
+     * Armed optimistic-echo entries PARKED from a previous instance of this key.
+     * Without them, a key LRU-evicted between `pushOptimisticSend` and its
+     * `MESSAGE_REQUEST` echo leaves the replacement reducer with nothing armed,
+     * so the echo renders a DUPLICATE user bubble. Entries already past
+     * `OWN_ECHO_AUTHOR_TTL_MS` are dropped on restore (an expired entry could
+     * only swallow an unrelated identical message), and the list is capped at
+     * `MAX_PENDING_ECHOES` exactly as the live path is.
+     */
+    pendingEchoes?: readonly PendingEcho[];
+    /**
+     * Whether the restored thread is a RESUMED dialog (a `MESSAGE_START` already
+     * fired server-side), which makes post-stream continuation chunks append
+     * into the existing bubble instead of taking the cold-start cumulative path.
+     * Defaults to "the restored thread is non-empty" — an eviction restore of a
+     * key that never streamed must NOT claim it did, or a cold text-delta with
+     * no preceding `turn-start` appends into a bubble that was never spawned.
+     * Pass explicitly only to override that derivation.
+     */
+    resumed?: boolean;
+}
+export interface BeginSseSendOptions {
+    text: string;
+    hidden?: boolean;
+    userName?: string;
+    assistantName?: string;
+    assistantAvatar?: string;
+}
+export interface ChatStreamReducer {
+    /** Apply one normalized stream event. */
+    apply(event: ChatStreamEvent): void;
+    /** Current immutable state snapshot (stable identity between mutations). */
+    readonly state: ChatReducerState;
+    /** Full reset — thread, per-turn kernel, dedup sets, seq gate, maps. */
+    reset(): void;
+    /**
+     * Seed the thread (history hydration / persisted-state rehydration) and
+     * optionally the per-turn kernel + escalated approvals (resume of an
+     * incomplete turn). `messages: null` keeps the current thread. Escalated
+     * entries are re-surfaced via `onEscalatedApproval` effects. Marks the
+     * instance as having streamed so continuation chunks append.
+     */
+    initializeWithState(messages: UnifiedChatMessage[] | null, extras?: InitializeExtras): void;
+    setMessages(messages: UnifiedChatMessage[]): void;
+    prependMessages(messages: UnifiedChatMessage[]): void;
+    /** Optimistic local send: user bubble (+ echo record) + assistant placeholder. */
+    pushOptimisticSend(text: string, hidden?: boolean): void;
+    /** Wipe thread + per-turn kernel, keep approval statuses (legacy clear). */
+    clearThread(): void;
+    /** Per-dialog reset (keeps approval statuses — request-ids are global). */
+    resetForDialogSwitch(): void;
+    beginSseSend(options: BeginSseSendOptions): void;
+    endSseTurn(): void;
+    failSseTurn(errorMessage: string): void;
+    seedSseMaps(seed: {
+        sources?: Array<[number, unknown[]]>;
+        refs?: Array<[number, Record<string, ChatRef>]>;
+        sendCount?: number;
+    }): void;
+    setPhase(phase: StreamingPhase): void;
+    setApprovalStatus(requestId: string, status: ChatApprovalStatus | null): void;
+    /**
+     * CANONICAL merge of a PERSISTED status map (host-side store, history
+     * hydration, dialog-switch top-up) into this reducer's map.
+     *
+     * Precedence is STATE-MONOTONIC, not source-based, because either side can
+     * be the stale one:
+     *  - persisted lags (a snapshot taken before the stream resolved the
+     *    request) → the stream's resolved status must win, or a just-approved
+     *    card would be downgraded back to `pending` and re-arm its buttons;
+     *  - the STREAM lags (this tab saw the request, the operator resolved it in
+     *    a SECOND TAB, and the persisted map is the one carrying the truth) →
+     *    the persisted resolution must win, or the card stays actionable and
+     *    invites a second approve on an already-resolved request.
+     *
+     * With statuses being exactly `pending | approved | rejected | cancelled`,
+     * "resolved beats pending" is a total order that gets both directions
+     * right: take the persisted value when ours is `pending` and theirs isn't;
+     * keep ours otherwise. Persisted entries still fill in every request-id the
+     * stream hasn't seen (other dialogs, pre-session history).
+     */
+    mergeApprovalStatuses(persisted: Record<string, ChatApprovalStatus>): void;
+    setDirectMode(isDirectMode: boolean): void;
+    setDialogTokenUsage(usage: DialogTokenUsage | null): void;
+    /** +1/-1 windows during catchup replay (suppresses agent-busy locks). */
+    adjustAgentBusySuppression(delta: number): void;
+    armAdoptTrailingAssistant(value: boolean): void;
+    projectApprovalResolution(requestId: string, status: ChatApprovalStatus, resolvedByName?: string | null): void;
+    projectToolExecution(segment: ToolExecutionSegment): void;
+    /**
+     * The seq gate's current value (`-Infinity` before anything seq-carrying was
+     * applied). Not part of `state` — it is bookkeeping, not render input — but
+     * a host that PARKS a reducer (LRU eviction, dialog swap) needs it to
+     * restore idempotency on the recreated instance via
+     * `initializeWithState(messages, { lastAppliedSeq })`.
+     */
+    getLastAppliedSeq(): number;
+    /**
+     * Currently-armed optimistic-echo entries. Same rationale as
+     * `getLastAppliedSeq`: not render input, but a host that PARKS a reducer
+     * needs them to restore echo dedup on the recreated instance via
+     * `initializeWithState(messages, { pendingEchoes })` — otherwise an echo
+     * in flight across the eviction renders a duplicate user bubble.
+     */
+    getPendingEchoes(): readonly PendingEcho[];
+    getSegments(): MessageSegment[];
+    updateApprovalStatus(requestId: string, status: ChatApprovalStatus, resolvedByName?: string | null): MessageSegment[];
+    getPendingEscalated(): Map<string, EscalatedApprovalData>;
+}
+export declare function createChatStreamReducer(options?: ChatStreamReducerOptions): ChatStreamReducer;
+//# sourceMappingURL=chat-stream-reducer.d.ts.map

package/dist/components/chat/stream/chat-stream-reducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-stream-reducer.d.ts","sourceRoot":"","sources":["../../../../src/components/chat/stream/chat-stream-reducer.ts"],"names":[],"mappings":"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"}

package/dist/components/chat/stream/delta-batcher.d.ts

@@ -0,0 +1,51 @@
+/**
+ * createDeltaBatcher — framework-free, append-only batching of `text-delta`
+ * and `thinking-delta` events.
+ *
+ * WHY THIS IS SHARED (and not a hook-private detail): every host that drives a
+ * `ChatStreamReducer` from a raw transport needs the SAME batching, and a
+ * copy-paste of it drifts. The React wrapper (`useChatStreamReducer`) and any
+ * non-React mirror in a product app both consume this one implementation.
+ *
+ * Behaviour:
+ *   - `push(event, key)` queues delta events and returns true; anything else
+ *     returns false so the caller can flush + apply it synchronously (ordering:
+ *     completion state must always land on fully-applied deltas).
+ *   - CONSECUTIVE same-type deltas are COALESCED into one event (the reducer's
+ *     append semantics distribute over concatenation), so a 60-delta/sec turn
+ *     costs ONE `applyOne` per frame instead of 60. `text-delta` additionally
+ *     requires a matching `leading` flag before coalescing.
+ *   - A flush is scheduled on `requestAnimationFrame` when available, with a
+ *     timer fallback that is ALWAYS armed (rAF pauses in background tabs, and a
+ *     hidden chat panel must still keep its thread current).
+ *   - `key` is an opaque routing token handed back to `applyOne`. When it
+ *     changes, the pending batch is flushed against the PREVIOUS key first, so
+ *     deltas never land on the wrong dialog/side.
+ */
+import type { ChatStreamEvent, TextDeltaEvent, ThinkingDeltaEvent } from '../../../chat-protocol/events';
+export declare const DELTA_FLUSH_FALLBACK_MS = 50;
+export type DeltaEvent = TextDeltaEvent | ThinkingDeltaEvent;
+export declare function isDeltaEvent(event: ChatStreamEvent): event is DeltaEvent;
+export interface CreateDeltaBatcherOptions<K> {
+    /** Apply one (possibly coalesced) delta against `key`'s reducer. */
+    applyOne: (event: DeltaEvent, key: K | undefined) => void;
+    /** Called after a flush that applied at least one delta. */
+    onFlushed?: (appliedCount: number) => void;
+    /** Timer fallback in ms (default `DELTA_FLUSH_FALLBACK_MS`). */
+    fallbackMs?: number;
+}
+export interface DeltaBatcher<K = unknown> {
+    /**
+     * Queue `event` when it is a delta (returns true). Non-delta events are NOT
+     * queued and return false — the caller flushes and applies them itself.
+     */
+    push(event: ChatStreamEvent, key?: K): boolean;
+    /** Synchronously apply the pending batch and cancel any scheduled flush. */
+    flush(): void;
+    /** Flush and release timers — call on teardown so tail deltas aren't lost. */
+    dispose(): void;
+    /** Queued (post-coalescing) delta count. Test/diagnostic surface. */
+    readonly pendingCount: number;
+}
+export declare function createDeltaBatcher<K = unknown>({ applyOne, onFlushed, fallbackMs, }: CreateDeltaBatcherOptions<K>): DeltaBatcher<K>;
+//# sourceMappingURL=delta-batcher.d.ts.map

package/dist/components/chat/stream/delta-batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta-batcher.d.ts","sourceRoot":"","sources":["../../../../src/components/chat/stream/delta-batcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAExG,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,kBAAkB,CAAA;AAE5D,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,KAAK,IAAI,UAAU,CAExE;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,oEAAoE;IACpE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,CAAA;IACzD,4DAA4D;IAC5D,SAAS,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAA;IAC9C,4EAA4E;IAC5E,KAAK,IAAI,IAAI,CAAA;IACb,8EAA8E;IAC9E,OAAO,IAAI,IAAI,CAAA;IACf,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,EAC9C,QAAQ,EACR,SAAS,EACT,UAAoC,GACrC,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAgGhD"}

package/dist/components/chat/stream/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Chat stream module — ONE master reader for every chat event source
+ * (SSE decoder, NATS chunk decoder, historical replay). See
+ * `chat-stream-reducer.ts` for the architecture note.
+ *
+ * NOTE: the pure message-mutation helpers (`appendToTrailingAssistant`,
+ * `applyToolExecutionToMessages`, …) are intentionally NOT star-exported
+ * here — their legacy public home is `use-nats-chat-adapter`, which
+ * re-exports them from `./message-mutations`; exporting the same bindings
+ * from two star-exported barrels would make them ambiguous and drop them
+ * from the chat barrel entirely.
+ */
+export { createChatStreamReducer, createEmptyTurnMeta, type BeginSseSendOptions, type ChatReducerEffect, type ChatReducerState, type ChatStreamReducer, type ChatStreamReducerOptions, type ChatTurnMetaState, type EscalatedApprovalData, type InitializeExtras, type PendingEcho, } from './chat-stream-reducer';
+export { createChatDialogStore, DEFAULT_DIALOG_SIDE, DEFAULT_MAX_REDUCERS, MAX_PENDING_RETAIN_KEYS, type ChatDialogSide, type ChatDialogStore, type CreateChatDialogStoreOptions, type EvictedReducerState, } from './chat-dialog-store';
+export { createDeltaBatcher, type CreateDeltaBatcherOptions, type DeltaBatcher, type DeltaEvent, } from './delta-batcher';
+export { useChatStreamReducer, type UseChatStreamReducerOptions, type UseChatStreamReducerReturn, } from './use-chat-stream-reducer';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/chat/stream/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/chat/stream/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAA;AAO5B,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,2BAA2B,CAAA"}