@smoothcodes/agent-client 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @smoothcodes/agent-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A SDK do **usuário final** da SmoothAgent (token do usuário, um por dispositivo). Roda no navegador e no Node ≥ 20,
+sem dependência.
+
+- **REST** gerada do contrato (`contract/api`, audiência `client`): chats, agentes, arquivos, máquinas, provedores.
+- **Ao vivo**: `watch` (o estado pronto da tela), `events` (eventos crus em ordem), `prompt` (pergunta e resposta),
+  `watchList` (a lista lateral). A lógica mora no núcleo único em Rust (`sdk/core-rs`, compilado pra wasm); o wasm
+  baixa num pedaço à parte, em paralelo, na primeira vez que a camada ao vivo é usada.
+
+```ts
+import { SmoothAgent } from '@smoothcodes/agent-client'
+
+const sa = new SmoothAgent({ getToken: () => meuBackend.tokenDoUsuario() })
+
+// estado pronto da tela (compatível com useSyncExternalStore)
+const chat = sa.chats.watch(chatId)
+chat.subscribe((s) => render(s.timeline, s.inbox, s.history))
+await chat.send('oi')          // aparece na hora (otimista); idempotente por messageId
+chat.release()                 // a tela desmontou
+
+// pergunta e resposta
+const r = await sa.chats.prompt(chatId, 'resume o pedido').result   // nunca rejeita por queda de rede
+
+// eventos crus, retomando de onde parou
+for await (const e of sa.chats.events(chatId, { after: ultimoSeq })) console.log(e.type)
+```
+
+Provedores do usuário prontos pra tela (a tela só desenha; o poll do device mora na SDK):
+
+```ts
+const ps = sa.providers.watch()            // /me/providers; no server: sa.as(u).providers.watch() ou sa.connections.watchProviders(id)
+ps.subscribe((s) => render(s.rows))        // rows: needed primeiro; cada linha com flow / busy / error
+const f = ps.connect('codex')              // pending {kind:'device', userCode, verificationUrl} → connected | expired | failed{message}
+const g = ps.connect('claude')             // pending {kind:'oauth', url}; depois g.complete(códigoColado)
+f.cancel(); await ps.setKey('claude', chave); await ps.disconnect('codex')
+ps.release()                               // a tela desmontou
+```
+
+O código do OAuth e a chave vão direto pro pedido: nunca ficam no estado nem em log.
+
+- `baseUrl`: white-label (padrão: produção). No navegador servido pela mesma origem, `location.origin`.
+- `strict: true` (testes): buraco no stream vira violação visível em vez de resync.
+- `@smoothcodes/agent-client/testing`: harness de N interfaces no mesmo chat (comparar ordem e estado).
+
+## Desenvolver
+
+```bash
+npm ci
+npm test            # vitest (fakes determinísticos do protocolo)
+npm run build       # dist/ (ESM) + .d.ts
+npm run pack:next   # tarball em sdk/.packs (o que o Studio e o tests instalam)
+node e2e/prod.mjs   # cenários contra o v3 de prod (lê C:/SmoothAgent/platform/.env.local; recursos v3-t-sdk-*)
+```
+
+O núcleo wasm é gerado em `sdk/core-rs` (`node build-wasm.mjs`) e embutido em `sdk/ts/core-live/src/wasm/`.