@vinaverse/client 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/conversation/index.d.cts

@@ -1,8 +1,8 @@
 export { C as CONTRACT } from '../contract-_NMdPjgN.cjs';
 import { Q as Question, A as AnswerInput } from '../session-8W3fRNeb.cjs';
 export { a as Card, b as CardGroup, c as CardImage, d as CardKind, C as CardLink, e as ClientErrorCode, H as HeldCard, f as HeldQuestion, P as Proposal, g as ProposalOutcome, T as ToolLine, V as VinaverseClientError, W as Welcome, i as isKnownCard } from '../session-8W3fRNeb.cjs';
-import { C as ConversationStore, a as ConversationOptions, S as SessionRequest, b as ConversationSession } from '../store-C7FtS5AY.cjs';
-export { c as CardItem, d as ConversationBanner, e as ConversationPersistence, f as ConversationStatus, g as ConversationView, F as FrameScheduler, M as MAX_TEXT, h as MessageItem, i as MessageState, j as SessionReason, k as StreamingText, l as SystemEvent, m as SystemItem, T as TimelineItem, n as createConversation } from '../store-C7FtS5AY.cjs';
+import { C as ConversationStore, a as ConversationOptions, S as SessionRequest, b as ConversationSession } from '../store-7WU1kD9W.cjs';
+export { c as CardItem, d as ConversationActivity, e as ConversationBanner, f as ConversationPersistence, g as ConversationStatus, h as ConversationView, F as FrameScheduler, M as MAX_TEXT, i as MessageItem, j as MessageState, k as SessionReason, l as StreamingText, m as SystemEvent, n as SystemItem, T as TimelineItem, o as createConversation } from '../store-7WU1kD9W.cjs';
 
 type AnswerProblem = 
 /** Nothing chosen or typed, and the question is required (or skipped while required). */

package/dist/conversation/index.d.ts

@@ -1,8 +1,8 @@
 export { C as CONTRACT } from '../contract-_NMdPjgN.js';
 import { Q as Question, A as AnswerInput } from '../session-8W3fRNeb.js';
 export { a as Card, b as CardGroup, c as CardImage, d as CardKind, C as CardLink, e as ClientErrorCode, H as HeldCard, f as HeldQuestion, P as Proposal, g as ProposalOutcome, T as ToolLine, V as VinaverseClientError, W as Welcome, i as isKnownCard } from '../session-8W3fRNeb.js';
-import { C as ConversationStore, a as ConversationOptions, S as SessionRequest, b as ConversationSession } from '../store-DFk0ayh8.js';
-export { c as CardItem, d as ConversationBanner, e as ConversationPersistence, f as ConversationStatus, g as ConversationView, F as FrameScheduler, M as MAX_TEXT, h as MessageItem, i as MessageState, j as SessionReason, k as StreamingText, l as SystemEvent, m as SystemItem, T as TimelineItem, n as createConversation } from '../store-DFk0ayh8.js';
+import { C as ConversationStore, a as ConversationOptions, S as SessionRequest, b as ConversationSession } from '../store-DrXSPHu6.js';
+export { c as CardItem, d as ConversationActivity, e as ConversationBanner, f as ConversationPersistence, g as ConversationStatus, h as ConversationView, F as FrameScheduler, M as MAX_TEXT, i as MessageItem, j as MessageState, k as SessionReason, l as StreamingText, m as SystemEvent, n as SystemItem, T as TimelineItem, o as createConversation } from '../store-DrXSPHu6.js';
 
 type AnswerProblem = 
 /** Nothing chosen or typed, and the question is required (or skipped while required). */

package/dist/conversation/index.js

@@ -1,6 +1,6 @@
 export { CONTRACT } from '../chunk-VSJDVLCP.js';
-import { createConversation } from '../chunk-ZWG2TMUL.js';
-export { ConversationStore, MAX_TEXT, createConversation, isAllowedLink, isValidLinkPrefix } from '../chunk-ZWG2TMUL.js';
+import { createConversation } from '../chunk-46D3FSLU.js';
+export { ConversationStore, MAX_TEXT, createConversation, isAllowedLink, isValidLinkPrefix } from '../chunk-46D3FSLU.js';
 export { VinaverseClientError, isKnownCard } from '../chunk-GWLLUOFY.js';
 
 // src/conversation/answers.ts

package/dist/{runtime-DDxwWBBr.d.cts → runtime-C3ZknHdG.d.cts}

@@ -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-7WU1kD9W.cjs';
+import { S as Schemas, k as ClientSecret } 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 {
@@ -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,6 +248,19 @@ 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;
 }
 /** The legs whose session address may be plaintext: `realtime` (the WebSocket), `turns` (HTTP). */
 interface AgentInsecureAddresses {
@@ -205,15 +277,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>;
@@ -225,8 +325,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, agentKey as t, createAgentRuntime as u, greetedKey as v, hashKey as w, isRefusal as x };

package/dist/{runtime-B4nKwOTF.d.ts → runtime-CZ1hLvAl.d.ts}

@@ -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-DrXSPHu6.js';
+import { S as Schemas, k as ClientSecret } 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 {
@@ -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,6 +248,19 @@ 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;
 }
 /** The legs whose session address may be plaintext: `realtime` (the WebSocket), `turns` (HTTP). */
 interface AgentInsecureAddresses {
@@ -205,15 +277,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>;
@@ -225,8 +325,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, agentKey as t, createAgentRuntime as u, greetedKey as v, hashKey as w, isRefusal as x };

package/dist/{store-C7FtS5AY.d.cts → store-7WU1kD9W.d.cts}

@@ -179,6 +179,15 @@ interface ConversationPersistence {
     getItem(key: string): string | null | Promise<string | null>;
     setItem(key: string, value: string): void | Promise<void>;
     removeItem(key: string): void | Promise<void>;
+    /**
+     * Optional: the keys under a prefix. With it (or `removePrefix`), a sign-out and an erasure are guaranteed to find every
+     * key kept, ones no index lists too (an earlier version's, a write lost with its process); without either, only the
+     * keys this version indexed and the shapes it can derive from them. AsyncStorage and MMKV: `getAllKeys()` filtered
+     * by the prefix; web `localStorage`: `Object.keys(localStorage)` filtered.
+     */
+    keys?(prefix: string): readonly string[] | Promise<readonly string[]>;
+    /** Optional: removes every key under a prefix at once (used instead of `keys` where it cannot reach a kept record). */
+    removePrefix?(prefix: string): void | Promise<void>;
 }
 interface ConversationOptions {
     /**
@@ -217,7 +226,24 @@ interface ConversationOptions {
     readonly clock?: {
         now(): number;
     };
+    /**
+     * What the person and the agent did live, for analytics (never what a transcript or the device brought back): the
+     * person sent a text, a reply finished, a card was drawn. Carries no text.
+     */
+    readonly onActivity?: (activity: ConversationActivity) => void;
 }
+/** One live step of the conversation, without its words. */
+type ConversationActivity = {
+    readonly type: 'message_sent';
+    readonly id: string;
+} | {
+    readonly type: 'reply_completed';
+    readonly turnId: string;
+} | {
+    readonly type: 'card_shown';
+    readonly cardId: string;
+    readonly kind: string;
+};
 /** A text is at most 2000 code points (`TurnInput`). */
 declare const MAX_TEXT = 2000;
 declare class ConversationStore {
@@ -346,6 +372,10 @@ declare class ConversationStore {
     /** A refusal already led to a new session, and none has been ready since: another refusal is no cue. */
     private rolled;
     private statusChanged;
+    /** The app's analytics hears of a step; what it throws is reported (`onError`), never in the way of a send or a frame. */
+    private tellActivity;
+    /** The live frames analytics hears of: a reply finished, cards drawn. */
+    private activity;
     private event;
     /** The person's text that started a turn, while its message is on screen. */
     private turnText;
@@ -381,4 +411,4 @@ declare class ConversationStore {
 /** One conversation with an agent, for any UI: see `ConversationStore`. */
 declare function createConversation(options: ConversationOptions): ConversationStore;
 
-export { ConversationStore as C, type FrameScheduler as F, MAX_TEXT as M, type SessionRequest as S, type TimelineItem as T, type ConversationOptions as a, type ConversationSession as b, type CardItem as c, type ConversationBanner as d, type ConversationPersistence as e, type ConversationStatus as f, type ConversationView as g, type MessageItem as h, type MessageState as i, type SessionReason as j, type StreamingText as k, type SystemEvent as l, type SystemItem as m, createConversation as n };
+export { ConversationStore as C, type FrameScheduler as F, MAX_TEXT as M, type SessionRequest as S, type TimelineItem as T, type ConversationOptions as a, type ConversationSession as b, type CardItem as c, type ConversationActivity as d, type ConversationBanner as e, type ConversationPersistence as f, type ConversationStatus as g, type ConversationView as h, type MessageItem as i, type MessageState as j, type SessionReason as k, type StreamingText as l, type SystemEvent as m, type SystemItem as n, createConversation as o };