@vinaverse/client 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-export { A as AnswerInput, l as AuthMode, b as CONTRACT, c as Card, f as CardKind, h as ClientErrorCode, m as ClientEvent, C as ClientSecret, n as Connection, o as ConversationEngine, p as ConversationState, F as FetchLike, q as Frame, H as HeldCard, i as HeldQuestion, M as Message, j as Proposal, P as ProposalOutcome, Q as Question, R as Reconnect, r as ServerEvent, s as ServerEventOf, t as ServerEventType, u as SessionEvents, S as SessionInfo, a as SessionOptions, v as SessionStatus, w as SseTarget, T as ToolLine, x as TranscriptItem, y as TurnInput, V as VinaverseClientError, z as VinaverseSession, B as WebSocketFactory, D as WebSocketLike, E as cardActionSse, k as isKnownCard, G as sseFrames, I as turnSse } from './session-C3qZwGPG.cjs';
+export { C as CONTRACT } from './contract-_NMdPjgN.cjs';
+export { A as AnswerInput, h as AuthMode, a as Card, d as CardKind, e as ClientErrorCode, j as ClientEvent, k as ClientSecret, l as Connection, m as ConversationEngine, n as ConversationState, F as FetchLike, o as Frame, H as HeldCard, f as HeldQuestion, M as Message, P as Proposal, g as ProposalOutcome, Q as Question, R as Reconnect, S as Schemas, p as ServerEvent, q as ServerEventOf, r as ServerEventType, s as SessionEvents, t as SessionInfo, u as SessionOptions, v as SessionStatus, w as SseTarget, T as ToolLine, x as TranscriptItem, y as TurnInput, V as VinaverseClientError, z as VinaverseSession, B as WebSocketFactory, D as WebSocketLike, E as cardActionSse, G as components, i as isKnownCard, I as operations, J as paths, K as sseFrames, L as turnSse } from './session-8W3fRNeb.cjs';
 
 /**
  * The client secret, checked: an app holds only the session's `vv_cs_` secret, which the tenant's backend got from

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { A as AnswerInput, l as AuthMode, b as CONTRACT, c as Card, f as CardKind, h as ClientErrorCode, m as ClientEvent, C as ClientSecret, n as Connection, o as ConversationEngine, p as ConversationState, F as FetchLike, q as Frame, H as HeldCard, i as HeldQuestion, M as Message, j as Proposal, P as ProposalOutcome, Q as Question, R as Reconnect, r as ServerEvent, s as ServerEventOf, t as ServerEventType, u as SessionEvents, S as SessionInfo, a as SessionOptions, v as SessionStatus, w as SseTarget, T as ToolLine, x as TranscriptItem, y as TurnInput, V as VinaverseClientError, z as VinaverseSession, B as WebSocketFactory, D as WebSocketLike, E as cardActionSse, k as isKnownCard, G as sseFrames, I as turnSse } from './session-C3qZwGPG.js';
+export { C as CONTRACT } from './contract-_NMdPjgN.js';
+export { A as AnswerInput, h as AuthMode, a as Card, d as CardKind, e as ClientErrorCode, j as ClientEvent, k as ClientSecret, l as Connection, m as ConversationEngine, n as ConversationState, F as FetchLike, o as Frame, H as HeldCard, f as HeldQuestion, M as Message, P as Proposal, g as ProposalOutcome, Q as Question, R as Reconnect, S as Schemas, p as ServerEvent, q as ServerEventOf, r as ServerEventType, s as SessionEvents, t as SessionInfo, u as SessionOptions, v as SessionStatus, w as SseTarget, T as ToolLine, x as TranscriptItem, y as TurnInput, V as VinaverseClientError, z as VinaverseSession, B as WebSocketFactory, D as WebSocketLike, E as cardActionSse, G as components, i as isKnownCard, I as operations, J as paths, K as sseFrames, L as turnSse } from './session-8W3fRNeb.js';
 
 /**
  * The client secret, checked: an app holds only the session's `vv_cs_` secret, which the tenant's backend got from

package/dist/index.js

@@ -1,3 +1,4 @@
-export { CONTRACT, ConversationEngine, VinaverseClientError, VinaverseSession, cardActionSse, clientSecret, isKnownCard, sseFrames, turnSse } from './chunk-MKUNSAMT.js';
+export { CONTRACT } from './chunk-VSJDVLCP.js';
+export { ConversationEngine, VinaverseClientError, VinaverseSession, cardActionSse, clientSecret, isKnownCard, sseFrames, turnSse } from './chunk-GWLLUOFY.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/runtime-CErMdYxJ.d.cts

@@ -0,0 +1,234 @@
+import { S as SessionRequest, b as ConversationSession, C as ConversationStore, a as ConversationOptions } from './store-C7FtS5AY.cjs';
+import { S as Schemas } from './session-8W3fRNeb.cjs';
+
+/** Whose conversation: a person (null for a guest), the app's side, the business acted for, and the thread. */
+interface AgentKey {
+    readonly subject: string | null;
+    readonly mode: string;
+    readonly scope?: string | null;
+    /** Default `chat`; a flow of its own (a business setup, say) is another thread. */
+    readonly thread?: string;
+}
+type ScreenContext = Schemas['ScreenContext'];
+/**
+ * Where the person asks from, in the contract's vocabulary (`ScreenContext`: the screen, the entity, the filters): told
+ * to the agent as data (`Session.screen_context`), never as their words. The tenant's backend vouches for it.
+ */
+interface AgentPlace {
+    readonly screen: ScreenContext['screen'];
+    readonly entity?: {
+        readonly type: string;
+        readonly id: string;
+    } | null;
+    readonly filters?: ScreenContext['filters'];
+}
+/** What the runtime asks the tenant's backend for: a session, for this key, told this place. */
+interface AgentSessionRequest extends SessionRequest {
+    readonly key: AgentKey;
+    readonly place: AgentPlace | null;
+    /** How the person came in (`button`, `inbox`, …): the app's own words, passed through. */
+    readonly entryPoint: string | null;
+}
+/** Why there is no session, typed, so an app never needs sentinel errors of its own. */
+type AgentFailureReason = 
+/** The conversation asked for is over: not theirs, deleted (404), or past the time it is kept (410). */
+'ended'
+/** The person's sign-in was refused by the tenant's API. */
+ | 'auth'
+/** The agent is switched off for this tenant, mode or person. */
+ | 'off' | 'rate_limited'
+/** No network, a timeout: retried, then said. */
+ | 'network'
+/** The tenant's API or Vinaverse failed (5xx): retried, then said. */
+ | 'server'
+/** The backend answered with a session the runtime will not use (not wss://, a field missing). */
+ | 'invalid_session' | 'unknown';
+/**
+ * A refusal from the backend, typed: `ended` (the conversation is over; a new one starts only when the person asks) or
+ * `unavailable` with its reason. An error with `retryable: true` (and its `reason`, `network` by default) is waited out
+ * by the retry policy, then said as `unreachable`.
+ */
+declare class AgentRefusal extends Error {
+    readonly kind: 'ended' | 'unavailable';
+    readonly reason: AgentFailureReason;
+    readonly code: string | null;
+    constructor(kind: 'ended' | 'unavailable', options?: {
+        readonly reason?: AgentFailureReason;
+        readonly code?: string;
+        readonly message?: string;
+    });
+}
+interface AgentStatus {
+    readonly available: boolean;
+    /** The floating launcher may show. */
+    readonly launcher: boolean;
+    readonly displayName: string | null;
+    readonly avatarUrl: string | null;
+    readonly features: {
+        readonly history: boolean;
+        readonly memory: boolean;
+        readonly businessAgent: boolean;
+        readonly businessSetup: boolean;
+    };
+}
+/** The status as the backend reads it; what it leaves out is off. */
+interface AgentStatusRead {
+    readonly available: boolean;
+    readonly launcher?: boolean;
+    readonly displayName?: string | null;
+    readonly avatarUrl?: string | null;
+    readonly features?: Partial<AgentStatus['features']>;
+}
+/** The tenant's backend: the one piece of integration an app writes. */
+interface AgentBackend {
+    /** A session from the tenant's API (it creates it at Vinaverse with its service key), or an `AgentRefusal`. */
+    openSession(request: AgentSessionRequest): Promise<ConversationSession>;
+    /** A fresh client secret for the same session (before its end). */
+    refreshSecret?(sessionId: string): Promise<string>;
+    /**
+     * The person's place changed while the chat is open: the tenant's backend tells Vinaverse
+     * (`PUT /v1/sessions/{id}/context`). Absent, or refused, the kit offers a question about the new place instead.
+     */
+    updateContext?(sessionId: string, place: AgentPlace, revision: number): Promise<void>;
+    /** Whether the agent is offered, and what it can do. Absent: available, nothing extra. */
+    status?(signal?: AbortSignal): Promise<AgentStatusRead>;
+    /** A thumbs on a whole reply; best effort, never an error for the person. */
+    sendFeedback?(feedback: {
+        readonly sessionId: string;
+        readonly turnId: string;
+        readonly rating: AgentRating;
+    }): Promise<void>;
+    /** Sign-out: end the person's open sessions at the tenant's API. */
+    endSessions?(): Promise<void>;
+}
+type AgentRating = 'up' | 'down';
+type AgentFailure = 'ended' | 'unreachable' | 'unavailable';
+type AgentEventType = 'session_opened' | 'session_resumed' | 'session_retried' | 'session_failed' | 'conversation_ended' | 'context_updated' | 'rated' | 'chip_tapped' | 'card_action' | 'target_opened' | 'link_opened' | 'launcher_shown' | 'launcher_opened' | 'launcher_greeted' | 'greeting_closed';
+/** For the app's analytics: what happened, for which conversation, with nothing the person said. */
+interface AgentEvent {
+    readonly type: AgentEventType;
+    readonly key?: string;
+    readonly sessionId?: string;
+    readonly failure?: AgentFailure;
+    readonly reason?: AgentFailureReason;
+    readonly attempt?: number;
+    readonly turnId?: string;
+    readonly rating?: AgentRating;
+    readonly cardId?: string;
+    readonly kind?: string;
+    /** Where the person opened from (`entryPoint`, the screen). */
+    readonly from?: string;
+}
+/** What a UI draws around the store: why there is no session, whether the person moved, the thumbs given. */
+interface AgentConversationState {
+    readonly failure: AgentFailure | null;
+    readonly reason: AgentFailureReason | null;
+    /** The API's own code for the failure (`conversation_expired`, …), when it gave one. */
+    readonly code: string | null;
+    /** The session was told another place than the one the person now asks from, and it could not be told live. */
+    readonly moved: boolean;
+    readonly ratings: ReadonlyMap<string, AgentRating>;
+    readonly sessionId: string | null;
+}
+interface AgentConversation {
+    /** The key as a string, for the app's own maps and the events. */
+    readonly key: string;
+    readonly store: ConversationStore;
+    /**
+     * A view attaches: kept, with its connection, while any view is attached. The first time, it starts. Returns the
+     * detach: with no view attached it is suspended (no pings; closed with `closeInBackground`) while its session lives
+     * (`keepAlive: 'session'`), and let go when it has none, is past its end, or `keepAlive` is `'view'`. Separate from the
+     * app's background, which the platform adapter tells the store.
+     */
+    show(open?: {
+        readonly place?: AgentPlace | null;
+        readonly entryPoint?: string | null;
+    }): () => void;
+    /** The place and the way in changed while a view is attached: told live where the backend can, else on the next session. */
+    tell(open: {
+        readonly place?: AgentPlace | null;
+        readonly entryPoint?: string | null;
+    }): void;
+    getState(): AgentConversationState;
+    subscribe(listener: () => void): () => void;
+    /** Asks for a session again, after the backend could not be reached. */
+    retry(): void;
+    /** A thumbs on a whole reply; a change of mind only is sent again. */
+    rate(turnId: string, rating: AgentRating): void;
+    /**
+     * Sends the person's `text` once in this conversation's life (a chip tapped twice, a retried tap). It is shown as
+     * theirs: only words they typed or tapped, never the app's in their name.
+     */
+    sendOnce(text: string): void;
+}
+/** When the runtime tries the backend again: before each try, a delay; `isRetryable` decides which errors are waited out. */
+interface AgentRetryPolicy {
+    readonly delays: readonly number[];
+    readonly isRetryable?: (error: unknown) => boolean;
+}
+/** The time the runtime judges a session's end by: the server's, when the app has it (a clock synced from responses). */
+interface AgentClock {
+    now(): number;
+}
+interface AgentRuntimeOptions {
+    readonly backend: AgentBackend;
+    /** The store's own options (locale, time zone, deep-link prefixes, transport, persistence, closeInBackground…). */
+    readonly conversation?: Omit<ConversationOptions, 'getSession' | 'refreshSecret' | 'clock'>;
+    /** Default: 500, 1500, 3500 ms, for errors with `retryable: true`; applied to `openSession` and `refreshSecret`. */
+    readonly retry?: AgentRetryPolicy;
+    /** Default: the device's clock. Give the server's: a phone set wrong otherwise reuses a dead session or drops a live one. */
+    readonly clock?: AgentClock;
+    /** `session` (default): kept while its session lives with no view attached; `view`: let go when the last view goes. */
+    readonly keepAlive?: 'session' | 'view';
+    /** How long a status read stays fresh. Default 5 minutes. */
+    readonly statusStaleMs?: number;
+    /**
+     * DANGEROUS: for mocks and local development only. Lets a leg's session address be plaintext (`ws://`, `http://`),
+     * which would carry the person's messages and the session's secret unencrypted. Off by default, whatever transport
+     * the app supplies; outside `__DEV__` the runtime warns once.
+     */
+    readonly insecureAddresses?: AgentInsecureAddresses;
+    readonly onEvent?: (event: AgentEvent) => void;
+    /** Where the runtime's warnings go (the app's logger, crash reporter); default `console.warn`. */
+    readonly onWarning?: (message: string) => void;
+}
+/** The legs whose session address may be plaintext: `realtime` (the WebSocket), `turns` (HTTP). */
+interface AgentInsecureAddresses {
+    readonly realtime?: boolean;
+    readonly turns?: boolean;
+}
+interface AgentRuntime {
+    /** The key's conversation: the same while it lives; a new one after `startNew`, `dispose` or its end. */
+    conversation(key: AgentKey): AgentConversation;
+    /**
+     * The key's conversation as it stands, ending nothing and telling no one: for a render (`useSyncExternalStore`).
+     * One past its session's end is ended when it is next shown, and subscribers then read the key's next one.
+     */
+    peek(key: AgentKey): AgentConversation;
+    /** A new conversation for the key from the person's next opening; the old one is let go and forgotten. */
+    startNew(key: AgentKey): void;
+    /** Closes the key's conversation now and drops every reference to it; the next opening continues it in a new session. */
+    dispose(key: AgentKey): void;
+    /**
+     * The key goes on with this conversation (history's "Continue"): pinned for the key and opened through the backend's
+     * resume. One that is gone (404, 410: the backend's `AgentRefusal('ended')`) is said as `ended`, never replaced by a
+     * new one silently.
+     */
+    continue(key: AgentKey, conversationId: string): AgentConversation;
+    /** Every conversation closed and forgotten (what the device kept too), and the backend told to end the sessions. */
+    signOut(): Promise<void>;
+    /** The agent's status, read from the backend at most every `statusStaleMs`. */
+    status(): Promise<AgentStatus>;
+    getStatus(): AgentStatus | null;
+    /** The agent's name: from the newest session, else from the status. */
+    getName(): string | null;
+    /** Told when the status or name changes, and when a key's conversation is let go (its next one is another). */
+    subscribe(listener: () => void): () => void;
+    /** An event from a kit or the app, passed to `onEvent`. */
+    emit(event: AgentEvent): void;
+}
+/** The key as a string: one conversation per person, mode, business and thread. */
+declare function agentKey(key: AgentKey): string;
+declare function createAgentRuntime(options: AgentRuntimeOptions): AgentRuntime;
+
+export { type AgentBackend as A, type AgentClock as a, type AgentConversation as b, type AgentConversationState as c, type AgentEvent as d, type AgentEventType as e, type AgentFailure as f, type AgentFailureReason as g, type AgentInsecureAddresses as h, type AgentKey as i, type AgentPlace as j, type AgentRating as k, AgentRefusal as l, type AgentRetryPolicy as m, type AgentRuntime as n, type AgentRuntimeOptions as o, type AgentSessionRequest as p, type AgentStatus as q, type AgentStatusRead as r, agentKey as s, createAgentRuntime as t };

package/dist/runtime-DLJbJkSr.d.ts

@@ -0,0 +1,234 @@
+import { S as SessionRequest, b as ConversationSession, C as ConversationStore, a as ConversationOptions } from './store-DFk0ayh8.js';
+import { S as Schemas } from './session-8W3fRNeb.js';
+
+/** Whose conversation: a person (null for a guest), the app's side, the business acted for, and the thread. */
+interface AgentKey {
+    readonly subject: string | null;
+    readonly mode: string;
+    readonly scope?: string | null;
+    /** Default `chat`; a flow of its own (a business setup, say) is another thread. */
+    readonly thread?: string;
+}
+type ScreenContext = Schemas['ScreenContext'];
+/**
+ * Where the person asks from, in the contract's vocabulary (`ScreenContext`: the screen, the entity, the filters): told
+ * to the agent as data (`Session.screen_context`), never as their words. The tenant's backend vouches for it.
+ */
+interface AgentPlace {
+    readonly screen: ScreenContext['screen'];
+    readonly entity?: {
+        readonly type: string;
+        readonly id: string;
+    } | null;
+    readonly filters?: ScreenContext['filters'];
+}
+/** What the runtime asks the tenant's backend for: a session, for this key, told this place. */
+interface AgentSessionRequest extends SessionRequest {
+    readonly key: AgentKey;
+    readonly place: AgentPlace | null;
+    /** How the person came in (`button`, `inbox`, …): the app's own words, passed through. */
+    readonly entryPoint: string | null;
+}
+/** Why there is no session, typed, so an app never needs sentinel errors of its own. */
+type AgentFailureReason = 
+/** The conversation asked for is over: not theirs, deleted (404), or past the time it is kept (410). */
+'ended'
+/** The person's sign-in was refused by the tenant's API. */
+ | 'auth'
+/** The agent is switched off for this tenant, mode or person. */
+ | 'off' | 'rate_limited'
+/** No network, a timeout: retried, then said. */
+ | 'network'
+/** The tenant's API or Vinaverse failed (5xx): retried, then said. */
+ | 'server'
+/** The backend answered with a session the runtime will not use (not wss://, a field missing). */
+ | 'invalid_session' | 'unknown';
+/**
+ * A refusal from the backend, typed: `ended` (the conversation is over; a new one starts only when the person asks) or
+ * `unavailable` with its reason. An error with `retryable: true` (and its `reason`, `network` by default) is waited out
+ * by the retry policy, then said as `unreachable`.
+ */
+declare class AgentRefusal extends Error {
+    readonly kind: 'ended' | 'unavailable';
+    readonly reason: AgentFailureReason;
+    readonly code: string | null;
+    constructor(kind: 'ended' | 'unavailable', options?: {
+        readonly reason?: AgentFailureReason;
+        readonly code?: string;
+        readonly message?: string;
+    });
+}
+interface AgentStatus {
+    readonly available: boolean;
+    /** The floating launcher may show. */
+    readonly launcher: boolean;
+    readonly displayName: string | null;
+    readonly avatarUrl: string | null;
+    readonly features: {
+        readonly history: boolean;
+        readonly memory: boolean;
+        readonly businessAgent: boolean;
+        readonly businessSetup: boolean;
+    };
+}
+/** The status as the backend reads it; what it leaves out is off. */
+interface AgentStatusRead {
+    readonly available: boolean;
+    readonly launcher?: boolean;
+    readonly displayName?: string | null;
+    readonly avatarUrl?: string | null;
+    readonly features?: Partial<AgentStatus['features']>;
+}
+/** The tenant's backend: the one piece of integration an app writes. */
+interface AgentBackend {
+    /** A session from the tenant's API (it creates it at Vinaverse with its service key), or an `AgentRefusal`. */
+    openSession(request: AgentSessionRequest): Promise<ConversationSession>;
+    /** A fresh client secret for the same session (before its end). */
+    refreshSecret?(sessionId: string): Promise<string>;
+    /**
+     * The person's place changed while the chat is open: the tenant's backend tells Vinaverse
+     * (`PUT /v1/sessions/{id}/context`). Absent, or refused, the kit offers a question about the new place instead.
+     */
+    updateContext?(sessionId: string, place: AgentPlace, revision: number): Promise<void>;
+    /** Whether the agent is offered, and what it can do. Absent: available, nothing extra. */
+    status?(signal?: AbortSignal): Promise<AgentStatusRead>;
+    /** A thumbs on a whole reply; best effort, never an error for the person. */
+    sendFeedback?(feedback: {
+        readonly sessionId: string;
+        readonly turnId: string;
+        readonly rating: AgentRating;
+    }): Promise<void>;
+    /** Sign-out: end the person's open sessions at the tenant's API. */
+    endSessions?(): Promise<void>;
+}
+type AgentRating = 'up' | 'down';
+type AgentFailure = 'ended' | 'unreachable' | 'unavailable';
+type AgentEventType = 'session_opened' | 'session_resumed' | 'session_retried' | 'session_failed' | 'conversation_ended' | 'context_updated' | 'rated' | 'chip_tapped' | 'card_action' | 'target_opened' | 'link_opened' | 'launcher_shown' | 'launcher_opened' | 'launcher_greeted' | 'greeting_closed';
+/** For the app's analytics: what happened, for which conversation, with nothing the person said. */
+interface AgentEvent {
+    readonly type: AgentEventType;
+    readonly key?: string;
+    readonly sessionId?: string;
+    readonly failure?: AgentFailure;
+    readonly reason?: AgentFailureReason;
+    readonly attempt?: number;
+    readonly turnId?: string;
+    readonly rating?: AgentRating;
+    readonly cardId?: string;
+    readonly kind?: string;
+    /** Where the person opened from (`entryPoint`, the screen). */
+    readonly from?: string;
+}
+/** What a UI draws around the store: why there is no session, whether the person moved, the thumbs given. */
+interface AgentConversationState {
+    readonly failure: AgentFailure | null;
+    readonly reason: AgentFailureReason | null;
+    /** The API's own code for the failure (`conversation_expired`, …), when it gave one. */
+    readonly code: string | null;
+    /** The session was told another place than the one the person now asks from, and it could not be told live. */
+    readonly moved: boolean;
+    readonly ratings: ReadonlyMap<string, AgentRating>;
+    readonly sessionId: string | null;
+}
+interface AgentConversation {
+    /** The key as a string, for the app's own maps and the events. */
+    readonly key: string;
+    readonly store: ConversationStore;
+    /**
+     * A view attaches: kept, with its connection, while any view is attached. The first time, it starts. Returns the
+     * detach: with no view attached it is suspended (no pings; closed with `closeInBackground`) while its session lives
+     * (`keepAlive: 'session'`), and let go when it has none, is past its end, or `keepAlive` is `'view'`. Separate from the
+     * app's background, which the platform adapter tells the store.
+     */
+    show(open?: {
+        readonly place?: AgentPlace | null;
+        readonly entryPoint?: string | null;
+    }): () => void;
+    /** The place and the way in changed while a view is attached: told live where the backend can, else on the next session. */
+    tell(open: {
+        readonly place?: AgentPlace | null;
+        readonly entryPoint?: string | null;
+    }): void;
+    getState(): AgentConversationState;
+    subscribe(listener: () => void): () => void;
+    /** Asks for a session again, after the backend could not be reached. */
+    retry(): void;
+    /** A thumbs on a whole reply; a change of mind only is sent again. */
+    rate(turnId: string, rating: AgentRating): void;
+    /**
+     * Sends the person's `text` once in this conversation's life (a chip tapped twice, a retried tap). It is shown as
+     * theirs: only words they typed or tapped, never the app's in their name.
+     */
+    sendOnce(text: string): void;
+}
+/** When the runtime tries the backend again: before each try, a delay; `isRetryable` decides which errors are waited out. */
+interface AgentRetryPolicy {
+    readonly delays: readonly number[];
+    readonly isRetryable?: (error: unknown) => boolean;
+}
+/** The time the runtime judges a session's end by: the server's, when the app has it (a clock synced from responses). */
+interface AgentClock {
+    now(): number;
+}
+interface AgentRuntimeOptions {
+    readonly backend: AgentBackend;
+    /** The store's own options (locale, time zone, deep-link prefixes, transport, persistence, closeInBackground…). */
+    readonly conversation?: Omit<ConversationOptions, 'getSession' | 'refreshSecret' | 'clock'>;
+    /** Default: 500, 1500, 3500 ms, for errors with `retryable: true`; applied to `openSession` and `refreshSecret`. */
+    readonly retry?: AgentRetryPolicy;
+    /** Default: the device's clock. Give the server's: a phone set wrong otherwise reuses a dead session or drops a live one. */
+    readonly clock?: AgentClock;
+    /** `session` (default): kept while its session lives with no view attached; `view`: let go when the last view goes. */
+    readonly keepAlive?: 'session' | 'view';
+    /** How long a status read stays fresh. Default 5 minutes. */
+    readonly statusStaleMs?: number;
+    /**
+     * DANGEROUS: for mocks and local development only. Lets a leg's session address be plaintext (`ws://`, `http://`),
+     * which would carry the person's messages and the session's secret unencrypted. Off by default, whatever transport
+     * the app supplies; outside `__DEV__` the runtime warns once.
+     */
+    readonly insecureAddresses?: AgentInsecureAddresses;
+    readonly onEvent?: (event: AgentEvent) => void;
+    /** Where the runtime's warnings go (the app's logger, crash reporter); default `console.warn`. */
+    readonly onWarning?: (message: string) => void;
+}
+/** The legs whose session address may be plaintext: `realtime` (the WebSocket), `turns` (HTTP). */
+interface AgentInsecureAddresses {
+    readonly realtime?: boolean;
+    readonly turns?: boolean;
+}
+interface AgentRuntime {
+    /** The key's conversation: the same while it lives; a new one after `startNew`, `dispose` or its end. */
+    conversation(key: AgentKey): AgentConversation;
+    /**
+     * The key's conversation as it stands, ending nothing and telling no one: for a render (`useSyncExternalStore`).
+     * One past its session's end is ended when it is next shown, and subscribers then read the key's next one.
+     */
+    peek(key: AgentKey): AgentConversation;
+    /** A new conversation for the key from the person's next opening; the old one is let go and forgotten. */
+    startNew(key: AgentKey): void;
+    /** Closes the key's conversation now and drops every reference to it; the next opening continues it in a new session. */
+    dispose(key: AgentKey): void;
+    /**
+     * The key goes on with this conversation (history's "Continue"): pinned for the key and opened through the backend's
+     * resume. One that is gone (404, 410: the backend's `AgentRefusal('ended')`) is said as `ended`, never replaced by a
+     * new one silently.
+     */
+    continue(key: AgentKey, conversationId: string): AgentConversation;
+    /** Every conversation closed and forgotten (what the device kept too), and the backend told to end the sessions. */
+    signOut(): Promise<void>;
+    /** The agent's status, read from the backend at most every `statusStaleMs`. */
+    status(): Promise<AgentStatus>;
+    getStatus(): AgentStatus | null;
+    /** The agent's name: from the newest session, else from the status. */
+    getName(): string | null;
+    /** Told when the status or name changes, and when a key's conversation is let go (its next one is another). */
+    subscribe(listener: () => void): () => void;
+    /** An event from a kit or the app, passed to `onEvent`. */
+    emit(event: AgentEvent): void;
+}
+/** The key as a string: one conversation per person, mode, business and thread. */
+declare function agentKey(key: AgentKey): string;
+declare function createAgentRuntime(options: AgentRuntimeOptions): AgentRuntime;
+
+export { type AgentBackend as A, type AgentClock as a, type AgentConversation as b, type AgentConversationState as c, type AgentEvent as d, type AgentEventType as e, type AgentFailure as f, type AgentFailureReason as g, type AgentInsecureAddresses as h, type AgentKey as i, type AgentPlace as j, type AgentRating as k, AgentRefusal as l, type AgentRetryPolicy as m, type AgentRuntime as n, type AgentRuntimeOptions as o, type AgentSessionRequest as p, type AgentStatus as q, type AgentStatusRead as r, agentKey as s, createAgentRuntime as t };