mitra-interactions-sdk 1.0.60-beta.1 → 1.0.60

package/README.md

@@ -483,6 +483,126 @@ await setProfileSelectTablesMitra({
 await setProfileServerFunctionsMitra({ projectId: 123, profileId: 1, serverFunctionIds: [5, 8, 12] });
 ```
 
+## Agent Chat (embedded)
+
+Chat com o agente de IA embarcado, sobre um WebSocket compartilhado (`/sdk-ws`). Uma única conexão atende todas as sessions — o roteamento de eventos é feito por `taskId`.
+
+> ⚙️ Requisitos: roda **apenas em apps publicadas pela plataforma Mitra** (o build-proxy injeta `window.__mitraEnv.agentWsUrl`) e precisa de `token` configurado (faça login antes ou passe em `configureSdkMitra`).
+
+### Gerenciar os chats — `manageAgentChatMitra`
+
+Operações stateless sobre a coleção de chats do usuário: listar, renomear, deletar.
+
+```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 });
+```
+
+- `action: 'list'` → `AgentChat[]` — `{ id, name, agentType?, provider?, createdAt, updatedAt }`. Aceita `projectId?` pra sobrescrever o global.
+- `action: 'rename'` → `{ taskId, name }`
+- `action: 'delete'` → `{ taskId, deleted }`
+
+### 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).
+
+```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 existente — detecta automaticamente se já há stream ativo
+const existing = getAgentTaskMitra({ taskId: 'abc123' });
+await existing.loadHistory({ limit: 50 });
+```
+
+`getAgentTaskMitra({ create: true, projectId?, agentType?, modelId?, name? })` ou `getAgentTaskMitra({ taskId })`.
+
+#### 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 |
+| `isNew` | `boolean` | Se foi aberto via `{ create: true }` |
+| `status` | `AgentTaskStatus` | `opening` · `idle` · `uploading` · `streaming` · `cancelled` · `error` · `closed` |
+| `history` | `AgentMessage[]` | Histórico carregado |
+| `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?, files? }`.
+- `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.
+- `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.
+
+#### Eventos (`session.on`)
+
+`statusChange` · `historyLoaded` · `taskCreated` · `turnStart` · `delta` · `tool` · `turnEnd` · `cancelled` · `queueChange` · `error`.
+
+```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('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');
+```
+
+#### Anexos e seleção de modelo
+
+```typescript
+// Anexos: passe os File crus (drop/input). A SDK sobe cada um (URL pública),
+// detecta o tipo e monta os anexos. Status vai pra 'uploading'; falha sai no evento 'error'.
+session.send('O que tem nesta planilha?', { files: [xlsxFile, pngFile] });
+
+// 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).
+
+> 🔒 Segurança: o token de subscription **nunca volta cru** pro cliente — fica server-side e é injetado no sandbox direto de lá.
+
+```typescript
+import { manageAgentCredentialMitra } from 'mitra-interactions-sdk';
+
+// Listar providers + status (pra montar a UI de conexão)
+const { providers } = await manageAgentCredentialMitra({ action: 'list_providers' });
+
+// Listar modelos disponíveis (só dos providers com credencial) → use o modelId em send()/getAgentTaskMitra
+const { providers: groups } = await manageAgentCredentialMitra({ action: 'list_models' });
+
+// API key
+await manageAgentCredentialMitra({ action: 'validate', target: 'openai', key: 'sk-...' });
+await manageAgentCredentialMitra({ action: 'save', target: 'glm', key: '...' });
+await manageAgentCredentialMitra({ action: 'remove', target: 'anthropic' });
+```
+
+Subscriptions (alto nível, sem redirect/callback page) — `auth` inicia e retorna 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 });
+
+// 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 });
+```
+
 ## Tipos TypeScript
 
 Todos os tipos estão incluídos:
@@ -534,7 +654,27 @@ import type {
   SetProfileScreensOptions,
   SetProfileServerFunctionsOptions,
   ProfileTableRef,
-  SetProfilePermissionResponse
+  SetProfilePermissionResponse,
+  // Agent Chat
+  AgentChat,
+  AgentMessage,
+  AgentType,
+  AgentTaskSession,
+  AgentTaskStatus,
+  AgentTaskEventMap,
+  AgentAttachment,
+  QueuedItem,
+  SendOptions,
+  GetAgentTaskOptions,
+  ManageAgentChatOptions,
+  // Agent Credentials
+  CredentialTarget,
+  CredentialAction,
+  ManageAgentCredentialOptions,
+  AuthAgentCredentialOptions,
+  ConnectAgentCredentialOptions,
+  ListAgentModelsResult,
+  ListAgentProvidersResult
 } from 'mitra-interactions-sdk';
 ```