@vinaverse/client 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/conversation/index.d.cts

@@ -102,13 +102,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
@@ -219,6 +223,12 @@ interface ConversationOptions {
     readonly createId?: () => string;
     /** Something failed that no call returned: getting a session, an input that could not be delivered. */
     readonly onError?: (error: unknown) => void;
+    /**
+     * Close the connection while the app is in the background, and open it again in the foreground (a backend that
+     * mints a client secret per connection: with `refreshSecret`, a fresh one is asked for first). Default false: the
+     * connection stays, with no pings, until the session idles out. Nothing typed or answered is lost either way.
+     */
+    readonly closeInBackground?: boolean;
 }
 /** A text is at most 2000 code points (`TurnInput`). */
 declare const MAX_TEXT = 2000;
@@ -243,12 +253,18 @@ 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;
     private historyState;
     /** A resumed session.ready carried a transcript: the server's history replaced what the device kept. */
     private transcriptSeen;
+    /** The session of the last session.ready: a card of another one takes no tap (§6). */
+    private readySession;
+    private cardOrder;
+    private kept;
     private locale;
     /** The request for a session in flight, to abort when it is no longer wanted. */
     private fetching;
@@ -284,6 +300,11 @@ declare class ConversationStore {
     setLocale(locale: string | undefined): void;
     /** The app came to the foreground or went to the background (AppState, `visibilitychange`). */
     setForeground(foreground: boolean): void;
+    /** 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. */
+    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;
     /** Send a typed message; returns its `client_event_id`. Typed before a session exists, it is sent once one does. */
@@ -306,6 +327,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. */
@@ -323,6 +350,15 @@ declare class ConversationStore {
     private reconnectIfDown;
     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
+     * message it followed (by key; the transcript keeps the live keys), so a pending proposal stays where it was, and a
+     * card the transcript dropped stays drawn there; taking no tap when it belongs to an earlier session.
+     */
+    private anchorCards;
     /**
      * Recomputes now (getSnapshot and getStreaming are always current) and notifies from the scheduler, at most once
      * per frame, both channels in the same flush: a streamed reply that completes becomes its message in one frame.

package/dist/conversation/index.d.ts

@@ -102,13 +102,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
@@ -219,6 +223,12 @@ interface ConversationOptions {
     readonly createId?: () => string;
     /** Something failed that no call returned: getting a session, an input that could not be delivered. */
     readonly onError?: (error: unknown) => void;
+    /**
+     * Close the connection while the app is in the background, and open it again in the foreground (a backend that
+     * mints a client secret per connection: with `refreshSecret`, a fresh one is asked for first). Default false: the
+     * connection stays, with no pings, until the session idles out. Nothing typed or answered is lost either way.
+     */
+    readonly closeInBackground?: boolean;
 }
 /** A text is at most 2000 code points (`TurnInput`). */
 declare const MAX_TEXT = 2000;
@@ -243,12 +253,18 @@ 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;
     private historyState;
     /** A resumed session.ready carried a transcript: the server's history replaced what the device kept. */
     private transcriptSeen;
+    /** The session of the last session.ready: a card of another one takes no tap (§6). */
+    private readySession;
+    private cardOrder;
+    private kept;
     private locale;
     /** The request for a session in flight, to abort when it is no longer wanted. */
     private fetching;
@@ -284,6 +300,11 @@ declare class ConversationStore {
     setLocale(locale: string | undefined): void;
     /** The app came to the foreground or went to the background (AppState, `visibilitychange`). */
     setForeground(foreground: boolean): void;
+    /** 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. */
+    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;
     /** Send a typed message; returns its `client_event_id`. Typed before a session exists, it is sent once one does. */
@@ -306,6 +327,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. */
@@ -323,6 +350,15 @@ declare class ConversationStore {
     private reconnectIfDown;
     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
+     * message it followed (by key; the transcript keeps the live keys), so a pending proposal stays where it was, and a
+     * card the transcript dropped stays drawn there; taking no tap when it belongs to an earlier session.
+     */
+    private anchorCards;
     /**
      * Recomputes now (getSnapshot and getStreaming are always current) and notifies from the scheduler, at most once
      * per frame, both channels in the same flush: a streamed reply that completes becomes its message in one frame.

package/dist/conversation/index.js

@@ -156,10 +156,13 @@ function buildTimeline(input, previous) {
         busy: input.busy.has(card.id),
         ...input.decisionErrors?.has(card.id) ? { decisionError: true } : {}
       },
-      order: card.seq
+      order: input.cardOrder?.get(card.id) ?? card.seq
     });
   }
   for (const { item, order } of input.system) live.push({ item, order });
+  const held = new Set(state.cards.map((c) => c.id));
+  for (const { item, order } of input.kept ?? [])
+    if (!held.has(item.key)) live.push({ item, order });
   for (const [id, sent] of input.sent) {
     const pending = pendingState(id, input);
     if (pending === null) continue;
@@ -233,6 +236,7 @@ function persistable(item) {
 
 // src/conversation/store.ts
 var MAX_TEXT = 2e3;
+var TURN_INPUTS = 50;
 var PERSIST_DELAY = 500;
 var PERSIST_VERSION = 1;
 var NO_ITEMS = [];
@@ -263,12 +267,18 @@ var ConversationStore = class {
   /** Proposals whose tenant decision threw: shown as recoverable, the person may decide again. */
   decisionErrors = /* @__PURE__ */ new Set();
   system = [];
+  /** The person's text that started each recent turn, by `turn_id` (`turn.started` echoes its `client_event_id`). */
+  turnInputs = /* @__PURE__ */ new Map();
   /** Numbers system rows that carry no id of their own. */
   systemSeq = 0;
   history = NO_ITEMS;
   historyState = "none";
   /** A resumed session.ready carried a transcript: the server's history replaced what the device kept. */
   transcriptSeen = false;
+  /** The session of the last session.ready: a card of another one takes no tap (§6). */
+  readySession = null;
+  cardOrder = /* @__PURE__ */ new Map();
+  kept = [];
   locale;
   /** The request for a session in flight, to abort when it is no longer wanted. */
   fetching = null;
@@ -350,9 +360,49 @@ var ConversationStore = class {
   /** The app came to the foreground or went to the background (AppState, `visibilitychange`). */
   setForeground(foreground) {
     this.foreground = foreground;
+    if (this.options.closeInBackground && !this.disposed) {
+      if (!foreground) {
+        this.suspend();
+        return;
+      }
+      if (this.suspended) {
+        void this.wake();
+        return;
+      }
+    }
     this.session?.setForeground(foreground);
     if (foreground) this.reconnectIfDown();
   }
+  /** In the background (`closeInBackground`): the connection is closed; the engine keeps what was sent, to resend. */
+  suspended = false;
+  suspend() {
+    const session = this.session;
+    if (!session || this.suspended || session.status === "ended") return;
+    this.suspended = true;
+    for (const off of this.unsubscribe) off();
+    this.unsubscribe = [];
+    session.close();
+    this.update();
+  }
+  /** Back in the foreground: a new connection to the same session, with a fresh secret when the backend gives one. */
+  async wake() {
+    const info = this.info;
+    this.suspended = false;
+    if (!info) return;
+    let next = info;
+    if (this.options.refreshSecret) {
+      try {
+        next = {
+          ...info,
+          client_secret: await this.options.refreshSecret(info.id)
+        };
+      } catch (error) {
+        this.options.onError?.(error);
+      }
+    }
+    if (this.disposed || this.suspended) return;
+    this.open(next);
+  }
   /** The network as the app sees it; null when unknown. Back online reconnects a connection that gave up. */
   setOnline(online) {
     this.online = online;
@@ -374,6 +424,12 @@ var ConversationStore = class {
       this.update();
       return id;
     }
+    if (this.suspended) {
+      this.early.set(id, text);
+      void this.wake();
+      this.update();
+      return id;
+    }
     if (this.nextFrom(this.engine.state()) === "continue_here") {
       this.early.set(id, text);
       void this.resumeWith("continue_here");
@@ -442,6 +498,24 @@ var ConversationStore = class {
     this.sent.delete(key);
     return this.send(sent.text);
   }
+  /**
+   * 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) {
+    const at = this.system.findIndex(
+      (s) => s.item.key === key && s.item.event === "turn_failed"
+    );
+    const entry = this.system[at];
+    if (entry?.item.data.retry !== true) return null;
+    const text = this.turnText(String(entry.item.data.turn ?? ""));
+    if (text === void 0) return null;
+    this.system = this.system.map(
+      (s, i) => i === at ? { ...s, item: { ...s.item, data: { ...s.item.data, retry: false } } } : s
+    );
+    return this.send(text);
+  }
   /** After the conversation continued on another device: continue it here (the person's choice). */
   continueHere() {
     return this.resumeWith("continue_here");
@@ -575,10 +649,16 @@ var ConversationStore = class {
       ];
     };
     switch (frame.type) {
-      case "session.ready":
-        if (frame.resumed === true && Array.isArray(frame.transcript))
+      case "session.ready": {
+        const session = frame.session?.id;
+        const moved = typeof session === "string" && session !== this.readySession;
+        if (typeof session === "string") this.readySession = session;
+        if (frame.resumed === true && Array.isArray(frame.transcript)) {
           this.transcriptSeen = true;
+          this.anchorCards(moved);
+        }
         return;
+      }
       // `at` is required (v1-draft.15); the same takeover announced again after a reconnect has the same `at`, so it
       // draws one row. A frame without one still gets a row of its own.
       case "takeover.started":
@@ -608,6 +688,17 @@ var ConversationStore = class {
           code: str(frame.code)
         });
         return;
+      case "turn.started": {
+        const turn = str(frame.turn_id);
+        const input = str(frame.client_event_id);
+        if (turn === null || input === null) return;
+        this.turnInputs.set(turn, input);
+        if (this.turnInputs.size > TURN_INPUTS) {
+          const oldest = this.turnInputs.keys().next().value;
+          if (oldest !== void 0) this.turnInputs.delete(oldest);
+        }
+        return;
+      }
       case "turn.failed": {
         const turn = str(frame.turn_id) ?? "";
         if (this.engine.state().messages.some((m) => m.key === `a:${turn}`))
@@ -616,7 +707,9 @@ var ConversationStore = class {
         add(`failed:${turn}`, "turn_failed", {
           code: str(frame.code),
           message: str(frame.message),
-          retryable: frame.retryable === true
+          retryable: frame.retryable === true,
+          retry: frame.retryable === true && this.turnText(turn) !== void 0,
+          turn
         });
         return;
       }
@@ -624,6 +717,45 @@ var ConversationStore = class {
         return;
     }
   }
+  /** The person's text that started a turn, while its message is on screen. */
+  turnText(turn) {
+    const input = this.turnInputs.get(turn);
+    if (input === void 0) return void 0;
+    const message = this.engine.state().messages.find((m) => m.key === input && m.role === "person");
+    return message?.text || void 0;
+  }
+  /**
+   * 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
+   * message it followed (by key; the transcript keeps the live keys), so a pending proposal stays where it was, and a
+   * card the transcript dropped stays drawn there; taking no tap when it belongs to an earlier session.
+   */
+  anchorCards(sessionChanged) {
+    const state = this.engine.state();
+    const seqOf = new Map(state.messages.map((m) => [m.key, m.seq]));
+    const first = Math.min(...state.messages.map((m) => m.seq), 0);
+    const held = new Set(state.cards.map((c) => c.id));
+    const order = /* @__PURE__ */ new Map();
+    const kept = [];
+    let anchor = first - 1;
+    let step = 0;
+    for (const item of this.view.items) {
+      if (item.type === "message" && seqOf.has(item.key)) {
+        anchor = seqOf.get(item.key);
+        step = 0;
+      } else if (item.type === "card") {
+        const at = anchor + 0.5 + ++step / 1e3;
+        order.set(item.key, at);
+        if (!held.has(item.key))
+          kept.push({
+            item: sessionChanged ? { ...item, busy: false, restored: true } : item,
+            order: at
+          });
+      }
+    }
+    this.cardOrder = order;
+    this.kept = kept;
+  }
   // ------------------------------------------------------------ the view
   /**
    * Recomputes now (getSnapshot and getStreaming are always current) and notifies from the scheduler, at most once
@@ -680,6 +812,8 @@ var ConversationStore = class {
         busy: this.busy,
         decisionErrors: this.decisionErrors,
         transcriptSeen: this.transcriptSeen,
+        cardOrder: this.cardOrder,
+        kept: this.kept,
         system: this.system
       },
       prev?.items ?? NO_ITEMS
@@ -691,6 +825,7 @@ var ConversationStore = class {
     const avatarUrl = this.info?.agent?.avatar_url ?? null;
     const view = {
       status,
+      conversationId: s.conversationId,
       banner: banner(status, next),
       next,
       agent: sameAgent(prev?.agent, name, avatarUrl) ? prev.agent : { name, avatarUrl },
@@ -709,6 +844,7 @@ var ConversationStore = class {
   }
   status() {
     if (this.disposed) return "closed";
+    if (this.suspended) return "idle";
     const session = this.session;
     if (!session) {
       if (this.failed) return "unavailable";