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

package/README.md

@@ -139,7 +139,8 @@ app comes back to the foreground).
 **Your backend, in two lines** (`@vinaverse/client/backend`): `backendFromFetch({ routes, headers })` is an
 `AgentBackend` over your own routes, sending the person's credentials from `headers`, never in a body.
 `backendRoutes(base)` gives the routes the .NET SDK's `MapVinaverseAgentSessions` serves by default (`session`,
-`refresh`, `status`, `feedback`, `end`, `context`, `delete`); give your own where they differ. Both sides speak
+`refresh`, `status`, `feedback`, `end`, `context`, `delete`, and history's `list` and `read`, answered
+`{ version: 1, page }` as the gateway wrote the page); give your own where they differ. Both sides speak
 `vinaverse.agent-backend/1` (vinaverse-contracts `docs/agent-backend.md`, tested here against its fixture): successes
 wrapped with the version (`{ version: 1, session }`, `{ version: 1, client_secret: { value, expires_at } }`,
 `{ version: 1, status }`, or 204), and one failure body for every route. Every session creation (a first open, a
@@ -182,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).
@@ -192,8 +195,23 @@ For a mock mode and tests, `@vinaverse/client/testing` has a scripted agent:
 `createMockAgent({ script, reply, refuse, welcome })` gives an `AgentBackend` and a WebSocket factory that speaks the
 protocol (`conversation.transport.webSocket`). `script` is the replies in order, one per turn, each with its text, its
 cards or a failure; `reply` answers after it. `mockCards` gives the cards your tools would: `professional`,
-`workspace`, `timeSlots`, `proposal` (pending, confirmed in your app) and `links`. Scripted history comes with the
-runtime's history.
+`workspace`, `timeSlots`, `proposal` (pending, confirmed in your app) and `links`. `history` scripts past
+conversations (`{ id, title, state, items: [{ role, text, refusal? }, { card, proposal_outcome? }] }`): listed, read
+back, continued with their messages, deleted (then `not_found`); a conversation begun in the mock is listed too once
+something was said.
+
+**History** (`@vinaverse/client/history`, an entry of its own): `createAgentHistory({ runtime, mode, scope, agent,
+pageSize })` is the person's past conversations, newest activity first, a page at a time (`refresh`, `loadMore`, and
+`retry` for the page that failed, the first or the next; `failure` says `off` when your backend serves no
+`listConversations`; a cursor the gateway no longer takes, refused `unavailable` with its `invalid_request`, starts the
+list over once, and any other refusal is said); `remove(key, id)` deletes through `runtime.deleteConversation` and drops
+the row, one already gone too. `createAgentTranscript({ runtime, conversationId })` reads one back, the newest page
+first and earlier pages prepended (`load`, `loadEarlier`, `retry`; a stale cursor reads back from the newest page
+once), its items as the kits draw them (`historyItems`: messages
+as sent, a cut-off reply and a guardrail's refusal kept, cards restored and inert, a proposal with the outcome it
+had). `continueKey(conversation, subject)` is the key it continues under (its side and business as bound when it
+started), for `runtime.continue` and `deleteConversation`. Nothing begun before a sign-out lands after it
+(`runtime.epoch()`), nor a page from before a newer read.
 
 The contract's types are exported too (`paths`, `components`, `operations`, `Schemas`): import them instead of copying
 the spec. Design: [docs/architecture/agent-runtime.md](../../docs/architecture/agent-runtime.md).

package/dist/agent/index.cjs

@@ -2590,6 +2590,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;
@@ -2908,6 +2909,8 @@ function createAgentRuntime(options) {
       place: null,
       told: null,
       revision: 0,
+      telling: false,
+      queued: false,
       entryPoint: null,
       expiresAt: null,
       shown: 0,
@@ -2942,26 +2945,55 @@ function createAgentRuntime(options) {
     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();
         }
       );
     };
@@ -3126,6 +3158,8 @@ function createAgentRuntime(options) {
     },
     getStatus: () => status?.value ?? null,
     getStatusState: () => statusState,
+    backend,
+    epoch: () => generation,
     getName: () => sessionName ?? status?.value.displayName ?? null,
     subscribe(listener) {
       listeners.add(listener);