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

package/dist/conversation/index.cjs

@@ -2,8 +2,8 @@
 
 // src/contract.ts
 var CONTRACT = {
-  api: "v1-draft.17",
-  commit: "fe4fb7d2945e1ced2bce7d44e85a4b28005e46df"
+  api: "v1-draft.22",
+  commit: "4695e3dc042e6e0cf1936aae24fcb093eacd27c8"
 };
 
 // src/errors.ts
@@ -36,7 +36,8 @@ var CARD_KINDS = {
   document: true,
   question: true,
   proposal: true,
-  next_step: true
+  next_step: true,
+  links: true
 };
 function isKnownCard(card) {
   return Object.hasOwn(CARD_KINDS, card.kind);
@@ -416,7 +417,9 @@ var ConversationEngine = class {
     this.takeover = null;
     this.cutOff("interrupted");
     if (event.resumed !== true) return;
-    if (event.transcript !== void 0) {
+    if (event.transcript !== void 0 && transcriptHasIds(event.transcript)) {
+      this.mergeTranscript(asArray(event.transcript));
+    } else if (event.transcript !== void 0) {
       this.messages = [];
       this.replaced = this.cards;
       this.cards = /* @__PURE__ */ new Map();
@@ -438,7 +441,61 @@ var ConversationEngine = class {
       this.hold(card, str(card.turn_id));
     this.replaced = null;
   }
-  hold(raw, turnId) {
+  /**
+   * A transcript merged by key: an item the app holds keeps its place, with the text the server recorded; one it does
+   * not hold goes just after the nearest earlier item it does (just before the first later one when none came before,
+   * at the end when it holds none of them). Nothing the app holds is dropped.
+   */
+  mergeTranscript(items) {
+    const seqOf = (key) => key === void 0 ? void 0 : (this.messages.find((m) => m.key === key) ?? this.cards.get(key))?.seq;
+    const keys = items.map(
+      (item) => item.role === "card" ? str(item.card?.id) : transcriptKey(str(item.role) ?? "", str(item.id), str(item.at))
+    );
+    let prev;
+    items.forEach((item, i) => {
+      const key = keys[i];
+      if (key === void 0) return;
+      const known = seqOf(key);
+      let at;
+      if (known === void 0) {
+        const near = prev ?? keys.slice(i + 1).map(seqOf).find((q) => q !== void 0);
+        if (near !== void 0) {
+          const seqs = [...this.messages, ...this.cards.values()].map(
+            (h) => h.seq
+          );
+          const bound = prev === void 0 ? Math.max(near - 1, ...seqs.filter((q) => q < near)) : Math.min(...seqs.filter((q) => q > near));
+          if (Number.isFinite(bound)) at = (near + bound) / 2;
+        }
+      }
+      if (item.role === "card") this.hold(item.card, void 0, at);
+      else {
+        const text = str(item.text) ?? "";
+        const partial = item.interrupted === true ? "interrupted" : void 0;
+        if (known === void 0)
+          this.say(
+            str(item.role) ?? "",
+            text,
+            key,
+            partial ? { partial } : {},
+            at
+          );
+        else
+          this.messages = this.messages.map((m) => {
+            if (m.key !== key) return m;
+            const { partial: local, ...rest } = m;
+            const kept = partial ?? (local === "interrupted" ? void 0 : local);
+            return {
+              ...rest,
+              text: text || m.text,
+              ...kept ? { partial: kept } : {}
+            };
+          });
+      }
+      prev = seqOf(key);
+    });
+    this.messages.sort((a, b) => a.seq - b.seq);
+  }
+  hold(raw, turnId, at) {
     if (!raw) return;
     const id = str(raw.id);
     if (id === void 0) return;
@@ -452,7 +509,7 @@ var ConversationEngine = class {
       locked: lockedFrom(question),
       ...turnId !== void 0 ? { turnId } : {},
       // A card still held keeps its place when it is drawn again (a reconnect's pending cards, a repeated ui.cards).
-      seq: this.cards.get(id)?.seq ?? this.seq++
+      seq: this.cards.get(id)?.seq ?? at ?? this.seq++
     };
     for (const held of this.held) {
       const sent = this.inputs.get(held);
@@ -548,9 +605,9 @@ var ConversationEngine = class {
     this.unqueue(id);
   }
   /** Adds a message once: a key already held (a frame seen twice) changes nothing. */
-  say(role, text, key, extra = {}, seq = this.seq++) {
+  say(role, text, key, extra = {}, seq) {
     if (this.messages.some((m) => m.key === key)) return;
-    this.messages.push({ role, text, key, seq, ...extra });
+    this.messages.push({ role, text, key, seq: seq ?? this.seq++, ...extra });
   }
   /** The turn's streamed text, kept as the agent's message when the turn ends without its `message.completed`. */
   cutOff(partial) {
@@ -645,6 +702,11 @@ function transcriptKey(role, id, at) {
   if (role === "staff") return `s:${id}`;
   return id;
 }
+function transcriptHasIds(transcript) {
+  return asArray(transcript).every(
+    (item) => item.role === "card" ? str(item.card?.id) !== void 0 : str(item.id) !== void 0
+  );
+}
 function lockedFrom(question) {
   if (!question) return [];
   if (question.state !== "open") {
@@ -1467,13 +1529,17 @@ function buildTimeline(input, previous) {
         type: "card",
         key: card.id,
         card,
-        busy: input.busy.has(card.id),
+        busy: !input.inert?.has(card.id) && input.busy.has(card.id),
+        ...input.inert?.has(card.id) ? { restored: true } : {},
         ...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;
@@ -1496,17 +1562,10 @@ function buildTimeline(input, previous) {
     });
   }
   live.sort((a, b) => a.order - b.order);
-  const liveByKey = new Map(live.map((l) => [l.item.key, l.item]));
-  const transcript = input.transcriptSeen === true;
-  const items = [];
-  const placed = /* @__PURE__ */ new Set();
-  if (!transcript)
-    for (const item of input.history) {
-      const current = liveByKey.get(item.key);
-      items.push(current ?? item);
-      if (current) placed.add(item.key);
-    }
-  for (const { item } of live) if (!placed.has(item.key)) items.push(item);
+  const items = mergeByKey(
+    input.transcriptSeen === true ? [] : input.history,
+    live.map((l) => l.item)
+  );
   let same = items.length === previous.length;
   const shared = items.map((item, i) => {
     const prev = before.get(item.key);
@@ -1516,6 +1575,24 @@ function buildTimeline(input, previous) {
   });
   return same ? previous : shared;
 }
+function mergeByKey(history, live) {
+  if (!history.length) return [...live];
+  const items = [...history];
+  const at = (key) => items.findIndex((item) => item.key === key);
+  let last = -1;
+  live.forEach((item, i) => {
+    const found = at(item.key);
+    if (found >= 0) {
+      items[found] = item;
+      last = found;
+      return;
+    }
+    const next = live.slice(i + 1).map((l) => at(l.key)).find((p) => p >= 0);
+    last = next === void 0 ? items.length : last >= 0 ? last + 1 : next;
+    items.splice(last, 0, item);
+  });
+  return items;
+}
 function messageItem(m) {
   const role = m.role === "assistant" ? "agent" : m.role;
   return {
@@ -1547,6 +1624,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 = [];
@@ -1577,12 +1655,20 @@ 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 = [];
+  /** Cards an earlier session drew, kept by a merged transcript: drawn as restored, taking no tap. */
+  inert = /* @__PURE__ */ new Set();
   locale;
   /** The request for a session in flight, to abort when it is no longer wanted. */
   fetching = null;
@@ -1624,6 +1710,8 @@ var ConversationStore = class {
     this.live();
     if (this.session) {
       if (this.session.status === "idle") this.session.connect();
+      else if (this.session.status === "unauthorized")
+        void this.resumeWith("resume");
       return;
     }
     void this.ensureSession("open");
@@ -1664,9 +1752,59 @@ 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, 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.
+   */
+  async wake(byPerson = false) {
+    const info = this.info;
+    if (info && this.sessionOver()) {
+      if (byPerson) await this.resumeWith("resume");
+      else this.update();
+      return;
+    }
+    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;
@@ -1682,18 +1820,31 @@ var ConversationStore = class {
       throw new RangeError(`A message is at most ${MAX_TEXT} characters.`);
     const id = (this.options.createId ?? randomId)();
     this.sent.set(id, { text, order: lastOrder(this.engine.state()) + 0.5 });
+    this.tellActivity({ type: "message_sent", id });
     if (!this.session) {
       this.early.set(id, text);
       void this.ensureSession("open");
       this.update();
       return id;
     }
+    if (this.suspended) {
+      this.early.set(id, text);
+      void this.wake(true);
+      this.update();
+      return id;
+    }
     if (this.nextFrom(this.engine.state()) === "continue_here") {
       this.early.set(id, text);
       void this.resumeWith("continue_here");
       this.update();
       return id;
     }
+    if (this.sessionOver()) {
+      this.early.set(id, text);
+      void this.resumeWith("resume");
+      this.update();
+      return id;
+    }
     this.nextId = id;
     this.session.sendText(text);
     this.nextId = null;
@@ -1756,6 +1907,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");
@@ -1812,11 +1981,21 @@ var ConversationStore = class {
   }
   open(info) {
     this.info = info;
+    this.suspended = false;
+    const refreshSecret = this.options.refreshSecret;
     const session = new VinaverseSession({
       ...this.options.transport,
       session: info,
       engine: this.engine,
-      ...this.options.refreshSecret ? { refreshSecret: this.options.refreshSecret } : {},
+      ...refreshSecret ? {
+        // Past the session's end a fresh secret cannot help: refused here, and the store rolls over instead.
+        refreshSecret: (id) => this.sessionOver() ? Promise.reject(
+          new VinaverseClientError(
+            "needs_new_session",
+            "This session has ended."
+          )
+        ) : refreshSecret(id)
+      } : {},
       createId: () => this.nextId ?? (this.options.createId ?? randomId)()
     });
     this.session = session;
@@ -1824,7 +2003,9 @@ var ConversationStore = class {
       session.on("state", () => this.update()),
       session.on("status", (status) => this.statusChanged(status)),
       session.on("event", (event) => this.event(event)),
-      session.on("error", (error) => this.options.onError?.(error))
+      session.on("error", (error) => {
+        if (!this.sessionOver()) this.options.onError?.(error);
+      })
     );
     session.setForeground(this.foreground);
     session.connect();
@@ -1851,6 +2032,10 @@ var ConversationStore = class {
     this.resuming = this.fetchSession(reason).then((info) => {
       this.resuming = null;
       if (!info || this.disposed || !this.session) return;
+      if (this.session.status === "closed") {
+        this.open(info);
+        return;
+      }
       this.info = info;
       this.session.resume(info);
       this.flushEarly();
@@ -1865,19 +2050,48 @@ var ConversationStore = class {
   }
   reconnectIfDown() {
     const session = this.session;
-    if (session && session.status === "idle" && this.nextFrom(this.engine.state()) === null)
+    if (session && session.status === "idle" && !this.sessionOver() && // past its end: the person's next action gets a new session
+    this.nextFrom(this.engine.state()) === null)
       session.connect();
   }
+  /** A refusal already led to a new session, and none has been ready since: another refusal is no cue. */
+  rolled = false;
   statusChanged(status) {
+    if (status === "ready") this.rolled = false;
+    if (status === "unauthorized" && !this.rolled) {
+      this.rolled = true;
+      void this.resumeWith("resume");
+    }
     if (status === "idle")
       this.offlineAfterRetries = this.lastStatus === "reconnecting";
     else if (status !== "reconnecting") this.offlineAfterRetries = false;
     this.lastStatus = status;
     this.update();
   }
+  /** The app's analytics hears of a step; what it throws is reported (`onError`), never in the way of a send or a frame. */
+  tellActivity(activity) {
+    try {
+      this.options.onActivity?.(activity);
+    } catch (error) {
+      this.options.onError?.(error);
+    }
+  }
+  /** The live frames analytics hears of: a reply finished, cards drawn. */
+  activity(frame) {
+    if (!this.options.onActivity) return;
+    const on = (a) => this.tellActivity(a);
+    if (frame.type === "message.completed" && typeof frame.turn_id === "string")
+      on({ type: "reply_completed", turnId: frame.turn_id });
+    if (frame.type === "ui.cards" && Array.isArray(frame.cards)) {
+      for (const card of frame.cards)
+        if (typeof card.id === "string" && typeof card.kind === "string")
+          on({ type: "card_shown", cardId: card.id, kind: card.kind });
+    }
+  }
   event(event) {
     const frame = event;
     const str2 = (v) => typeof v === "string" ? v : null;
+    this.activity(frame);
     const add = (key, kind, data) => {
       if (this.system.some((s) => s.item.key === key)) return;
       this.system = [
@@ -1889,10 +2103,25 @@ 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) && !transcriptHasIds(frame.transcript)) {
           this.transcriptSeen = true;
+          this.anchorCards(moved);
+        } else if (moved && frame.resumed === true) {
+          const pending = new Set(
+            (Array.isArray(frame.pending_cards) ? frame.pending_cards : []).map(
+              (c) => str2(c.id)
+            )
+          );
+          for (const card of this.engine.state().cards)
+            if (pending.has(card.id)) this.inert.delete(card.id);
+            else this.inert.add(card.id);
+        }
         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":
@@ -1922,6 +2151,17 @@ var ConversationStore = class {
           code: str2(frame.code)
         });
         return;
+      case "turn.started": {
+        const turn = str2(frame.turn_id);
+        const input = str2(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 = str2(frame.turn_id) ?? "";
         if (this.engine.state().messages.some((m) => m.key === `a:${turn}`))
@@ -1930,7 +2170,9 @@ var ConversationStore = class {
         add(`failed:${turn}`, "turn_failed", {
           code: str2(frame.code),
           message: str2(frame.message),
-          retryable: frame.retryable === true
+          retryable: frame.retryable === true,
+          retry: frame.retryable === true && this.turnText(turn) !== void 0,
+          turn
         });
         return;
       }
@@ -1938,6 +2180,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
@@ -1994,6 +2275,9 @@ var ConversationStore = class {
         busy: this.busy,
         decisionErrors: this.decisionErrors,
         transcriptSeen: this.transcriptSeen,
+        cardOrder: this.cardOrder,
+        kept: this.kept,
+        inert: this.inert,
         system: this.system
       },
       prev?.items ?? NO_ITEMS
@@ -2005,10 +2289,12 @@ 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 },
       disclosure: s.disclosure ?? this.info?.disclosure ?? null,
+      welcome: this.info?.welcome ?? null,
       takeover: s.takeover,
       items,
       activity: prev && sameTools(prev.activity, activity) ? prev.activity : activity,
@@ -2023,6 +2309,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";
@@ -2114,6 +2401,11 @@ var ConversationStore = class {
     }, PERSIST_DELAY);
   }
   // ------------------------------------------------------------ guards
+  /** Past the session's end (`expires_at`), when the backend passed it on. */
+  sessionOver() {
+    const end = this.info?.expires_at;
+    return end !== void 0 && (this.options.clock?.now() ?? Date.now()) >= Date.parse(end);
+  }
   live() {
     if (this.disposed)
       throw new VinaverseClientError(
@@ -2167,6 +2459,42 @@ function shallowEqual(a, b) {
   return a.status === b.status && a.banner === b.banner && a.next === b.next && a.agent.name === b.agent.name && a.agent.avatarUrl === b.agent.avatarUrl && a.disclosure === b.disclosure && a.takeover?.by === b.takeover?.by && a.takeover?.at === b.takeover?.at && a.takeover === null === (b.takeover === null) && a.items === b.items && a.activity === b.activity && a.responding === b.responding && a.openQuestion === b.openQuestion && a.answersNeedWebSocket === b.answersNeedWebSocket && a.turnsLeft === b.turnsLeft && a.history === b.history;
 }
 
+// src/conversation/modes.ts
+function createConversationsByMode(options) {
+  const { getSession, modes = [], ...shared } = options;
+  const base = shared.persistenceKey ?? "vinaverse.conversation";
+  const stores = /* @__PURE__ */ new Map();
+  const get = (mode) => {
+    let store = stores.get(mode);
+    if (!store) {
+      store = createConversation({
+        ...shared,
+        persistenceKey: `${base}.${mode}`,
+        getSession: (request) => getSession({ ...request, mode })
+      });
+      stores.set(mode, store);
+    }
+    return store;
+  };
+  return {
+    get,
+    select(mode) {
+      for (const [other, store] of stores)
+        if (other !== mode) store.setForeground(false);
+      return get(mode);
+    },
+    dispose() {
+      for (const store of stores.values()) store.dispose();
+      stores.clear();
+    },
+    clear() {
+      for (const mode of /* @__PURE__ */ new Set([...stores.keys(), ...modes]))
+        get(mode).clear();
+      stores.clear();
+    }
+  };
+}
+
 exports.CONTRACT = CONTRACT;
 exports.ConversationStore = ConversationStore;
 exports.MAX_TEXT = MAX_TEXT;
@@ -2174,6 +2502,7 @@ exports.VinaverseClientError = VinaverseClientError;
 exports.answerProblem = answerProblem;
 exports.codePoints = codePoints;
 exports.createConversation = createConversation;
+exports.createConversationsByMode = createConversationsByMode;
 exports.isAllowedLink = isAllowedLink;
 exports.isKnownCard = isKnownCard;
 exports.isValidLinkPrefix = isValidLinkPrefix;