@mgamadeus/ddd-agents 0.0.1-stage → 0.1.0-alpha.22

package/dist/types/client/testing/createInMemoryAgentsConversationClient.d.ts

@@ -0,0 +1,139 @@
+import type { AgentsConversationClient, AgentsConversationOperation } from "../AgentsConversationClient";
+import { type AgentsConversation, type AgentsConversationMessage, type ChangedConversationMessages, type ChangedMessagesRequest, type ConversationActivity, type ConversationAttachmentReference, type ConversationChangeSignal, type ConversationListQueryOptions, type ConversationMessageSearchHit, type ConversationMessageSentPayload, type ConversationMessagesPage, type ConversationRunStatus, type ConversationSearchGroup, type ConversationSearchOptions, type ConversationSignal, type ConversationSubscriptionEndReason, type PostedMessage, type SelectableModel, type StartedConversation } from "../../contract/conversation";
+/** One recorded conversation handed to the in-memory client: plain data, as a fixture file holds it. */
+export interface RecordedConversation {
+    conversation: AgentsConversation;
+    messages: AgentsConversationMessage[];
+    /** What `getConversationActivity` answers for this conversation; an empty, finished turn when omitted. */
+    activity?: ConversationActivity;
+}
+export interface InMemoryAgentsConversationClientData {
+    conversations: RecordedConversation[];
+    /**
+     * The assistant's answers to a post, an injected signal, a start or a retry, used in order; the last one repeats.
+     * Default: one answer, "Done.".
+     */
+    scriptedAssistantAnswers?: string[];
+    /** What `getSelectableModels` answers; the client has no `getSelectableModels` when omitted. */
+    selectableModels?: SelectableModel[];
+    /** The page size of `getChangedMessages` when the request names none. Default 50. */
+    defaultPageSize?: number;
+    /** What `getMessageSentPayload` answers, by message id; the client has no `getMessageSentPayload` when omitted. */
+    sentPayloadsByMessageId?: Record<number, ConversationMessageSentPayload>;
+    /**
+     * The assistant answers this many milliseconds after the send, like a server's turn: the run state is RUNNING
+     * meanwhile, then the answer is stored and the run state goes back to IDLE — no `emit()` involved, so a poller sees it.
+     * Default 0: the answer is stored together with the send.
+     */
+    assistantAnswerDelayMs?: number;
+    /**
+     * The client has no `subscribeToConversationChanges` — a backend without push. The chat then follows the
+     * conversation through the polling default (`withPollingChangeSubscription`). Default false.
+     */
+    withoutChangeSubscription?: boolean;
+}
+/** A subscriber of one conversation's live updates. */
+interface ConversationChangeSubscriber {
+    onChange: (signal: ConversationChangeSignal) => void;
+    onEnded: (reason: ConversationSubscriptionEndReason) => void;
+}
+/** The live-update state of one conversation. */
+interface ConversationSignalState {
+    changeCounter: number;
+    summaryUpdatedAt: number | null;
+}
+/**
+ * The conversation client over recorded conversations, for specs, stories and the reference app
+ * (`./testing`). Behaves like the server where the chat can see it: a post stores the owner's message and, at once,
+ * the next scripted assistant answer — but live updates are driven by hand: `emit()` sends the conversation's next
+ * signal to its subscribers (counter advanced, newest message id, the run status), `end()` ends the subscriptions.
+ * With `assistantAnswerDelayMs` the answer is stored later, as a server turn would (RUNNING meanwhile); with
+ * `withoutChangeSubscription` the client has no subscription at all and the chat polls it.
+ */
+export declare class InMemoryAgentsConversationClient implements AgentsConversationClient {
+    protected readonly recordsByConversationId: Map<number, RecordedConversation>;
+    protected readonly subscribersByConversationId: Map<number, Set<ConversationChangeSubscriber>>;
+    protected readonly signalStateByConversationId: Map<number, ConversationSignalState>;
+    protected readonly scriptedAssistantAnswers: string[];
+    protected readonly defaultPageSize: number;
+    protected readonly selectableModels: SelectableModel[] | undefined;
+    protected readonly sentPayloadsByMessageId: Record<number, ConversationMessageSentPayload> | undefined;
+    protected readonly assistantAnswerDelayMs: number;
+    protected readonly requestCountsByOperation: Map<AgentsConversationOperation, number>;
+    protected scriptedAssistantAnswersUsed: number;
+    protected nextMessageId: number;
+    protected nextConversationId: number;
+    /** Present only when the data names selectable models (the port function is optional). */
+    readonly getSelectableModels?: () => Promise<SelectableModel[]>;
+    /** Present only when the data names sent payloads (the port function is optional). */
+    readonly getMessageSentPayload?: (conversationId: number, messageId: number) => Promise<ConversationMessageSentPayload>;
+    /** Present unless the data asks for a client without push (`withoutChangeSubscription`). */
+    readonly subscribeToConversationChanges?: (conversationId: number, onChange: (signal: ConversationChangeSignal) => void, onEnded: (reason: ConversationSubscriptionEndReason) => void) => () => void;
+    constructor(data: InMemoryAgentsConversationClientData);
+    listConversations: (agentSpaceKey: number, options?: ConversationListQueryOptions) => Promise<AgentsConversation[]>;
+    /** Account-wide, like the server: every recorded conversation is searched. */
+    searchConversations: (text: string, options?: ConversationSearchOptions) => Promise<ConversationSearchGroup[]>;
+    /** The stored conversation with `lastMessageId` (the newest stored message), as a backend without push answers it. */
+    getConversationMetadata: (conversationId: number) => Promise<AgentsConversation>;
+    getNewestMessagesPage: (conversationId: number, pageSize: number) => Promise<ConversationMessagesPage>;
+    getOlderMessagesPage: (conversationId: number, beforeIndex: number, pageSize: number) => Promise<ConversationMessagesPage>;
+    getChangedMessages: (conversationId: number, request: ChangedMessagesRequest) => Promise<ChangedConversationMessages>;
+    searchConversationMessages: (conversationId: number, text: string, options?: ConversationSearchOptions) => Promise<ConversationMessageSearchHit[]>;
+    getConversationActivity: (conversationId: number) => Promise<ConversationActivity>;
+    startConversation: (request: {
+        agentSpaceKey: number;
+        text: string;
+        startSignalText?: string;
+        entryPointKey?: string;
+        model?: string;
+        attachments?: ConversationAttachmentReference[];
+    }) => Promise<StartedConversation>;
+    postMessage: (conversationId: number, message: {
+        text: string;
+        model?: string;
+        attachments?: ConversationAttachmentReference[];
+    }) => Promise<PostedMessage>;
+    injectSignal: (conversationId: number, signal: ConversationSignal) => Promise<void>;
+    retryConversation: (conversationId: number) => Promise<void>;
+    renameConversation: (conversationId: number, title: string) => Promise<AgentsConversation>;
+    deleteConversation: (conversationId: number) => Promise<void>;
+    /** The port's `subscribeToConversationChanges` unless `withoutChangeSubscription`; signals come from `emit()`. */
+    protected subscribeToRecordedConversationChanges: (conversationId: number, onChange: (signal: ConversationChangeSignal) => void, onEnded: (reason: ConversationSubscriptionEndReason) => void) => (() => void);
+    /**
+     * Sends the conversation's next signal to its subscribers: the counter advances, `lastMessageId` is the newest
+     * stored message, the run status follows the stored run state unless `runStatus` is given. `summaryChanged` also
+     * advances `summaryUpdatedAt`. Returns the sent signal.
+     */
+    emit: (conversationId: number, change?: {
+        runStatus?: ConversationRunStatus;
+        summaryChanged?: boolean;
+    }) => ConversationChangeSignal;
+    /** Ends every subscription of the conversation with `reason`, as the server's deletion or a lost access would. */
+    end: (conversationId: number, reason: ConversationSubscriptionEndReason) => void;
+    /** Sets a conversation's stored run state (a turn that runs, fails, or a conversation that closes). */
+    setRunState: (conversationId: number, runState: AgentsConversation["runState"]) => void;
+    /**
+     * How many requests the client answered — of one port function, or of all when `operation` is omitted (the
+     * subscription is no request). For assertions such as "no read after the chat unmounted".
+     */
+    readRequestCount: (operation?: AgentsConversationOperation) => number;
+    /** Every stored message of a conversation in index order — for assertions. */
+    readStoredMessages: (conversationId: number) => AgentsConversationMessage[];
+    protected countRequest(operation: AgentsConversationOperation): void;
+    protected readSelectableModels: () => Promise<SelectableModel[]>;
+    protected readMessageSentPayload: (conversationId: number, messageId: number) => Promise<ConversationMessageSentPayload>;
+    protected readMessagesNewestFirst(conversationId: number): AgentsConversationMessage[];
+    protected readRecord(conversationId: number): RecordedConversation;
+    /** The record of a conversation that still takes input; a completed or cancelled one refuses like the server. */
+    protected readOpenRecord(conversationId: number): RecordedConversation;
+    protected readSignalState(conversationId: number): ConversationSignalState;
+    protected buildSignal(recorded: RecordedConversation, signalState: ConversationSignalState, runStatus: ConversationRunStatus | null): ConversationChangeSignal;
+    protected appendMessage(recorded: RecordedConversation, fields: Pick<AgentsConversationMessage, "role" | "messageType" | "authorType" | "message"> & Partial<Pick<AgentsConversationMessage, "signalSource">>): AgentsConversationMessage;
+    /** The next scripted answer: stored at once, or after `assistantAnswerDelayMs` with the run state RUNNING meanwhile. */
+    protected appendScriptedAssistantAnswer(recorded: RecordedConversation): void;
+    protected storeAssistantAnswer: (recorded: RecordedConversation, answerText: string) => void;
+    protected findMessageSearchHits(recorded: RecordedConversation, text: string): ConversationMessageSearchHit[];
+}
+/** The in-memory conversation client over recorded conversations (plain data). */
+export declare const createInMemoryAgentsConversationClient: (data: InMemoryAgentsConversationClientData) => InMemoryAgentsConversationClient;
+export {};

package/dist/types/contract/conversation.d.ts

@@ -0,0 +1,370 @@
+/**
+ * The conversation contract of the package: plain TypeScript types the conversation client port
+ * (`client/AgentsConversationClient.ts`) returns and the chat reads. Every field is derived from what the chat files and
+ * the chat controller read from the server today (the host application's generated `AIConversation`, `AIConversationMessage`,
+ * `AgentActivityLine`, `SemanticSearchHit`, `AIConversationSearchGroup`, `AgentCustomerSelectableModel`); nothing the
+ * chat does not read is here.
+ *
+ * Naming: a field keeps the wire name where the name is neutral (`message`, `indexInConversation`, `role`, `status`,
+ * `toolCall`); a name that carries an app's vocabulary is renamed (`aiConversationId` → `conversationId`,
+ * the app's own key of the thing the agent works for → `agentSpaceKey`, `summary.title` → `title`). Each field carries a
+ * one-line note:
+ * - `generic` — every app that runs the agent conversation backend has it;
+ * - `app extension` — read by the chat today but specific to one app's backend or debug surface; optional, and a
+ *   binding may leave it out.
+ *
+ * Client-side state is NOT part of the contract: the `fresh` tag of a live-arrived message, the optimistic user
+ * message without an id and the `isNewConversation` / `isReopenedConversation` flags belong to the package store.
+ */
+/** The run state of a conversation as the server stores it (`AIConversationRunState`). */
+export type ConversationRunState = "IDLE" | "QUEUED" | "RUNNING" | "AWAITING_DELEGATES" | "FAILED" | "COMPLETED" | "CANCELLED";
+/** The three-value run status the live-update signal speaks; the chat keys its indicator and error card off it. */
+export type ConversationRunStatus = "running" | "idle" | "failed";
+export type ConversationMessageRole = "SYSTEM" | "USER" | "ASSISTANT";
+export type ConversationMessageType = "TEXT" | "TOOL_CALL" | "CHECKPOINT" | "ERROR" | "SIGNAL" | "TOOL_MESSAGE";
+export type ConversationMessageStatus = "PENDING" | "RUNNING" | "CANCEL_REQUESTED" | "CANCELLED" | "COMPLETED" | "FAILED";
+export type ConversationMessageAuthorType = "USER" | "ASSISTANT" | "AGENT" | "TOOL";
+/** Run states after which nothing runs any more and the server refuses further customer input. */
+export declare const CONVERSATION_RUN_STATES_THAT_END_THE_CONVERSATION: readonly ConversationRunState[];
+/** Maps a stored run state onto the signal's three-value status (`runStateToSignalStatus` of the live-update hook). */
+export declare const readConversationRunStatusOfRunState: (runState: string | null | undefined) => ConversationRunStatus | null;
+/** One step of the progress stepper a purposed conversation declares (`CustomerProgressStep`). */
+export interface ConversationProgressStep {
+    /** generic */
+    key: string;
+    /** generic — already in the owner's language */
+    label: string;
+    /** generic */
+    status: "done" | "active" | "upcoming";
+}
+/** A conversation as the chat, the conversation list and the window around the chat read it. */
+export interface AgentsConversation {
+    /** generic */
+    id: number;
+    /** generic — the key of the agent space the conversation belongs to */
+    agentSpaceKey: number | null;
+    /** generic */
+    runState: ConversationRunState | null;
+    /**
+     * generic — set while the server owes a turn on an IDLE conversation (a failed hand-over the recovery re-drives);
+     * an IDLE conversation with this set counts as running (`effectiveRunState`)
+     */
+    agentTurnOwedAt: string | null;
+    /** generic — the display title (`summary.title`); null until the first title was generated */
+    title: string | null;
+    /** generic — the owner set the title by hand; the generated title never replaces it then */
+    titleManuallyEdited: boolean;
+    /** generic — the generated summary of what the conversation is about (`summary.text`); null until generated */
+    summary: string | null;
+    /** generic — when the conversation was created, in the server's date-time format */
+    created: string | null;
+    /** generic — when the conversation was last modified, in the server's date-time format */
+    updated: string | null;
+    /** generic — the purpose of a purposed conversation (e.g. `Example.Build`, a first-run setup purpose); null otherwise */
+    purposeName: string | null;
+    /** generic — who started the conversation (`SCHEDULE` for a run of a scheduled task) */
+    initiatorType: string | null;
+    /** generic — the scheduled task a `SCHEDULE` conversation is a run of */
+    scheduleId: number | null;
+    /** generic — the entry point a start came from; a start from the same entry point reopens this conversation */
+    entryPointKey: string | null;
+    /** generic — empty unless the purpose declares a progress stepper */
+    progressSteps: ConversationProgressStep[];
+    /**
+     * generic — the id of the newest stored message; null before the first. The polling default of the live updates
+     * (`client/polling/`) reads it to see a new message while the run status stays the same, and hands it to the rules as
+     * the signal's `lastMessageId`. Optional: a binding with a push transport may leave it out (the host application's metadata
+     * read does not carry it); without it the poller treats every poll of a running turn as a change.
+     */
+    lastMessageId?: number | null;
+    /** app extension — the prompt extension of the host application's older AI-Extensions chat */
+    promptExtensionId?: number | null;
+    /** app extension — the category of that prompt extension (its colour and product name in the conversation list) */
+    promptExtensionCategory?: {
+        alias: string | null;
+        name: string | null;
+    } | null;
+}
+/** A sub-agent conversation a delegation started, as far as the chat reads it (`delegatedConversations(select=id,runState)`). */
+export interface ConversationDelegatedConversation {
+    /** generic */
+    id: number;
+    /** generic */
+    runState: ConversationRunState | null;
+}
+/** One run of a sub-agent, as the activity derivation reads it (`DelegationSubAgentRun`). */
+export interface ConversationSubAgentRun {
+    /** generic */
+    runNumber: number | null;
+    /** generic */
+    status: string | null;
+}
+/** The sub-agent record a newer `delegate` call row carries instead of expanded children (`DelegationSubAgentRecord`). */
+export interface ConversationSubAgent {
+    /** generic */
+    currentRunNumber: number | null;
+    /** generic */
+    runs: ConversationSubAgentRun[];
+}
+/** The tool call a `TOOL_CALL` row carries, as far as the chat reads it. */
+export interface ConversationToolCall {
+    /** generic */
+    toolCallId: string | null;
+    /** generic */
+    name: string | null;
+    /** generic — the call's arguments as the model wrote them (the `delegate` call's `tasks` is read) */
+    arguments: unknown;
+    /** generic — the call's own progress; a row's `status` says nothing about it */
+    status: string | null;
+}
+/** The admin debug numbers of one message (the message forensics panel). */
+export interface ConversationMessageForensics {
+    /** app extension */
+    inputTokens: number | null;
+    /** app extension */
+    outputTokens: number | null;
+    /** app extension */
+    costInUSD: number | null;
+    /** app extension — the stored request snapshot of the model call (model name, reasoning effort, sent at) */
+    requestSnapshot: unknown;
+}
+/** One stored message of a conversation. */
+export interface AgentsConversationMessage {
+    /** generic */
+    id: number;
+    /** generic */
+    conversationId: number | null;
+    /** generic — the position in the conversation; the merge key of every page */
+    indexInConversation: number | null;
+    /** generic */
+    role: ConversationMessageRole | null;
+    /** generic */
+    messageType: ConversationMessageType | null;
+    /** generic — non-final only on a waiting signal row */
+    status: ConversationMessageStatus | null;
+    /** generic */
+    authorType: ConversationMessageAuthorType | null;
+    /** generic — the source of a SIGNAL or ERROR row (`AI_BUDGET_REACHED`, `FRONTEND_WIDGET_CLICK`, …) */
+    signalSource: string | null;
+    /** generic — the text in markdown, widget blocks included */
+    message: string;
+    /** generic */
+    createdDate: string | null;
+    /** generic */
+    toolCall: ConversationToolCall | null;
+    /** generic — the sub-agent conversations a `delegate` call started (older rows) */
+    delegatedConversations: ConversationDelegatedConversation[];
+    /** generic — the sub-agent record of a `delegate` call (newer rows) */
+    subAgent: ConversationSubAgent | null;
+    /** app extension — admin debug numbers; absent outside the admin surfaces */
+    forensics?: ConversationMessageForensics;
+}
+/** A file from the app's media library that rides along with a message. */
+export interface ConversationAttachmentReference {
+    /** generic — the app's id of the file (host application: the media manager file id) */
+    fileId: string | number | null;
+    /** generic */
+    fileName: string | null;
+    /** generic — a URL the model and the tools can fetch */
+    publicUrl: string | null;
+}
+/** A page of messages read newest first (the newest page on open, an older page on scroll-up). */
+export interface ConversationMessagesPage {
+    /** generic — in any order; the store merges by `indexInConversation` */
+    messages: AgentsConversationMessage[];
+    /** generic — an older page exists */
+    hasMoreOlder: boolean;
+}
+/**
+ * What a live update reads: every message written since the newest known id, plus every message from the lowest
+ * loaded index that can still change (`build-live-refetch-query.ts`). The package computes both values.
+ */
+export interface ChangedMessagesRequest {
+    /** generic — the highest message id loaded */
+    highestKnownId: number;
+    /** generic — the lowest index that can still change, never below the newest page */
+    fromIndex: number;
+    /** generic — the page size of the read; the binding's default (host application: 50, as the chat sends) when omitted */
+    pageSize?: number;
+}
+/** The answer of a changed-messages read; it says nothing about older pages (the store keeps `hasMoreOlder`). */
+export interface ChangedConversationMessages {
+    /** generic */
+    messages: AgentsConversationMessage[];
+}
+/** The answer of a start: the new conversation with what it holds so far, or the reopened one of the entry point. */
+export interface StartedConversation {
+    /** generic */
+    conversation: AgentsConversation;
+    /** generic — the stored messages of a new conversation; empty for a reopened one (the chat reads its newest page) */
+    messages: AgentsConversationMessage[];
+    /** generic — the start returned the recent conversation of its entry point; nothing was appended, no turn started */
+    reopenedExisting: boolean;
+}
+/** The answer of a post: the conversation's messages so far (the reply arrives through live updates). */
+export interface PostedMessage {
+    /** generic */
+    messages: AgentsConversationMessage[];
+}
+/** A model-visible, owner-invisible note into a conversation (a widget click, a render report, a correction). */
+export interface ConversationSignal {
+    /** generic */
+    text: string;
+    /** generic — the signal source; the server's default applies when omitted (a widget click) */
+    source?: string;
+}
+/** How a list read pages and which conversations it includes. */
+export interface ConversationListQueryOptions {
+    /** generic — include conversations that have no summary (title) yet, e.g. a just-started one */
+    includeUnsummarized?: boolean;
+    /** generic — the host application's history reads the newest 50 */
+    paging?: {
+        top?: number;
+        skip?: number;
+    };
+}
+/** The size of a search answer. */
+export interface ConversationSearchOptions {
+    /** generic — the most groups (or hits) returned; the host application's chat asks for 10 */
+    limit?: number;
+    /** generic — the excerpt length in characters; the host application's chat asks for 420 */
+    excerptLength?: number;
+}
+/** app extension — the reconstructed request a model call was sent with (the admin details panel); opaque data. */
+export type ConversationMessageSentPayload = unknown[];
+/** One matched message of a message search (`SemanticSearchHit`). */
+export interface ConversationMessageSearchHit {
+    /** generic */
+    messageId: number | null;
+    /** generic */
+    conversationId: number | null;
+    /** generic */
+    indexInConversation: number | null;
+    /** generic */
+    role: string | null;
+    /** generic */
+    excerpt: string;
+    /** generic */
+    relevance: number;
+    /** generic */
+    created: string | null;
+    /** generic */
+    updated: string | null;
+    /** generic — the conversation's title */
+    title: string | null;
+}
+/** One conversation of a search across conversations, with its matched messages (`AIConversationSearchGroup`). */
+export interface ConversationSearchGroup {
+    /** generic */
+    conversationId: number | null;
+    /** generic */
+    title: string | null;
+    /** generic */
+    summary: string | null;
+    /** generic */
+    created: string | null;
+    /** generic */
+    updated: string | null;
+    /** generic */
+    relevance: number;
+    /** generic */
+    hits: ConversationMessageSearchHit[];
+}
+/** One generated line of what the agent is doing (`AgentActivityLine`). */
+export interface ConversationActivityElement {
+    /** generic — the row the line narrates; the merge key */
+    toolCallMessageId: number;
+    /** generic */
+    batchId: string | null;
+    /** generic */
+    state: "queued" | "running" | "finished" | "failed" | "skipped" | null;
+    /** generic */
+    kind: "tool" | "delegation" | "background" | "long" | "turnStart" | null;
+    /** generic */
+    childCount: number | null;
+    /** generic — the 1-based delegation helper that ran the step; null for the assistant's own steps */
+    helperIndex: number | null;
+    /** generic — the sentence; null while the narrator has not answered */
+    line: string | null;
+}
+/** The activity of one turn (`GET …/activity`). */
+export interface ConversationActivity {
+    /** generic — the message that started the narrated turn */
+    turnMessageId: number | null;
+    /** generic */
+    turnRunning: boolean;
+    /** generic */
+    elements: ConversationActivityElement[];
+}
+/** A model the owner (host application: an impersonating admin) may pick for the next turns (`AgentCustomerSelectableModel`). */
+export interface SelectableModel {
+    /** generic — the name a send carries */
+    name: string;
+    /** generic */
+    displayName: string;
+    /** generic */
+    description: string;
+    /** generic */
+    strengthLevel: number | null;
+    /** generic */
+    speedLevel: number | null;
+    /** app extension — the host application's credit multiplier of the model */
+    creditsMultiplier?: number | null;
+}
+/**
+ * What a live update carries: a claim check, never content. The chat reads the conversation again when
+ * `changeCounter` advances, at once on a terminal status, and until `lastMessageId` is loaded.
+ */
+export interface ConversationChangeSignal {
+    /** generic — advances on every change of the conversation */
+    changeCounter: number;
+    /** generic — the newest message the server wrote; null before the first */
+    lastMessageId: number | null;
+    /** generic */
+    runStatus: ConversationRunStatus | null;
+    /** generic — advances when the title or summary was generated again (a light metadata read is enough then) */
+    summaryUpdatedAt: number | null;
+    /**
+     * generic — the binding produced this emission from a run-state read, not from a pushed change (a binding without
+     * push, or a push transport whose path is not proven readable, or a check that corrects a stale status). It carries
+     * only `runStatus` as news: `changeCounter`, `lastMessageId` and `summaryUpdatedAt` repeat the last pushed values
+     * (before any push: a counter that counts down from -1, never equal to a pushed one). The package sets the status
+     * from it and reads the conversation again on a status change while the push path is not alive (`isPushPathAlive`).
+     */
+    isStatusCheck?: boolean;
+    /**
+     * generic, on a status-check emission — the binding's push path delivers: a pushed change arrived and the path was not
+     * denied since. False after a denied read until a push arrives again; then the status checks are the live path and a
+     * status change reads the conversation again. A binding without push leaves it out: the package then counts the
+     * pushed changes it saw itself.
+     */
+    isPushPathAlive?: boolean;
+}
+/** Why a subscription ended for good: the conversation was deleted or is no longer readable, or the account lost access. */
+export type ConversationSubscriptionEndReason = "gone" | "forbidden";
+/**
+ * What went wrong, as the chat tells the owner. The codes the chat's error handling reads today map
+ * onto it: `AI_BUDGET_REACHED` → `budget`, HTTP 429 / `RATE_LIMIT_EXCEEDED` → `rateLimit`, `CONVERSATION_CLOSED` →
+ * `closed`, the not-found and no-access answers → `notFound` / `forbidden` (`conversation-not-found.ts`), no answer or a
+ * server failure → `network`, everything else (a refused retry, a cancelled request) → `other` with its `code`.
+ */
+export type AgentsClientErrorKind = "budget" | "rateLimit" | "closed" | "notFound" | "forbidden" | "network" | "other";
+/** The code `other` carries for a request the client cancelled; the chat shows no error card for it. */
+export declare const AGENTS_CLIENT_ERROR_CODE_REQUEST_ABORTED = "REQUEST_ABORTED";
+/** The one error shape every port function rejects with. */
+export declare class AgentsClientError extends Error {
+    readonly kind: AgentsClientErrorKind;
+    /** The server's stable error code, or the client's own code (`REQUEST_ABORTED`); null when none arrived. */
+    readonly code: string | null;
+    /** Seconds until a quota frees up again; set only for `rateLimit`. */
+    readonly retryAfterSeconds: number | null;
+    /** The HTTP status when one arrived (not part of the contract's shape; kept for diagnostics). */
+    readonly httpStatus: number | null;
+    constructor(kind: AgentsClientErrorKind, details?: {
+        message?: string;
+        code?: string | null;
+        retryAfterSeconds?: number | null;
+        httpStatus?: number | null;
+    });
+}
+export declare const isAgentsClientError: (value: unknown) => value is AgentsClientError;

package/dist/types/entries/chat.d.ts

@@ -0,0 +1,21 @@
+export { AgentChat, type AgentChatProps } from "../chat/AgentChat/AgentChat";
+export { AgentChatController, type AgentChatActivityHistoryProps, type AgentChatActivityProps, type AgentChatControllerProps, type AgentChatSendModelSource, } from "../chat/controller/AgentChatController";
+export { AgentChatActivityIndicator } from "../chat/AgentChatActivityIndicator/AgentChatActivityIndicator";
+export { AgentChatActivityHistory } from "../chat/AgentChatActivityHistory/AgentChatActivityHistory";
+export { ConversationClosedBar, type ConversationClosedBarProps } from "../chat/ConversationClosedBar/ConversationClosedBar";
+export * from "../chat/store";
+export { useAgentsConversationRunStatus } from "../chat/controller/use-conversation-live-updates";
+export { useConversationMessageSearch, useConversationsSearch, type ConversationMessageSearchState, type ConversationsSearchState, } from "../chat/controller/use-conversation-search";
+export { deriveAgentActivity, type AgentActivity } from "../chat/controller/derive-agent-activity";
+export type { ActivityTicker, ActivityTickerTurn } from "../chat/controller/use-activity-ticker";
+export type { ChatScrollTarget } from "../chat/controller/chat-scroll-target";
+export type { ChatMessage } from "../chat/chat-message";
+export type { ChatAssistantCategory, ChatAssistantIdentity, ChatAssistantOpening } from "../chat/chat-assistant-identity";
+export type { SendMessageHandler, SendMessageOptions } from "../chat/conversation-send-message";
+export { ConversationView, type ConversationViewProps } from "../chat/ConversationView";
+export { ConversationErrorCard, type ConversationErrorCardProps } from "../chat/ConversationErrorCard/ConversationErrorCard";
+export { ConversationMessageInputAttachmentsErrorBox } from "../chat/ConversationMessageInput/ConversationMessageInputAttachments/ConversationMessageInputAttachmentsErrorBox";
+export { ConversationMessageInputAttachmentsPreviewStrip } from "../chat/ConversationMessageInput/ConversationMessageInputAttachments/ConversationMessageInputAttachmentsPreviewStrip";
+export { normalizeServerMessageToMarkdown } from "../chat/normalize-server-message-to-markdown";
+export { ConversationWidgetProvider, type ConversationWidgetProviderProps } from "../renderer/ConversationWidgetContext";
+export { CanvasRestoreOnMount, type CanvasRestoreOnMountProps } from "../renderer/canvas/CanvasRestoreOnMount";

package/dist/types/entries/client-testing.d.ts

@@ -0,0 +1 @@
+export * from "../client/testing/createInMemoryAgentsConversationClient";

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

@@ -0,0 +1,4 @@
+export * from "../client/AgentsConversationClient";
+export * from "../client/AgentsConversationClientContext";
+export * from "../client/polling/createPollingConversationChangeSubscription";
+export * from "../client/polling/withPollingChangeSubscription";

package/dist/types/entries/contract.d.ts

@@ -0,0 +1 @@
+export * from "../contract/conversation";

package/dist/types/entries/image-render.d.ts

@@ -0,0 +1,9 @@
+export { WidgetImageRender, WidgetImageCaptureBoundary, followWidgetHydrationReadiness, registerStaticWidgetImageComponents, staticWidgetImageComponents, } from "../image-render/WidgetImageRender";
+export * from "../image-render/WidgetImageRenderContext";
+export * from "../image-render/widget-image-render.types";
+export { createWidgetImageReadiness } from "../image-render/widget-image-readiness";
+export { publishWidgetImageReadiness, readWidgetImageReadiness, readWidgetImageReadinessGlobalNames, WIDGET_IMAGE_READINESS_GLOBAL_NAME, } from "../image-render/widget-image-readiness-signal";
+export { installFrozenWidgetRequests } from "../image-render/frozen-widget-requests";
+export { installLiveWidgetRequests } from "../image-render/live-widget-requests";
+export { isGoogleMapCapture } from "../image-render/widget-image-google-map";
+export { readComposedViewDataTimes, type ComposedViewDataTimes } from "../image-render/composed-view-data-times";

package/dist/types/entries/index.d.ts

@@ -0,0 +1,9 @@
+import "../styles/agents.scss";
+export * from "../provider";
+export { registerConversationWidgets, type ConversationWidgetEntry, } from "../renderer/conversationWidgetRegistry";
+export { registerCanvasBodies } from "../renderer/canvas/canvasBodies";
+export { registerCanvasFeatureFlags } from "../renderer/canvas/canvas-feature-flags";
+export { registerWidgetHydrator } from "../renderer/widget-hydration/widget-hydration.registry";
+export { registerComposedViewDataSourceFetcher } from "../renderer/widget-tree/composed-view-data-sources";
+export { registerEntityDetailBodies } from "../kit/entity-detail/entity-detail-bodies";
+export { registerConceptExplainerTypes } from "../widgets/ConceptExplainerConversationWidget/shared/concept-explainer-types";

package/dist/types/entries/kit.d.ts

@@ -0,0 +1,4 @@
+export { ComposedViewConversationWidget } from "../kit/ComposedViewConversationWidget";
+export { ComposedViewRenderer } from "../kit/ComposedViewRenderer";
+export * from "../kit/composed-view-component-types";
+export * from "../kit/composed-view-tones";

package/dist/types/entries/preview.d.ts

@@ -0,0 +1,8 @@
+export { WidgetPreview, PREVIEW_AGENT_SPACE_KEY, type WidgetPreviewProps } from "../preview/WidgetPreviewHost";
+export * from "../preview/widget-preview.types";
+export { buildWidgetPreviewFence, findWidgetPreviewFixture, findWidgetPreviewFixtures, registerWidgetPreviewFixtureFiles, widgetPreviewFixtureFiles, } from "../preview/widget-preview-fixtures";
+export { createWidgetPreviewReadiness, observeWidgetPreviewState, type WidgetPreviewReadiness, } from "../preview/widget-preview-readiness";
+export { publishWidgetPreviewSignal, readWidgetPreviewSignalGlobalNames, WIDGET_PREVIEW_SIGNAL_GLOBAL_NAME, } from "../preview/widget-preview-signal";
+export { installWidgetPreviewRequests, isPendingResponse, widgetPreviewRequestKey } from "../preview/widget-preview-requests";
+export { installWidgetPreviewHydration } from "../preview/widget-preview-hydration";
+export { buildPreviewComposedViewComponents } from "../preview/preview-stub-components";

package/dist/types/entries/renderer.d.ts

@@ -0,0 +1,15 @@
+export { ConversationMarkdown, type ConversationMarkdownProps } from "../renderer/ConversationMarkdown";
+export { ConversationWidgetHost, type ConversationWidgetRenderProps } from "../renderer/ConversationWidgetHost";
+export { ConversationWidgetErrorBoundary } from "../renderer/ConversationWidgetErrorBoundary";
+export { type ConversationWidgetUpsellProps, ConversationWidgetFeatureGate, } from "../renderer/_access/ConversationWidgetFeatureGate";
+export * from "../renderer/ConversationWidgetCallbacksContext";
+export type { BaseConversationWidgetProps, ComposerConversationWidgetProps, PayloadConversationWidgetProps, } from "../renderer/conversation-widget-props";
+export { conversationWidgetRegistry, getConversationWidgetRegistryRevision, readConversationWidgetRegistrations, } from "../renderer/conversationWidgetRegistry";
+export { closestWidgetNames, resolveCanonicalWidgetName, resolveWidgetName } from "../renderer/widget-name-resolver";
+export * from "../renderer/render-report/widget-render-report";
+export * from "../renderer/widget-hydration";
+export * from "../renderer/canvas/canvas-behaviours";
+export * from "../renderer/canvas/canvas-state";
+export { canvasBodies, canvasFeatureFlagOf, type CanvasBodyProps } from "../renderer/canvas/canvasBodies";
+export { readComposedViewTree } from "../renderer/widget-tree/composed-view-tree";
+export { addComposedNodeSchemaApplicationPart, composedNodeSchema, getComposedNodeSchema, type ComposedNodeSchema, type ComposedNodeSchemaApplicationPart, } from "../renderer/widget-tree/composed-node-schema";

package/dist/types/entries/widgets.d.ts

@@ -0,0 +1,16 @@
+export { CanvasWidgetCard, type CanvasWidgetCardProps } from "../widgets/CanvasWidgetCard/CanvasWidgetCard";
+export { CanvasWidgetSwitch } from "../widgets/CanvasWidgetCard/CanvasWidgetSwitch";
+export { canvasForMessageWidget } from "../widgets/CanvasWidgetCard/canvas-for-message-widget";
+export { ClockConversationWidget } from "../widgets/ClockConversationWidget/ClockConversationWidget";
+export { ConceptExplainerConversationWidget } from "../widgets/ConceptExplainerConversationWidget/ConceptExplainerConversationWidget";
+export { ConversationSearchResultsConversationWidget } from "../widgets/ConversationSearchResultsConversationWidget/ConversationSearchResultsConversationWidget";
+export { CurrencyConverterConversationWidget } from "../widgets/CurrencyConverterConversationWidget/CurrencyConverterConversationWidget";
+export { CustomVisualizationConversationWidget } from "../widgets/CustomVisualizationConversationWidget/CustomVisualizationConversationWidget";
+export { EntityMentionConversationWidget } from "../widgets/EntityMentionConversationWidget/EntityMentionConversationWidget";
+export { MultiChoiceConversationWidget } from "../widgets/MultiChoiceConversationWidget/MultiChoiceConversationWidget";
+export { QuickRepliesConversationWidget } from "../widgets/QuickRepliesConversationWidget/QuickRepliesConversationWidget";
+export { SuggestedActions } from "../widgets/SuggestedActions/SuggestedActions";
+export { ToolTraceConversationWidget } from "../widgets/ToolTraceConversationWidget/ToolTraceConversationWidget";
+export { WebSearchResultsConversationWidget } from "../widgets/WebSearchResultsConversationWidget/WebSearchResultsConversationWidget";
+export { WritingDraftConversationWidget } from "../widgets/WritingDraftConversationWidget/WritingDraftConversationWidget";
+export * from "../widgets/_shared/modern";

package/dist/types/image-render/ComposedViewEmailDataTimes/ComposedViewEmailDataTimes.d.ts

@@ -0,0 +1,15 @@
+import type { ComposedViewTree } from "../../renderer/widget-tree/composed-view-tree";
+/** A moment in the owner's date locale and zone (`25.10.2026, 08:00`); without a usable zone, the capture's own. */
+export declare const formatDataTime: (moment: Date, dateLocale: string, timeZone: string | null | undefined) => string;
+export interface ComposedViewEmailDataTimesProps {
+    tree: ComposedViewTree;
+}
+/**
+ * The time of each data path of an e-mailed `ComposedView`, as ONE caption line under the tree: a report
+ * mail mixes the tool results written into the block at turn time (`$from`) with data read live while the mail is
+ * captured (`$source`, embedded domain widgets) — the reader must know which numbers are from when. The turn time is
+ * the `resolvedAt` the resolution wrote into the snapshot; the mail time is the capture moment, fixed at the first
+ * render. Each phrase is its own translation key; the phrases are joined by a middle dot. A tree with inline data only
+ * shows no line.
+ */
+export declare const ComposedViewEmailDataTimes: (props: ComposedViewEmailDataTimesProps) => import("react/jsx-runtime").JSX.Element | null;