mitra-interactions-sdk 1.0.60-beta.23 → 1.0.60-beta.25

package/README.md

@@ -244,123 +244,130 @@ const result2 = await listRecordsMitra({
 });
 ```
 
-## Agent Chat (embedded)
+## Agent Chat (copilot)
 
-Chat com o agente de IA embarcado, sobre um WebSocket compartilhado. Uma única conexão atende todas as sessions — o roteamento de eventos é feito por `taskId`.
+Chat com o agente de IA embarcado. **REST-first**: credenciais e modelos vão pela **BFF no `baseURL` normal** (`/agentAiShortcut/*` — herdam `fetchWithRefresh` e CORS); chats e histórico via `{origin}/copilot/api/v1`. **Só o prompt é streaming** — um WebSocket por task em `wss://{origin}/copilot/ws/tasks/{taskId}?token=JWT`, aberto pela SDK quando a conversa começa (WS não passa por preflight de CORS).
 
-A URL do WebSocket é derivada da `baseURL` configurada: mesmo domínio/path, protocolo `http(s)` → `ws(s)`, endpoint `/sdk-ws`. Ex.: `baseURL: 'https://stg.mitralab.io/legacy'` → `wss://stg.mitralab.io/legacy/sdk-ws`. Precisa de `token` configurado (faça login antes ou passe em `configureSdkMitra`).
+Precisa de `token` e `baseURL` configurados (o login já deixa pronto). O transporte do prompt aceita `transport: 'ws' | 'http'` — `'ws'` é o default; `'http'` é reservado pra ambientes serverless e hoje lança erro claro (o backend ainda não expõe prompt por HTTP).
 
 ### Gerenciar os chats — `manageAgentChatMitra`
 
-Operações stateless sobre a coleção de chats do usuário: listar, renomear, deletar.
+Tudo HTTP: listar (com filtros), renomear e deletar (= arquivar).
 
 ```typescript
 import { manageAgentChatMitra } from 'mitra-interactions-sdk';
 
-const chats  = await manageAgentChatMitra({ action: 'list' });                       // AgentChat[]
-const renamed = await manageAgentChatMitra({ action: 'rename', taskId, name: 'Novo nome' });
-const deleted = await manageAgentChatMitra({ action: 'delete', taskId });
+const chats    = await manageAgentChatMitra({ action: 'list' });                          // AgentChat[]
+const doAgente = await manageAgentChatMitra({ action: 'list', agentId: 'uuid-do-agente' }); // só os chats de um agente business
+const busca    = await manageAgentChatMitra({ action: 'list', search: 'vendas', page: 0, size: 20 });
+const renamed  = await manageAgentChatMitra({ action: 'rename', taskId, name: 'Novo nome' });
+const deleted  = await manageAgentChatMitra({ action: 'delete', taskId }); // arquiva (some da lista default)
 ```
 
-- `action: 'list'` → `AgentChat[]` — `{ id, name, agentType?, provider?, createdAt, updatedAt }`. Aceita `projectId?` pra sobrescrever o global e `agentId?` pra filtrar os chats de um agente business (omitido = todos).
-- `action: 'rename'` → `{ taskId, name }`
-- `action: 'delete'` → `{ taskId, deleted }`
+- `action: 'list'` → `AgentChat[]` — `{ id, name, agentType, agentId, archived, createdAt, updatedAt }`. Filtros: `agentId?`, `archived?`, `search?`, `page?`, `size?`.
+- `action: 'rename'` → `{ taskId, name }` (PATCH `/tasks/{id}`)
+- `action: 'delete'` → `{ taskId, deleted }` (PATCH `/tasks/{id}/archive` — o histórico não é destruído)
 
 ### Abrir uma session — `getAgentTaskMitra`
 
-Retorna uma `AgentTaskSession` que encapsula todo o ciclo de vida de um chat (histórico, streaming, fila, cancel, eventos). Abrir a mesma `taskId` duas vezes devolve a **mesma** instância (cache).
+Retorna uma `AgentTaskSession` que encapsula o ciclo de vida do chat. A task é criada via REST (`POST /tasks`) no primeiro `send()`; o WS da task conecta em seguida. Abrir a mesma `taskId` duas vezes devolve a **mesma** instância (cache).
 
 ```typescript
 import { getAgentTaskMitra } from 'mitra-interactions-sdk';
 
-// Chat novo — taskId é preenchido depois do primeiro send()
-const session = getAgentTaskMitra({ create: true, agentType: 'claudecode', modelId: 'openai/gpt-5.5:medium' });
+// Chat novo — taskId é preenchido no primeiro send() (evento taskCreated)
+const session = getAgentTaskMitra({ create: true, agentType: 'ANTHROPIC_CLAUDE_OPUS', name: 'Meu chat' });
 
-// Chat existente — detecta automaticamente se já há stream ativo
-const existing = getAgentTaskMitra({ taskId: 'abc123' });
+// Chat com um agente business (system prompt + SFs do agente; token escopado)
+const sales = getAgentTaskMitra({ create: true, agentId: 'uuid-do-agente' });
+
+// Chat existente
+const existing = getAgentTaskMitra({ taskId: 'uuid-da-task' });
 await existing.loadHistory({ limit: 50 });
 ```
 
-`getAgentTaskMitra({ create: true, projectId?, agentType?, modelId?, name?, agentId? })` ou `getAgentTaskMitra({ taskId })`.
-
-**Agente business (`agentId`)**: passe o `id` de um agente business (CRUD via `mitra-sdk`: `listAgentsMitra` e família) pra sessão subir com o system prompt do agente e um token escopado — as tools enxergam só as Server Functions daquele agente. Sem `agentId`, é o chat de desenvolvimento de sempre.
+`getAgentTaskMitra({ create: true, agentType?, name?, agentId?, transport? })` ou `getAgentTaskMitra({ taskId, transport? })`.
 
-```typescript
-// Chat com um agente business (prompt + SFs do agente)
-const sales = getAgentTaskMitra({ create: true, agentId: 'uuid-do-agente' });
-```
+- `agentType` vem de `manageAgentCredentialMitra({ action: 'list_models' })` — ex.: `'ANTHROPIC_CLAUDE_OPUS'`, `'OPENAI_GPT5'`, `'GOOGLE_GEMINI_PRO'`. Default: `'ANTHROPIC_CLAUDE_OPUS'`.
+- **`agentId`**: id de um agente business (CRUD via `mitra-sdk`: `listAgentsMitra` e família). A sessão sobe com o system prompt do agente e um token escopado — as tools enxergam só as Server Functions dele. Sem `agentId`, é o chat de desenvolvimento.
 
 #### Propriedades (somente leitura)
 
 | Propriedade | Tipo | Descrição |
 |-------------|------|-----------|
 | `taskId` | `string \| null` | `null` até o primeiro `send()` num chat novo |
-| `task` | `AgentChat \| null` | Metadados do chat após criado |
+| `task` | `AgentChat \| null` | Metadados do chat |
 | `isNew` | `boolean` | Se foi aberto via `{ create: true }` |
 | `status` | `AgentTaskStatus` | `opening` · `idle` · `streaming` · `cancelled` · `error` · `closed` |
-| `history` | `AgentMessage[]` | Histórico carregado |
+| `history` | `AgentMessage[]` | Histórico carregado (`{ id, sender, type, content, createdAt }`) |
 | `content` | `string` | Conteúdo acumulado do turno atual |
 | `queue` | `QueuedItem[]` | Mensagens enfileiradas (enviadas enquanto streamava) |
 
 #### Métodos
 
-- `send(prompt, options?)` → `void` — dispara um turno. Se já está streamando, **enfileira** (FIFO, máx 10). `options`: `{ agentType?, modelId? }`.
-- `cancel()` → `Promise<void>` — cancela o turno atual; resolve quando o backend confirma (ou safety net de 30s).
-- `loadHistory({ limit? })` → `Promise<AgentMessage[]>` — carrega o histórico do chat.
+- `send(prompt)` → `void` — dispara um turno (WS `message`). Se já está streamando, **enfileira** (FIFO, máx 10).
+- `cancel()` → `Promise<void>` — interrompe o turno atual (WS `interrupt`, safety net de 10s).
+- `respondApproval(approved)` → `void` — responde um pedido de aprovação do agente (WS `approval_response`).
+- `loadHistory({ limit? })` → `Promise<AgentMessage[]>` — histórico persistido via REST.
 - `editQueueItem(id, text)` / `removeQueueItem(id)` / `clearQueue()` — manipulam a fila.
 - `on(event, handler)` → função de unsubscribe — assina eventos da session.
-- `close()` — encerra a session e libera os listeners.
+- `close()` — encerra a session, fecha o WS e libera os listeners.
 
 #### Eventos (`session.on`)
 
-`statusChange` · `historyLoaded` · `taskCreated` · `turnStart` · `delta` · `tool` · `turnEnd` · `cancelled` · `queueChange` · `error`.
+`statusChange` · `historyLoaded` · `taskCreated` · `turnStart` · `delta` (`{ delta, kind: 'text' | 'thinking' }`) · `tool` (`{ tool, toolId?, input?, content?, phase: 'call' | 'result' }`) · `turnEnd` (`{ content }`) · `cancelled` · `queueChange` · `error` (`{ code?, error }`) · `raw` (eventos não mapeados do stream, ex.: `workspace`).
 
 ```typescript
 const session = getAgentTaskMitra({ create: true });
 
-session.on('delta', ({ delta, kind }) => process.stdout.write(delta)); // kind: 'text' | 'tool'
-session.on('tool',  ({ tool, input }) => console.log('🔧', tool));
+session.on('delta', ({ delta, kind }) => { if (kind === 'text') process.stdout.write(delta); });
+session.on('tool',  ({ tool, phase }) => console.log('🔧', phase, tool));
 session.on('turnEnd', ({ content }) => console.log('\n✓ fim do turno'));
 session.on('taskCreated', ({ task }) => console.log('chat criado:', task.id));
 session.on('error', ({ error }) => console.error(error));
 
 session.send('Analise estas vendas e gere um resumo');
-
-// Modelo por turno (sobrescreve o default da session)
-session.send('Refaça com mais detalhes', { modelId: 'subscription:anthropic:claude-opus-4-7' });
 ```
 
 ### Credenciais do agente — `manageAgentCredentialMitra`
 
-Função única (sobre `/sdk-ws`) para API keys (8 providers: `anthropic`, `openai`, `gemini`, `kimi`, `minimax`, `glm`, `qwen`, `openrouter`) e subscriptions OAuth (Claude paste-código / OpenAI device flow via Codex).
+Função única, toda HTTP **via BFF** (`/agentAiShortcut/listProviders`, `saveCredential`, `oauthStart`...). Providers: `'anthropic'`, `'openai'`, `'google'`. API key via `save`/`remove`; OAuth via `auth`/`connect`; device flow via `device_auth`/`device_poll`.
+
+**`projectId` é obrigatório** em todas as actions (opcional na chamada se já veio do `configureSdkMitra`) — é ele que define de qual app é a credencial; o BFF resolve `projectId → appId` e cunha o token de app.
 
-> 🔒 Segurança: o token de subscription **nunca volta cru** pro cliente — fica server-side e é injetado no sandbox direto de lá.
+> 🔒 Tokens/keys nunca voltam crus — o backend devolve só status, e-mail da conta e a key mascarada.
 
 ```typescript
 import { manageAgentCredentialMitra } from 'mitra-interactions-sdk';
 
-// Listar providers + status (pra montar a UI de conexão)
+// Status por provider (pra montar a UI de conexão)
 const { providers } = await manageAgentCredentialMitra({ action: 'list_providers' });
+// AgentCredentialStatus[]: { provider, connected, credentialType, accountEmail, maskedApiKey }
 
-// Listar modelos disponíveis (só dos providers com credencial) → use o modelId em send()/getAgentTaskMitra
-const { providers: groups } = await manageAgentCredentialMitra({ action: 'list_models' });
+// Modelos selecionáveis → use o agentType em getAgentTaskMitra
+const { models } = await manageAgentCredentialMitra({ action: 'list_models' });
+// AgentModel[]: { model, name, provider, agentType }
 
 // API key
-await manageAgentCredentialMitra({ action: 'validate', target: 'openai', key: 'sk-...' });
-await manageAgentCredentialMitra({ action: 'save', target: 'glm', key: '...' });
+await manageAgentCredentialMitra({ action: 'save', target: 'openai', key: 'sk-...' });
 await manageAgentCredentialMitra({ action: 'remove', target: 'anthropic' });
 ```
 
-Subscriptions (alto nível, sem redirect/callback page) — `auth` inicia e retorna o que mostrar; `connect` finaliza:
+OAuth (ex.: Anthropic) — `auth` devolve o que mostrar, `connect` finaliza:
 
 ```typescript
-// Claude — abra a authUrl, colete o código que a Anthropic mostra
-const { authUrl, state } = await manageAgentCredentialMitra({ action: 'auth', target: 'claude' });
-await manageAgentCredentialMitra({ action: 'connect', target: 'claude', code, state });
+const { authUrl, state } = await manageAgentCredentialMitra({ action: 'auth', target: 'anthropic' });
+// app abre authUrl; usuário autoriza e copia o código
+const { connected, email } = await manageAgentCredentialMitra({ action: 'connect', target: 'anthropic', code, state });
+```
 
-// Codex (OpenAI device flow) — mostre verificationUrl + userCode; a SDK faz o polling
-const { verificationUrl, userCode, pollId } = await manageAgentCredentialMitra({ action: 'auth', target: 'codex' });
-await manageAgentCredentialMitra({ action: 'connect', target: 'codex', pollId });
+Device flow (ex.: OpenAI) — mostre `userCode` + `verificationUri` e faça polling:
+
+```typescript
+const { deviceAuthId, userCode, verificationUri, intervalSeconds } =
+  await manageAgentCredentialMitra({ action: 'device_auth', target: 'openai' });
+// app mostra: "abra {verificationUri} e digite {userCode}"; depois, a cada intervalSeconds:
+const { connected } = await manageAgentCredentialMitra({ action: 'device_poll', target: 'openai', deviceAuthId });
 ```
 
 ## Tipos TypeScript