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

package/README.md

@@ -90,6 +90,52 @@ conversation.subscribe(() => draw(conversation.getSnapshot()));
 
 How it works, and what it guarantees: [docs/architecture/client.md](../../docs/architecture/client.md).
 
+## The agent runtime (`@vinaverse/client/agent`)
+
+An app that hosts an agent writes one thing, its `AgentBackend` (its own API: open a session, a fresh secret, status,
+feedback, sign-out), and the runtime does the rest: one conversation per person, mode, business and thread; kept
+across screens while its session lives; the backend waited out, never answered with a new conversation; the agent's
+status and name; ratings; sign-out; events for analytics. `readCard` reads a card for drawing, every field checked.
+
+```ts
+import { AgentRefusal, createAgentRuntime } from '@vinaverse/client/agent';
+
+const runtime = createAgentRuntime({
+  backend: {
+    openSession: async (request) => {
+      const answer = await api.openAgentSession(request); // your API, with the person's own sign-in
+      if (!answer.available) throw new AgentRefusal('unavailable');
+      return answer.session; // id, realtime_url, turns_url, client_secret, conversation_id, expires_at …
+    },
+    refreshSecret: (sessionId) => api.refreshAgentSecret(sessionId),
+    status: () => api.agentStatus(),
+  },
+  conversation: { locale: 'en-US', closeInBackground: true, deepLinkPrefixes: ['yourapp://'] },
+  onEvent: (event) => analytics.track(`agent_${event.type}`, event),
+});
+
+const chat = runtime.conversation({ subject: user.id, mode: 'customer' });
+const release = chat.show({ place: { screen: 'explore' }, entryPoint: 'button' }); // when the screen goes: release()
+```
+
+Policies and adapters: `retry: { delays, isRetryable }`, `clock: { now }` (the server's time for a session's end),
+`keepAlive: 'session' | 'view'`, `onEvent` (analytics). `AgentBackend.updateContext` tells a new place live where your
+API serves it. Failures are typed on the conversation (`failure`, `reason`, `code`), with `startNew(key)`.
+History's "Continue" is `continue(key, conversationId)`: the key goes on with that conversation, and one that is gone
+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__`.
+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.
+
+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).
+
 ## License
 
 Apache-2.0