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

package/dist/index.d.ts

@@ -195,6 +195,318 @@ interface StopServerFunctionExecutionResponse {
         executionStatus: string;
     };
 }
+type AgentType = 'claudecode' | 'codex' | 'opencode-cli' | 'opencode-sdk';
+interface AgentChat {
+    id: string;
+    name: string;
+    agentType?: string;
+    provider?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AgentMessage {
+    id: string;
+    content: string;
+    type: string;
+    sender?: 'user' | 'agent';
+    createdAt: string;
+    metadata?: Record<string, unknown> | null;
+}
+type ChatManageAction = 'list' | 'rename' | 'delete';
+interface ManageAgentChatListOptions {
+    action: 'list';
+    /** Sobrescreve o projectId configurado globalmente. */
+    projectId?: number | string;
+    /** Filtra os chats de um agente business específico. Omitido = todos os chats. */
+    agentId?: string;
+}
+interface ManageAgentChatRenameOptions {
+    action: 'rename';
+    taskId: string;
+    name: string;
+}
+interface ManageAgentChatDeleteOptions {
+    action: 'delete';
+    taskId: string;
+}
+type ManageAgentChatOptions = ManageAgentChatListOptions | ManageAgentChatRenameOptions | ManageAgentChatDeleteOptions;
+interface RenameAgentChatResult {
+    taskId: string;
+    name: string;
+}
+interface DeleteAgentChatResult {
+    taskId: string;
+    deleted: boolean;
+}
+interface GetAgentTaskCreateOptions {
+    /** Cria chat novo. taskId é preenchido depois do primeiro send(). */
+    create: true;
+    /** Sobrescreve projectId global. */
+    projectId?: number | string;
+    /** Tipo do agente. Default: 'claudecode'. */
+    agentType?: AgentType;
+    /**
+     * Modelo a usar (value vindo de manageAgentCredentialMitra({action:'list_models'})).
+     * Ex: 'openai/gpt-5.5:medium', 'glm/glm-5.1', 'subscription:anthropic:claude-opus-4-7'.
+     * O backend deriva agentType/provider/model a partir dele. Vira o default da
+     * task; cada send() pode sobrescrever via SendOptions.modelId.
+     */
+    modelId?: string;
+    /** Nome do chat (default: derivado do prompt). */
+    name?: string;
+    /**
+     * ID de um agente business (CRUD via mitra-sdk: listAgentsMitra e família).
+     * Com agentId, a sessão sobe 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.
+     */
+    agentId?: string;
+}
+interface GetAgentTaskOpenOptions {
+    /** Abre chat existente. Detecta automático se stream está ativo. */
+    taskId: string;
+}
+type GetAgentTaskOptions = GetAgentTaskCreateOptions | GetAgentTaskOpenOptions;
+type AgentTaskStatus = 'opening' | 'idle' | 'streaming' | 'cancelled' | 'error' | 'closed';
+interface QueuedItem {
+    id: string;
+    text: string;
+    agentType?: AgentType;
+    seq: number;
+    createdAt: number;
+    status: 'pending' | 'sending';
+    injected?: boolean;
+}
+interface SendOptions {
+    agentType?: AgentType;
+    /**
+     * Modelo a usar neste turno (value de list_models). Ex: 'openai/gpt-5.5:medium',
+     * 'glm/glm-5.1', 'subscription:anthropic:claude-opus-4-7'. Sobrescreve o modelId
+     * default da session. Se omitido, usa o default da session / agentType.
+     */
+    modelId?: string;
+}
+interface AgentDeltaEvent {
+    delta: string;
+    kind: 'text' | 'tool';
+}
+interface AgentToolEvent {
+    tool: string;
+    input?: string;
+    content?: string;
+    timestamp: number;
+}
+interface AgentTurnEndEvent {
+    /** Conteúdo final acumulado do turno. */
+    content: string;
+}
+interface AgentTaskCreatedEvent {
+    task: AgentChat;
+}
+interface AgentErrorEvent {
+    error: string;
+}
+interface AgentQueueChangeEvent {
+    queue: ReadonlyArray<QueuedItem>;
+}
+interface AgentStatusChangeEvent {
+    status: AgentTaskStatus;
+    previous: AgentTaskStatus;
+}
+type AgentTaskEventMap = {
+    historyLoaded: AgentMessage[];
+    turnStart: void;
+    delta: AgentDeltaEvent;
+    tool: AgentToolEvent;
+    turnEnd: AgentTurnEndEvent;
+    taskCreated: AgentTaskCreatedEvent;
+    cancelled: void;
+    error: AgentErrorEvent;
+    queueChange: AgentQueueChangeEvent;
+    statusChange: AgentStatusChangeEvent;
+};
+type AgentTaskEventName = keyof AgentTaskEventMap;
+interface AgentTaskSession {
+    readonly taskId: string | null;
+    readonly task: AgentChat | null;
+    readonly isNew: boolean;
+    readonly status: AgentTaskStatus;
+    readonly history: ReadonlyArray<AgentMessage>;
+    readonly content: string;
+    readonly queue: ReadonlyArray<QueuedItem>;
+    loadHistory(options?: {
+        limit?: number;
+    }): Promise<AgentMessage[]>;
+    close(): void;
+    send(prompt: string, options?: SendOptions): void;
+    cancel(): Promise<void>;
+    editQueueItem(itemId: string, newText: string): boolean;
+    removeQueueItem(itemId: string): boolean;
+    clearQueue(): void;
+    on<E extends AgentTaskEventName>(event: E, handler: (payload: AgentTaskEventMap[E]) => void): () => void;
+}
+/** Targets de subscription (OAuth/device flow). */
+type AgentSubscriptionTarget = 'claude' | 'openai_oauth' | 'codex';
+/** Targets de API key (8 providers suportados pelo backend). */
+type AgentApiKeyTarget = 'anthropic' | 'openai' | 'gemini' | 'kimi' | 'minimax' | 'glm' | 'qwen' | 'openrouter';
+/** Union — qualquer credencial. */
+type CredentialTarget = AgentSubscriptionTarget | AgentApiKeyTarget;
+/**
+ * Verbos aceitos por `manageAgentCredentialMitra`.
+ *
+ * Baixo nível (RPC direto contra o backend `credentials`):
+ *   status | remove | list | validate | save
+ *   oauth_start | oauth_exchange | device_start | device_poll | device_cancel
+ *
+ * Alto nível (orquestrado no browser, NÃO é um type WS — encadeia as actions
+ * de baixo nível + abre popup + espera autorização):
+ *   connect
+ */
+type CredentialAction = 'auth' | 'connect' | 'status' | 'remove' | 'list' | 'list_models' | 'list_providers' | 'validate' | 'save' | 'oauth_start' | 'oauth_exchange' | 'device_start' | 'device_poll' | 'device_cancel';
+/** Forma de acesso a uma credencial. */
+type CredentialAccessType = 'subscription' | 'api_key';
+/** Método de conexão — diz ao app/agent qual UI montar. */
+type AuthMethod = 'api_key' | 'paste_code' | 'device';
+/** Metadados pra montar a UI de conexão (vem em cada provider de list_providers). */
+interface AgentAuthMeta {
+    method: AuthMethod;
+    /** Só para method='api_key'. */
+    keyLabel?: string;
+    /** Só para method='api_key'. */
+    keyPlaceholder?: string;
+}
+/** Um modelo selecionável (retornado por action='list_models'). */
+interface AgentModelOption {
+    /** Passe direto em send({ modelId }) ou getAgentTaskMitra({ create, modelId }). */
+    modelId: string;
+    /** Label exibível. */
+    name: string;
+}
+/** Grupo de modelos por (tipo × provedor) — só grupos com credencial. */
+interface AgentModelGroup {
+    id: string;
+    name: string;
+    type: CredentialAccessType;
+    models: AgentModelOption[];
+}
+/** Retorno de manageAgentCredentialMitra({ action: 'list_models' }). */
+interface ListAgentModelsResult {
+    providers: AgentModelGroup[];
+}
+/** Um provedor suportado + status (retornado por action='list_providers'). */
+interface AgentProviderListItem {
+    id: string;
+    name: string;
+    type: CredentialAccessType;
+    /** Passe direto em auth/connect/save/remove. */
+    target: string;
+    /** Como conectar: method (api_key|paste_code|device) + label/placeholder. */
+    auth: AgentAuthMeta;
+    connected: boolean;
+    /** Presente em subscription Claude conectada. */
+    account?: AgentSubscriptionAccount;
+    expiresAt?: number;
+    /** Presente em API key conectada. */
+    maskedKey?: string;
+    updatedAt?: string | Date;
+}
+/** Retorno de manageAgentCredentialMitra({ action: 'list_providers' }). */
+interface ListAgentProvidersResult {
+    providers: AgentProviderListItem[];
+}
+/**
+ * Opções de baixo nível (RPC direto) de `manageAgentCredentialMitra`. Campos
+ * extras (key, code, codeVerifier, redirectUri, pollId, accessToken,
+ * refreshToken, expiresAt) são empacotados em `data` antes de enviar ao backend.
+ *
+ * NÃO use com action='connect' — para isso use ConnectAgentCredentialOptions.
+ */
+interface ManageAgentCredentialOptions {
+    action: Exclude<CredentialAction, 'connect' | 'auth'>;
+    /** Obrigatório exceto para action='list' / 'list_models'. */
+    target?: CredentialTarget;
+    /** Para `save` / `validate` de API key. */
+    key?: string;
+    /** Para `oauth_exchange`. */
+    code?: string;
+    /** Para `oauth_exchange`. */
+    state?: string;
+    /** Para `oauth_exchange`. */
+    codeVerifier?: string;
+    /** Para `oauth_start` (openai_oauth) e `oauth_exchange` (openai_oauth). */
+    redirectUri?: string;
+    /** Para `device_poll` / `device_cancel`. */
+    pollId?: string;
+    /** Para `save` (codex). */
+    accessToken?: string;
+    /** Para `save` (codex). */
+    refreshToken?: string;
+    /** Para `save` (codex). */
+    expiresAt?: number;
+}
+/** Tipo "ampliado" — o backend retorna shapes diferentes por (action, target). */
+type ManageAgentCredentialResult = unknown;
+interface AgentSubscriptionAccount {
+    email: string;
+    orgName: string;
+}
+/**
+ * Opções de alto nível de `manageAgentCredentialMitra` quando action='connect'.
+ * Orquestra o fluxo OAuth/device ponta-a-ponta no browser (abre popup, espera
+ * autorização, troca por tokens server-side).
+ */
+/**
+ * Targets que conectam SEM redirect (paste código / device flow). O
+ * 'openai_oauth' fica de fora porque depende de redirect localhost:1455
+ * (client OAuth compartilhado da OpenAI) — inviável em domínio de cliente.
+ * OpenAI subscription conecta via 'codex' (device flow).
+ */
+type ConnectableSubscriptionTarget = 'claude' | 'codex';
+interface AuthAgentCredentialOptions {
+    action: 'auth';
+    target: ConnectableSubscriptionTarget;
+}
+/** Resultado de auth(claude): abra a authUrl, depois connect com o código. */
+interface AuthClaudeResult {
+    target: 'claude';
+    /** URL pra abrir (a Anthropic mostra o código na própria tela). */
+    authUrl: string;
+    /** Passe de volta no connect junto com o código. */
+    state: string;
+}
+/** Resultado de auth(codex): mostre userCode/verificationUrl, depois connect com pollId. */
+interface AuthCodexResult {
+    target: 'codex';
+    /** Código que o user digita no site da OpenAI. */
+    userCode: string | null;
+    /** URL que o user abre pra autorizar. */
+    verificationUrl: string | null;
+    /** Passe de volta no connect; a SDK faz o polling. */
+    pollId: string;
+}
+type AuthAgentCredentialResult = AuthClaudeResult | AuthCodexResult;
+interface ConnectAgentCredentialOptions {
+    action: 'connect';
+    target: ConnectableSubscriptionTarget;
+    /** Código que o user copiou da página da Anthropic. Obrigatório p/ claude. */
+    code?: string;
+    /** O `state` devolvido por auth(claude). Obrigatório p/ claude. */
+    state?: string;
+    /** O `pollId` devolvido por auth(codex). Obrigatório p/ codex. */
+    pollId?: string;
+    /** Intervalo de poll do device flow (default 2000ms). */
+    pollIntervalMs?: number;
+    /** Timeout total do device flow (default 15min). */
+    deviceTimeoutMs?: number;
+}
+interface ConnectAgentSubscriptionResult {
+    target: ConnectableSubscriptionTarget;
+    success: boolean;
+    /** Presente em claude (epoch ms). */
+    expiresAt?: number;
+    /** Presente apenas em claude. */
+    account?: AgentSubscriptionAccount | null;
+}
 
 /**
  * Mitra Interactions SDK - Instance
@@ -219,6 +531,9 @@ interface MitraInstance {
     patchRecord(options: PatchRecordOptions): Promise<Record<string, any>>;
     deleteRecord(options: DeleteRecordOptions): Promise<void>;
     createRecordsBatch(options: CreateRecordsBatchOptions): Promise<Record<string, any>[]>;
+    getAgentTask(options: GetAgentTaskOptions): AgentTaskSession;
+    manageAgentChat(options: ManageAgentChatOptions): Promise<unknown>;
+    manageAgentCredential(options: ManageAgentCredentialOptions | ConnectAgentCredentialOptions): Promise<unknown>;
 }
 declare function createMitraInstance(initialConfig: Partial<MitraConfig>): MitraInstance;
 
@@ -282,6 +597,97 @@ declare function exchangeSsoCodeMitra(options: {
     state: string;
 }): Promise<LoginResponse>;
 
+/**
+ * Mitra Interactions SDK — Agent Chat
+ *
+ * Hub do WebSocket compartilhado e factories da API pública:
+ *   - manageAgentChatMitra({ action: 'list' | 'rename' | 'delete', ... })
+ *   - getAgentTaskMitra({ create | taskId, ... })
+ *
+ * O WS é singleton: todas as sessions usam UMA conexão. O roteamento
+ * de eventos é feito por taskId, despachando pra session correspondente.
+ *
+ * NÃO há `sendAgentPromptMitra` ou `getAgentHistoryMitra` exportados —
+ * essas operações vivem dentro de `AgentTaskSession`.
+ */
+
+/**
+ * Gerencia os chats do user (coleção) — espelha `manageAgentCredentialMitra`.
+ * Operações stateless: listar, renomear, deletar.
+ *
+ * @example
+ * const chats = await manageAgentChatMitra({ action: 'list' });
+ * await manageAgentChatMitra({ action: 'rename', taskId, name: 'Novo nome' });
+ * await manageAgentChatMitra({ action: 'delete', taskId });
+ */
+declare function manageAgentChatMitra(options: ManageAgentChatListOptions): Promise<AgentChat[]>;
+declare function manageAgentChatMitra(options: ManageAgentChatRenameOptions): Promise<RenameAgentChatResult>;
+declare function manageAgentChatMitra(options: ManageAgentChatDeleteOptions): Promise<DeleteAgentChatResult>;
+/**
+ * Abre um handle de chat (session). Use:
+ *   - `{ create: true }` para iniciar um chat novo
+ *   - `{ taskId: 'X' }` para abrir um chat existente
+ *
+ * A session expõe histórico, streaming, fila, cancel e eventos. Se a
+ * mesma taskId for aberta duas vezes, retorna a MESMA instância (cache).
+ */
+declare function getAgentTaskMitra(options: GetAgentTaskOptions): AgentTaskSession;
+
+/**
+ * Mitra Interactions SDK — Agent Credentials
+ *
+ * Função ÚNICA `manageAgentCredentialMitra` sobre /sdk-ws para todas as
+ * operações de credencial do agente:
+ *   - API keys (8 providers: anthropic, openai, gemini, kimi, minimax, glm, qwen, openrouter)
+ *   - Subscriptions OAuth (Claude paste-código / OpenAI device flow via Codex)
+ *
+ * Actions de baixo nível (RPC direto contra o backend):
+ *   status | remove | list | list_models | validate | save
+ *   oauth_start | oauth_exchange | device_start | device_poll | device_cancel
+ *
+ * Actions de alto nível (orquestradas na SDK — o app controla UI/popup/timing):
+ *   auth     — inicia o fluxo e retorna o que a UI mostra (sem efeito colateral
+ *              de janela). claude → { authUrl, state }; codex → { userCode,
+ *              verificationUrl, pollId }.
+ *   connect  — finaliza/salva. claude → passa { code, state }; codex → passa
+ *              { pollId } e a SDK faz o polling até autorizar.
+ *
+ * Fluxo típico (sem callbacks, sem redirect, sem callback page):
+ *   const { authUrl, state } = await manageAgentCredentialMitra({ action:'auth', target:'claude' });
+ *   // app abre authUrl + coleta o código do user
+ *   await manageAgentCredentialMitra({ action:'connect', target:'claude', code, state });
+ *
+ *   const { userCode, verificationUrl, pollId } = await manageAgentCredentialMitra({ action:'auth', target:'codex' });
+ *   // app mostra "abra {verificationUrl}, digite {userCode}"
+ *   await manageAgentCredentialMitra({ action:'connect', target:'codex', pollId });
+ *
+ * SEGURANÇA: o token de subscription NUNCA volta cru pro cliente. É salvo
+ * server-side (Firestore) e injetado no sandbox E2B direto de lá.
+ */
+
+/**
+ * Inicia um fluxo de subscription. Não abre janelas — retorna os dados pra UI:
+ *   claude → { authUrl, state }   codex → { userCode, verificationUrl, pollId }
+ */
+declare function manageAgentCredentialMitra(options: AuthAgentCredentialOptions): Promise<AuthAgentCredentialResult>;
+/**
+ * Finaliza/salva uma subscription:
+ *   claude → { code, state }   codex → { pollId } (a SDK faz o polling)
+ */
+declare function manageAgentCredentialMitra(options: ConnectAgentCredentialOptions): Promise<ConnectAgentSubscriptionResult>;
+/**
+ * RPC direto contra o backend. Retorno depende de (action, target).
+ *
+ * @example
+ * await manageAgentCredentialMitra({ action: 'list' });
+ * await manageAgentCredentialMitra({ action: 'list_models' });
+ * await manageAgentCredentialMitra({ action: 'status', target: 'anthropic' });
+ * await manageAgentCredentialMitra({ action: 'validate', target: 'openai', key: 'sk-...' });
+ * await manageAgentCredentialMitra({ action: 'save', target: 'glm', key: '...' });
+ * await manageAgentCredentialMitra({ action: 'remove', target: 'claude' });
+ */
+declare function manageAgentCredentialMitra<R = ManageAgentCredentialResult>(options: ManageAgentCredentialOptions): Promise<R>;
+
 /**
  * Mitra Interactions SDK - Services
  */
@@ -337,4 +743,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 CallIntegrationOptions, type CallIntegrationResponse, type CreateRecordOptions, type CreateRecordsBatchOptions, type DeleteRecordOptions, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecutePublicServerFunctionResponse, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type GetPublicServerFunctionExecutionOptions, type GetPublicServerFunctionExecutionResponse, type GetRecordOptions, type IntegrationResponse, type ListIntegrationsOptions, type ListRecordsOptions, type ListRecordsResponse, type LoginOptions, type LoginResponse, type MitraConfig, type MitraInstance, type PatchRecordOptions, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type UpdateRecordOptions, callIntegrationMitra, configureSdkMitra, createMitraInstance, createRecordMitra, createRecordsBatchMitra, deleteRecordMitra, exchangeSsoCodeMitra, executePublicServerFunctionAsyncMitra, executePublicServerFunctionMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getConfig, getPublicServerFunctionExecutionMitra, getRecordMitra, listIntegrationsMitra, listRecordsMitra, loginMitra, loginWithGoogleMitra, loginWithMicrosoftMitra, patchRecordMitra, refreshTokenSilently, resolveProjectId, stopServerFunctionExecutionMitra, updateRecordMitra };
+export { type AgentApiKeyTarget, type AgentAuthMeta, type AgentChat, type AgentDeltaEvent, type AgentErrorEvent, type AgentMessage, type AgentModelGroup, type AgentModelOption, type AgentProviderListItem, type AgentQueueChangeEvent, type AgentStatusChangeEvent, type AgentSubscriptionAccount, type AgentSubscriptionTarget, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AuthAgentCredentialOptions, type AuthAgentCredentialResult, type AuthClaudeResult, type AuthCodexResult, type AuthMethod, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialOptions, type ConnectAgentSubscriptionResult, type ConnectableSubscriptionTarget, type CreateRecordOptions, type CreateRecordsBatchOptions, type CredentialAccessType, type CredentialAction, type CredentialTarget, type DeleteAgentChatResult, type DeleteRecordOptions, 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 ManageAgentCredentialResult, 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 };