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

package/dist/types/chat/conversation-send-message.d.ts

@@ -0,0 +1,43 @@
+import type { ConversationAttachmentReference } from "../contract/conversation";
+import { ConversationComposerWidget } from "../renderer/conversation-composer-widget";
+/**
+ * Everything a chat send carries alongside the plain message text. The object is always passed
+ * (a bare `{}` when there is nothing extra) so callers stop juggling a growing tail of positional
+ * optional arguments — every extra becomes a named, individually-optional field here instead.
+ */
+export type SendMessageOptions = {
+    /**
+     * Invisible START context: a model-visible, user-invisible SIGNAL prepended before the
+     * (possibly empty) user message when a dashboard-widget CTA starts the conversation, so the agent's
+     * first turn already has it. Empty/omitted for a normal typed message.
+     */
+    startSignalText?: string;
+    /**
+     * Uploaded media-library images that ride along with this message. ConversationMessageInput never builds these —
+     * it forwards the host-provided `outgoingAttachmentImages`.
+     */
+    attachments?: ConversationAttachmentReference[];
+    /**
+     * Composer widgets sent alongside this message — informational for hosts (the message TEXT is already the
+     * record: `onSendMessage` receives it with each widget's ```widget fence appended, see
+     * `buildMessageTextWithComposerWidgets`). ConversationMessageInput never builds these — it forwards the
+     * host-provided `outgoingComposerWidgets`.
+     */
+    composerWidgets?: ConversationComposerWidget[];
+    /**
+     * The stable key of the product entry point a NEW conversation is started from (e.g. `hub.starter.R2`): the start
+     * reopens the recent conversation of that entry point instead of starting an identical one. Ignored when the
+     * message goes into an existing conversation.
+     */
+    entryPointKey?: string;
+};
+/**
+ * Signature shared by every chat "send" callback across the Conversation components (ConversationMessageInput →
+ * ConversationViewBody → ConversationView) and their hosts (AgentChat, Conversation, …). The message text stays a
+ * required positional argument; everything else lives in the mandatory `options` object.
+ *
+ * May return `true`/`false` when the host can tell whether the send was actually accepted (dispatched/posted) or
+ * dropped by a caller-side guard (a closed conversation, an in-flight start) — see AgentChat's `handleSendMessage`,
+ * whose result feeds `ConversationWidgetCallbacks.sendMessageToChat`. `void` (most callers) reports nothing.
+ */
+export type SendMessageHandler = (message: string, options: SendMessageOptions) => void | boolean;

package/dist/types/chat/last-wire-message-is-unanswered-user-message.d.ts

@@ -0,0 +1,22 @@
+import type { ChatMessage } from "./chat-message";
+/** The phone call's started / ended markers — the call marker chip, structural context, never owed work. */
+export declare const PHONE_CALL_LIFECYCLE_SIGNAL_SOURCES: readonly string[];
+/**
+ * The SIGNAL rows that owe no work — the backend's `owesWork() === false` on a SIGNAL row, pinned by
+ * `signal-source-parity.json` (`_signal-source-parity.spec.ts`).
+ */
+export declare const SIGNAL_SOURCES_THAT_OWE_NO_WORK: readonly string[];
+/**
+ * Whether the newest WIRE message is the customer's own, still unanswered — the backend's `hasUnansweredInboundMessage`
+ * seen from the frontend, walked the same way: ERROR / CHECKPOINT rows are bookkeeping (never rendered, never an
+ * answer); a TOOL_MESSAGE (a tool's own widget to the customer, stored role ASSISTANT) is NOT the agent's answer — a
+ * customer question followed only by a tool's status widget stays owed; the phone-call lifecycle chips are structural
+ * context, never owed work, and so is the platform's notice that it wrote a widget on its own; any other trailing SIGNAL (a widget click, a memory-conflict clarify) IS owed work, exactly
+ * like a user message. Only then does a failed run have something to RETRY — the persisted
+ * message is re-driven server-side instead of asking the customer to send it again. A walk that diverges from the
+ * backend's shows the error card without the button while the backend would accept the retry — keep the two in step.
+ *
+ * The slice keeps `messages` ordered by `indexInConversation`; the sort here is belt-and-suspenders for a caller that
+ * hands in an unordered page, not a fix for an upstream ordering defect.
+ */
+export declare const lastWireMessageIsUnansweredUserMessage: (messages: ChatMessage[] | null) => boolean;

package/dist/types/chat/normalize-server-message-to-markdown.d.ts

@@ -0,0 +1,23 @@
+type ServerTextPart = {
+    type: "text";
+    text?: string;
+};
+type ServerComponentPart = {
+    type: "component";
+    name?: string;
+    props?: Record<string, unknown>;
+};
+type ServerToolUsePart = {
+    type: "tool_use";
+    name?: string;
+    input?: unknown;
+};
+type ServerMessagePart = ServerTextPart | ServerComponentPart | ServerToolUsePart;
+export type AssistantServerMessagePayload = {
+    role?: string;
+    content?: ServerMessagePart[];
+    parts?: ServerMessagePart[];
+    messageId?: string;
+};
+export declare const normalizeServerMessageToMarkdown: (message: unknown) => string;
+export {};

package/dist/types/chat/store/agents-chat-state.d.ts

@@ -0,0 +1,132 @@
+import type { AgentsClientError, AgentsConversation, AgentsConversationMessage, PostedMessage, StartedConversation } from "../../contract/conversation";
+import type { ChatMessage } from "../chat-message";
+import type { CanvasCreatedEntity, CanvasSliceState } from "../../renderer/canvas/canvas-reducers";
+import type { CanvasOpenRequest } from "../../renderer/canvas/canvas-state";
+import type { ConversationErrorType } from "./conversation-error-type";
+/**
+ * How an entry point outside the chat hands a job over to the chat that opens next (one generic opening
+ * request): the first visible message, or an invisible start signal so the agent speaks first, the entry point the
+ * start comes from, and a widget to mount without a message (a page handing over a tool). Set before the chat mounts,
+ * so a reset keeps it; the chat clears each part once it consumed it.
+ */
+export interface AgentsChatOpeningRequest {
+    /** The first visible owner message of the next started conversation. */
+    userMessage: string | null;
+    /** The invisible start signal of the next started conversation (an empty visible message carries it). */
+    startSignalText: string | null;
+    /** The entry point the start comes from; the server reopens that entry point's recent conversation instead. */
+    entryPointKey: string | null;
+    /** The canonical wire name of a deep-linkable widget the chat mounts once, without a message. */
+    deepLinkedWidgetName: string | null;
+}
+/** The state of one chat instance. */
+export interface AgentsChatState extends CanvasSliceState {
+    /** The conversation shown; null for a cold chat until a start or the metadata read brings it. */
+    conversation: AgentsConversation | null;
+    /** Null until the first page or a send; ordered by `indexInConversation`, the optimistic message last. */
+    messages: ChatMessage[] | null;
+    /** A send is on its way. */
+    conversationLoading: boolean;
+    /** The last read or send for this conversation came back. */
+    conversationLoaded: boolean;
+    /** An older page exists: the scroll-up load stays armed. */
+    hasMoreOlder: boolean;
+    /** The agent works on a turn (the controller mirrors the derived activity here; read by the launcher). */
+    aiThinking: boolean;
+    error: ConversationErrorType | null;
+    /** Seconds until the quota frees up again; set only while `error` is RATE_LIMIT. */
+    rateLimitRetryAfterSeconds: number | null;
+    /**
+     * The conversation the newest metadata or page read asked for; null after a reset. A late answer for another
+     * conversation — or one that lands after a reset — is dropped.
+     */
+    requestedConversationId: number | null;
+    /** A start is on its way; no second start is sent meanwhile. */
+    startingNewConversation: boolean;
+    /** The token of the start on its way; its answer applies only while it is still the pending one. */
+    pendingStartToken: number | null;
+    /**
+     * How many starts this chat instance sent — the source of `pendingStartToken`. Survives a reset (like
+     * `canvasMountCount`): the store outlives a remount of the chat, so a token is never reused for another start.
+     */
+    startTokenCount: number;
+    openingRequest: AgentsChatOpeningRequest;
+}
+export declare const EMPTY_AGENTS_CHAT_OPENING_REQUEST: AgentsChatOpeningRequest;
+export declare const INITIAL_AGENTS_CHAT_STATE: AgentsChatState;
+/**
+ * What happens to a chat instance. The read and send events carry the port's answers (`AgentsConversationClient`);
+ * the controller dispatches the `…Requested` event before it calls the port and the `…Received` / `…Failed` event
+ * with the answer.
+ */
+export type AgentsChatEvent = 
+/** A conversation switch, an empty chat, the chat's unmount: everything goes except the opening request and the two counters. */
+{
+    type: "reset";
+} | {
+    type: "conversationMetadataRequested";
+    conversationId: number;
+} | {
+    type: "conversationMetadataReceived";
+    conversationId: number;
+    conversation: AgentsConversation;
+} | {
+    type: "conversationMetadataFailed";
+    conversationId: number;
+} | {
+    type: "messagesPageRequested";
+    conversationId: number;
+}
+/** `hasMoreOlder` null: a changed-messages read, which says nothing about older pages. */
+ | {
+    type: "messagesPageReceived";
+    conversationId: number;
+    messages: AgentsConversationMessage[];
+    hasMoreOlder: boolean | null;
+} | {
+    type: "messagePostRequested";
+    message: ChatMessage;
+} | {
+    type: "messagePostReceived";
+    conversationId: number;
+    posted: PostedMessage;
+} | {
+    type: "messagePostFailed";
+    error: AgentsClientError;
+}
+/** Takes the next start token (`pendingStartToken`); the controller reads it after the dispatch. */
+ | {
+    type: "startRequested";
+    message: ChatMessage;
+} | {
+    type: "startReceived";
+    startToken: number;
+    started: StartedConversation;
+} | {
+    type: "startFailed";
+    error: AgentsClientError;
+} | {
+    type: "errorSet";
+    error: ConversationErrorType | null;
+} | {
+    type: "aiThinkingSet";
+    aiThinking: boolean;
+}
+/** Sets the named parts of the opening request; the others stay. */
+ | {
+    type: "openingRequestSet";
+    openingRequest: Partial<AgentsChatOpeningRequest>;
+} | {
+    type: "canvasOpened";
+    request: CanvasOpenRequest;
+} | {
+    type: "canvasClosed";
+    byCustomer: boolean;
+} | {
+    type: "canvasResetForNewTurn";
+} | {
+    type: "canvasCleared";
+} | {
+    type: "canvasCreatedEntityIdSet";
+    created: CanvasCreatedEntity;
+};

package/dist/types/chat/store/conversation-error-type.d.ts

@@ -0,0 +1,32 @@
+import type { AgentsClientError } from "../../contract/conversation";
+/**
+ * The error card the chat shows. A plain object with string values (not a TypeScript `enum`), so the chat store, the
+ * view and an app's older chat state share one vocabulary without a nominal type in between.
+ */
+export declare const ConversationErrorType: {
+    readonly AI_BUDGET: "AI_BUDGET";
+    /**
+     * HTTP 429 from an AI endpoint — a per-minute/hour/day usage quota was hit. Distinct from AI_BUDGET (monthly budget):
+     * this one clears on its own after the Retry-After window.
+     */
+    readonly RATE_LIMIT: "RATE_LIMIT";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly CONVERSATION_NOT_FOUND: "CONVERSATION_NOT_FOUND";
+    /**
+     * The backend run FAILED (e.g. the model provider returned an error). The raw provider error is admin-only (never
+     * shown here); the owner gets a generic "something went wrong" card.
+     */
+    readonly AGENT_ERROR: "AGENT_ERROR";
+    /**
+     * The conversation is COMPLETED/CANCELLED and refuses further owner input. Set from the server's stable error code
+     * `CONVERSATION_CLOSED` or by the chat's own pre-send guard; the error card owns the copy.
+     */
+    readonly CONVERSATION_CLOSED: "CONVERSATION_CLOSED";
+};
+export type ConversationErrorType = (typeof ConversationErrorType)[keyof typeof ConversationErrorType];
+/**
+ * The error card of a refused send (post or start), read from the port's error. Only the stable outcomes select a
+ * dedicated card; every other refusal is a generic network error — the same classification the older chat applies to
+ * the server's error codes (`AI_BUDGET_REACHED`, `RATE_LIMIT_EXCEEDED`, `CONVERSATION_CLOSED`).
+ */
+export declare const readConversationErrorTypeOfRefusedSend: (error: AgentsClientError) => ConversationErrorType;

package/dist/types/chat/store/create-agents-chat-store.d.ts

@@ -0,0 +1,23 @@
+import { type AgentsChatEvent, type AgentsChatState } from "./agents-chat-state";
+/**
+ * The state handle of one chat instance. The app creates one per chat (host application: one per agent
+ * window, created before the window's chat mounts) and releases it with the chat; the chat and the app's code outside
+ * the chat read and dispatch through the same handle. React reads it through `useAgentsChatSelector`.
+ */
+export interface AgentsChatStore {
+    getState: () => AgentsChatState;
+    /** Calls the listener after every state change; returns the unsubscribe. */
+    subscribe: (listener: () => void) => () => void;
+    dispatch: (event: AgentsChatEvent) => void;
+}
+/** The plain implementation of `AgentsChatStore`: one state object, replaced by the reducer on every event. */
+export declare class AgentsChatStateContainer implements AgentsChatStore {
+    protected state: AgentsChatState;
+    protected readonly listeners: Set<() => void>;
+    constructor(initialState?: AgentsChatState);
+    getState: () => AgentsChatState;
+    subscribe: (listener: () => void) => (() => void);
+    dispatch: (event: AgentsChatEvent) => void;
+}
+/** Creates the state handle of one chat instance. */
+export declare const createAgentsChatStore: (initialState?: AgentsChatState) => AgentsChatStore;

package/dist/types/chat/store/index.d.ts

@@ -0,0 +1,5 @@
+export { type AgentsChatEvent, type AgentsChatOpeningRequest, type AgentsChatState, EMPTY_AGENTS_CHAT_OPENING_REQUEST, INITIAL_AGENTS_CHAT_STATE, } from "./agents-chat-state";
+export { type AgentsChatStore, AgentsChatStateContainer, createAgentsChatStore } from "./create-agents-chat-store";
+export { reduceAgentsChatState } from "./reduce-agents-chat-state";
+export { ConversationErrorType, readConversationErrorTypeOfRefusedSend } from "./conversation-error-type";
+export { AgentsChatStoreProvider, useAgentsChatSelector, useAgentsChatState, useAgentsChatStore, useOptionalAgentsChatStore, } from "./use-agents-chat-store";

package/dist/types/chat/store/merge-chat-messages.d.ts

@@ -0,0 +1,20 @@
+import type { ChatMessage } from "../chat-message";
+/**
+ * Merges two message lists by `indexInConversation`, preferring `incoming` on a collision, sorted ascending by index.
+ * Messages without an index (the optimistic owner message) cannot be matched, so they follow the indexed ones in order.
+ * A start or post answer carries the whole list and a live read brings it again: concatenating would show every
+ * message twice.
+ */
+export declare const mergeChatMessagesByIndex: (existing: ChatMessage[], incoming: ChatMessage[]) => ChatMessage[];
+/**
+ * Tags the messages of a send's answer: `fresh` when the id was not in the list before — the server just delivered it,
+ * so its one-shot widgets may fire; a replayed message never fires them again.
+ */
+export declare const tagFreshChatMessages: (incoming: ChatMessage[], previousMessages: ChatMessage[]) => ChatMessage[];
+/**
+ * Merges a page of a keyset read (the newest page, an older page, the changed tail) into the loaded messages by index.
+ * A message is `fresh` only when it is a live arrival: never shown before and newer than everything loaded — so the
+ * streamed reply opens its canvas while a scroll-up page and the first page on open stay history. A message already
+ * shown keeps its tag. A page of another conversation than the one shown replaces the list.
+ */
+export declare const mergeMessagesPage: (loadedMessages: ChatMessage[] | null, page: ChatMessage[], requestedConversationId: number) => ChatMessage[];

package/dist/types/chat/store/reduce-agents-chat-state.d.ts

@@ -0,0 +1,7 @@
+import { type AgentsChatEvent, type AgentsChatState } from "./agents-chat-state";
+/**
+ * The chat store's reducer: plain functions over the contract types. Each case is the one of the older
+ * chat state (a Redux slice and its cases) it replaces, reading the port's answers instead of the
+ * generated client's actions; the replay spec feeds both the same recorded sequence.
+ */
+export declare const reduceAgentsChatState: (state: AgentsChatState, event: AgentsChatEvent) => AgentsChatState;

package/dist/types/chat/store/use-agents-chat-store.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from "react";
+import type { AgentsChatState } from "./agents-chat-state";
+import type { AgentsChatStore } from "./create-agents-chat-store";
+export interface AgentsChatStoreProviderProps {
+    /** The state handle of the chat below (the app creates and releases it). */
+    chatStore: AgentsChatStore;
+    children?: ReactNode;
+}
+/** Puts one chat instance's state handle in reach of the chat and of the app's components inside it. */
+export declare const AgentsChatStoreProvider: (props: AgentsChatStoreProviderProps) => import("react/jsx-runtime").JSX.Element;
+/** The state handle of the chat this component renders in; throws outside `AgentsChatStoreProvider`. */
+export declare const useAgentsChatStore: () => AgentsChatStore;
+/** The state handle of the chat this component renders in, or null outside a chat. */
+export declare const useOptionalAgentsChatStore: () => AgentsChatStore | null;
+/**
+ * Reads one value of a chat instance's state and re-renders when it changes. The selector must return a value that
+ * keeps its identity while the state does not change (a state field, not a new object). Without a store it returns
+ * `valueWithoutStore`.
+ */
+export declare const useAgentsChatSelector: <Selected>(chatStore: AgentsChatStore | null | undefined, selector: (state: AgentsChatState) => Selected, valueWithoutStore?: Selected) => Selected;
+/** Reads one value of the state of the chat this component renders in. */
+export declare const useAgentsChatState: <Selected>(selector: (state: AgentsChatState) => Selected) => Selected;

package/dist/types/chat/strip-pre-call-message-marker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Mirrors `AIConversationMessage::PRE_CALL_MESSAGE_MARKER` (PHP). The model prefixes a short "I'm about to do X"
+ * status line with this sentinel; the BACKEND only detects/signals on it and stores it RAW (it never strips). Every
+ * render layer — this is the customer chat one — strips it before showing the text to the user.
+ */
+export declare const PRE_CALL_MESSAGE_MARKER = "{preCallMessage}";
+/**
+ * Remove the {preCallMessage} sentinel from assistant text before display, and normalize the mangled JSON form to
+ * its inner status line. Also holds back a leading PARTIAL of either shape while it is still streaming in (so the
+ * user never sees a "{preCa…" or `{ "preCallMessage": "Einen Mo` flash before the full form arrives).
+ */
+export declare const stripPreCallMessageMarker: (text: string) => string;

package/dist/types/chat/use-canvas-shell-transitions.d.ts

@@ -0,0 +1,25 @@
+export interface CanvasShellTransitionsInput {
+    /** The conversation the view shows; undefined for a cold chat that has none yet. */
+    conversationId?: number;
+    /** The viewport is wide enough for the side split (`useCanvasViable`). */
+    canvasViable: boolean;
+}
+/**
+ * The two SHELL-driven transitions of the canvas model that `ConversationView` owns (the widget-driven ones go through
+ * `openCanvas`; the send boundary is the hosts'):
+ *
+ *  - **A conversation switch** (history select / new chat) makes the previous conversation's canvas stale — it is
+ *    cleared so the new conversation starts with a closed canvas. History replay never auto-opens a canvas (the
+ *    opening rule rejects replay), and the LEFT conversation keeps its stored pointer for when the customer comes
+ *    back. Only a REAL switch between two conversations counts. Not the first mount: a canvas the host opened on open
+ *    (the `?agentWidget=` deep-link, a restored canvas) mounts its widget BEFORE this parent effect runs, and an
+ *    unconditional reset would tear it down before the customer ever sees it. And not the id ARRIVING on a chat that
+ *    had none: that is the same conversation, just persisted now (the first send creates it) — closing the customer's
+ *    pinned work surface at that moment would be wrong.
+ *  - **The wide → narrow crossing** closes the side-split canvas as a shell close (re-openable, no customer veto).
+ *    Keyed on `canvasViable` ONLY (the canvas read through a ref) so it fires on the crossing, NOT when the mobile CTA
+ *    opens a canvas on an already narrow viewport. Skipped for a canvas whose behaviour says `narrowViewport:
+ *    "overlay"`: its widget renders nothing inline, so closing it on the crossing would leave the chat with no content
+ *    at all — it stays open as the full-screen overlay.
+ */
+export declare const useCanvasShellTransitions: ({ conversationId, canvasViable }: CanvasShellTransitionsInput) => void;

package/dist/types/client/AgentsConversationClient.d.ts

@@ -0,0 +1,93 @@
+import type { AgentsConversation, ChangedConversationMessages, ChangedMessagesRequest, ConversationActivity, ConversationAttachmentReference, ConversationChangeSignal, ConversationListQueryOptions, ConversationMessageSearchHit, ConversationMessageSentPayload, ConversationMessagesPage, ConversationSearchGroup, ConversationSearchOptions, ConversationSignal, ConversationSubscriptionEndReason, PostedMessage, SelectableModel, StartedConversation } from "../contract/conversation";
+/**
+ * The conversation client port (one function per row of the table, derived from the chat
+ * controller's requests). The package calls only this; an app binds it over its own request layer; the package
+ * ships an in-memory binding for specs, stories and the reference app (`client/testing/`).
+ *
+ * Rules every binding keeps:
+ * - ids are numbers; the agent space key is passed where the endpoint needs it;
+ * - every function rejects with `AgentsClientError` (`contract/conversation.ts`), never with a transport error;
+ * - a send returns once the server stored it — the agent's reply arrives through `subscribeToConversationChanges`;
+ * - the package adds the optimistic owner message before it calls a send and pairs request and answer itself;
+ * - a purposed start is not part of the port (it stays an app call).
+ */
+export interface AgentsConversationClient {
+    /** The conversation without messages: title, run state, the owed-turn mark, purpose, initiator. */
+    getConversationMetadata: (conversationId: number) => Promise<AgentsConversation>;
+    /** The newest page, each message with its delegated children's `{ id, runState }`. */
+    getNewestMessagesPage: (conversationId: number, pageSize: number) => Promise<ConversationMessagesPage>;
+    /** The page before `beforeIndex` (scroll-up). */
+    getOlderMessagesPage: (conversationId: number, beforeIndex: number, pageSize: number) => Promise<ConversationMessagesPage>;
+    /** New rows and rows that can still change (a live update); the package computes the request and keeps `hasMoreOlder`. */
+    getChangedMessages: (conversationId: number, request: ChangedMessagesRequest) => Promise<ChangedConversationMessages>;
+    /**
+     * Start a conversation with its first message. `text` may be empty only together with `startSignalText` (the agent
+     * speaks first); `entryPointKey` reopens the recent conversation of that entry point instead of starting an
+     * identical one; `model` is a name from `getSelectableModels`.
+     */
+    startConversation: (request: {
+        agentSpaceKey: number;
+        text: string;
+        startSignalText?: string;
+        entryPointKey?: string;
+        model?: string;
+        attachments?: ConversationAttachmentReference[];
+    }) => Promise<StartedConversation>;
+    /** Post the owner's message. Allowed while a turn runs: the server answers it in the next turn. */
+    postMessage: (conversationId: number, message: {
+        text: string;
+        model?: string;
+        attachments?: ConversationAttachmentReference[];
+    }) => Promise<PostedMessage>;
+    /** Inject a model-visible, owner-invisible signal (a widget click) and let the agent take a turn on it. */
+    injectSignal: (conversationId: number, signal: ConversationSignal) => Promise<void>;
+    /** Re-drive the failed run on the stored, still unanswered owner message. */
+    retryConversation: (conversationId: number) => Promise<void>;
+    /** Set the title by hand; returns the conversation with the stored title. */
+    renameConversation: (conversationId: number, title: string) => Promise<AgentsConversation>;
+    deleteConversation: (conversationId: number) => Promise<void>;
+    /** The root conversations of an agent space, newest first. */
+    listConversations: (agentSpaceKey: number, options?: ConversationListQueryOptions) => Promise<AgentsConversation[]>;
+    /** Search across the account's conversations, grouped by conversation. */
+    searchConversations: (text: string, options?: ConversationSearchOptions) => Promise<ConversationSearchGroup[]>;
+    /** Search inside one conversation. */
+    searchConversationMessages: (conversationId: number, text: string, options?: ConversationSearchOptions) => Promise<ConversationMessageSearchHit[]>;
+    /** What the agent does in the current turn; `turnMessageId` pins the narrated turn once known. */
+    getConversationActivity: (conversationId: number, turnMessageId?: number | null) => Promise<ConversationActivity>;
+    /** The models the owner may pick. Optional: without it the chat shows no model picker. */
+    getSelectableModels?: () => Promise<SelectableModel[]>;
+    /**
+     * The text the server stores for a message with attachments — the package shows the optimistic owner message with
+     * it, so the bubble does not change when the stored message arrives. Optional: without it the text stays as typed
+     * (a binding that sends attachments in a field of their own).
+     */
+    composeSentMessageText?: (text: string, attachments: ConversationAttachmentReference[] | undefined) => string;
+    /** The reconstructed request of a model call (the admin details panel). Optional. */
+    getMessageSentPayload?: (conversationId: number, messageId: number) => Promise<ConversationMessageSentPayload>;
+    /**
+     * Live updates: `onSignal` receives the conversation's signal as data, the first one right after the
+     * subscription is up; `onEnded` reports that the conversation is gone or no longer accessible (`gone`, `forbidden`) —
+     * the binding stops its own reads for it then (run-state checks), the package clears the status; a push transport may
+     * keep delivering until the unsubscribe. Returns the unsubscribe. The rules on top (throttle, terminal re-read,
+     * convergence on `lastMessageId`) are the package's; transport health (connection watchdog, token cache) is the
+     * binding's.
+     *
+     * Optional: a binding without a push transport leaves it out, and `withPollingChangeSubscription`
+     * (`client/polling/`) fills it with the polling default over `getConversationMetadata`; the default `AgentChat` does
+     * that by itself. `AgentChatController` and `useAgentsConversationRunStatus` follow nothing for a client without it.
+     */
+    subscribeToConversationChanges?: (conversationId: number, onSignal: (signal: ConversationChangeSignal) => void, onEnded: (reason: ConversationSubscriptionEndReason) => void) => () => void;
+}
+/** The port functions by name — the `operation` that `extraRequestParameters` receives. */
+export type AgentsConversationOperation = Exclude<keyof AgentsConversationClient, "subscribeToConversationChanges">;
+/** Extra query parameters a binding stamps onto a request: an app's own routing tags, admin overrides. */
+export type AgentsExtraRequestParameters = Record<string, string | number | boolean | undefined>;
+/** Options every binding that issues HTTP requests takes. */
+export interface AgentsConversationClientBindingOptions {
+    /**
+     * App-only request parameters per operation, merged over the binding's own (the host application's own
+     * overrides and its chat partition tag). Read on every request, so it may read
+     * state that changes at runtime. The package never names these parameters.
+     */
+    extraRequestParameters?: (operation: AgentsConversationOperation) => AgentsExtraRequestParameters;
+}

package/dist/types/client/AgentsConversationClientContext.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from "react";
+import type { AgentsConversationClient } from "./AgentsConversationClient";
+export interface AgentsConversationClientProviderProps {
+    /** The app's binding of the conversation client port. */
+    client: AgentsConversationClient;
+    children?: ReactNode;
+}
+/**
+ * Puts the app's conversation client in reach of the package's chat hooks (search, activity, conversation list). The
+ * app mounts it around the chat; until the provider carries the `client` member, this is where the
+ * hooks read it from.
+ */
+export declare const AgentsConversationClientProvider: (props: AgentsConversationClientProviderProps) => import("react/jsx-runtime").JSX.Element;
+/** The conversation client the app mounted; throws when a chat hook renders outside `AgentsConversationClientProvider`. */
+export declare const useAgentsConversationClient: () => AgentsConversationClient;
+/** The conversation client the app mounted, or null outside `AgentsConversationClientProvider`. */
+export declare const useOptionalAgentsConversationClient: () => AgentsConversationClient | null;

package/dist/types/client/polling/createPollingConversationChangeSubscription.d.ts

@@ -0,0 +1,62 @@
+import { type AgentsConversation, type ConversationChangeSignal, type ConversationRunStatus, type ConversationSubscriptionEndReason } from "../../contract/conversation";
+/** Read interval while a turn runs (or right after a local send). */
+export declare const POLLING_RUNNING_INTERVAL_MS = 2000;
+/** Read interval while the conversation is idle or failed. */
+export declare const POLLING_IDLE_INTERVAL_MS = 20000;
+/** Ceiling of the exponential backoff after failed reads. */
+export declare const POLLING_MAX_BACKOFF_MS = 60000;
+/**
+ * How long after a local send the poller keeps the running interval although the conversation still reads idle: the
+ * server may store the owner's message before it marks the turn as running.
+ */
+export declare const POLLING_LOCAL_ACTIVITY_WINDOW_MS = 10000;
+/** Reads a conversation's metadata — the port's `getConversationMetadata`. */
+export type ConversationMetadataReader = (conversationId: number) => Promise<AgentsConversation>;
+/** The timer functions the poller uses; a spec hands in fake ones. */
+export interface PollingTimers {
+    setTimeout: (callback: () => void, delayMs: number) => unknown;
+    clearTimeout: (timerHandle: unknown) => void;
+    now: () => number;
+}
+/** Whether the page is hidden, and a way to hear when that changes; a spec hands in its own. */
+export interface PollingDocumentVisibility {
+    isHidden: () => boolean;
+    /** Calls `listener` on every visibility change; returns the function that stops it. */
+    listen: (listener: () => void) => () => void;
+}
+export interface PollingConversationChangeSubscriptionOptions {
+    /** Default `POLLING_RUNNING_INTERVAL_MS` (2 s). */
+    runningIntervalMs?: number;
+    /** Default `POLLING_IDLE_INTERVAL_MS` (20 s). */
+    idleIntervalMs?: number;
+    /** Default `POLLING_MAX_BACKOFF_MS` (60 s). */
+    maxBackoffMs?: number;
+    /** Default `POLLING_LOCAL_ACTIVITY_WINDOW_MS` (10 s). */
+    localActivityWindowMs?: number;
+    /** Default: the global `setTimeout` / `clearTimeout` and `Date.now`. */
+    timers?: PollingTimers;
+    /** Default: the browser `document`; `null` = the page counts as always visible (no `document`, a worker). */
+    documentVisibility?: PollingDocumentVisibility | null;
+}
+/**
+ * The polling default of the live updates: the port's `subscribeToConversationChanges` plus
+ * `notifyLocalActivity`, which `withPollingChangeSubscription` calls after every send the server accepted.
+ */
+export interface PollingConversationChangeSubscription {
+    subscribeToConversationChanges: (conversationId: number, onSignal: (signal: ConversationChangeSignal) => void, onEnded: (reason: ConversationSubscriptionEndReason) => void) => () => void;
+    /** Reads the conversation's metadata now and keeps the running interval for the local-activity window. */
+    notifyLocalActivity: (conversationId: number) => void;
+}
+/**
+ * The three-value run status a polled read reports: the stored run state, and "running" for an idle conversation the
+ * server owes a turn (`agentTurnOwedAt`), as the chat's own derivation does.
+ */
+export declare const readPolledRunStatus: (conversation: AgentsConversation) => ConversationRunStatus | null;
+/**
+ * The polling default of `subscribeToConversationChanges` over a metadata read: every 2 s while a turn
+ * runs, every 20 s while idle, at once after `notifyLocalActivity`; paused while the page is hidden and read once when
+ * it shows again; exponential backoff on failed reads up to 60 s; a `notFound` / `forbidden` read ends the subscription
+ * with `gone` / `forbidden`. One poller per subscription; see `ConversationMetadataPoller` for how a read becomes a
+ * signal.
+ */
+export declare const createPollingConversationChangeSubscription: (readMetadata: ConversationMetadataReader, options?: PollingConversationChangeSubscriptionOptions) => PollingConversationChangeSubscription;

package/dist/types/client/polling/withPollingChangeSubscription.d.ts

@@ -0,0 +1,11 @@
+import type { AgentsConversationClient } from "../AgentsConversationClient";
+import { type PollingConversationChangeSubscriptionOptions } from "./createPollingConversationChangeSubscription";
+/** A conversation client whose `subscribeToConversationChanges` is present. */
+export type AgentsConversationClientWithChangeSubscription = AgentsConversationClient & Required<Pick<AgentsConversationClient, "subscribeToConversationChanges">>;
+/**
+ * The client with live updates: a client that brings its own `subscribeToConversationChanges` (a push
+ * transport — the host application's Firebase binding) is returned as it is; any other gets the polling default over its
+ * `getConversationMetadata` (`createPollingConversationChangeSubscription`, `options` tune the intervals). The default
+ * `AgentChat` calls this by itself.
+ */
+export declare const withPollingChangeSubscription: (client: AgentsConversationClient, options?: PollingConversationChangeSubscriptionOptions) => AgentsConversationClientWithChangeSubscription;