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

package/dist/conversation/index.d.cts

@@ -1,5 +1,5 @@
-import { Q as Question, A as AnswerInput, H as HeldCard, T as ToolLine, S as SessionInfo, C as ClientSecret, a as SessionOptions, P as ProposalOutcome } from '../session--W6JXfwo.cjs';
-export { b as CONTRACT, c as Card, d as CardKind, e as ClientErrorCode, f as HeldQuestion, g as Proposal, V as VinaverseClientError, i as isKnownCard } from '../session--W6JXfwo.cjs';
+import { Q as Question, A as AnswerInput, H as HeldCard, W as Welcome, T as ToolLine, S as SessionInfo, C as ClientSecret, a as SessionOptions, P as ProposalOutcome } from '../session-C3qZwGPG.cjs';
+export { b as CONTRACT, c as Card, d as CardGroup, e as CardImage, f as CardKind, g as CardLink, h as ClientErrorCode, i as HeldQuestion, j as Proposal, V as VinaverseClientError, k as isKnownCard } from '../session-C3qZwGPG.cjs';
 
 type AnswerProblem = 
 /** Nothing chosen or typed, and the question is required (or skipped while required). */
@@ -47,7 +47,10 @@ type ConversationStatus =
  | 'sse'
 /** The session ended; `next` says how the conversation goes on. */
  | 'ended'
-/** The client secret was refused and no fresh one could be had. */
+/**
+ * The client secret was refused, and the new session the store then asked for was refused as well: `start()` (the
+ * person's "Try again") asks for another.
+ */
  | 'unauthorized'
 /** `dispose()` or `clear()` closed it. */
  | 'closed';
@@ -102,13 +105,17 @@ interface SystemItem {
     readonly event: SystemEvent;
     /**
      * `takeover_started`: `by`; `handoff_created`: `expected_response`; `flow_completed`: `result`, `code`;
-     * `turn_failed` (a turn that failed before any of its reply streamed): `code`, `message`, `retryable`.
+     * `turn_failed` (a turn that failed before any of its reply streamed): `code`, `message`, `retryable`, `turn` (its `turn_id`), and `retry`:
+     * the server allows a retry and the person's text that started the turn is known, so `retryTurn(key)` sends it
+     * again (false once it did).
      */
     readonly data: Readonly<Record<string, string | boolean | null>>;
 }
 type TimelineItem = MessageItem | CardItem | SystemItem;
 interface ConversationView {
     readonly status: ConversationStatus;
+    /** The conversation the sessions belong to, once a session named it; for the tenant's own records and support. */
+    readonly conversationId: string | null;
     readonly banner: ConversationBanner;
     /**
      * How the conversation goes on after the session ended: `continue` on the person's next action (it resumes on its
@@ -119,6 +126,11 @@ interface ConversationView {
         readonly name: string | null;
         readonly avatarUrl: string | null;
     };
+    /**
+     * The tenant's greeting and chips for the session's mode (v1-draft.20, `Session.welcome`), or null. A UI shows it on
+     * an empty conversation; a chip sends its `message` as the person's own text (`send`).
+     */
+    readonly welcome: Welcome | null;
     /** The server's AI disclosure; null until the first one, when the UI shows its own line. Never hidden. */
     readonly disclosure: string | null;
     /** While a person from the business replies: their role (`by`, never a name). */
@@ -179,6 +191,13 @@ type ConversationSession = SessionInfo & {
         readonly avatar_url?: string;
     };
     readonly disclosure?: string;
+    /**
+     * When the session ends (`Session.expires_at`: the earliest of its own limit and the tenant's tool token). Past it,
+     * the conversation goes on in a new session from `getSession`, never with a fresh secret for this one.
+     */
+    readonly expires_at?: string;
+    /** v1-draft.20: the tenant's greeting and chips for the session's mode (`Session.welcome`); no model call. */
+    readonly welcome?: Welcome;
 };
 /**
  * Runs a callback before the next frame; `requestAnimationFrame` where there is one. Every listener, of the view and
@@ -249,6 +268,8 @@ declare class ConversationStore {
     /** Proposals whose tenant decision threw: shown as recoverable, the person may decide again. */
     private readonly decisionErrors;
     private system;
+    /** The person's text that started each recent turn, by `turn_id` (`turn.started` echoes its `client_event_id`). */
+    private readonly turnInputs;
     /** Numbers system rows that carry no id of their own. */
     private systemSeq;
     private history;
@@ -259,6 +280,8 @@ declare class ConversationStore {
     private readySession;
     private cardOrder;
     private kept;
+    /** Cards an earlier session drew, kept by a merged transcript: drawn as restored, taking no tap. */
+    private readonly inert;
     private locale;
     /** The request for a session in flight, to abort when it is no longer wanted. */
     private fetching;
@@ -297,7 +320,12 @@ declare class ConversationStore {
     /** In the background (`closeInBackground`): the connection is closed; the engine keeps what was sent, to resend. */
     private suspended;
     private suspend;
-    /** Back in the foreground: a new connection to the same session, with a fresh secret when the backend gives one. */
+    /**
+     * Back in the foreground, or the person acted while away: a new connection to the same session, with a fresh secret
+     * when the backend gives one. A session that passed its end meanwhile is never reopened (a fresh secret cannot bring
+     * back an expired tool token): the person's action continues the conversation in a new session from `getSession`,
+     * and until then nothing connects.
+     */
     private wake;
     /** The network as the app sees it; null when unknown. Back online reconnects a connection that gave up. */
     setOnline(online: boolean | null): void;
@@ -321,6 +349,12 @@ declare class ConversationStore {
     decideProposal(cardId: string, decide: () => Promise<ProposalOutcome>): Promise<ProposalOutcome | null>;
     /** Send a "not sent" message again, as a new message (the person's action). Returns the new id. */
     retry(key: string): string | null;
+    /**
+     * Send again the person's text whose turn failed before any reply (a `turn_failed` row with `data.retry`), as a new
+     * message (the person's action). Once per row: its `retry` turns false. Returns the new id, or null when the row
+     * allows no retry.
+     */
+    retryTurn(key: string): string | null;
     /** After the conversation continued on another device: continue it here (the person's choice). */
     continueHere(): Promise<void>;
     /** Stop the turn in progress. */
@@ -336,8 +370,12 @@ declare class ConversationStore {
     /** The person acted after the session ended idle, expired or at its limit: the next session takes what they sent. */
     private continueIfEnded;
     private reconnectIfDown;
+    /** A refusal already led to a new session, and none has been ready since: another refusal is no cue. */
+    private rolled;
     private statusChanged;
     private event;
+    /** The person's text that started a turn, while its message is on screen. */
+    private turnText;
     /**
      * A resumed session's transcript replaced the messages, and a chat transcript carries text only: the engine drops
      * the cards it drew, and draws the pending ones again at the end. Each card on screen is anchored just after the
@@ -362,10 +400,37 @@ declare class ConversationStore {
     private key;
     private restore;
     private schedulePersist;
+    /** Past the session's end (`expires_at`), when the backend passed it on. */
+    private sessionOver;
     private live;
     private required;
 }
 /** One conversation with an agent, for any UI: see `ConversationStore`. */
 declare function createConversation(options: ConversationOptions): ConversationStore;
 
-export { AnswerInput, type AnswerProblem, type CardItem, type ConversationBanner, type ConversationOptions, type ConversationPersistence, type ConversationSession, type ConversationStatus, ConversationStore, type ConversationView, type FrameScheduler, HeldCard, MAX_TEXT, type MessageItem, type MessageState, ProposalOutcome, Question, type SessionReason, type SessionRequest, type StreamingText, type SystemEvent, type SystemItem, type TimelineItem, ToolLine, answerProblem, codePoints, createConversation, isAllowedLink, isValidLinkPrefix };
+/** A session request, with the mode it is for. */
+interface ModeSessionRequest extends SessionRequest {
+    readonly mode: string;
+}
+interface ConversationsByModeOptions extends Omit<ConversationOptions, 'getSession'> {
+    /** Your backend creates the session for the mode's agent (its `subject.type`, its agent), with its service key. */
+    readonly getSession: (request: ModeSessionRequest) => Promise<ConversationSession>;
+    /** Every mode the app has, so `clear()` forgets each one's kept history, even one not opened since launch. */
+    readonly modes?: readonly string[];
+}
+interface ConversationsByMode {
+    /** The mode's store, made the first time it is asked for; the same store after that. */
+    get(mode: string): ConversationStore;
+    /**
+     * The mode the person switched to: its store, with every other mode's sent to the background (no pings; closed
+     * with `closeInBackground`). The kit then drives the selected one with the app's foreground and background.
+     */
+    select(mode: string): ConversationStore;
+    /** Close every mode's store. */
+    dispose(): void;
+    /** Close every mode's store and forget what each kept on the device (sign-out). */
+    clear(): void;
+}
+declare function createConversationsByMode(options: ConversationsByModeOptions): ConversationsByMode;
+
+export { AnswerInput, type AnswerProblem, type CardItem, type ConversationBanner, type ConversationOptions, type ConversationPersistence, type ConversationSession, type ConversationStatus, ConversationStore, type ConversationView, type ConversationsByMode, type ConversationsByModeOptions, type FrameScheduler, HeldCard, MAX_TEXT, type MessageItem, type MessageState, type ModeSessionRequest, ProposalOutcome, Question, type SessionReason, type SessionRequest, type StreamingText, type SystemEvent, type SystemItem, type TimelineItem, ToolLine, Welcome, answerProblem, codePoints, createConversation, createConversationsByMode, isAllowedLink, isValidLinkPrefix };

package/dist/conversation/index.d.ts

@@ -1,5 +1,5 @@
-import { Q as Question, A as AnswerInput, H as HeldCard, T as ToolLine, S as SessionInfo, C as ClientSecret, a as SessionOptions, P as ProposalOutcome } from '../session--W6JXfwo.js';
-export { b as CONTRACT, c as Card, d as CardKind, e as ClientErrorCode, f as HeldQuestion, g as Proposal, V as VinaverseClientError, i as isKnownCard } from '../session--W6JXfwo.js';
+import { Q as Question, A as AnswerInput, H as HeldCard, W as Welcome, T as ToolLine, S as SessionInfo, C as ClientSecret, a as SessionOptions, P as ProposalOutcome } from '../session-C3qZwGPG.js';
+export { b as CONTRACT, c as Card, d as CardGroup, e as CardImage, f as CardKind, g as CardLink, h as ClientErrorCode, i as HeldQuestion, j as Proposal, V as VinaverseClientError, k as isKnownCard } from '../session-C3qZwGPG.js';
 
 type AnswerProblem = 
 /** Nothing chosen or typed, and the question is required (or skipped while required). */
@@ -47,7 +47,10 @@ type ConversationStatus =
  | 'sse'
 /** The session ended; `next` says how the conversation goes on. */
  | 'ended'
-/** The client secret was refused and no fresh one could be had. */
+/**
+ * The client secret was refused, and the new session the store then asked for was refused as well: `start()` (the
+ * person's "Try again") asks for another.
+ */
  | 'unauthorized'
 /** `dispose()` or `clear()` closed it. */
  | 'closed';
@@ -102,13 +105,17 @@ interface SystemItem {
     readonly event: SystemEvent;
     /**
      * `takeover_started`: `by`; `handoff_created`: `expected_response`; `flow_completed`: `result`, `code`;
-     * `turn_failed` (a turn that failed before any of its reply streamed): `code`, `message`, `retryable`.
+     * `turn_failed` (a turn that failed before any of its reply streamed): `code`, `message`, `retryable`, `turn` (its `turn_id`), and `retry`:
+     * the server allows a retry and the person's text that started the turn is known, so `retryTurn(key)` sends it
+     * again (false once it did).
      */
     readonly data: Readonly<Record<string, string | boolean | null>>;
 }
 type TimelineItem = MessageItem | CardItem | SystemItem;
 interface ConversationView {
     readonly status: ConversationStatus;
+    /** The conversation the sessions belong to, once a session named it; for the tenant's own records and support. */
+    readonly conversationId: string | null;
     readonly banner: ConversationBanner;
     /**
      * How the conversation goes on after the session ended: `continue` on the person's next action (it resumes on its
@@ -119,6 +126,11 @@ interface ConversationView {
         readonly name: string | null;
         readonly avatarUrl: string | null;
     };
+    /**
+     * The tenant's greeting and chips for the session's mode (v1-draft.20, `Session.welcome`), or null. A UI shows it on
+     * an empty conversation; a chip sends its `message` as the person's own text (`send`).
+     */
+    readonly welcome: Welcome | null;
     /** The server's AI disclosure; null until the first one, when the UI shows its own line. Never hidden. */
     readonly disclosure: string | null;
     /** While a person from the business replies: their role (`by`, never a name). */
@@ -179,6 +191,13 @@ type ConversationSession = SessionInfo & {
         readonly avatar_url?: string;
     };
     readonly disclosure?: string;
+    /**
+     * When the session ends (`Session.expires_at`: the earliest of its own limit and the tenant's tool token). Past it,
+     * the conversation goes on in a new session from `getSession`, never with a fresh secret for this one.
+     */
+    readonly expires_at?: string;
+    /** v1-draft.20: the tenant's greeting and chips for the session's mode (`Session.welcome`); no model call. */
+    readonly welcome?: Welcome;
 };
 /**
  * Runs a callback before the next frame; `requestAnimationFrame` where there is one. Every listener, of the view and
@@ -249,6 +268,8 @@ declare class ConversationStore {
     /** Proposals whose tenant decision threw: shown as recoverable, the person may decide again. */
     private readonly decisionErrors;
     private system;
+    /** The person's text that started each recent turn, by `turn_id` (`turn.started` echoes its `client_event_id`). */
+    private readonly turnInputs;
     /** Numbers system rows that carry no id of their own. */
     private systemSeq;
     private history;
@@ -259,6 +280,8 @@ declare class ConversationStore {
     private readySession;
     private cardOrder;
     private kept;
+    /** Cards an earlier session drew, kept by a merged transcript: drawn as restored, taking no tap. */
+    private readonly inert;
     private locale;
     /** The request for a session in flight, to abort when it is no longer wanted. */
     private fetching;
@@ -297,7 +320,12 @@ declare class ConversationStore {
     /** In the background (`closeInBackground`): the connection is closed; the engine keeps what was sent, to resend. */
     private suspended;
     private suspend;
-    /** Back in the foreground: a new connection to the same session, with a fresh secret when the backend gives one. */
+    /**
+     * Back in the foreground, or the person acted while away: a new connection to the same session, with a fresh secret
+     * when the backend gives one. A session that passed its end meanwhile is never reopened (a fresh secret cannot bring
+     * back an expired tool token): the person's action continues the conversation in a new session from `getSession`,
+     * and until then nothing connects.
+     */
     private wake;
     /** The network as the app sees it; null when unknown. Back online reconnects a connection that gave up. */
     setOnline(online: boolean | null): void;
@@ -321,6 +349,12 @@ declare class ConversationStore {
     decideProposal(cardId: string, decide: () => Promise<ProposalOutcome>): Promise<ProposalOutcome | null>;
     /** Send a "not sent" message again, as a new message (the person's action). Returns the new id. */
     retry(key: string): string | null;
+    /**
+     * Send again the person's text whose turn failed before any reply (a `turn_failed` row with `data.retry`), as a new
+     * message (the person's action). Once per row: its `retry` turns false. Returns the new id, or null when the row
+     * allows no retry.
+     */
+    retryTurn(key: string): string | null;
     /** After the conversation continued on another device: continue it here (the person's choice). */
     continueHere(): Promise<void>;
     /** Stop the turn in progress. */
@@ -336,8 +370,12 @@ declare class ConversationStore {
     /** The person acted after the session ended idle, expired or at its limit: the next session takes what they sent. */
     private continueIfEnded;
     private reconnectIfDown;
+    /** A refusal already led to a new session, and none has been ready since: another refusal is no cue. */
+    private rolled;
     private statusChanged;
     private event;
+    /** The person's text that started a turn, while its message is on screen. */
+    private turnText;
     /**
      * A resumed session's transcript replaced the messages, and a chat transcript carries text only: the engine drops
      * the cards it drew, and draws the pending ones again at the end. Each card on screen is anchored just after the
@@ -362,10 +400,37 @@ declare class ConversationStore {
     private key;
     private restore;
     private schedulePersist;
+    /** Past the session's end (`expires_at`), when the backend passed it on. */
+    private sessionOver;
     private live;
     private required;
 }
 /** One conversation with an agent, for any UI: see `ConversationStore`. */
 declare function createConversation(options: ConversationOptions): ConversationStore;
 
-export { AnswerInput, type AnswerProblem, type CardItem, type ConversationBanner, type ConversationOptions, type ConversationPersistence, type ConversationSession, type ConversationStatus, ConversationStore, type ConversationView, type FrameScheduler, HeldCard, MAX_TEXT, type MessageItem, type MessageState, ProposalOutcome, Question, type SessionReason, type SessionRequest, type StreamingText, type SystemEvent, type SystemItem, type TimelineItem, ToolLine, answerProblem, codePoints, createConversation, isAllowedLink, isValidLinkPrefix };
+/** A session request, with the mode it is for. */
+interface ModeSessionRequest extends SessionRequest {
+    readonly mode: string;
+}
+interface ConversationsByModeOptions extends Omit<ConversationOptions, 'getSession'> {
+    /** Your backend creates the session for the mode's agent (its `subject.type`, its agent), with its service key. */
+    readonly getSession: (request: ModeSessionRequest) => Promise<ConversationSession>;
+    /** Every mode the app has, so `clear()` forgets each one's kept history, even one not opened since launch. */
+    readonly modes?: readonly string[];
+}
+interface ConversationsByMode {
+    /** The mode's store, made the first time it is asked for; the same store after that. */
+    get(mode: string): ConversationStore;
+    /**
+     * The mode the person switched to: its store, with every other mode's sent to the background (no pings; closed
+     * with `closeInBackground`). The kit then drives the selected one with the app's foreground and background.
+     */
+    select(mode: string): ConversationStore;
+    /** Close every mode's store. */
+    dispose(): void;
+    /** Close every mode's store and forget what each kept on the device (sign-out). */
+    clear(): void;
+}
+declare function createConversationsByMode(options: ConversationsByModeOptions): ConversationsByMode;
+
+export { AnswerInput, type AnswerProblem, type CardItem, type ConversationBanner, type ConversationOptions, type ConversationPersistence, type ConversationSession, type ConversationStatus, ConversationStore, type ConversationView, type ConversationsByMode, type ConversationsByModeOptions, type FrameScheduler, HeldCard, MAX_TEXT, type MessageItem, type MessageState, type ModeSessionRequest, ProposalOutcome, Question, type SessionReason, type SessionRequest, type StreamingText, type SystemEvent, type SystemItem, type TimelineItem, ToolLine, Welcome, answerProblem, codePoints, createConversation, createConversationsByMode, isAllowedLink, isValidLinkPrefix };