mitra-interactions-sdk 1.0.60-beta.33 → 1.0.60-beta.35

package/README.md

@@ -248,7 +248,7 @@ const result2 = await listRecordsMitra({
 
 Chat com o agente de IA embarcado. **REST-first, tudo pela BFF no `baseURL` normal** (`/agentAiShortcut/*` — herda `fetchWithRefresh` e CORS): chats (`createChat`/`listChats`/`readChat`/`renameChat`/`deleteChat`), histórico (`listChatMessages`), credenciais e modelos. `projectId` obrigatório em todas (opcional na chamada se veio do `configureSdkMitra`). **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).
 
-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).
+Precisa de `token` e `baseURL` configurados (o login já deixa pronto). O transporte do prompt aceita `transport: 'ws' | 'http'` — `'ws'` é o default; `'http'` é **funcional**: `POST /copilot/api/v1/tasks/{id}/inputs` + SSE em `/events` via fetch, com a MESMA paridade de eventos do WS (pra ambientes onde WebSocket não rola, ex.: serverless).
 
 ### Gerenciar os chats — `manageAgentChatMitra`
 
@@ -284,7 +284,9 @@ const existing = getAgentTaskMitra({ taskId: 'uuid-da-task' });
 await existing.loadHistory({ limit: 50 });
 ```
 
-`getAgentTaskMitra({ create: true, agentType?, name?, agentId?, transport? })` ou `getAgentTaskMitra({ taskId, transport? })`.
+`getAgentTaskMitra({ create: true, agentType?, name?, agentId?, reasoningEffort?, autonomous?, transport? })` ou `getAgentTaskMitra({ taskId, transport? })`.
+
+**Chat autônomo (`autonomous: true`)**: cria o chat **sem dono** (`user_id NULL` — a dona é o agente), pra Server Function/webhook/cron dirigir o agente. Exige `agentId` (fail-fast no client) e o agente precisa ter uma **connection anexada** como credencial; auth `AGENT_WRITE` (chave de SF ou token de app EDIT), senão 403. Depois de criado, dirigir/listar é igual ao chat normal (`getAgentTaskMitra({ taskId })`, `send`, `manageAgentChatMitra({ list, agentId })`). Sem o flag, comportamento de sempre (chat com dono = o caller). ⚠️ Depende do backend `impl-autonomous` — antes dele o servidor ignora o flag.
 
 - `agentType` vem de `manageAgentCredentialMitra({ action: 'list_models' })` — ex.: `'ANTHROPIC_CLAUDE_OPUS'`, `'OPENAI_GPT5'`. 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`: sessão business sem agente** — sem system prompt e sem acesso às Server Functions (as tools recusam); não há adoção automática de agente único. Na prática, sempre passe `agentId`.
@@ -303,7 +305,7 @@ await existing.loadHistory({ limit: 50 });
 
 #### Métodos
 
-- `send(prompt)` → `void` — dispara um turno (WS `message`). Se já está streamando, **enfileira** (FIFO, máx 10).
+- `send(prompt, { reasoningEffort?, agentType? })` → `void` — dispara um turno (`message` no WS ou POST `/inputs`). Se já está streamando, **enfileira** (FIFO, máx 10; as opções viajam com o item). `reasoningEffort`: intensidade desta mensagem — valores válidos vêm das `reasoningOptions` do modelo em `list_models` (**nunca invente**; fora do registro = `INVALID_REASONING_EFFORT`); herda o default de `getAgentTaskMitra({ create, reasoningEffort })` quando omitido. `agentType`: troca o modelo nesta mensagem — **só dentro do mesmo harness** (Claude↔Codex em conversa iniciada = `HARNESS_SWITCH`).
 - `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<AgentTimelineItem[]>` — histórico persistido via REST, já no formato canônico da timeline (renderizou o streaming, renderizou o histórico).
@@ -344,7 +346,9 @@ const { providers } = await manageAgentCredentialMitra({ action: 'list_providers
 
 // Modelos selecionáveis → use o agentType em getAgentTaskMitra
 const { models } = await manageAgentCredentialMitra({ action: 'list_models' });
-// AgentModel[]: { model, name, provider, agentType }
+// AgentModel[]: { model, name, provider, agentType, reasoningOptions }
+// reasoningOptions = registro das intensidades válidas por modelo (variam por
+// harness) — monte o seletor de reasoning a partir DAQUI, nunca hardcode
 
 // API key
 await manageAgentCredentialMitra({ action: 'save', target: 'openai', key: 'sk-...' });
@@ -359,6 +363,30 @@ const { authUrl, state } = await manageAgentCredentialMitra({ action: 'auth', ta
 const { connected, email } = await manageAgentCredentialMitra({ action: 'connect', target: 'anthropic', code, state });
 ```
 
+### Connections do app — `manageAgentConnectionMitra`
+
+Credencial de agente **compartilhada do app** (tenant+app) — espelho do management de credencial de user, apontando um `connectionId`. Pra sistemas montarem a tela de auth do agente. REST direto no copilot (`{origin}/copilot/api/v1/connections`).
+
+Chamável com **token de user** (app-scoped, roles EDIT/OWNER/ADMIN) **ou** com **chave de SF** (`CONNECTION_READ`/`CONNECTION_WRITE`) — o caminho por chave é aditivo. A credencial nunca sai do servidor.
+
+```typescript
+import { manageAgentConnectionMitra } from 'mitra-interactions-sdk';
+
+const { connections } = await manageAgentConnectionMitra({ action: 'list' });
+const conn = await manageAgentConnectionMitra({ action: 'create', provider: 'anthropic', name: 'shared' });
+
+// API key
+await manageAgentConnectionMitra({ action: 'save', connectionId: conn.id, key: 'sk-...' });
+
+// OAuth (anthropic)
+const { authUrl, state } = await manageAgentConnectionMitra({ action: 'auth', connectionId: conn.id });
+await manageAgentConnectionMitra({ action: 'connect', connectionId: conn.id, code, state });
+
+// Device flow (openai)
+const { deviceAuthId, userCode, verificationUri } = await manageAgentConnectionMitra({ action: 'device_auth', connectionId: conn.id });
+await manageAgentConnectionMitra({ action: 'device_poll', connectionId: conn.id, deviceAuthId });
+```
+
 Device flow (só OpenAI) — mostre `userCode` + `verificationUri` e faça polling:
 
 ```typescript

package/dist/index.d.mts

@@ -276,9 +276,9 @@ interface DeleteAgentChatResult {
     deleted: boolean;
 }
 /**
- * Transporte do prompt. 'ws' (default) = streaming via WebSocket.
- * 'http' = reservado pra ambientes serverless — o backend ainda não expõe
- * o prompt por HTTP; hoje lança erro claro.
+ * Transporte do prompt. 'ws' (default) = streaming via WebSocket por task.
+ * 'http' = POST /inputs + SSE /events via fetch — mesma paridade de eventos,
+ * pra ambientes onde WebSocket não rola (ex.: serverless).
  */
 type AgentTaskTransport = 'ws' | 'http';
 interface GetAgentTaskCreateOptions {
@@ -288,6 +288,12 @@ interface GetAgentTaskCreateOptions {
     projectId?: number | string;
     /** Tipo/modelo do agente (de list_models). Default: 'ANTHROPIC_CLAUDE_OPUS'. */
     agentType?: AgentType;
+    /**
+     * Default de intensidade de reasoning da session — o send() herda quando a
+     * mensagem não sobrescreve. Valores válidos: reasoningOptions do modelo em
+     * list_models (nunca invente).
+     */
+    reasoningEffort?: string;
     /** Nome/título do chat. */
     name?: string;
     /**
@@ -299,6 +305,16 @@ interface GetAgentTaskCreateOptions {
      * único; na prática, sempre passe agentId.
      */
     agentId?: string;
+    /**
+     * Cria o chat SEM dono (user_id NULL — a dona é o agente): a modalidade
+     * AUTÔNOMA, onde uma Server Function / webhook / cron dirige o agente.
+     * Exige `agentId` e o agente precisa ter uma connection anexada (credencial);
+     * auth AGENT_WRITE (chave de SF ou token de app EDIT), senão 403.
+     * Omitido = chat com dono (o caller), comportamento de sempre.
+     * ATENÇÃO: depende do backend impl-autonomous — antes dele o servidor
+     * ignora o flag e cria chat com dono normalmente.
+     */
+    autonomous?: boolean;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
 }
@@ -318,10 +334,26 @@ interface QueuedItem {
     seq: number;
     createdAt: number;
     status: 'pending' | 'sending';
+    /** Opções da mensagem preservadas na fila (enviadas quando o item despachar). */
+    reasoningEffort?: string;
+    agentType?: AgentType;
 }
 interface SendOptions {
-    /** Reservado (o modelo/agentType é fixado na criação da task). */
-    _reserved?: never;
+    /**
+     * Intensidade de reasoning DESTA mensagem. Valores válidos vêm SEMPRE do
+     * registro `reasoningOptions` do modelo em list_models (variam por harness) —
+     * nunca invente: valor fora do registro é recusado pelo copilot
+     * (INVALID_REASONING_EFFORT). Sobrescreve o default da session; a SDK envia
+     * em maiúsculo. Omitido = herda o default da abertura (ou o do backend).
+     */
+    reasoningEffort?: string;
+    /**
+     * Troca o modelo NESTA mensagem (value de list_models). O copilot reinicia a
+     * sessão retomando o mesmo chat com os parâmetros novos. Só dentro do MESMO
+     * harness — trocar Claude↔Codex numa conversa iniciada é recusado
+     * (HARNESS_SWITCH).
+     */
+    agentType?: AgentType;
 }
 interface AgentDeltaEvent {
     delta: string;
@@ -416,6 +448,12 @@ interface AgentModel {
     name: string;
     provider: string;
     agentType: AgentType;
+    /**
+     * Registro das intensidades de reasoning válidas pra este modelo (variam por
+     * harness — ex.: claude low..max; codex none..ultra). A UI monta o seletor a
+     * partir DAQUI; valor fora do registro é recusado pelo copilot.
+     */
+    reasoningOptions?: string[];
 }
 interface ListAgentProvidersResult {
     providers: AgentCredentialStatus[];
@@ -476,6 +514,43 @@ type ManageAgentCredentialOptions = {
     deviceAuthId: string;
     projectId?: number | string;
 };
+/** Connection do app (shape do copilot; campos extras passam intactos). */
+interface AgentConnection {
+    id: string;
+    provider?: string;
+    name?: string;
+    connected?: boolean;
+    [key: string]: unknown;
+}
+type ManageAgentConnectionOptions = {
+    action: 'list';
+} | {
+    action: 'create';
+    provider: AgentProvider;
+    name?: string;
+} | {
+    action: 'save';
+    connectionId: string;
+    key: string;
+} | {
+    action: 'auth';
+    connectionId: string;
+} | {
+    action: 'connect';
+    connectionId: string;
+    code: string;
+    state: string;
+} | {
+    action: 'device_auth';
+    connectionId: string;
+} | {
+    action: 'device_poll';
+    connectionId: string;
+    deviceAuthId: string;
+};
+interface ListAgentConnectionsResult {
+    connections: AgentConnection[];
+}
 
 /**
  * Mitra Interactions SDK - Instance
@@ -681,6 +756,66 @@ declare function manageAgentCredentialMitra(options: {
     projectId?: number | string;
 }): Promise<ConnectAgentCredentialResult>;
 
+/**
+ * Mitra Interactions SDK — Agent Connections
+ *
+ * Management de credencial de agente COMPARTILHADA (connection do app,
+ * tenant+app) — espelho do management de credencial de user
+ * (agent-credentials.ts), apontando um connectionId. Pra sistemas montarem
+ * a tela de auth do agente.
+ *
+ * REST direto no copilot ({origin}/copilot/api/v1/connections):
+ *   - list        → GET  /connections
+ *   - create      → POST /connections
+ *   - save        → PUT  /connections/{id}/api-key
+ *   - auth        → POST /connections/{id}/oauth/start
+ *   - connect     → POST /connections/{id}/oauth/exchange
+ *   - device_auth → POST /connections/{id}/device-authorizations
+ *   - device_poll → POST /connections/{id}/device-authorizations/{deviceAuthId}/poll
+ *
+ * Auth: Authorization Bearer com o token da config — funciona com token de
+ * user (app-scoped, roles EDIT/OWNER/ADMIN) E com chave de SF
+ * (CONNECTION_READ/WRITE). O caminho por chave é aditivo: nada aqui exige
+ * tipo específico de credencial — o servidor decide. Só sessão de CONSOLE
+ * (JWT token_use=session, sem app_id) é barrada no client, com causa clara.
+ *
+ * SEGURANÇA: a credencial nunca sai do servidor — as respostas trazem só
+ * status/metadados da connection.
+ */
+
+declare function manageAgentConnectionMitra(options: {
+    action: 'list';
+}): Promise<ListAgentConnectionsResult>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'create';
+    provider: 'anthropic' | 'openai';
+    name?: string;
+}): Promise<AgentConnection>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'save';
+    connectionId: string;
+    key: string;
+}): Promise<void>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'auth';
+    connectionId: string;
+}): Promise<AuthAgentCredentialResult>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'connect';
+    connectionId: string;
+    code: string;
+    state: string;
+}): Promise<ConnectAgentCredentialResult>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'device_auth';
+    connectionId: string;
+}): Promise<DeviceAuthAgentCredentialResult>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'device_poll';
+    connectionId: string;
+    deviceAuthId: string;
+}): Promise<ConnectAgentCredentialResult>;
+
 /**
  * Mitra Interactions SDK - Services
  */
@@ -736,4 +871,4 @@ declare function patchRecordMitra(options: PatchRecordOptions): Promise<Record<s
 declare function deleteRecordMitra(options: DeleteRecordOptions): Promise<void>;
 declare function createRecordsBatchMitra(options: CreateRecordsBatchOptions): Promise<Record<string, any>[]>;
 
-export { type AgentChat, type AgentCredentialStatus, type AgentDeltaEvent, type AgentErrorEvent, type AgentMessage, type AgentModel, type AgentProvider, type AgentQueueChangeEvent, type AgentRawEvent, type AgentStatusChangeEvent, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentTaskTransport, type AgentTimelineItem, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AuthAgentCredentialResult, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialResult, type CreateRecordOptions, type CreateRecordsBatchOptions, type CredentialAction, type DeleteAgentChatResult, type DeleteRecordOptions, type DeviceAuthAgentCredentialResult, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecutePublicServerFunctionResponse, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type GetAgentTaskCreateOptions, type GetAgentTaskOpenOptions, type GetAgentTaskOptions, type GetPublicServerFunctionExecutionOptions, type GetPublicServerFunctionExecutionResponse, type GetRecordOptions, type IntegrationResponse, type ListAgentModelsResult, type ListAgentProvidersResult, type ListIntegrationsOptions, type ListRecordsOptions, type ListRecordsResponse, type LoginOptions, type LoginResponse, type ManageAgentChatDeleteOptions, type ManageAgentChatListOptions, type ManageAgentChatOptions, type ManageAgentChatRenameOptions, type ManageAgentCredentialOptions, type MitraConfig, type MitraInstance, type PatchRecordOptions, type QueuedItem, type RenameAgentChatResult, type SendOptions, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type UpdateRecordOptions, callIntegrationMitra, configureSdkMitra, createMitraInstance, createRecordMitra, createRecordsBatchMitra, deleteRecordMitra, exchangeSsoCodeMitra, executePublicServerFunctionAsyncMitra, executePublicServerFunctionMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getAgentTaskMitra, getConfig, getPublicServerFunctionExecutionMitra, getRecordMitra, listIntegrationsMitra, listRecordsMitra, loginMitra, loginWithGoogleMitra, loginWithMicrosoftMitra, manageAgentChatMitra, manageAgentCredentialMitra, patchRecordMitra, refreshTokenSilently, resolveProjectId, stopServerFunctionExecutionMitra, updateRecordMitra };
+export { type AgentChat, type AgentConnection, type AgentCredentialStatus, type AgentDeltaEvent, type AgentErrorEvent, type AgentMessage, type AgentModel, type AgentProvider, type AgentQueueChangeEvent, type AgentRawEvent, type AgentStatusChangeEvent, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentTaskTransport, type AgentTimelineItem, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AuthAgentCredentialResult, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialResult, type CreateRecordOptions, type CreateRecordsBatchOptions, type CredentialAction, type DeleteAgentChatResult, type DeleteRecordOptions, type DeviceAuthAgentCredentialResult, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecutePublicServerFunctionResponse, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type GetAgentTaskCreateOptions, type GetAgentTaskOpenOptions, type GetAgentTaskOptions, type GetPublicServerFunctionExecutionOptions, type GetPublicServerFunctionExecutionResponse, type GetRecordOptions, type IntegrationResponse, type ListAgentConnectionsResult, type ListAgentModelsResult, type ListAgentProvidersResult, type ListIntegrationsOptions, type ListRecordsOptions, type ListRecordsResponse, type LoginOptions, type LoginResponse, type ManageAgentChatDeleteOptions, type ManageAgentChatListOptions, type ManageAgentChatOptions, type ManageAgentChatRenameOptions, type ManageAgentConnectionOptions, type ManageAgentCredentialOptions, type MitraConfig, type MitraInstance, type PatchRecordOptions, type QueuedItem, type RenameAgentChatResult, type SendOptions, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type UpdateRecordOptions, callIntegrationMitra, configureSdkMitra, createMitraInstance, createRecordMitra, createRecordsBatchMitra, deleteRecordMitra, exchangeSsoCodeMitra, executePublicServerFunctionAsyncMitra, executePublicServerFunctionMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getAgentTaskMitra, getConfig, getPublicServerFunctionExecutionMitra, getRecordMitra, listIntegrationsMitra, listRecordsMitra, loginMitra, loginWithGoogleMitra, loginWithMicrosoftMitra, manageAgentChatMitra, manageAgentConnectionMitra, manageAgentCredentialMitra, patchRecordMitra, refreshTokenSilently, resolveProjectId, stopServerFunctionExecutionMitra, updateRecordMitra };

package/dist/index.d.ts

@@ -276,9 +276,9 @@ interface DeleteAgentChatResult {
     deleted: boolean;
 }
 /**
- * Transporte do prompt. 'ws' (default) = streaming via WebSocket.
- * 'http' = reservado pra ambientes serverless — o backend ainda não expõe
- * o prompt por HTTP; hoje lança erro claro.
+ * Transporte do prompt. 'ws' (default) = streaming via WebSocket por task.
+ * 'http' = POST /inputs + SSE /events via fetch — mesma paridade de eventos,
+ * pra ambientes onde WebSocket não rola (ex.: serverless).
  */
 type AgentTaskTransport = 'ws' | 'http';
 interface GetAgentTaskCreateOptions {
@@ -288,6 +288,12 @@ interface GetAgentTaskCreateOptions {
     projectId?: number | string;
     /** Tipo/modelo do agente (de list_models). Default: 'ANTHROPIC_CLAUDE_OPUS'. */
     agentType?: AgentType;
+    /**
+     * Default de intensidade de reasoning da session — o send() herda quando a
+     * mensagem não sobrescreve. Valores válidos: reasoningOptions do modelo em
+     * list_models (nunca invente).
+     */
+    reasoningEffort?: string;
     /** Nome/título do chat. */
     name?: string;
     /**
@@ -299,6 +305,16 @@ interface GetAgentTaskCreateOptions {
      * único; na prática, sempre passe agentId.
      */
     agentId?: string;
+    /**
+     * Cria o chat SEM dono (user_id NULL — a dona é o agente): a modalidade
+     * AUTÔNOMA, onde uma Server Function / webhook / cron dirige o agente.
+     * Exige `agentId` e o agente precisa ter uma connection anexada (credencial);
+     * auth AGENT_WRITE (chave de SF ou token de app EDIT), senão 403.
+     * Omitido = chat com dono (o caller), comportamento de sempre.
+     * ATENÇÃO: depende do backend impl-autonomous — antes dele o servidor
+     * ignora o flag e cria chat com dono normalmente.
+     */
+    autonomous?: boolean;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
 }
@@ -318,10 +334,26 @@ interface QueuedItem {
     seq: number;
     createdAt: number;
     status: 'pending' | 'sending';
+    /** Opções da mensagem preservadas na fila (enviadas quando o item despachar). */
+    reasoningEffort?: string;
+    agentType?: AgentType;
 }
 interface SendOptions {
-    /** Reservado (o modelo/agentType é fixado na criação da task). */
-    _reserved?: never;
+    /**
+     * Intensidade de reasoning DESTA mensagem. Valores válidos vêm SEMPRE do
+     * registro `reasoningOptions` do modelo em list_models (variam por harness) —
+     * nunca invente: valor fora do registro é recusado pelo copilot
+     * (INVALID_REASONING_EFFORT). Sobrescreve o default da session; a SDK envia
+     * em maiúsculo. Omitido = herda o default da abertura (ou o do backend).
+     */
+    reasoningEffort?: string;
+    /**
+     * Troca o modelo NESTA mensagem (value de list_models). O copilot reinicia a
+     * sessão retomando o mesmo chat com os parâmetros novos. Só dentro do MESMO
+     * harness — trocar Claude↔Codex numa conversa iniciada é recusado
+     * (HARNESS_SWITCH).
+     */
+    agentType?: AgentType;
 }
 interface AgentDeltaEvent {
     delta: string;
@@ -416,6 +448,12 @@ interface AgentModel {
     name: string;
     provider: string;
     agentType: AgentType;
+    /**
+     * Registro das intensidades de reasoning válidas pra este modelo (variam por
+     * harness — ex.: claude low..max; codex none..ultra). A UI monta o seletor a
+     * partir DAQUI; valor fora do registro é recusado pelo copilot.
+     */
+    reasoningOptions?: string[];
 }
 interface ListAgentProvidersResult {
     providers: AgentCredentialStatus[];
@@ -476,6 +514,43 @@ type ManageAgentCredentialOptions = {
     deviceAuthId: string;
     projectId?: number | string;
 };
+/** Connection do app (shape do copilot; campos extras passam intactos). */
+interface AgentConnection {
+    id: string;
+    provider?: string;
+    name?: string;
+    connected?: boolean;
+    [key: string]: unknown;
+}
+type ManageAgentConnectionOptions = {
+    action: 'list';
+} | {
+    action: 'create';
+    provider: AgentProvider;
+    name?: string;
+} | {
+    action: 'save';
+    connectionId: string;
+    key: string;
+} | {
+    action: 'auth';
+    connectionId: string;
+} | {
+    action: 'connect';
+    connectionId: string;
+    code: string;
+    state: string;
+} | {
+    action: 'device_auth';
+    connectionId: string;
+} | {
+    action: 'device_poll';
+    connectionId: string;
+    deviceAuthId: string;
+};
+interface ListAgentConnectionsResult {
+    connections: AgentConnection[];
+}
 
 /**
  * Mitra Interactions SDK - Instance
@@ -681,6 +756,66 @@ declare function manageAgentCredentialMitra(options: {
     projectId?: number | string;
 }): Promise<ConnectAgentCredentialResult>;
 
+/**
+ * Mitra Interactions SDK — Agent Connections
+ *
+ * Management de credencial de agente COMPARTILHADA (connection do app,
+ * tenant+app) — espelho do management de credencial de user
+ * (agent-credentials.ts), apontando um connectionId. Pra sistemas montarem
+ * a tela de auth do agente.
+ *
+ * REST direto no copilot ({origin}/copilot/api/v1/connections):
+ *   - list        → GET  /connections
+ *   - create      → POST /connections
+ *   - save        → PUT  /connections/{id}/api-key
+ *   - auth        → POST /connections/{id}/oauth/start
+ *   - connect     → POST /connections/{id}/oauth/exchange
+ *   - device_auth → POST /connections/{id}/device-authorizations
+ *   - device_poll → POST /connections/{id}/device-authorizations/{deviceAuthId}/poll
+ *
+ * Auth: Authorization Bearer com o token da config — funciona com token de
+ * user (app-scoped, roles EDIT/OWNER/ADMIN) E com chave de SF
+ * (CONNECTION_READ/WRITE). O caminho por chave é aditivo: nada aqui exige
+ * tipo específico de credencial — o servidor decide. Só sessão de CONSOLE
+ * (JWT token_use=session, sem app_id) é barrada no client, com causa clara.
+ *
+ * SEGURANÇA: a credencial nunca sai do servidor — as respostas trazem só
+ * status/metadados da connection.
+ */
+
+declare function manageAgentConnectionMitra(options: {
+    action: 'list';
+}): Promise<ListAgentConnectionsResult>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'create';
+    provider: 'anthropic' | 'openai';
+    name?: string;
+}): Promise<AgentConnection>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'save';
+    connectionId: string;
+    key: string;
+}): Promise<void>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'auth';
+    connectionId: string;
+}): Promise<AuthAgentCredentialResult>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'connect';
+    connectionId: string;
+    code: string;
+    state: string;
+}): Promise<ConnectAgentCredentialResult>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'device_auth';
+    connectionId: string;
+}): Promise<DeviceAuthAgentCredentialResult>;
+declare function manageAgentConnectionMitra(options: {
+    action: 'device_poll';
+    connectionId: string;
+    deviceAuthId: string;
+}): Promise<ConnectAgentCredentialResult>;
+
 /**
  * Mitra Interactions SDK - Services
  */
@@ -736,4 +871,4 @@ declare function patchRecordMitra(options: PatchRecordOptions): Promise<Record<s
 declare function deleteRecordMitra(options: DeleteRecordOptions): Promise<void>;
 declare function createRecordsBatchMitra(options: CreateRecordsBatchOptions): Promise<Record<string, any>[]>;
 
-export { type AgentChat, type AgentCredentialStatus, type AgentDeltaEvent, type AgentErrorEvent, type AgentMessage, type AgentModel, type AgentProvider, type AgentQueueChangeEvent, type AgentRawEvent, type AgentStatusChangeEvent, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentTaskTransport, type AgentTimelineItem, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AuthAgentCredentialResult, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialResult, type CreateRecordOptions, type CreateRecordsBatchOptions, type CredentialAction, type DeleteAgentChatResult, type DeleteRecordOptions, type DeviceAuthAgentCredentialResult, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecutePublicServerFunctionResponse, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type GetAgentTaskCreateOptions, type GetAgentTaskOpenOptions, type GetAgentTaskOptions, type GetPublicServerFunctionExecutionOptions, type GetPublicServerFunctionExecutionResponse, type GetRecordOptions, type IntegrationResponse, type ListAgentModelsResult, type ListAgentProvidersResult, type ListIntegrationsOptions, type ListRecordsOptions, type ListRecordsResponse, type LoginOptions, type LoginResponse, type ManageAgentChatDeleteOptions, type ManageAgentChatListOptions, type ManageAgentChatOptions, type ManageAgentChatRenameOptions, type ManageAgentCredentialOptions, type MitraConfig, type MitraInstance, type PatchRecordOptions, type QueuedItem, type RenameAgentChatResult, type SendOptions, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type UpdateRecordOptions, callIntegrationMitra, configureSdkMitra, createMitraInstance, createRecordMitra, createRecordsBatchMitra, deleteRecordMitra, exchangeSsoCodeMitra, executePublicServerFunctionAsyncMitra, executePublicServerFunctionMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getAgentTaskMitra, getConfig, getPublicServerFunctionExecutionMitra, getRecordMitra, listIntegrationsMitra, listRecordsMitra, loginMitra, loginWithGoogleMitra, loginWithMicrosoftMitra, manageAgentChatMitra, manageAgentCredentialMitra, patchRecordMitra, refreshTokenSilently, resolveProjectId, stopServerFunctionExecutionMitra, updateRecordMitra };
+export { type AgentChat, type AgentConnection, type AgentCredentialStatus, type AgentDeltaEvent, type AgentErrorEvent, type AgentMessage, type AgentModel, type AgentProvider, type AgentQueueChangeEvent, type AgentRawEvent, type AgentStatusChangeEvent, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentTaskTransport, type AgentTimelineItem, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AuthAgentCredentialResult, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialResult, type CreateRecordOptions, type CreateRecordsBatchOptions, type CredentialAction, type DeleteAgentChatResult, type DeleteRecordOptions, type DeviceAuthAgentCredentialResult, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecutePublicServerFunctionResponse, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type GetAgentTaskCreateOptions, type GetAgentTaskOpenOptions, type GetAgentTaskOptions, type GetPublicServerFunctionExecutionOptions, type GetPublicServerFunctionExecutionResponse, type GetRecordOptions, type IntegrationResponse, type ListAgentConnectionsResult, type ListAgentModelsResult, type ListAgentProvidersResult, type ListIntegrationsOptions, type ListRecordsOptions, type ListRecordsResponse, type LoginOptions, type LoginResponse, type ManageAgentChatDeleteOptions, type ManageAgentChatListOptions, type ManageAgentChatOptions, type ManageAgentChatRenameOptions, type ManageAgentConnectionOptions, type ManageAgentCredentialOptions, type MitraConfig, type MitraInstance, type PatchRecordOptions, type QueuedItem, type RenameAgentChatResult, type SendOptions, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type UpdateRecordOptions, callIntegrationMitra, configureSdkMitra, createMitraInstance, createRecordMitra, createRecordsBatchMitra, deleteRecordMitra, exchangeSsoCodeMitra, executePublicServerFunctionAsyncMitra, executePublicServerFunctionMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getAgentTaskMitra, getConfig, getPublicServerFunctionExecutionMitra, getRecordMitra, listIntegrationsMitra, listRecordsMitra, loginMitra, loginWithGoogleMitra, loginWithMicrosoftMitra, manageAgentChatMitra, manageAgentConnectionMitra, manageAgentCredentialMitra, patchRecordMitra, refreshTokenSilently, resolveProjectId, stopServerFunctionExecutionMitra, updateRecordMitra };