mitra-interactions-sdk 1.0.60-beta.47 → 1.0.60-beta.49

package/README.md

@@ -263,7 +263,7 @@ const result2 = await listRecordsMitra({
 
 ## Agent Chat (copilot)
 
-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).
+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). Chats que nascem no **box T3** têm canal direto. A decisão é do copilot por app e vem no campo `runtime` da task (`RUNNER` ou `T3`), que a SDK lê no `createChat`/`readChat`: **só quando ele é `T3`** a SDK chama `POST /copilot/api/v1/tasks/{id}/channel` antes de conectar e abre o WebSocket na URL devolvida, que aponta ao box do agente pelo gateway com `grant` e `ticket` curtos na query. O envelope de eventos é o mesmo; só a URL muda. Esse POST responde na hora: `200` com `status: "ready"` e a URL, ou `202` com `status: "booting"` enquanto o box ainda sobe — nesse caso a SDK repete a cada 2s até 120s, teto que cobre o boot frio de box T3, que leva até ~2 min. Chat do runner, copilot antigo (que não devolve `runtime`), box que não subiu dentro do teto ou falha nessa chamada seguem pelo WebSocket do copilot, byte a byte como hoje. Cada reconexão pede um canal novo.
 
 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).
 
@@ -301,9 +301,9 @@ const existing = getAgentTaskMitra({ taskId: 'uuid-da-task' });
 await existing.loadHistory({ limit: 50 });
 ```
 
-`getAgentTaskMitra({ create: true, agentType?, name?, agentId?, reasoningEffort?, transport?, userId? })` ou `getAgentTaskMitra({ taskId, transport? })`.
+`getAgentTaskMitra({ create: true, agentType?, name?, agentId?, reasoningEffort?, autonomous?, userId?, transport? })` ou `getAgentTaskMitra({ taskId, transport? })`.
 
-**Agente autônomo**: a autonomia é **propriedade do AGENTE** (`autonomous` em `createAgentMitra`/`updateAgentMitra`, no `mitra-sdk`) — não existe flag na criação do chat. Ao criar um chat contra um agente autônomo (`getAgentTaskMitra({ create: true, agentId })`), o copilot deriva a autonomia do agente e o chat já nasce **sem dono** (`user_id NULL` — a dona é o agente), usando a connection anexada ao agente como credencial. Exige auth `AGENT_WRITE` (chave de SF ou token de app EDIT) — usuário business comum não abre chat autônomo. Depois de criado, dirigir/listar é igual ao chat normal (`getAgentTaskMitra({ taskId })`, `send`, `manageAgentChatMitra({ list, agentId })`).
+**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. A autonomia é **propriedade do CHAT** — o flag `autonomous` do agente não tem mais leitor no backend. Exige `agentId` (fail-fast no client) e o agente precisa ter uma **connection anexada** como credencial (senão `400 AUTONOMOUS_TASK_REQUIRES_CONNECTION`); 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).
 
 - `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`.

package/dist/index.d.mts

@@ -333,6 +333,17 @@ interface GetAgentTaskCreateOptions {
      * ela age.
      */
     userId?: 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 (é a
+     * credencial do chat); auth AGENT_WRITE (chave de SF), senão 403. Agente
+     * sem connection: 400 AUTONOMOUS_TASK_REQUIRES_CONNECTION. Mutuamente
+     * exclusivo com `userId` (400 AUTONOMOUS_TASK_HAS_NO_OWNER).
+     * Omitido = chat com dono (o caller), comportamento de sempre.
+     * A autonomia é do CHAT: o flag `autonomous` do AGENTE não tem leitor.
+     */
+    autonomous?: boolean;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
 }
@@ -640,8 +651,8 @@ declare function refreshTokenSilently(authUrl: string, _projectId: number | stri
  * Mitra Interactions SDK — Agent Chat (via BFF)
  *
  * REST-first, tudo pela BFF no baseURL normal (`/agentAiShortcut/*`) — herda
- * fetchWithRefresh e o CORS do BFF. Envelope `{ status, result }`; listas vêm
- * desembrulhadas do Page (result é o array direto).
+ * fetchWithRefresh e a troca de token server-side. Envelope `{ status, result }`;
+ * listas vêm desembrulhadas do Page (result é o array direto).
  *
  * SÓ o prompt é streaming: WebSocket por task em
  * `wss://{origin}/copilot/ws/tasks/{taskId}?token=JWT` (não passa por
@@ -683,7 +694,8 @@ declare function getAgentTaskMitra(options: GetAgentTaskOptions): AgentTaskSessi
  * Mitra Interactions SDK — Agent Credentials (via BFF)
  *
  * Função ÚNICA `manageAgentCredentialMitra`, toda HTTP pela BFF no baseURL
- * normal (`/agentAiShortcut/*`) — herda fetchWithRefresh e o CORS do BFF:
+ * normal (`/agentAiShortcut/*`) — herda fetchWithRefresh e a troca de token
+ * server-side:
  *   - list_providers → GET  /agentAiShortcut/listProviders?projectId=
  *   - list_models    → GET  /agentAiShortcut/listModels?projectId=&agentId=  (agentId opcional)
  *   - save           → POST /agentAiShortcut/saveCredential   {projectId, provider, key}

package/dist/index.d.ts

@@ -333,6 +333,17 @@ interface GetAgentTaskCreateOptions {
      * ela age.
      */
     userId?: 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 (é a
+     * credencial do chat); auth AGENT_WRITE (chave de SF), senão 403. Agente
+     * sem connection: 400 AUTONOMOUS_TASK_REQUIRES_CONNECTION. Mutuamente
+     * exclusivo com `userId` (400 AUTONOMOUS_TASK_HAS_NO_OWNER).
+     * Omitido = chat com dono (o caller), comportamento de sempre.
+     * A autonomia é do CHAT: o flag `autonomous` do AGENTE não tem leitor.
+     */
+    autonomous?: boolean;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
 }
@@ -640,8 +651,8 @@ declare function refreshTokenSilently(authUrl: string, _projectId: number | stri
  * Mitra Interactions SDK — Agent Chat (via BFF)
  *
  * REST-first, tudo pela BFF no baseURL normal (`/agentAiShortcut/*`) — herda
- * fetchWithRefresh e o CORS do BFF. Envelope `{ status, result }`; listas vêm
- * desembrulhadas do Page (result é o array direto).
+ * fetchWithRefresh e a troca de token server-side. Envelope `{ status, result }`;
+ * listas vêm desembrulhadas do Page (result é o array direto).
  *
  * SÓ o prompt é streaming: WebSocket por task em
  * `wss://{origin}/copilot/ws/tasks/{taskId}?token=JWT` (não passa por
@@ -683,7 +694,8 @@ declare function getAgentTaskMitra(options: GetAgentTaskOptions): AgentTaskSessi
  * Mitra Interactions SDK — Agent Credentials (via BFF)
  *
  * Função ÚNICA `manageAgentCredentialMitra`, toda HTTP pela BFF no baseURL
- * normal (`/agentAiShortcut/*`) — herda fetchWithRefresh e o CORS do BFF:
+ * normal (`/agentAiShortcut/*`) — herda fetchWithRefresh e a troca de token
+ * server-side:
  *   - list_providers → GET  /agentAiShortcut/listProviders?projectId=
  *   - list_models    → GET  /agentAiShortcut/listModels?projectId=&agentId=  (agentId opcional)
  *   - save           → POST /agentAiShortcut/saveCredential   {projectId, provider, key}

package/dist/index.js

@@ -498,6 +498,8 @@ var httpTenant = {
 var QUEUE_MAX = 10;
 var DEFAULT_AGENT_TYPE = "ANTHROPIC_CLAUDE_OPUS";
 var CANCEL_SAFETY_MS = 1e4;
+var WS_SILENCE_MS = 6e4;
+var WS_RECONNECT_DELAYS_MS = [1e3, 2e3, 4e3, 8e3, 16e3, 3e4];
 var queueSeq = 0;
 var AgentTaskSession = class {
   constructor(init) {
@@ -512,7 +514,24 @@ var AgentTaskSession = class {
     // ── Transporte ────────────────────────
     this._ws = null;
     this._wsConnectPromise = null;
+    /** Metadados do chat existente (o `runtime` entre eles). Quem escolhe transporte espera
+     *  por ela: sem o runtime a session nem pergunta pelo canal do box e cai no WS do copilot,
+     *  que numa conversa entregue por HTTP não tem como levar a mensagem ao agente. */
+    this._metadataReady = null;
     this._creatingTask = false;
+    /** O socket atual é o do box (canal direto), que sabe repetir o log por `sequence`. */
+    this._wsIsDirect = false;
+    /** Já houve socket aberto nesta session: do segundo em diante existe buraco a cobrir. */
+    this._wsEverOpened = false;
+    /** Onde o log do box estava quando esta session entrou. Congelado no primeiro socket: numa
+     *  reconexão o canal já conta o que a session perdeu, e adotar o número de lá pularia
+     *  justamente esses eventos. */
+    this._joinSequence = 0;
+    /** Maior `sequence` já vista nesta session: de onde o box repete depois de uma queda. */
+    this._lastSequence = 0;
+    this._wsSilenceTimer = null;
+    this._wsReconnectTimer = null;
+    this._wsReconnectAttempt = 0;
     // ── Cancel ────────────────────────────
     this._cancelTimer = null;
     // ── Transporte HTTP (SSE por fetch; o WS continua o default) ───────────
@@ -531,6 +550,7 @@ var AgentTaskSession = class {
       this._initialName = init.name;
       this._agentId = init.agentId;
       this._reasoningEffort = init.reasoningEffort;
+      this._autonomous = init.autonomous;
       this._status = "idle";
     } else {
       this._agentType = DEFAULT_AGENT_TYPE;
@@ -563,11 +583,15 @@ var AgentTaskSession = class {
   }
   // ── Abertura de chat existente ─────────
   async _openExisting(taskId) {
-    try {
+    this._metadataReady = (async () => {
       const t = await readChatTask(taskId, this._projectId);
       this._task = toAgentChat(t);
+      this._runtime = t.runtime;
       this._agentType = this._task.agentType;
       if (this._status === "opening") this._setStatus("idle");
+    })();
+    try {
+      await this._metadataReady;
       if (this._transport === "http") await this._ensureSse();
       else await this._ensureWs();
     } catch (err) {
@@ -620,9 +644,11 @@ var AgentTaskSession = class {
             title: this._initialName,
             agentType: this._agentType,
             agentId: this._agentId,
-            userId: this._userId
+            userId: this._userId,
+            autonomous: this._autonomous
           });
           this._task = toAgentChat(t);
+          this._runtime = t.runtime;
           this._taskId = this._task.id;
           registerSession(this._taskId, this);
           this._emit("taskCreated", { task: this._task });
@@ -696,6 +722,7 @@ var AgentTaskSession = class {
       clearTimeout(this._cancelTimer);
       this._cancelTimer = null;
     }
+    this._clearWsTimers();
     if (this._ws) {
       try {
         this._ws.close();
@@ -858,13 +885,15 @@ var AgentTaskSession = class {
     }
     this._wsConnectPromise = (async () => {
       try {
+        if (this._metadataReady) await this._metadataReady.catch(() => {
+        });
         if (isTokenExpiring()) await tryRefreshToken();
         try {
           return await this._connectWs(this._taskId);
         } catch (err) {
           const refreshed = await tryRefreshToken();
-          if (!refreshed) throw err;
-          return await this._connectWs(this._taskId);
+          if (!refreshed && this._runtime !== "T3") throw err;
+          return await this._connectWs(this._taskId, false);
         }
       } finally {
         this._wsConnectPromise = null;
@@ -872,8 +901,14 @@ var AgentTaskSession = class {
     })();
     return this._wsConnectPromise;
   }
-  _connectWs(taskId) {
-    const url = getTaskWsUrl(taskId);
+  /** `allowDirect` false força o WS do copilot: é como a reconexão degrada um box que não abriu. */
+  async _connectWs(taskId, allowDirect = true) {
+    var _a;
+    const direct = allowDirect && this._runtime === "T3" ? await requestDirectChannel(taskId, () => this._status === "closed") : null;
+    if (this._status === "closed") {
+      throw new Error("AgentTaskSession: session fechada durante a conex\xE3o.");
+    }
+    const url = (_a = direct == null ? void 0 : direct.wsUrl) != null ? _a : getTaskWsUrl(taskId);
     return new Promise((resolve, reject) => {
       const socket = new WebSocket(url);
       let opened = false;
@@ -889,7 +924,28 @@ var AgentTaskSession = class {
       socket.onopen = () => {
         opened = true;
         clearTimeout(timer);
+        if (this._status === "closed") {
+          try {
+            socket.close();
+          } catch (e) {
+          }
+          reject(new Error("AgentTaskSession: session fechada durante a conex\xE3o."));
+          return;
+        }
         this._ws = socket;
+        this._wsIsDirect = direct !== null;
+        this._wsReconnectAttempt = 0;
+        this._armSilenceWatchdog(socket);
+        const reconexao = this._wsEverOpened;
+        if (!reconexao && direct) this._joinSequence = direct.lastSequence;
+        this._wsEverOpened = true;
+        if (this._wsIsDirect && reconexao) {
+          const fromSequence = Math.max(this._lastSequence, this._joinSequence);
+          try {
+            socket.send(JSON.stringify({ type: "replay", fromSequence }));
+          } catch (e) {
+          }
+        }
         resolve(socket);
       };
       socket.onerror = () => {
@@ -899,9 +955,13 @@ var AgentTaskSession = class {
         }
       };
       socket.onclose = () => {
-        if (this._ws === socket) this._ws = null;
+        if (this._ws !== socket) return;
+        this._ws = null;
+        this._clearSilenceWatchdog();
+        if (this._status !== "closed") this._scheduleReconnect();
       };
       socket.onmessage = (evt) => {
+        if (this._ws === socket) this._armSilenceWatchdog(socket);
         let msg;
         try {
           msg = JSON.parse(String(evt.data));
@@ -912,13 +972,68 @@ var AgentTaskSession = class {
       };
     });
   }
-  // ── Eventos do stream (WsOutboundMessage { type, payload, timestamp }) ──
+  // ── Vida do socket: watchdog de silêncio e reconexão ──────────────────
+  _armSilenceWatchdog(socket) {
+    this._clearSilenceWatchdog();
+    this._wsSilenceTimer = setTimeout(() => {
+      this._wsSilenceTimer = null;
+      if (this._ws !== socket) return;
+      try {
+        socket.close();
+      } catch (e) {
+      }
+      if (this._ws === socket) {
+        this._ws = null;
+        if (this._status !== "closed") this._scheduleReconnect();
+      }
+    }, WS_SILENCE_MS);
+  }
+  _clearSilenceWatchdog() {
+    if (this._wsSilenceTimer) {
+      clearTimeout(this._wsSilenceTimer);
+      this._wsSilenceTimer = null;
+    }
+  }
+  _clearWsTimers() {
+    this._clearSilenceWatchdog();
+    if (this._wsReconnectTimer) {
+      clearTimeout(this._wsReconnectTimer);
+      this._wsReconnectTimer = null;
+    }
+  }
+  _scheduleReconnect() {
+    if (this._wsReconnectTimer || this._wsConnectPromise) return;
+    const delay = WS_RECONNECT_DELAYS_MS[this._wsReconnectAttempt];
+    if (delay === void 0) {
+      this._wsReconnectAttempt = 0;
+      this._emit("error", { code: "CONNECTION_LOST", error: "Conex\xE3o com o agente perdida; a resposta segue no hist\xF3rico." });
+      if (this._status === "streaming" || this._status === "cancelled") this._setStatus("idle");
+      return;
+    }
+    this._wsReconnectAttempt += 1;
+    this._wsReconnectTimer = setTimeout(() => {
+      this._wsReconnectTimer = null;
+      if (this._status === "closed") return;
+      void this._ensureWs().catch(() => {
+        if (this._status !== "closed") this._scheduleReconnect();
+      });
+    }, delay);
+  }
+  // ── Eventos do stream (WsOutboundMessage { type, payload, timestamp, sequence? }) ──
   _handleWsEvent(msg) {
     var _a, _b, _c, _d, _e, _f, _g, _h;
     if (!msg || typeof msg.type !== "string" || !msg.type) return;
+    if (typeof msg.sequence === "number" && msg.sequence > this._lastSequence) {
+      this._lastSequence = msg.sequence;
+    }
     const { type, payload } = msg;
     switch (type) {
-      case "textDelta": {
+      // `textChunk` é a forma que o texto do agente tem no log do box: ele transmite ao vivo
+      // em `textDelta` e dobra os deltas em chunks numerados ao gravar. Uma repetição depois
+      // de queda devolve chunks, então tratá-los como texto é o que faz a resposta recuperada
+      // aparecer; sem este caso ela chega no socket e é descartada em silêncio.
+      case "textDelta":
+      case "textChunk": {
         const text = (_a = payload == null ? void 0 : payload.text) != null ? _a : "";
         if (this._status !== "streaming" && this._status !== "cancelled") this._setStatus("streaming");
         this._content += text;
@@ -1097,6 +1212,59 @@ function getRawToken() {
   }
   return stripBearer(config.token);
 }
+var CHANNEL_BOOT_RETRY_MS = 2e3;
+var CHANNEL_BOOT_TIMEOUT_MS = 12e4;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isGatewayWsUrl(wsUrl) {
+  const expected = getGatewayOrigin().replace(/^http/, "ws");
+  try {
+    return new URL(wsUrl).origin === expected;
+  } catch (e) {
+    return false;
+  }
+}
+async function requestDirectChannel(taskId, isCancelled) {
+  var _a;
+  if (!hasAppScope(getRawToken())) return null;
+  const url = `${getGatewayOrigin()}/copilot/api/v1/tasks/${encodeURIComponent(taskId)}/channel`;
+  const doPost = async () => fetch(url, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${getRawToken()}` }
+  });
+  const deadline = Date.now() + CHANNEL_BOOT_TIMEOUT_MS;
+  for (; ; ) {
+    if (isCancelled == null ? void 0 : isCancelled()) return null;
+    let response;
+    try {
+      response = await doPost();
+      if (response.status === 401 && await tryRefreshToken()) response = await doPost();
+    } catch (e) {
+      return null;
+    }
+    if (response.status === 202) {
+      if (Date.now() >= deadline) return null;
+      await sleep(CHANNEL_BOOT_RETRY_MS);
+      continue;
+    }
+    if (response.status !== 200) return null;
+    let body;
+    try {
+      body = await response.json();
+    } catch (e) {
+      return null;
+    }
+    const channel = body;
+    if (!channel || typeof channel.wsUrl !== "string" || !channel.wsUrl) return null;
+    if (!isGatewayWsUrl(channel.wsUrl)) return null;
+    return {
+      wsUrl: channel.wsUrl,
+      expiresAt: String((_a = channel.expiresAt) != null ? _a : ""),
+      lastSequence: typeof channel.lastSequence === "number" ? channel.lastSequence : 0
+    };
+  }
+}
 function toAgentChat(t) {
   return {
     id: t.id,
@@ -1113,15 +1281,16 @@ async function createChatTask(options) {
     projectId: resolveProjectId(options.projectId),
     ...options.title ? { title: options.title } : {},
     agentType: options.agentType,
-    // Autonomia é propriedade do AGENTE (createAgentMitra/updateAgentMitra no
-    // mitra-sdk): o copilot deriva do agentId — o chat de agente autônomo já
-    // nasce ownerless sem flag nenhum aqui.
+    // Autonomia é propriedade do CHAT: autonomous: true cria a task SEM dono
+    // (a dona é o agente; exige connection anexada e AGENT_WRITE). O flag no
+    // AGENTE não tem mais leitor no backend.
     ...options.agentId ? { agentId: options.agentId } : {},
+    ...options.autonomous ? { autonomous: true } : {},
     // Agir EM NOME do dono (SF/webhook/cron com AGENT_WRITE): o chat nasce
     // pertencendo a esse usuário; o turno roda com a identidade/credencial
     // DELE. Ausente = chat do caller, byte a byte como sempre.
     // Erros do backend passam crus: 403 (sem AGENT_WRITE),
-    // 400 AUTONOMOUS_TASK_HAS_NO_OWNER (userId + agente autônomo é contradição).
+    // 400 AUTONOMOUS_TASK_HAS_NO_OWNER (userId + autonomous é contradição).
     ...options.userId ? { userId: options.userId } : {}
   });
   return env.result;
@@ -1198,6 +1367,9 @@ function getAgentTaskMitra(options) {
     });
   }
   if ("create" in options && options.create) {
+    if (options.autonomous && !options.agentId) {
+      throw new Error("getAgentTaskMitra: autonomous exige agentId \u2014 o chat aut\xF4nomo pertence ao agente (e o agente precisa ter uma connection anexada).");
+    }
     return new AgentTaskSession({
       kind: "new",
       projectId: options.projectId,
@@ -1206,7 +1378,8 @@ function getAgentTaskMitra(options) {
       agentId: options.agentId,
       transport: options.transport,
       reasoningEffort: options.reasoningEffort,
-      userId: options.userId
+      userId: options.userId,
+      autonomous: options.autonomous
     });
   }
   throw new Error("getAgentTaskMitra: passe { create: true } ou { taskId }.");