@vinaverse/client 0.1.0-alpha.11 → 0.1.0-alpha.13

package/README.md

@@ -183,7 +183,9 @@ against the session it was given in; a reply restored from the device or a resum
 `{ screen: 'other' }`, no entity); revisions only grow across a conversation's sessions (`placeRevision` on the
 session request), a `context_conflict` (409, with `current_revision`) sends the newest place once more above it, only while the session
 and the person are the same, then says `moved`,
-and a telling lands only on the session it was told to. `onEvent` also says `message_sent`, `reply_completed` and
+and a telling lands only on the session it was told to. One update is in flight per conversation: a place told meanwhile
+(`show` and `tell` in one move, rapid moves) waits, only the newest, and goes next; a refusal that is no conflict is said
+through `onWarning` (`context_refused`) in development builds. `onEvent` also says `message_sent`, `reply_completed` and
 `card_shown` (never the words), its `key` is a salted SHA-256 hash of the conversation's key (`hashKey`), never the person's id: stable per install
 (the salt is kept at `<persistenceKey>:salt` in your storage, a new one after `erase()`), and
 `session_opened` says where the chat was opened from (`entryPoint`: `launcher`, `ask`, `deep_link`, or your own).

package/dist/agent/index.cjs

@@ -19,7 +19,8 @@ var CARD_KINDS = {
   question: true,
   proposal: true,
   next_step: true,
-  links: true
+  links: true,
+  anchor: true
 };
 function isKnownCard(card) {
   return Object.hasOwn(CARD_KINDS, card.kind);
@@ -129,6 +130,11 @@ var RECONNECTABLE = /* @__PURE__ */ new Set(["server_restart"]);
 var NEW_SESSION = /* @__PURE__ */ new Set(["idle", "expired", "limit_reached"]);
 var str = (v) => typeof v === "string" ? v : void 0;
 var ConversationEngine = class {
+  /** `now`: the clock a message is stamped by when the server gives no time. */
+  constructor(now = Date.now) {
+    this.now = now;
+  }
+  now;
   sessionId = null;
   conversationId = null;
   connection = null;
@@ -317,7 +323,14 @@ var ConversationEngine = class {
       case "message.staff": {
         const id = str(event.message_id);
         if (id !== void 0)
-          this.say("staff", str(event.text) ?? "", `s:${id}`);
+          this.say(
+            "staff",
+            str(event.text) ?? "",
+            `s:${id}`,
+            {},
+            void 0,
+            str(event.at)
+          );
         return;
       }
       case "input.received": {
@@ -399,7 +412,9 @@ var ConversationEngine = class {
             role,
             str(item.text) ?? "",
             transcriptKey(role, str(item.id), str(item.at)),
-            item.interrupted === true ? { partial: "interrupted" } : {}
+            item.interrupted === true ? { partial: "interrupted" } : {},
+            void 0,
+            str(item.at)
           );
         }
       }
@@ -444,7 +459,8 @@ var ConversationEngine = class {
             text2,
             key,
             partial ? { partial } : {},
-            at
+            at,
+            str(item.at)
           );
         else
           this.messages = this.messages.map((m) => {
@@ -572,9 +588,16 @@ var ConversationEngine = class {
     this.unqueue(id);
   }
   /** Adds a message once: a key already held (a frame seen twice) changes nothing. */
-  say(role, text2, key, extra = {}, seq) {
+  say(role, text2, key, extra = {}, seq, at) {
     if (this.messages.some((m) => m.key === key)) return;
-    this.messages.push({ role, text: text2, key, seq: seq ?? this.seq++, ...extra });
+    this.messages.push({
+      role,
+      text: text2,
+      key,
+      seq: seq ?? this.seq++,
+      ...extra,
+      at: at || new Date(this.now()).toISOString()
+    });
   }
   /** The turn's streamed text, kept as the agent's message when the turn ends without its `message.completed`. */
   cutOff(partial) {
@@ -1547,6 +1570,7 @@ function buildTimeline(input, previous) {
         role: "person",
         text: sent.text,
         state: pending,
+        at: sent.at,
         ...pending === "not_sent" ? {
           rejection: rejection ?? {
             code: state.refused[id] ?? "",
@@ -1598,7 +1622,8 @@ function messageItem(m) {
     text: m.text,
     state: m.received ? "delivered" : "sent",
     ...m.partial ? { partial: m.partial } : {},
-    ...m.refusal ? { refusal: true } : {}
+    ...m.refusal ? { refusal: true } : {},
+    at: m.at
   };
 }
 function equal(a, b) {
@@ -1632,7 +1657,9 @@ var OUTCOMES2 = /* @__PURE__ */ new Set([
 ]);
 var ConversationStore = class {
   options;
-  engine = new ConversationEngine();
+  engine = new ConversationEngine(
+    () => this.options.clock?.now() ?? Date.now()
+  );
   session = null;
   info = null;
   getting = null;
@@ -1815,7 +1842,11 @@ var ConversationStore = class {
     if ([...text2].length > MAX_TEXT)
       throw new RangeError(`A message is at most ${MAX_TEXT} characters.`);
     const id = (this.options.createId ?? randomId)();
-    this.sent.set(id, { text: text2, order: lastOrder(this.engine.state()) + 0.5 });
+    this.sent.set(id, {
+      text: text2,
+      order: lastOrder(this.engine.state()) + 0.5,
+      at: new Date(this.options.clock?.now() ?? Date.now()).toISOString()
+    });
     this.tellActivity({ type: "message_sent", id });
     if (!this.session) {
       this.early.set(id, text2);
@@ -2456,6 +2487,65 @@ function shallowEqual(a, b) {
 }
 
 // src/agent/runtime.ts
+var ANCHOR_TYPES = /* @__PURE__ */ new Set([
+  "booking",
+  "rental",
+  "professional",
+  "workspace",
+  "service",
+  "class",
+  "policy"
+]);
+function anchorRef(type, id) {
+  return ANCHOR_TYPES.has(type) && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(id) ? { type, id } : null;
+}
+var JOINS = [
+  768,
+  879,
+  6832,
+  6911,
+  7616,
+  7679,
+  8400,
+  8447,
+  65056,
+  65071,
+  8205,
+  8205,
+  65038,
+  65039,
+  127995,
+  127999
+];
+var joins = (point) => {
+  const c = point?.codePointAt(0) ?? -1;
+  for (let i = 0; i < JOINS.length; i += 2)
+    if (c >= JOINS[i] && c <= JOINS[i + 1]) return true;
+  return false;
+};
+function entryLabel(label) {
+  let out = "";
+  let size = 0;
+  const points = Array.from(label.trim());
+  for (let i = 0; i < points.length; ) {
+    let end = i + 1;
+    while (end < points.length && (joins(points[end]) || points[end - 1] === "\u200D"))
+      end++;
+    if (size + end - i > 60) break;
+    out += points.slice(i, end).join("");
+    size += end - i;
+    i = end;
+  }
+  return out || void 0;
+}
+function askAboutKey(key, place) {
+  return { ...key, thread: `ask:${place.entity.type}:${place.entity.id}` };
+}
+function entryOf(entry) {
+  if (!/^[a-z][a-z0-9_]{0,31}$/.test(entry.point)) return null;
+  const label = entry.label === void 0 ? void 0 : entryLabel(entry.label);
+  return label ? { point: entry.point, label } : { point: entry.point };
+}
 var AgentRefusal = class extends Error {
   constructor(kind, options = {}) {
     super(
@@ -2590,6 +2680,7 @@ var samePlace = (a, b) => a?.screen === b?.screen && (a?.entity?.type ?? null) =
 function usable(session, insecure) {
   return typeof session.id === "string" && session.id !== "" && (insecure.realtime === true || /^wss:\/\//i.test(session.realtime_url ?? "")) && (insecure.turns === true || /^https:\/\//i.test(session.turns_url ?? "")) && Boolean(session.client_secret);
 }
+var devBuild = () => globalThis.__DEV__ === true;
 function warnInsecure(insecure, warn) {
   if (!(insecure.realtime || insecure.turns)) return;
   if (globalThis.__DEV__ === true) return;
@@ -2608,6 +2699,7 @@ function createAgentRuntime(options) {
   };
   const clock = options.clock ?? SYSTEM_CLOCK;
   const keepAlive = options.keepAlive ?? "session";
+  const graceMs = options.graceMs ?? 6e4;
   const staleMs = options.statusStaleMs ?? 5 * 6e4;
   const insecure = options.insecureAddresses ?? {};
   warnInsecure(insecure, options.onWarning ?? ((m) => console.warn(m)));
@@ -2627,6 +2719,7 @@ function createAgentRuntime(options) {
     changed();
   };
   let sessionName = null;
+  const names = /* @__PURE__ */ new Map();
   let generation = 0;
   const keyOf = (key) => agentKey(key, options.agent ?? null);
   const prefix = options.conversation?.persistenceKey ?? "vinaverse.agent";
@@ -2709,6 +2802,7 @@ function createAgentRuntime(options) {
     if (!entry) return;
     live.delete(k);
     clearTimeout(entry.timer);
+    clearTimeout(entry.grace);
     entry.store.dispose();
     emit({ type: "conversation_ended", key: k });
     changed();
@@ -2734,7 +2828,9 @@ function createAgentRuntime(options) {
       agent: options.agent ?? null,
       place: entry.place,
       placeRevision: ++entry.revision,
-      entryPoint: entry.entryPoint
+      entryPoint: entry.entryPoint,
+      ...options.sendAnchor && entry.anchor ? { anchor: entry.anchor } : {},
+      ...options.sendAnchor && entry.via ? { entry: entry.via } : {}
     };
     const { conversationId, openId, place: told } = asked;
     let session;
@@ -2761,6 +2857,7 @@ function createAgentRuntime(options) {
         const unsettled = reason === "unknown_open" ? String(field(error, "openId") ?? openId) : null;
         update(entry, { failure, reason, code, openId: unsettled });
         emit({ type: "session_failed", key: entry.key, failure, reason });
+        if (entry.shown === 0) end(entry.key);
       }
       throw error;
     }
@@ -2770,8 +2867,9 @@ function createAgentRuntime(options) {
     if (session.conversation_id)
       current.set(entry.key, session.conversation_id);
     const name = session.agent?.display_name?.trim();
-    if (name && name !== sessionName) {
+    if (name && (name !== sessionName || names.get(key.mode) !== name)) {
       sessionName = name;
+      names.set(key.mode, name);
       changed();
     }
     update(entry, {
@@ -2789,6 +2887,14 @@ function createAgentRuntime(options) {
       sessionId: session.id,
       ...entry.entryPoint ? { from: entry.entryPoint } : {}
     });
+    if (entry.shown === 0) {
+      if (entry.expiresAt === null || over(entry)) {
+        end(entry.key);
+        return session;
+      }
+      expireLater(entry);
+    }
+    if (!samePlace(told, entry.place)) tell(entry, {});
     return session;
   }
   const kept = (k) => `${prefix}.${k}`;
@@ -2803,6 +2909,7 @@ function createAgentRuntime(options) {
     live.clear();
     current.clear();
     sessionName = null;
+    names.clear();
     status = null;
     reading = null;
     statusState = NO_STATUS;
@@ -2908,18 +3015,31 @@ function createAgentRuntime(options) {
       place: null,
       told: null,
       revision: 0,
+      telling: false,
+      queued: false,
       entryPoint: null,
+      anchor: null,
+      via: null,
       expiresAt: null,
       shown: 0,
       started: false,
       suspended: false,
       sentOnce: /* @__PURE__ */ new Set(),
       timer: void 0,
+      grace: void 0,
       turns: /* @__PURE__ */ new Map(),
       failedOpen: void 0
     };
     return entry;
   }
+  const suspend = (entry) => {
+    clearTimeout(entry.grace);
+    entry.grace = void 0;
+    if (entry.shown > 0 || entry.suspended || live.get(entry.key) !== entry)
+      return;
+    entry.suspended = true;
+    entry.store.setForeground(false);
+  };
   const over = (entry) => entry.expiresAt !== null && entry.expiresAt <= clock.now();
   const expireLater = (entry) => {
     clearTimeout(entry.timer);
@@ -2937,31 +3057,63 @@ function createAgentRuntime(options) {
   const tell = (entry, at) => {
     if (at.place !== void 0) entry.place = at.place;
     if (at.entryPoint !== void 0) entry.entryPoint = at.entryPoint;
+    if (at.anchor !== void 0)
+      entry.anchor = at.anchor && anchorRef(at.anchor.type, at.anchor.id);
+    if (at.entry !== void 0) entry.via = at.entry && entryOf(at.entry);
     const sessionId = entry.state.sessionId;
     const moved = sessionId !== null && !samePlace(entry.told, entry.place);
     update(entry, { moved });
     const updateContext = backend.updateContext?.bind(backend);
     if (!moved || !updateContext || sessionId === null) return;
+    if (entry.telling) {
+      entry.queued = true;
+      return;
+    }
+    entry.telling = true;
     const asked = generation;
     const current2 = () => asked === generation && live.get(entry.key) === entry && entry.state.sessionId === sessionId;
+    const settle = () => {
+      entry.telling = false;
+      if (!entry.queued) return;
+      entry.queued = false;
+      if (asked === generation && live.get(entry.key) === entry)
+        tell(entry, {});
+    };
     const send = (again) => {
       const place = entry.place;
       const revision = ++entry.revision;
-      updateContext(sessionId, place ?? CLEARED, revision).then(
+      let told;
+      try {
+        told = updateContext(sessionId, place ?? CLEARED, revision);
+      } catch (error) {
+        told = Promise.reject(error);
+      }
+      told.then(
         () => {
-          if (!current2() || entry.revision !== revision) return;
-          entry.told = place;
-          update(entry, { moved: !samePlace(entry.told, entry.place) });
-          emit({ type: "context_updated", key: entry.key, sessionId });
+          if (current2() && entry.revision === revision) {
+            entry.told = place;
+            update(entry, { moved: !samePlace(entry.told, entry.place) });
+            emit({ type: "context_updated", key: entry.key, sessionId });
+          }
+          settle();
         },
         (error) => {
           const theirs = field(error, "currentRevision");
           const conflict = field(error, "outcome") === "context_conflict" || field(error, "reason") === "conflict";
-          if (!conflict || again || !current2() || entry.revision !== revision)
+          if (conflict && !again && current2() && entry.revision === revision) {
+            if (typeof theirs === "number" && theirs >= entry.revision)
+              entry.revision = theirs;
+            send(true);
             return;
-          if (typeof theirs === "number" && theirs >= entry.revision)
-            entry.revision = theirs;
-          send(true);
+          }
+          if (!conflict && devBuild()) {
+            const status2 = field(error, "status");
+            warn(
+              `@vinaverse/client/agent: updateContext was refused${typeof status2 === "number" ? ` (${status2})` : ""}: ${error instanceof Error ? error.message : String(error)}. The new place is offered as a question instead.`,
+              { code: "context_refused" }
+            );
+          }
+          settle();
         }
       );
     };
@@ -2980,6 +3132,8 @@ function createAgentRuntime(options) {
         entry.shown++;
         clearTimeout(entry.timer);
         entry.timer = void 0;
+        clearTimeout(entry.grace);
+        entry.grace = void 0;
         if (entry.suspended) {
           entry.suspended = false;
           entry.store.setForeground(true);
@@ -2995,12 +3149,15 @@ function createAgentRuntime(options) {
           released = true;
           entry.shown--;
           if (entry.shown > 0 || live.get(entry.key) !== entry) return;
-          if (keepAlive === "view" || NOT_KEPT.has(entry.store.getSnapshot().status) || entry.expiresAt === null || over(entry)) {
+          const status2 = entry.store.getSnapshot().status;
+          const opening = status2 === "starting" && keepAlive !== "view";
+          if (!opening && (keepAlive === "view" || NOT_KEPT.has(status2) || entry.expiresAt === null || over(entry))) {
             end(entry.key);
             return;
           }
-          entry.suspended = true;
-          entry.store.setForeground(false);
+          if (graceMs > 0)
+            entry.grace = setTimeout(() => suspend(entry), graceMs);
+          else suspend(entry);
           expireLater(entry);
         };
       },
@@ -3070,6 +3227,9 @@ function createAgentRuntime(options) {
     forget(key) {
       forget(keyOf(key));
     },
+    background() {
+      for (const entry of live.values()) if (entry.grace) suspend(entry);
+    },
     sweep() {
       for (const entry of [...live.values()])
         if (entry.shown === 0 && over(entry)) end(entry.key);
@@ -3128,7 +3288,7 @@ function createAgentRuntime(options) {
     getStatusState: () => statusState,
     backend,
     epoch: () => generation,
-    getName: () => sessionName ?? status?.value.displayName ?? null,
+    getName: (mode) => (mode === void 0 ? sessionName : names.get(mode)) ?? status?.value.displayName ?? null,
     subscribe(listener) {
       listeners.add(listener);
       return () => listeners.delete(listener);
@@ -3312,7 +3472,10 @@ async function retrying(run, policy, signal, onRetry) {
 
 exports.AgentRefusal = AgentRefusal;
 exports.agentKey = agentKey;
+exports.anchorRef = anchorRef;
+exports.askAboutKey = askAboutKey;
 exports.createAgentRuntime = createAgentRuntime;
+exports.entryLabel = entryLabel;
 exports.greetedKey = greetedKey;
 exports.hashKey = hashKey;
 exports.isRefusal = isRefusal;