@smoothbuilder/smoothagent-agent-client 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# @smoothcodes/agent-client
+
+## 0.4.0
+
+- Métodos e exports anteriores preservados; contrato aditivo.
+- Metadata opcional no envio, autoria de agente, recibo de mensagem e views de mensagens/seleção.
+- O fallback HTTP mantém o messageId e metadata; o caminho legado permanece disponível.
+- As views novas exigem o backend integrado de novembro de 2026. A autenticação interna da box não muda neste pacote.
+
+## 0.3.0
+
+- `watch(chatId).send()` durável: se o socket não confirmar em 2 s (`stream.sendFallbackMs`), a mensagem vai pelo REST `POST /v3/chats/{id}/messages` com o MESMO messageId (`clientMessageId` e `Idempotency-Key`); o servidor deduplica, nunca 2x. Gravada pelo REST, aparece em `local.sending` como `pending`. Antes, com o socket fechado a mensagem ficava só na memória do navegador e se perdia.
+- `close()` não deixa espera pendurada: o `send` não confirmado vai pelo REST na hora e resolve gravado; se nem isso der, rejeita com `SendNotConfirmedError` (`reason`, `messageId`, `content`, `mode`) pro app reenviar. Os outros comandos (stop/respond/reset/fila/troca) rejeitam com `CommandAbortedError` (`ref`). Mensagem continua `stream closed` (compatível).
+- `send(content, { timeoutMs })`: rejeita com `SendNotConfirmedError` `reason: 'timeout'` se nada confirmou no prazo (reenviar com o mesmo `messageId` é seguro). O `timeoutMs` só para de esperar: NÃO cancela o envio pelo socket, então a mensagem ainda pode chegar à fila depois, e a ordem dela em relação aos `send` seguintes não é garantida.
+- Os envios pelo REST saem em ordem por chat, um por vez (B nunca passa na frente de A). Com o servidor fora, a nova tentativa espera cada vez mais (5 s, dobrando, até 60 s).
+- Exporta `SendNotConfirmedError` e `CommandAbortedError`.
+
+## 0.2.3
+
+- `files.upload` agora envia o arquivo: o tipo virou `file: Uploadable` (obrigatório; `Blob`, `File`, `Buffer`/`Uint8Array`, `ReadableStream`, `{ data, filename, contentType }` ou, no Node, `{ path }`) e a parte `file` vai no multipart. Até a 0.2.2 o campo era `file?: unknown` e só array/Set era anexado, então `files.upload({ file: blob })` saía sem o arquivo.
+
+## 0.2.2
+
+- Só documentação: o CHANGELOG da 0.2.1 foi publicado com marcas de conflito de merge; o código é o mesmo da 0.2.1.
+
+## 0.2.1
+
+- Sem mudança de API: o mesmo número da `@smoothcodes/agent-server` 0.2.1. Ganha o teste de cobertura: todo grupo do cliente REST gerado tem que estar exposto na casca, com todos os métodos.
+
+## 0.2.0
+
+Desde a 0.1.0 (0.1.1/0.1.2 só republicaram a 0.1.0, presa no stage do npm; a 0.1.3 só trocou a base padrão).
+
+**Migrar da 0.1:** nenhum método, classe ou tipo exportado foi renomeado ou removido (conferido contra a 0.1.0). Só mudam tipos de retorno/campos:
+
+| Onde | 0.1 | 0.2 | O que fazer |
+|---|---|---|---|
+| `chats.delete()` | `Deleted` | `ChatDeleted` (`+ cleanup`) | nada, se só lia `id`/`deleted` |
+| `providers.myProvidersList().data[]` | `ProviderStatus` | `MyProviderStatus` | trocar a anotação de tipo, se houver |
+| `Agent.provider`, `AgentPublic.provider` | obrigatório | opcional | tratar `undefined` (agente sem motor → `providers[]`) |
+| `err.body` dos erros HTTP (`BadRequestError`, `ForbiddenError`…) | `unknown` | `Error_` | os casts passam a ser desnecessários |
+| `DEFAULT_BASE_URL` | `api.smoothagent.dev` | `smoothagent-v3-api.uaibuilder.workers.dev` | nada (quem passa `baseUrl` não muda) |
+
+**Quebra (tipos):**
+- `chats.delete()` devolve `ChatDeleted` (`{ id, deleted, cleanup: "pending" | "done" }`) em vez de `Deleted`.
+- `providers.myProvidersList()`: `data` agora é `MyProviderStatus[]` (`connected`, `via`, `status`, `models`, `connect`, `needed`, `expiresAt`) em vez de `ProviderStatus[]`.
+- `Agent.provider` / `AgentPublic.provider` ficaram opcionais: agente SEM motor; as opções vêm em `providers: AgentProviderOption[]` (`provider`, `models`, `capabilities`, `ready`).
+
+**Novo:**
+- Erros HTTP tipados: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `ConflictError`, `TooManyRequestsError`, `InternalServerError` passam a ter `body: Error_` (`{ error: ErrorBody }`) em vez de `unknown` (os outros, `NotFoundError` incluso, já eram `Error_` na 0.1.0). Todos os erros HTTP agora têm `body: Error_`.
+- `agents`: `queue.defaultMode` ausente na criação = `queue` (era `steer`).
+- `chats.create({ provider })`: escolhe o motor do chat quando o agente não tem motor (no agente com motor, só o dele).
+- `chats.switchAgent({ provider?, model?: string | null, effort?: string | null })`: `null` = voltar ao padrão do agente, explícito; ausente = fica o de agora.
+- `EventsInboxState` ganha `wake_failed`; `EventsFailure.details.provider` documenta qual credencial falta/venceu.
+- A base padrão (`DEFAULT_BASE_URL`, `https://smoothagent-v3-api.uaibuilder.workers.dev`, consertada na 0.1.3; antes era `api.smoothagent.dev`, que não existe) agora sai do `servers` do contrato.
+
+Camada ao vivo (`watch`, `events`, `prompt`): sem mudança de API desde a 0.1.0.

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/`.