@vinaverse/client 0.1.0-alpha.5 → 0.1.0-alpha.7

package/README.md

@@ -9,7 +9,10 @@ dependencies.
 npm install @vinaverse/client@alpha
 ```
 
-Alphas are published under the `alpha` tag.
+Alphas are published under the `alpha` tag. Upgrading from an earlier alpha: [MIGRATION.md](https://github.com/vinaverse-ai/vinaverse-js/blob/develop/MIGRATION.md)
+lists every change against the alpha before and what your app does (often nothing); each package's changes are in its
+changelog ([client](https://github.com/vinaverse-ai/vinaverse-js/blob/develop/packages/client/CHANGELOG.md), [react](https://github.com/vinaverse-ai/vinaverse-js/blob/develop/packages/react/CHANGELOG.md), [react-native](https://github.com/vinaverse-ai/vinaverse-js/blob/develop/packages/react-native/CHANGELOG.md),
+[server](https://github.com/vinaverse-ai/vinaverse-js/blob/develop/packages/server/CHANGELOG.md), [tokens](https://github.com/vinaverse-ai/vinaverse-js/blob/develop/packages/tokens/CHANGELOG.md)).
 
 ## Use
 
@@ -125,13 +128,70 @@ History's "Continue" is `continue(key, conversationId)`: the key goes on with th
 is said as `ended` (your backend throws `AgentRefusal('ended', { code })` on a 404 or 410). A session must have an id
 and a secret, and `wss://` and `https://` addresses whatever transport you supply (a wrapper adding headers or logging
 still gets only secure ones). `insecureAddresses: { realtime, turns }` allows plaintext for one leg: dangerous, for mocks
-and local development only, and the runtime warns outside `__DEV__`.
+and local development only, and the runtime warns outside `__DEV__` (through `onWarning`, your logger, else `console.warn`).
 A UI binding reads the key's conversation with `peek(key)`, which ends nothing (a render must not): one past its
-session's end is ended when it is next shown, and `subscribe` then tells the binding to read the next one.
-
-For a mock mode and tests, `@vinaverse/client/testing` has a scripted agent: `createMockAgent({ reply, refuse, welcome })`
-gives an `AgentBackend` and a WebSocket factory that speaks the protocol (`conversation.transport.webSocket`), and
-`mockCards` the cards your tools would.
+session's end is ended when it is next shown, and `subscribe` then tells the binding to read the next one. One no view
+shows ends at its session's end while the app's timers run, and on `sweep()` (the React Native parts call it when the
+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
+`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
+resume, continue-here, a rollover) carries a new `open_id`, the gateway's idempotency key; a creation that could not
+reach your backend is asked again unchanged, under the same `open_id`, by the runtime's tries and the person's "try
+again" alike, for 24 hours, so a lost answer never opens two sessions.
+
+Failures, yours or the adapter's, are read by `decodeBackendFailure(status, body, headers)` without matching strings:
+`{ version: 1, outcome, retryable, retry_after?, open_id?, current_revision?, code? }` at its outcome's status, one
+meaning per outcome with the contract's client action (`OUTCOMES`): `conversation_not_found`, `_expired`, `_mismatch`
+and `_completed` end the conversation (`not_found`, `expired`, `mismatch`, `completed`); `session_closed` on a refresh
+rolls over to a new session of the same conversation; `feature_off`, `unauthorized` and `forbidden_ownership` refuse
+(`off`, `auth`, `forbidden`); `rate_limited` is waited out, `retry_after` apart, at most 60 s; `unavailable` is retried
+when `retryable`; `unknown_open` (the backend could not tell whether the session opened) is final, said as unavailable,
+its `open_id` kept on the conversation's state (`openId`) for support; `context_conflict` (with `current_revision`)
+resends the newest place once. `code` is the gateway's code it was translated from (`gatewayCode` on the error).
+Anything else, another version, another status, a proxy page, a 2xx that is not the operation's success, is read by
+its status alone (401 auth; 429, 408 and 5xx retried; anything else, a 404 or 410 too, unavailable, never "ended");
+what `fetch` threw is a network failure, retried.
+
+**Keys, forgetting, signing out, erasing.** Keys are encoded so no person, mode or business can pass for another (a
+guest is `null`, never a subject named "guest"), and `agent` (the agent's id) is part of each, so two agents sharing a
+device's storage never share a conversation. `dispose(key)` closes a conversation and keeps what continues it;
+`forget(key)` also drops the conversation it continued and the transcript the device kept.
+`deleteConversation(key, conversationId)` is history's delete: your backend deletes it (`AgentBackend.deleteConversation`),
+then the device forgets it only where the key still continues that conversation (`conversationId` on its state). `signOut()` ends the sessions at your
+backend while it removes everything the runtime ever kept under `conversation.persistenceKey`: its durable index finds
+what an earlier process wrote and the alpha.5 and alpha.6 names of those conversations go too. Removal of keys no index
+lists (an earlier version's, a write lost with its process) is guaranteed only with a storage that can list
+(`keys(prefix)`: AsyncStorage's or MMKV's `getAllKeys()` filtered by the prefix) or clear (`removePrefix(prefix)`); without
+either, the index, the shapes derived from it, and the `legacyKeys` you pass (what your earlier code wrote) go. It clears the status and the name,
+and a write, a read or a status from before it lands nowhere. The launcher's greeting record outlives a sign-out on
+purpose (no greeting again after signing back in), under `vinaverse.greeted.` (outside the transcripts' prefix); give
+the runtime `greetingStorage` and `erase()` removes it too, with the analytics salt, for the person's erasure
+(`forgetGreeting` is the low-level helper for one person and modes in a storage of your own). A thumbs rates a reply
+against the session it was given in; a reply restored from the device or a resumed transcript cannot be rated
+(`canRate(turnId)` is false, and `AgentChat` draws no thumbs for it).
+
+**Places and steps.** `tell({ place })` with `undefined` keeps the place, with `null` clears it (`updateContext` gets
+`{ 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
+`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).
+`isRefusal(error)` recognises an `AgentRefusal` from any copy of the package (the mock, the backend helpers).
+
+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.
 
 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).