@mgamadeus/ddd-agents 0.0.0-stage → 0.1.0-alpha.21

package/dist/types/chat/controller/activity-ticker.d.ts

@@ -0,0 +1,120 @@
+import { ActivityElement } from "./merge-activity-elements";
+/**
+ * The least time a line stands beside the face before the next one takes its place — the concept's rhythm (the agent
+ * prototype's ThinkingIndicator swaps its line every 2.2 s), so every sentence can be read between two swaps.
+ */
+export declare const LINE_PACE_MS = 2200;
+/** The shorter wait while more than {@link BACKLOG_THRESHOLD} lines are queued, so a burst catches up. */
+export declare const BACKLOG_LINE_PACE_MS = 1400;
+/**
+ * More queued lines than this are shown at once, oldest first: one narrator answer carries up to 8 lines, and the
+ * ticker must never trail the turn by more than a few seconds.
+ */
+export declare const MAX_WAITING_LINES = 4;
+/** Finished turns kept in the thread at most (keepActivityHistoryAfterAnswer); the oldest one falls away beyond. */
+export declare const MAX_KEPT_TURNS = 30;
+/** One sentence the ticker shows: the started or the finished line of one step. */
+export interface ActivityTickerLine {
+    toolCallMessageId: number;
+    /** The step's state when this line was told: queued / running / finished / failed. */
+    state: string;
+    line: string;
+    kind: string | null;
+    /** The delegation helper that ran the step (1-based); null for the assistant's own steps. */
+    helperIndex: number | null;
+}
+/** Whether the line's step was still at work (queued or running) when the line was told, not finished or failed. */
+export declare const isStepStillRunning: (line: ActivityTickerLine) => boolean;
+/**
+ * What the ticker shows and what still waits to be shown. The endpoint delivers lines in bursts (one request per 3 s,
+ * up to 8 lines per narrator answer); this queue hands them to the screen one at a time.
+ */
+export interface ActivityTickerQueue {
+    /** The line each step shows right now, keyed by its tool-call message id. */
+    shownLines: Record<number, ActivityTickerLine>;
+    /** The steps shown before the newest one, oldest first; never contains {@link currentId}. */
+    trailIds: number[];
+    /** The step whose line was shown last: the one beside the face. */
+    currentId: number | null;
+    /** Lines not shown yet, oldest first, at most one per step (a newer line of the same step replaces the waiting one). */
+    waitingLines: ActivityTickerLine[];
+    /** When the newest line last changed (ms since epoch); the pace counts from here. */
+    lastShownAt: number;
+}
+export declare const EMPTY_ACTIVITY_TICKER_QUEUE: ActivityTickerQueue;
+/** Every shown line in the order it was told, oldest first. */
+export declare const shownLinesInOrder: (queue: ActivityTickerQueue) => ActivityTickerLine[];
+/**
+ * Put one line on screen. A line of a step already told replaces that step's line in place (the history keeps every
+ * step once); any other line becomes the newest one, beside the face, and the previous newest one moves up into the
+ * trail.
+ */
+export declare const showActivityLine: (queue: ActivityTickerQueue, line: ActivityTickerLine, now: number) => ActivityTickerQueue;
+/**
+ * Take the endpoint's elements in: every line not shown yet waits in the queue, except the finished line of a step
+ * already in the trail, which replaces that row in place at once. Skipped elements and elements of a step never told
+ * a sentence never show (only generated sentences appear).
+ */
+export declare const receiveActivityElements: (queue: ActivityTickerQueue, elements: ActivityElement[], now: number) => ActivityTickerQueue;
+/** Milliseconds until the next waiting line may be shown; null when nothing waits. */
+export declare const msUntilNextActivityLine: (queue: ActivityTickerQueue, now: number) => number | null;
+/** Show the oldest waiting line. The caller's timer decides when (see {@link msUntilNextActivityLine}). */
+export declare const releaseNextActivityLine: (queue: ActivityTickerQueue, now: number) => ActivityTickerQueue;
+/** Show every waiting line at once, oldest first — the turn has ended and the answer is on screen. */
+export declare const releaseAllActivityLines: (queue: ActivityTickerQueue, now: number) => ActivityTickerQueue;
+/** Steps the turn has finished or failed, the count the ticker reports. */
+export declare const countFinishedSteps: (elements: ActivityElement[]) => number;
+/**
+ * Delegation helpers with a step queued or running right now; a helper running several tool calls counts once. The
+ * helper number restarts at 1 for every delegate call, so a helper is told apart by the delegate call its steps follow
+ * (the endpoint lists each delegate call's helper steps right after it).
+ */
+export declare const countWorkingHelpers: (elements: ActivityElement[]) => number;
+/** "0:42" / "2:04" — elapsed time as a clock, no unit to translate. */
+export declare const formatElapsedClock: (elapsedMs: number) => string;
+/** Nothing on screen · lines beside the face while the turn runs · the face's success beat after it ended. */
+export type ActivityTickerPhase = "idle" | "live" | "done";
+/** A finished turn whose lines stay in the thread, above its answer, under the message that started it. */
+export interface KeptActivityTurn {
+    turnMessageId: number;
+    /** Every line the turn told, oldest first. */
+    lines: ActivityTickerLine[];
+}
+export interface ActivityTickerState {
+    queue: ActivityTickerQueue;
+    phase: ActivityTickerPhase;
+    /** The message that started the turn on screen, as the endpoint named it; null until it did. */
+    turnMessageId: number | null;
+    /** When the running turn started on this screen (ms since epoch), for the elapsed clock; null before any turn. */
+    liveSince: number | null;
+    /** Finished turns that stay in the thread, oldest first; filled only while the history is kept. */
+    keptTurns: KeptActivityTurn[];
+    /** The `running` of the previous input, to see where a turn starts and ends. */
+    wasRunning: boolean;
+}
+export declare const INITIAL_ACTIVITY_TICKER_STATE: ActivityTickerState;
+export type ActivityTickerAction = {
+    type: "elementsReceived";
+    elements: ActivityElement[];
+    running: boolean;
+    failed: boolean;
+    turnMessageId: number | null;
+    /** A turn in its success beat that the next turn replaces goes into {@link ActivityTickerState.keptTurns} first. */
+    keepHistory: boolean;
+    now: number;
+} | {
+    type: "nextLineDue";
+    now: number;
+} | {
+    type: "doneBeatOver";
+    keepHistory: boolean;
+};
+/**
+ * The ticker's life across turns. A turn starts when `running` rises: the queue starts clean and the phase goes live.
+ * Within a turn the endpoint's snapshot only grows (mergeActivityElements keeps every row it has seen), so a shown step
+ * missing from the elements means another turn or another conversation: the queue starts clean. When `running` falls,
+ * the waiting lines are shown at once and the face's success beat follows — unless the turn failed or never told a
+ * line. After the beat the turn's lines either stay in the thread ({@link KeptActivityTurn}) or are gone, as
+ * `keepHistory` says.
+ */
+export declare const activityTickerReducer: (state: ActivityTickerState, action: ActivityTickerAction) => ActivityTickerState;

package/dist/types/chat/controller/changed-messages-request.d.ts

@@ -0,0 +1,12 @@
+import type { ChangedMessagesRequest } from "../../contract/conversation";
+import type { ChatMessage } from "../chat-message";
+/**
+ * What a live update reads, given the loaded messages: every row written since the newest loaded one, plus every
+ * message from the lowest one that can still change. "Written since" goes by id, not index: ids grow with every write,
+ * while an index can be taken below the newest loaded one (a call row persisted after the row its execution emitted)
+ * or reused (a re-drive after an admin delete-from). The index start never lies below the newest page (a newest-first
+ * page of `pageSize` cannot return older rows anyway), so a row a dead worker left pending cannot pin it. Nothing
+ * loaded yet → null: the caller reads the newest page as on open. How the request reaches the wire (the filter string)
+ * is the binding's matter (`AgentsConversationClient.getChangedMessages`).
+ */
+export declare const buildChangedMessagesRequest: (messages: ChatMessage[] | null, pageSize: number) => ChangedMessagesRequest | null;

package/dist/types/chat/controller/chat-scroll-target.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A request to scroll the chat to a specific message and flash it. Produced when a search result is clicked
+ * (the app's search → the chat host) and consumed by the chat controller. `nonce` changes on every request so clicking the
+ * same result twice re-triggers the scroll even though messageId/indexInConversation are unchanged.
+ */
+export type ChatScrollTarget = {
+    messageId?: number | null;
+    indexInConversation?: number | null;
+    nonce: number;
+};

package/dist/types/chat/controller/conversation-change-signal-rules.d.ts

@@ -0,0 +1,64 @@
+import type { ConversationChangeSignal, ConversationRunStatus, ConversationSubscriptionEndReason } from "../../contract/conversation";
+/** While a turn streams, per-message signals arrive in bursts — the re-read is coalesced to one per this window. */
+export declare const LIVE_READ_THROTTLE_MS = 1200;
+/** Grace before the first convergence re-read (lets the terminal status' own immediate read land first). */
+export declare const CONVERGENCE_BASE_DELAY_MS = 700;
+/** Backoff ceiling between convergence re-reads. */
+export declare const CONVERGENCE_MAX_DELAY_MS = 2500;
+/** Stop re-reading for a missing terminal `lastMessageId` after this many attempts (the next action recovers). */
+export declare const CONVERGENCE_MAX_ATTEMPTS = 6;
+/** What the live-update rules make the chat do. */
+export interface ConversationLiveUpdateReads {
+    /** Read the rows that changed (the chat's changed-tail read). */
+    readChangedMessages: () => void;
+    /** Read the conversation's metadata again (title, run state). */
+    readConversationMetadata: () => void;
+    /** Whether a message is loaded — the convergence check of a terminal signal's `lastMessageId`. */
+    hasLoadedMessage: (messageId: number) => boolean;
+    /** The run status the chat shows; null once the subscription ended. */
+    showRunStatus: (runStatus: ConversationRunStatus | null) => void;
+}
+/**
+ * The package's rules over a conversation's live updates — one instance per subscription:
+ * - the first pushed signal reads once (a turn may have moved between the chat's open and the subscription), and is
+ *   the baseline of the counter and of `summaryUpdatedAt`;
+ * - a counter advance reads again, throttled to one read per `LIVE_READ_THROTTLE_MS` with one trailing read;
+ * - a terminal status reads at once, re-reads the metadata (on the baseline and on every terminal signal that
+ *   advances the counter: the server closes a conversation after the turn and publishes one more idle signal), and
+ *   keeps reading with backoff until the signal's `lastMessageId` is loaded (a reply that beat its own commit);
+ * - a changed `summaryUpdatedAt` after the baseline re-reads the metadata only;
+ * - a status-check emission (`isStatusCheck`) sets the status, and reads again — at once on a terminal status — only
+ *   while the push path is not alive (the binding's `isPushPathAlive`; without it: no pushed signal arrived yet) and
+ *   its status differs from the previous check's;
+ * - an ended subscription clears the status.
+ * The transport's health (reconnect, a dead path, token refresh) is the binding's.
+ */
+export declare class ConversationChangeSignalRules {
+    protected readonly reads: ConversationLiveUpdateReads;
+    protected lastChangeCounter: number | null;
+    protected hasSummaryBaseline: boolean;
+    protected lastSummaryUpdatedAt: number | null;
+    protected hasPushedSignalArrived: boolean;
+    protected lastStatusCheckRunStatus: ConversationRunStatus | null;
+    protected lastReadAt: number;
+    protected trailingReadTimer: ReturnType<typeof setTimeout> | null;
+    protected convergenceTimer: ReturnType<typeof setTimeout> | null;
+    protected convergenceAttempt: number;
+    protected convergenceMessageId: number | null;
+    protected disposed: boolean;
+    constructor(reads: ConversationLiveUpdateReads);
+    receiveSignal: (signal: ConversationChangeSignal) => void;
+    receiveEnd: (_reason: ConversationSubscriptionEndReason) => void;
+    /** Reads now, bypassing the throttle (the chat's safety poll). */
+    readNow: () => void;
+    dispose: () => void;
+    protected receiveStatusCheck(runStatus: ConversationRunStatus | null, isPushPathAlive: boolean): void;
+    /** One coordinated read path: `immediate` (a terminal status) cancels a pending trailing read and reads now. */
+    protected requestRead(immediate: boolean): void;
+    protected readThrottled(): void;
+    protected readTrailing: () => void;
+    protected clearTrailingRead(): void;
+    protected convergeOnMessage(messageId: number | null): void;
+    protected checkConvergence: () => void;
+    protected clearConvergence(): void;
+}

package/dist/types/chat/controller/derive-agent-activity.d.ts

@@ -0,0 +1,31 @@
+import type { ChatMessage } from "../chat-message";
+/** How many sub-agents spawned by this message are still working. */
+export declare const countOutstandingChildren: (message: ChatMessage) => number;
+/** A tool call whose result is still to come — its progress lives in `toolCall.status`, never in the row's status. */
+export declare const hasUnresolvedToolCall: (message: ChatMessage) => boolean;
+/** Whether this message's delegation can still change: a child is still working, or the call is not resolved yet. */
+export declare const hasDelegationInFlight: (message: ChatMessage) => boolean;
+export type AgentActivity = {
+    /** Whether a turn is in flight — drives the indicator's visibility (ConversationView aiThinking). */
+    active: boolean;
+    /**
+     * Translation source string for "what the agent is doing right now" (empty when nothing to show). Rendered through
+     * the chat's `Text`, so this is the translatable key with %placeholders% — NOT pre-interpolated. The dynamic values
+     * arrive via {@link AgentActivity.replacements} and plural form via {@link AgentActivity.context}.
+     */
+    label: string;
+    /** Dynamic values substituted into the %placeholders% of {@link AgentActivity.label} by <Text>. */
+    replacements?: Record<string, string | number>;
+    /** Plural selector for <Text> when the label is count-dependent. */
+    context?: "one" | "other";
+    /** A non-delegate tool is running → show the ASCII wrench spinner instead of a text label. */
+    toolRunning?: boolean;
+};
+/**
+ * Derive "what the agent is doing right now" for the agent activity indicator PURELY from the
+ * live conversation data: the message tree (refreshed on each realtime-signal tick / on open) plus the signal's
+ * coarse runStatus ("running" | "idle" | "failed" | null). No network. Mirrors the backend truth —
+ * AIConversation.runState (IDLE/RUNNING/AWAITING_DELEGATES/…) and per-message status/messageType/toolCall — but reads
+ * it off the messages the FE already holds, so the indicator is correct even before the first signal emission.
+ */
+export declare const deriveAgentActivity: (messages: ChatMessage[] | null, runStatus: string | null) => AgentActivity;

package/dist/types/chat/controller/merge-activity-elements.d.ts

@@ -0,0 +1,25 @@
+import type { ConversationActivityElement } from "../../contract/conversation";
+/**
+ * What the activity read sends per element and the stack reads (`ConversationActivityElement`); every field may be
+ * missing on an element a caller builds by hand (stories, specs).
+ */
+export type ActivityLineInput = Partial<ConversationActivityElement>;
+/** One row of the stack: the element as the endpoint sent it last, keyed by its tool-call message id. */
+export type ActivityElement = ActivityLineInput & {
+    toolCallMessageId: number;
+};
+/**
+ * Merge a response into the stack: a later state replaces an earlier one, a line never disappears once told (an
+ * element answered without a line, because the narrator was late, keeps the sentence it already had), and an element
+ * the response no longer carries stays (the turn snapshot is complete, so this only happens on a pinned turn that a
+ * later turn pushed out of the window). Row order is the endpoint's: the order of the persisted rows.
+ */
+export declare const mergeActivityElements: (previous: ActivityElement[], incoming: ActivityLineInput[] | null | undefined) => ActivityElement[];
+/** The rows the customer reads: skipped elements carry nothing. */
+export declare const visibleActivityElements: (elements: ActivityElement[]) => ActivityElement[];
+/**
+ * Whether a response names a turn different from the one pinned locally — the stack must start clean instead of
+ * merging the new turn's rows into the previous (already folded) one. False until a turn is pinned, and false while
+ * the response has not named a turn yet (a request still in flight for the newly pinned, not-yet-answered turn).
+ */
+export declare const isDifferentTurn: (pinnedTurnMessageId: number | null, answeredTurnMessageId: number | null) => boolean;

package/dist/types/chat/controller/pending-start-request.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A start an agent entry point outside the widget handed over: a visible USER message (`message`), or the invisible
+ * START signal behind an EMPTY visible message (`signal`), which makes the agent speak first.
+ */
+export interface PendingStartRequest {
+    kind: "message" | "signal";
+    text: string;
+}
+/**
+ * The one start the chat should send from the two hand-over fields (the opening request's `userMessage` and
+ * `startSignalText`). The app's openers keep at most one of the two set — each clears the
+ * other's leftover on the way in — but the message still wins here if both somehow are, since the customer's own words
+ * are the stronger request.
+ */
+export declare const pickPendingStartRequest: (pendingStartUserMessage: string | null, pendingStartSignalText: string | null) => PendingStartRequest | null;
+export interface ChatStateForPendingStartRequest {
+    /** The start an agent entry point outside the widget handed over (`pickPendingStartRequest`). */
+    pendingStartRequest: PendingStartRequest | null;
+    /** The conversation the widget currently wants open (the chat's `conversationId` prop). */
+    activeConversationId: number | null | undefined;
+    /** The conversation the chat slice currently holds — set until a new-chat reset clears it. */
+    loadedConversationId: number | null | undefined;
+    /** A start-with-message POST is already in flight (the chat store's `startingNewConversation`). */
+    startingNewConversation: boolean;
+    /** The start this chat has already sent, so the same one is never posted twice. */
+    alreadySentStartRequest: PendingStartRequest | null;
+}
+/**
+ * Whether the chat should send `pendingStartRequest` as the start of a NEW conversation right now. Called on every
+ * relevant state change — NOT once on mount: the widget is often already open (and mounted) when an entry point
+ * outside it hands over a request, which is what BUF-4009 was.
+ *
+ * "Not yet" (false) and "never" (false) deliberately look the same to the caller: the request stays in the slice, and
+ * this is asked again on the next change. A conversation still being open is the "not yet" case — Agent drops to a new
+ * chat when a request arrives, because every incentive CTA promises a fresh chat for its job, and this then says yes
+ * on the cold chat that follows.
+ */
+export declare const isChatReadyToSendPendingStartRequest: ({ pendingStartRequest, activeConversationId, loadedConversationId, startingNewConversation, alreadySentStartRequest, }: ChatStateForPendingStartRequest) => boolean;

package/dist/types/chat/controller/use-activity-ticker.d.ts

@@ -0,0 +1,60 @@
+import { ActivityTickerLine, ActivityTickerPhase } from "./activity-ticker";
+import { ActivityElement } from "./merge-activity-elements";
+/**
+ * How long the face's success beat rests before the face turns back to idle — counted from the start of the success
+ * roll. The ticker keeps or drops the turn's lines once it is over; an app's face times its success roll by it.
+ */
+export declare const SUCCESS_BEAT_MS = 1400;
+interface UseActivityTickerParams {
+    /** The rows of the running turn from {@link useConversationActivity}, in row order. */
+    elements: ActivityElement[];
+    /** Whether the endpoint says the turn is still in flight. */
+    running: boolean;
+    /** The message that started the turn, as the endpoint named it; null until it did. */
+    turnMessageId?: number | null;
+    /** The turn ended in an error: no success beat, nothing kept. */
+    failed?: boolean;
+    /**
+     * After the answer, each finished turn's lines stay in the thread above its answer, under the message that started
+     * it; false = they fade out with the line beside the face and nothing remains.
+     */
+    keepActivityHistoryAfterAnswer?: boolean;
+}
+/** One turn's lines — the turn running now, in the face's success beat, or kept in the thread. */
+export interface ActivityTickerTurn {
+    /** The message that started the turn: its kept history stands right after it. Null until the endpoint named it. */
+    turnMessageId: number | null;
+    /** live = the turn runs; done = it ended. */
+    phase: "live" | "done";
+    /** Every line told in the turn, oldest first; while live, the last one stands beside the face. */
+    lines: ActivityTickerLine[];
+    /** Steps finished or failed so far. */
+    stepCount: number;
+    /** Steps delegation helpers are running right now. */
+    helperCount: number;
+    /** When the running turn started on this screen (ms since epoch), for the elapsed clock; null once it ended. */
+    liveSince: number | null;
+}
+/** What the ticker shows right now — read by AgentActivity (the face and its lines) and the history in the thread. */
+export interface ActivityTicker {
+    /** The phase of the turn on screen; the face keeps working while it is live. */
+    phase: ActivityTickerPhase;
+    /** The turn running now or in the face's success beat; null when idle and before the turn's first line. */
+    currentTurn: ActivityTickerTurn | null;
+    /**
+     * The finished turns whose lines stand in the thread, under the message that started each, oldest first: every kept
+     * turn plus the turn in the face's success beat. Empty unless the history is kept; a turn the endpoint never named
+     * is never among them (it has no message to stand under).
+     */
+    historyTurns: ActivityTickerTurn[];
+}
+/**
+ * Paces the activity lines of a running turn at the prototype's ThinkingIndicator rhythm. The
+ * endpoint delivers lines in bursts; the ticker puts them beside the face one at a time — each stays at least 2.2 s,
+ * or 1.4 s while more than two wait — and never falls more than a few lines behind. When the turn ends, the rest is
+ * shown at once and the face plays its success beat ({@link SUCCESS_BEAT_MS}); the turn's lines then stay in the
+ * thread or are gone, as `keepActivityHistoryAfterAnswer` says. The state machine lives in
+ * {@link activityTickerReducer}; this hook only owns the timers.
+ */
+export declare const useActivityTicker: (params: UseActivityTickerParams) => ActivityTicker;
+export {};

package/dist/types/chat/controller/use-conversation-activity.d.ts

@@ -0,0 +1,38 @@
+import { ActivityElement } from "./merge-activity-elements";
+/** At most one activity request per this many milliseconds per conversation, whatever the tick rate. */
+export declare const ACTIVITY_REQUEST_WINDOW_MS = 3000;
+/** While a turn runs, a request also fires on this cadence: the floor for a dead signal. */
+export declare const RUNNING_FLOOR_MS = 4000;
+/**
+ * Once the signal no longer says "running", this many failed requests in a row end the turn on screen: an endpoint that
+ * keeps failing must not keep the face working and ask again every {@link RUNNING_FLOOR_MS} while the chat is open.
+ */
+export declare const MAX_FAILED_REQUESTS_AFTER_SIGNAL_ENDED = 3;
+type Params = {
+    conversationId: number;
+    /** The signal's run status: "running" while a turn drives, "idle" / "failed" when it ended, null before the first read. */
+    runStatus: string | null;
+    /** Advances on every signal tick the host acts on (its message refetch); each advance asks for the activity too. */
+    signalVersion: number;
+    enabled?: boolean;
+};
+type Result = {
+    /** The rows of the stack in row order; empty before the first turn of this mount. */
+    elements: ActivityElement[];
+    /** Whether the narrated turn is still in flight. */
+    running: boolean;
+    /** The message that started the narrated turn, as the endpoint named it; null before its first answer. */
+    turnMessageId: number | null;
+};
+/**
+ * What the agent is doing for the customer right now: pulls the conversation client's
+ * `getConversationActivity` (`AgentsConversationClientProvider`) while the customer watches a running turn and merges the answer into the stack. Frontend-driven on purpose: nothing is
+ * generated for a hidden tab or a closed chat. The turn is pinned when it starts (`turnMessageId` from the first
+ * answer), so a message the customer sends mid-turn does not move the window. Debounced to one request per
+ * {@link ACTIVITY_REQUEST_WINDOW_MS} with one trailing request after a burst; a terminal status fires one request for
+ * the finished lines, and the requests go on until the endpoint answers that the turn ended — then the stack rests
+ * until the next turn. A failed run ends the turn with that last request, whatever it answers, and so do
+ * {@link MAX_FAILED_REQUESTS_AFTER_SIGNAL_ENDED} failed requests in a row once the signal stopped saying "running".
+ */
+export declare const useConversationActivity: ({ conversationId, runStatus, signalVersion, enabled, }: Params) => Result;
+export {};

package/dist/types/chat/controller/use-conversation-live-updates.d.ts

@@ -0,0 +1,30 @@
+import type { AgentsConversationClient } from "../../client/AgentsConversationClient";
+import type { ConversationRunStatus } from "../../contract/conversation";
+import type { AgentsChatStore } from "../store/create-agents-chat-store";
+import type { ConversationMessagePages } from "./use-conversation-message-pages";
+export interface ConversationLiveUpdatesInputs {
+    client: AgentsConversationClient;
+    chatStore: AgentsChatStore;
+    /** The reads the rules trigger (`useConversationMessagePages`). */
+    messagePages: ConversationMessagePages;
+    /** The conversation to follow; undefined for a cold chat (no subscription). */
+    conversationId: number | undefined;
+}
+export interface ConversationLiveUpdates {
+    /** The run status the signal (or the binding's run-state check) reported last; null before the first and once ended. */
+    runStatus: ConversationRunStatus | null;
+    /** Counts the live reads the rules triggered — the activity read follows it (one activity read per signal tick). */
+    liveReadCount: number;
+    /** Reads the changed tail now, bypassing the throttle, and counts it (the chat's safety poll). */
+    readChangedTailNow: () => void;
+}
+/**
+ * The chat's live updates over `subscribeToConversationChanges`: one subscription per conversation,
+ * the rules of `ConversationChangeSignalRules`, the reads written into the chat store.
+ */
+export declare const useConversationLiveUpdates: (inputs: ConversationLiveUpdatesInputs) => ConversationLiveUpdates;
+/**
+ * The run status of a conversation for code outside the chat (the launcher button, the end of a voice call), over the
+ * same port function and the same status rules as the chat — without reading any message.
+ */
+export declare const useAgentsConversationRunStatus: (client: AgentsConversationClient, conversationId: number | undefined) => ConversationRunStatus | null;

package/dist/types/chat/controller/use-conversation-message-pages.d.ts

@@ -0,0 +1,24 @@
+import type { AgentsConversationClient } from "../../client/AgentsConversationClient";
+import type { AgentsChatStore } from "../store/create-agents-chat-store";
+/** The page size of every message read of the chat: the newest page, the changed tail and an older page. */
+export declare const CONVERSATION_MESSAGE_PAGE_SIZE = 50;
+export interface ConversationMessagePages {
+    /** Reads the conversation without messages into the store; resolves false when the read was refused. */
+    readConversationMetadata: (conversationId: number) => Promise<boolean>;
+    /** The newest page an open reads; a changed-tail read asked meanwhile waits for it. */
+    fetchOpeningPage: (conversationId: number) => void;
+    /** The rows written since the newest loaded one and the rows that can still change (a live update). */
+    refetchChangedTail: (conversationId: number) => void;
+    /** The page before the oldest loaded message (scroll-up); guarded against a second load and an exhausted history. */
+    loadOlder: (conversationId: number | undefined) => Promise<void>;
+    /** An older page is on its way. */
+    loadingOlder: boolean;
+}
+/**
+ * The chat's message reads over the conversation client port, written into the chat store: the newest page of an
+ * open, the changed tail every live update asks for, an older page on scroll-up, and the metadata read. A changed-tail
+ * read asked while the open's newest page is still on its way would read that same page again (nothing is loaded yet,
+ * so it has no filter): it is held instead and sent once the page is in, reading past what the page brought, so a
+ * reply stored in between still arrives. A failed page read changes nothing (the next live update reads again).
+ */
+export declare const useConversationMessagePages: (chatStore: AgentsChatStore, client: AgentsConversationClient, pageSize?: number) => ConversationMessagePages;

package/dist/types/chat/controller/use-conversation-scroll-jump.d.ts

@@ -0,0 +1,47 @@
+import { RefObject } from "react";
+import type { ChatMessage } from "../chat-message";
+import type { ChatScrollTarget } from "./chat-scroll-target";
+/** What the scroll follow reads of the activity ticker: its phase and the lines of the turn on screen. */
+export interface ConversationScrollActivityTicker {
+    phase: string;
+    currentTurn: {
+        lines: {
+            toolCallMessageId: number;
+            state: string | null;
+        }[];
+    } | null;
+}
+export interface ConversationScrollJumpInputs {
+    /** The top-bar search's request to scroll a message into view and flash it; re-applied whenever its nonce changes. */
+    scrollTarget: ChatScrollTarget | undefined;
+    /** The conversation the host asked for (the chat's `conversationId` prop) — the one a request is armed for. */
+    conversationId: number | undefined;
+    /** The conversation the chat store holds right now; differs from `conversationId` for a beat after a switch. */
+    conversation: {
+        id?: number | null;
+    } | null;
+    /** The loaded messages: every change retries a pending request. */
+    messages: ChatMessage[] | null;
+    /** The loaded messages as of the last render, read where the retry runs. */
+    messagesRef: RefObject<ChatMessage[] | null>;
+    /** Whether an older page exists, as of the last render. */
+    hasMoreOlderRef: RefObject<boolean>;
+    /** Pages the next older page in (self-guarded against concurrent and exhausted loads). */
+    loadOlder: () => Promise<void>;
+    /** The chat's scroll container (the host may own it, e.g. for a scroll-linked background). */
+    chatScrollRef: RefObject<HTMLDivElement | null>;
+    /** What the activity ticker shows; a new line scrolls it into view while the chat follows the bottom. */
+    activityTicker: ConversationScrollActivityTicker;
+}
+export interface ConversationScrollJump {
+    /** Bottom-follow flag shared with ConversationViewBody; false while a jump is armed and after it. */
+    followBottomRef: RefObject<boolean>;
+    /** "A programmatic jump is in flight" gate shared with ConversationViewBody. */
+    scrollJumpActiveRef: RefObject<boolean>;
+}
+/**
+ * The chat's programmatic scrolling: the jump to a requested message (paging older pages in until it is rendered, then
+ * the flash once the smooth scroll settled) and keeping the activity ticker in view as it grows. Owns the two refs it
+ * shares with ConversationViewBody, which suspend the bottom-follow while a jump is armed.
+ */
+export declare const useConversationScrollJump: (inputs: ConversationScrollJumpInputs) => ConversationScrollJump;

package/dist/types/chat/controller/use-conversation-search.d.ts

@@ -0,0 +1,31 @@
+import type { ConversationMessageSearchHit, ConversationSearchGroup } from "../../contract/conversation";
+export interface ConversationMessageSearchState {
+    query: string;
+    setQuery: (query: string) => void;
+    trimmedQuery: string;
+    hits: ConversationMessageSearchHit[] | null;
+    searching: boolean;
+    isSearchActive: boolean;
+    /** Wipe query + hits. The caller runs this in the click handler that OPENS the panel (see hook doc). */
+    clearSearch: () => void;
+}
+export interface ConversationsSearchState {
+    query: string;
+    setQuery: (query: string) => void;
+    trimmedQuery: string;
+    searchGroups: ConversationSearchGroup[] | null;
+    searching: boolean;
+    isSearchActive: boolean;
+    /** Wipe query + results. The caller runs this in the click handler that OPENS the panel (see hook doc). */
+    clearSearch: () => void;
+}
+/**
+ * In-conversation "find in this chat" search state: the conversation client's `searchConversationMessages` returns
+ * the matched hits of one conversation.
+ */
+export declare const useConversationMessageSearch: (conversationId: number, enabled: boolean) => ConversationMessageSearchState;
+/**
+ * Cross-conversation "search all my chats" state: the conversation client's `searchConversations` returns the
+ * matches grouped by conversation.
+ */
+export declare const useConversationsSearch: (enabled: boolean) => ConversationsSearchState;

package/dist/types/chat/controller/use-conversation-signals.d.ts

@@ -0,0 +1,44 @@
+import { Dispatch, SetStateAction } from "react";
+import type { AgentsConversationClient } from "../../client/AgentsConversationClient";
+import type { ChatMessage } from "../chat-message";
+import type { SendMessageHandler } from "../conversation-send-message";
+import type { InjectSignalOptions } from "../../renderer/ConversationWidgetCallbacksContext";
+import { createWidgetRenderReportCollector } from "../../renderer/render-report/widget-render-report-collector";
+export interface ConversationSignalsInputs {
+    /** The conversation client the signals go through (`injectSignal`). */
+    client: AgentsConversationClient;
+    /** The conversation the host asked for (the chat's `conversationId` prop); a signal targets it while none is loaded. */
+    conversationId: number | undefined;
+    /** The conversation the chat store holds right now. */
+    conversation: {
+        id?: number | null;
+    } | null;
+    /** The loaded messages; the newest settled assistant message is checked for a dropped widget block. */
+    messages: ChatMessage[] | null;
+    /** The signal's run status ("running" | "idle" | "failed" | null). */
+    runStatus: string | null;
+    /** A start is in flight; a signal is not sent into a conversation that does not exist yet then. */
+    startingNewConversation: boolean;
+    /** The run is over; the backend refuses further input. */
+    isConversationRunEnded: boolean;
+    /** The chat's send — a signal without a conversation starts one through it. */
+    handleSendMessage: SendMessageHandler;
+    /** Shows the closed-conversation refusal on the error card. */
+    rejectAsConversationClosed: () => void;
+    /** Re-reads the conversation's metadata (the closed run state locks the widget controls). */
+    refetchConversationSummary: () => void;
+    /** The chat's jump-to-bottom request counter; a customer's click follows the turn it starts. */
+    setScrollToBottomNonce: Dispatch<SetStateAction<number>>;
+}
+export interface ConversationSignals {
+    /** Injects a model-visible, customer-invisible signal into the current conversation (the widget context's `injectSignal`). */
+    handleInjectSignal: (signalText: string, options?: InjectSignalOptions) => Promise<boolean>;
+    /** The widget render report collector of the current conversation (one per conversation). */
+    renderReportCollector: ReturnType<typeof createWidgetRenderReportCollector>;
+}
+/**
+ * The signals the chat sends besides the customer's messages: a widget's injected signal (with the closed-conversation
+ * guard and the cold start through a START signal), a context-only signal parked until a turn is observed running,
+ * the corrective signal for a widget block the renderer dropped, and the widget render report.
+ */
+export declare const useConversationSignals: (inputs: ConversationSignalsInputs) => ConversationSignals;

package/dist/types/chat/controller/use-debounced-semantic-search.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared semantic-search state with a hard 700ms debounce and a minimum three-character query because every request
+ * runs an LLM reranker and consumes AI credits. `enabled` mirrors whether the owning panel is open; the caller runs
+ * `clearSearch` in the open handler so it renders clean immediately, while a rising-edge reset effect would flash the
+ * previous session's query and results.
+ */
+export declare const useDebouncedSemanticSearch: <TResult>(fetcher: (trimmedQuery: string) => Promise<TResult[]>, enabled: boolean) => {
+    query: string;
+    setQuery: import("react").Dispatch<import("react").SetStateAction<string>>;
+    trimmedQuery: string;
+    results: TResult[] | null;
+    searching: boolean;
+    isSearchActive: boolean;
+    clearSearch: () => void;
+};