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

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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';
+export { C as CONTRACT } from './contract-DmQs8amJ.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-CPz4pcPu.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,5 +1,5 @@
-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';
+export { C as CONTRACT } from './contract-DmQs8amJ.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-CPz4pcPu.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,4 +1,4 @@
-export { CONTRACT } from './chunk-VSJDVLCP.js';
+export { CONTRACT } from './chunk-YNUHXJD6.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-DLJbJkSr.d.ts → runtime-A4ovUdrc.d.cts}

@@ -1,5 +1,5 @@
-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';
+import { S as SessionRequest, b as ConversationSession, C as ConversationStore, f as ConversationPersistence, a as ConversationOptions } from './store-BxiicOKG.cjs';
+import { S as Schemas, k as ClientSecret } from './session-CPz4pcPu.cjs';
 
 /** Whose conversation: a person (null for a guest), the app's side, the business acted for, and the thread. */
 interface AgentKey {
@@ -22,17 +22,47 @@ interface AgentPlace {
     } | null;
     readonly filters?: ScreenContext['filters'];
 }
+/** How the person came in: the kit's parts say `launcher` and `ask`; an app adds `deep_link` or its own words. */
+type AgentEntryPoint = 'launcher' | 'ask' | 'deep_link' | (string & Record<never, never>);
 /** What the runtime asks the tenant's backend for: a session, for this key, told this place. */
 interface AgentSessionRequest extends SessionRequest {
     readonly key: AgentKey;
+    /**
+     * This session creation's id: the same through its retries, so the backend uses it as the gateway's idempotency key
+     * and never opens twice; a new one for every creation (a first open, a resume, continue-here, a rollover). A creation
+     * that could not reach the backend keeps it, and its whole request, for the next try, the person's "try again" too,
+     * for 24 hours. An `unknown_open` answer is final: not retried under it.
+     */
+    readonly openId: string;
+    /** The runtime's `agent`, for a backend that serves more than one. */
+    readonly agent: string | null;
     readonly place: AgentPlace | null;
-    /** How the person came in (`button`, `inbox`, …): the app's own words, passed through. */
-    readonly entryPoint: string | null;
+    /**
+     * The place's revision (`ScreenContext.revision`): higher than any the session was told before, and lower than any
+     * `updateContext` after it, so the API keeps the newest place across a session's rollover.
+     */
+    readonly placeRevision: number;
+    /** How the person came in (`launcher`, `ask`, `deep_link`, the app's own words), passed through. */
+    readonly entryPoint: AgentEntryPoint | 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). */
+/** The conversation is over (its session's own end, or a refusal with no finer reason). */
 'ended'
+/** The conversation asked for does not exist for this person (deleted, or never theirs). */
+ | 'not_found'
+/** Past the time the conversation is kept. */
+ | 'expired'
+/** The conversation belongs to another business, mode or agent than the key's. */
+ | 'mismatch'
+/** The conversation's flow is completed; a new one starts when the person asks. */
+ | 'completed'
+/** The person may not act for this business or conversation. */
+ | 'forbidden'
+/** The server holds a newer screen context than the one told (an update, never a session). */
+ | 'conflict'
+/** The backend could not tell whether the session opened: unavailable, never retried, its `openId` kept for support. */
+ | 'unknown_open'
 /** The person's sign-in was refused by the tenant's API. */
  | 'auth'
 /** The agent is switched off for this tenant, mode or person. */
@@ -83,11 +113,17 @@ interface AgentStatusRead {
 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>;
+    /**
+     * A fresh client secret for the same session (before its end): a `ClientSecret` `{ value, expires_at }`, or its
+     * value. A refusal (`session_closed`: the session is over) goes on with the conversation in a new session.
+     */
+    refreshSecret?(sessionId: string): Promise<ClientSecret | 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.
+     * (`PUT /v1/sessions/{id}/context`). A place cleared (`tell({ place: null })`) comes as `{ screen: 'other' }`.
+     * `revision` only grows for a conversation, across its sessions. A conflict (`decodeBackendFailure`'s
+     * `context_conflict`, or a refusal with reason `conflict`, with the server's `currentRevision`) is sent once more
+     * above it, then said as `moved`. Absent, or refused otherwise, the kit offers a question about the new place.
      */
     updateContext?(sessionId: string, place: AgentPlace, revision: number): Promise<void>;
     /** Whether the agent is offered, and what it can do. Absent: available, nothing extra. */
@@ -100,13 +136,16 @@ interface AgentBackend {
     }): Promise<void>;
     /** Sign-out: end the person's open sessions at the tenant's API. */
     endSessions?(): Promise<void>;
+    /** History's delete: the tenant's API deletes the person's conversation (authenticated, theirs only). */
+    deleteConversation?(conversationId: string): 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';
+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' | 'message_sent' | 'reply_completed' | 'card_shown';
 /** For the app's analytics: what happened, for which conversation, with nothing the person said. */
 interface AgentEvent {
     readonly type: AgentEventType;
+    /** The conversation, as a hash of its key (`hashKey`): stable, and never the person's id. */
     readonly key?: string;
     readonly sessionId?: string;
     readonly failure?: AgentFailure;
@@ -116,8 +155,8 @@ interface AgentEvent {
     readonly rating?: AgentRating;
     readonly cardId?: string;
     readonly kind?: string;
-    /** Where the person opened from (`entryPoint`, the screen). */
-    readonly from?: string;
+    /** Where the person opened from (`launcher`, `ask`, `deep_link`, the app's own words). */
+    readonly from?: AgentEntryPoint;
 }
 /** What a UI draws around the store: why there is no session, whether the person moved, the thumbs given. */
 interface AgentConversationState {
@@ -129,6 +168,13 @@ interface AgentConversationState {
     readonly moved: boolean;
     readonly ratings: ReadonlyMap<string, AgentRating>;
     readonly sessionId: string | null;
+    /**
+     * The conversation the key holds: the one it continues before a session opens, then its session's. Null for a new
+     * one not yet opened. History's delete compares against it (`deleteConversation` does).
+     */
+    readonly conversationId: string | null;
+    /** The open the backend could not settle (`unknown_open`), for support; null otherwise. */
+    readonly openId: string | null;
 }
 interface AgentConversation {
     /** The key as a string, for the app's own maps and the events. */
@@ -142,18 +188,26 @@ interface AgentConversation {
      */
     show(open?: {
         readonly place?: AgentPlace | null;
-        readonly entryPoint?: string | null;
+        readonly entryPoint?: AgentEntryPoint | 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. */
+    /**
+     * The place and the way in changed while a view is attached: told live where the backend can, else on the next
+     * session. `undefined` keeps what was told; `null` clears it.
+     */
     tell(open: {
         readonly place?: AgentPlace | null;
-        readonly entryPoint?: string | null;
+        readonly entryPoint?: AgentEntryPoint | 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. */
+    /**
+     * Whether a reply can be rated: one this runtime saw given live. A reply restored from the device or a resumed
+     * transcript cannot be, until the API rates a turn by its conversation; the kits draw no thumbs for it.
+     */
+    canRate(turnId: string): boolean;
+    /** A thumbs on a whole reply, against the session it was given in; 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
@@ -172,6 +226,11 @@ interface AgentClock {
 }
 interface AgentRuntimeOptions {
     readonly backend: AgentBackend;
+    /**
+     * The agent this runtime talks to (its id at Vinaverse). It is part of every key, so two agents sharing the device's
+     * storage (`conversation.persistence`) never share a conversation. Default: none (one agent per storage namespace).
+     */
+    readonly agent?: string;
     /** 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`. */
@@ -189,8 +248,28 @@ interface AgentRuntimeOptions {
      */
     readonly insecureAddresses?: AgentInsecureAddresses;
     readonly onEvent?: (event: AgentEvent) => void;
+    /**
+     * Where the launcher remembers it greeted a person (the app's preferences store). Given here, the launcher reads and
+     * writes it through the runtime (`greetings`), a sign-out fences it, and `erase()` removes it.
+     */
+    readonly greetingStorage?: ConversationPersistence;
+    /**
+     * Keys an earlier version of the app or the kit wrote that no index lists, for a storage with neither `keys` nor
+     * `removePrefix`: removed by every sign-out from `conversation.persistence`, and by `erase()` from `greetingStorage`
+     * too. The migration that makes their removal certain on such a storage.
+     */
+    readonly legacyKeys?: readonly string[];
     /** Where the runtime's warnings go (the app's logger, crash reporter); default `console.warn`. */
-    readonly onWarning?: (message: string) => void;
+    readonly onWarning?: (message: string, warning: AgentWarning) => void;
+}
+/**
+ * What a warning is about, for an app's logger to count without reading the message: `insecure_addresses` (a leg let
+ * off the wss:// and https:// check outside development), `callback_threw` (the app's `onEvent` or `onActivity` threw;
+ * `callback` names it), `events_dropped` (the oldest analytics events, while the salt is read).
+ */
+interface AgentWarning {
+    readonly code: 'insecure_addresses' | 'callback_threw' | 'events_dropped';
+    readonly callback?: 'onEvent' | 'onActivity';
 }
 /** The legs whose session address may be plaintext: `realtime` (the WebSocket), `turns` (HTTP). */
 interface AgentInsecureAddresses {
@@ -207,15 +286,43 @@ interface AgentRuntime {
     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. */
+    /**
+     * Closes the key's conversation now; the next opening continues it in a new session. What the device kept of it and
+     * the conversation it continues stay: `forget` removes them.
+     */
     dispose(key: AgentKey): void;
+    /**
+     * Closes the key's conversation and forgets it on this device: the conversation it continued and the transcript kept
+     * by `persistence`. History's "delete" calls it after the tenant's backend deleted the conversation.
+     */
+    forget(key: AgentKey): void;
+    /** Ends every conversation no view shows that is past its session's end. The kits call it when the app comes back. */
+    sweep(): void;
+    /**
+     * History's delete: the backend deletes the conversation, then the device forgets it, only where the key still
+     * continues that conversation (an older history entry never forgets the key's newer one).
+     */
+    deleteConversation(key: AgentKey, conversationId: string): Promise<void>;
+    /**
+     * The person's erasure on this device: a sign-out, plus the launcher's greeting records (`greetingStorage`) and the
+     * analytics salt, every key this version and alpha.5 or alpha.6 wrote. Keys no index lists (an earlier version's, a
+     * write lost with its process) are found only when the storage has `keys` or `removePrefix`.
+     */
+    erase(): Promise<void>;
+    /** The launcher's greeting storage, under the sign-out fence; null without `greetingStorage`. */
+    readonly greetings: ConversationPersistence | null;
     /**
      * 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. */
+    /**
+     * Every conversation closed and forgotten, and everything this runtime kept on the device (every transcript it ever
+     * wrote under `conversation.persistenceKey`, even of conversations already closed), the status and the name; then
+     * the backend is told to end the sessions at the same time. A late answer from before (a session, a status, a write)
+     * changes nothing. Kept on purpose: the launcher's greeting records and the analytics salt (`erase` takes them).
+     */
     signOut(): Promise<void>;
     /** The agent's status, read from the backend at most every `statusStaleMs`. */
     status(): Promise<AgentStatus>;
@@ -227,8 +334,27 @@ interface AgentRuntime {
     /** 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;
+/**
+ * Where the launcher remembers that it greeted a person in a mode, the key its storage sees. Encoded so a guest
+ * (`null`) is never a person whose id is "guest".
+ */
+declare function greetedKey(subject: string | null, mode: string): string;
+/**
+ * A conversation's key as analytics sees it: SHA-256 of the install's salt and the key, 128 bits in hex. Stable per
+ * install (the runtime keeps the salt in the app's storage until `erase()`), never the person's id, and not
+ * recomputable from a guessed id without the salt.
+ */
+declare function hashKey(key: string, salt: string): string;
+/**
+ * The key as a string: one conversation per agent, person, mode, business and thread. Encoded as a JSON array, so no
+ * value can pass for another (a guest is `null`, never a subject named "guest"; a `|` in an id is just a character).
+ */
+declare function agentKey(key: AgentKey, agent?: string | null): string;
 declare function createAgentRuntime(options: AgentRuntimeOptions): AgentRuntime;
+/**
+ * An `AgentRefusal`, also one made by another copy of this package (the mock in `@vinaverse/client/testing`, the
+ * backend helpers in `@vinaverse/client/backend`, a second install): recognised by its name and kind, not its class.
+ */
+declare function isRefusal(error: unknown): error is AgentRefusal;
 
-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 };
+export { type AgentBackend as A, type AgentClock as a, type AgentConversation as b, type AgentConversationState as c, type AgentEntryPoint as d, type AgentEvent as e, type AgentEventType as f, type AgentFailure as g, type AgentFailureReason as h, type AgentInsecureAddresses as i, type AgentKey as j, type AgentPlace as k, type AgentRating as l, AgentRefusal as m, type AgentRetryPolicy as n, type AgentRuntime as o, type AgentRuntimeOptions as p, type AgentSessionRequest as q, type AgentStatus as r, type AgentStatusRead as s, type AgentWarning as t, agentKey as u, createAgentRuntime as v, greetedKey as w, hashKey as x, isRefusal as y };

package/dist/{runtime-CErMdYxJ.d.cts → runtime-B6_l8--U.d.ts}

@@ -1,5 +1,5 @@
-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';
+import { S as SessionRequest, b as ConversationSession, C as ConversationStore, f as ConversationPersistence, a as ConversationOptions } from './store-DZka9T2-.js';
+import { S as Schemas, k as ClientSecret } from './session-CPz4pcPu.js';
 
 /** Whose conversation: a person (null for a guest), the app's side, the business acted for, and the thread. */
 interface AgentKey {
@@ -22,17 +22,47 @@ interface AgentPlace {
     } | null;
     readonly filters?: ScreenContext['filters'];
 }
+/** How the person came in: the kit's parts say `launcher` and `ask`; an app adds `deep_link` or its own words. */
+type AgentEntryPoint = 'launcher' | 'ask' | 'deep_link' | (string & Record<never, never>);
 /** What the runtime asks the tenant's backend for: a session, for this key, told this place. */
 interface AgentSessionRequest extends SessionRequest {
     readonly key: AgentKey;
+    /**
+     * This session creation's id: the same through its retries, so the backend uses it as the gateway's idempotency key
+     * and never opens twice; a new one for every creation (a first open, a resume, continue-here, a rollover). A creation
+     * that could not reach the backend keeps it, and its whole request, for the next try, the person's "try again" too,
+     * for 24 hours. An `unknown_open` answer is final: not retried under it.
+     */
+    readonly openId: string;
+    /** The runtime's `agent`, for a backend that serves more than one. */
+    readonly agent: string | null;
     readonly place: AgentPlace | null;
-    /** How the person came in (`button`, `inbox`, …): the app's own words, passed through. */
-    readonly entryPoint: string | null;
+    /**
+     * The place's revision (`ScreenContext.revision`): higher than any the session was told before, and lower than any
+     * `updateContext` after it, so the API keeps the newest place across a session's rollover.
+     */
+    readonly placeRevision: number;
+    /** How the person came in (`launcher`, `ask`, `deep_link`, the app's own words), passed through. */
+    readonly entryPoint: AgentEntryPoint | 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). */
+/** The conversation is over (its session's own end, or a refusal with no finer reason). */
 'ended'
+/** The conversation asked for does not exist for this person (deleted, or never theirs). */
+ | 'not_found'
+/** Past the time the conversation is kept. */
+ | 'expired'
+/** The conversation belongs to another business, mode or agent than the key's. */
+ | 'mismatch'
+/** The conversation's flow is completed; a new one starts when the person asks. */
+ | 'completed'
+/** The person may not act for this business or conversation. */
+ | 'forbidden'
+/** The server holds a newer screen context than the one told (an update, never a session). */
+ | 'conflict'
+/** The backend could not tell whether the session opened: unavailable, never retried, its `openId` kept for support. */
+ | 'unknown_open'
 /** The person's sign-in was refused by the tenant's API. */
  | 'auth'
 /** The agent is switched off for this tenant, mode or person. */
@@ -83,11 +113,17 @@ interface AgentStatusRead {
 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>;
+    /**
+     * A fresh client secret for the same session (before its end): a `ClientSecret` `{ value, expires_at }`, or its
+     * value. A refusal (`session_closed`: the session is over) goes on with the conversation in a new session.
+     */
+    refreshSecret?(sessionId: string): Promise<ClientSecret | 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.
+     * (`PUT /v1/sessions/{id}/context`). A place cleared (`tell({ place: null })`) comes as `{ screen: 'other' }`.
+     * `revision` only grows for a conversation, across its sessions. A conflict (`decodeBackendFailure`'s
+     * `context_conflict`, or a refusal with reason `conflict`, with the server's `currentRevision`) is sent once more
+     * above it, then said as `moved`. Absent, or refused otherwise, the kit offers a question about the new place.
      */
     updateContext?(sessionId: string, place: AgentPlace, revision: number): Promise<void>;
     /** Whether the agent is offered, and what it can do. Absent: available, nothing extra. */
@@ -100,13 +136,16 @@ interface AgentBackend {
     }): Promise<void>;
     /** Sign-out: end the person's open sessions at the tenant's API. */
     endSessions?(): Promise<void>;
+    /** History's delete: the tenant's API deletes the person's conversation (authenticated, theirs only). */
+    deleteConversation?(conversationId: string): 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';
+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' | 'message_sent' | 'reply_completed' | 'card_shown';
 /** For the app's analytics: what happened, for which conversation, with nothing the person said. */
 interface AgentEvent {
     readonly type: AgentEventType;
+    /** The conversation, as a hash of its key (`hashKey`): stable, and never the person's id. */
     readonly key?: string;
     readonly sessionId?: string;
     readonly failure?: AgentFailure;
@@ -116,8 +155,8 @@ interface AgentEvent {
     readonly rating?: AgentRating;
     readonly cardId?: string;
     readonly kind?: string;
-    /** Where the person opened from (`entryPoint`, the screen). */
-    readonly from?: string;
+    /** Where the person opened from (`launcher`, `ask`, `deep_link`, the app's own words). */
+    readonly from?: AgentEntryPoint;
 }
 /** What a UI draws around the store: why there is no session, whether the person moved, the thumbs given. */
 interface AgentConversationState {
@@ -129,6 +168,13 @@ interface AgentConversationState {
     readonly moved: boolean;
     readonly ratings: ReadonlyMap<string, AgentRating>;
     readonly sessionId: string | null;
+    /**
+     * The conversation the key holds: the one it continues before a session opens, then its session's. Null for a new
+     * one not yet opened. History's delete compares against it (`deleteConversation` does).
+     */
+    readonly conversationId: string | null;
+    /** The open the backend could not settle (`unknown_open`), for support; null otherwise. */
+    readonly openId: string | null;
 }
 interface AgentConversation {
     /** The key as a string, for the app's own maps and the events. */
@@ -142,18 +188,26 @@ interface AgentConversation {
      */
     show(open?: {
         readonly place?: AgentPlace | null;
-        readonly entryPoint?: string | null;
+        readonly entryPoint?: AgentEntryPoint | 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. */
+    /**
+     * The place and the way in changed while a view is attached: told live where the backend can, else on the next
+     * session. `undefined` keeps what was told; `null` clears it.
+     */
     tell(open: {
         readonly place?: AgentPlace | null;
-        readonly entryPoint?: string | null;
+        readonly entryPoint?: AgentEntryPoint | 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. */
+    /**
+     * Whether a reply can be rated: one this runtime saw given live. A reply restored from the device or a resumed
+     * transcript cannot be, until the API rates a turn by its conversation; the kits draw no thumbs for it.
+     */
+    canRate(turnId: string): boolean;
+    /** A thumbs on a whole reply, against the session it was given in; 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
@@ -172,6 +226,11 @@ interface AgentClock {
 }
 interface AgentRuntimeOptions {
     readonly backend: AgentBackend;
+    /**
+     * The agent this runtime talks to (its id at Vinaverse). It is part of every key, so two agents sharing the device's
+     * storage (`conversation.persistence`) never share a conversation. Default: none (one agent per storage namespace).
+     */
+    readonly agent?: string;
     /** 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`. */
@@ -189,8 +248,28 @@ interface AgentRuntimeOptions {
      */
     readonly insecureAddresses?: AgentInsecureAddresses;
     readonly onEvent?: (event: AgentEvent) => void;
+    /**
+     * Where the launcher remembers it greeted a person (the app's preferences store). Given here, the launcher reads and
+     * writes it through the runtime (`greetings`), a sign-out fences it, and `erase()` removes it.
+     */
+    readonly greetingStorage?: ConversationPersistence;
+    /**
+     * Keys an earlier version of the app or the kit wrote that no index lists, for a storage with neither `keys` nor
+     * `removePrefix`: removed by every sign-out from `conversation.persistence`, and by `erase()` from `greetingStorage`
+     * too. The migration that makes their removal certain on such a storage.
+     */
+    readonly legacyKeys?: readonly string[];
     /** Where the runtime's warnings go (the app's logger, crash reporter); default `console.warn`. */
-    readonly onWarning?: (message: string) => void;
+    readonly onWarning?: (message: string, warning: AgentWarning) => void;
+}
+/**
+ * What a warning is about, for an app's logger to count without reading the message: `insecure_addresses` (a leg let
+ * off the wss:// and https:// check outside development), `callback_threw` (the app's `onEvent` or `onActivity` threw;
+ * `callback` names it), `events_dropped` (the oldest analytics events, while the salt is read).
+ */
+interface AgentWarning {
+    readonly code: 'insecure_addresses' | 'callback_threw' | 'events_dropped';
+    readonly callback?: 'onEvent' | 'onActivity';
 }
 /** The legs whose session address may be plaintext: `realtime` (the WebSocket), `turns` (HTTP). */
 interface AgentInsecureAddresses {
@@ -207,15 +286,43 @@ interface AgentRuntime {
     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. */
+    /**
+     * Closes the key's conversation now; the next opening continues it in a new session. What the device kept of it and
+     * the conversation it continues stay: `forget` removes them.
+     */
     dispose(key: AgentKey): void;
+    /**
+     * Closes the key's conversation and forgets it on this device: the conversation it continued and the transcript kept
+     * by `persistence`. History's "delete" calls it after the tenant's backend deleted the conversation.
+     */
+    forget(key: AgentKey): void;
+    /** Ends every conversation no view shows that is past its session's end. The kits call it when the app comes back. */
+    sweep(): void;
+    /**
+     * History's delete: the backend deletes the conversation, then the device forgets it, only where the key still
+     * continues that conversation (an older history entry never forgets the key's newer one).
+     */
+    deleteConversation(key: AgentKey, conversationId: string): Promise<void>;
+    /**
+     * The person's erasure on this device: a sign-out, plus the launcher's greeting records (`greetingStorage`) and the
+     * analytics salt, every key this version and alpha.5 or alpha.6 wrote. Keys no index lists (an earlier version's, a
+     * write lost with its process) are found only when the storage has `keys` or `removePrefix`.
+     */
+    erase(): Promise<void>;
+    /** The launcher's greeting storage, under the sign-out fence; null without `greetingStorage`. */
+    readonly greetings: ConversationPersistence | null;
     /**
      * 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. */
+    /**
+     * Every conversation closed and forgotten, and everything this runtime kept on the device (every transcript it ever
+     * wrote under `conversation.persistenceKey`, even of conversations already closed), the status and the name; then
+     * the backend is told to end the sessions at the same time. A late answer from before (a session, a status, a write)
+     * changes nothing. Kept on purpose: the launcher's greeting records and the analytics salt (`erase` takes them).
+     */
     signOut(): Promise<void>;
     /** The agent's status, read from the backend at most every `statusStaleMs`. */
     status(): Promise<AgentStatus>;
@@ -227,8 +334,27 @@ interface AgentRuntime {
     /** 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;
+/**
+ * Where the launcher remembers that it greeted a person in a mode, the key its storage sees. Encoded so a guest
+ * (`null`) is never a person whose id is "guest".
+ */
+declare function greetedKey(subject: string | null, mode: string): string;
+/**
+ * A conversation's key as analytics sees it: SHA-256 of the install's salt and the key, 128 bits in hex. Stable per
+ * install (the runtime keeps the salt in the app's storage until `erase()`), never the person's id, and not
+ * recomputable from a guessed id without the salt.
+ */
+declare function hashKey(key: string, salt: string): string;
+/**
+ * The key as a string: one conversation per agent, person, mode, business and thread. Encoded as a JSON array, so no
+ * value can pass for another (a guest is `null`, never a subject named "guest"; a `|` in an id is just a character).
+ */
+declare function agentKey(key: AgentKey, agent?: string | null): string;
 declare function createAgentRuntime(options: AgentRuntimeOptions): AgentRuntime;
+/**
+ * An `AgentRefusal`, also one made by another copy of this package (the mock in `@vinaverse/client/testing`, the
+ * backend helpers in `@vinaverse/client/backend`, a second install): recognised by its name and kind, not its class.
+ */
+declare function isRefusal(error: unknown): error is AgentRefusal;
 
-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 };
+export { type AgentBackend as A, type AgentClock as a, type AgentConversation as b, type AgentConversationState as c, type AgentEntryPoint as d, type AgentEvent as e, type AgentEventType as f, type AgentFailure as g, type AgentFailureReason as h, type AgentInsecureAddresses as i, type AgentKey as j, type AgentPlace as k, type AgentRating as l, AgentRefusal as m, type AgentRetryPolicy as n, type AgentRuntime as o, type AgentRuntimeOptions as p, type AgentSessionRequest as q, type AgentStatus as r, type AgentStatusRead as s, type AgentWarning as t, agentKey as u, createAgentRuntime as v, greetedKey as w, hashKey as x, isRefusal as y };