mitra-interactions-sdk 1.0.60-beta.41 → 1.0.60-beta.43

package/README.md

@@ -87,6 +87,23 @@ const result = await loginWithMicrosoftMitra();
 // result: { token, baseURL, refreshToken }
 ```
 
+`create` separa a intenção do SSO sem quebrar integrações existentes:
+
+| Valor | Comportamento |
+| --- | --- |
+| omitido | Fluxo combinado compatível: autentica e cria o vínculo quando o app permite |
+| `false` | Login estrito: exige acesso efetivo existente e nunca cria o vínculo |
+| `true` | Signup explícito: cria o vínculo quando o app permite |
+
+```typescript
+await loginWithGoogleMitra({ create: false }); // Entrar
+await loginWithGoogleMitra({ create: true });  // Criar conta
+```
+
+O login estrito pode retornar `APP_ACCESS_REQUIRED` quando não existe acesso ou
+`APP_ACCESS_REVOKED` quando o vínculo foi desligado. Signup bloqueado retorna
+`SIGNUP_NOT_ALLOWED`. O mesmo campo é preservado no modo redirect.
+
 ### Login via Redirect (mobile)
 
 No celular o popup vira aba — use `mode: 'redirect'`: a página de auth navega de volta pro app com `#codeMitra`/`#stateMitra` no fragment, e o app conclui com `exchangeSsoCodeMitra`.
@@ -284,13 +301,24 @@ const existing = getAgentTaskMitra({ taskId: 'uuid-da-task' });
 await existing.loadHistory({ limit: 50 });
 ```
 
-`getAgentTaskMitra({ create: true, agentType?, name?, agentId?, reasoningEffort?, transport? })` ou `getAgentTaskMitra({ taskId, transport? })`.
+`getAgentTaskMitra({ create: true, agentType?, name?, agentId?, reasoningEffort?, transport?, userId? })` ou `getAgentTaskMitra({ taskId, transport?, userId? })`.
 
 **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 })`).
 
 - `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`.
 
+**Agir em nome do dono (`userId`)**: uma Server Function disparada por webhook/cron pode abrir e dirigir o chat de um usuário específico, em nome dele — o chat é normal, com dono; o turno roda com a identidade e a credencial do dono (connection do agente primeiro, senão a conta dele). Exige `AGENT_WRITE` no app (senão 403); o backend decide a autorização, a SDK só repassa. Tudo opcional: ausente = comportamento de sempre, byte a byte.
+
+```typescript
+// SF reagindo a webhook: continua a thread da pessoa atendida
+const task = getAgentTaskMitra({ create: true, agentId, userId: 'uuid-do-usuario' }); // chat nasce DELE
+const dela = await manageAgentChatMitra({ action: 'list', userId: 'uuid-do-usuario' }); // chats DELA
+const mesma = getAgentTaskMitra({ taskId, userId: 'uuid-do-usuario' }); // defensivo: 404 se o chat não for dela
+```
+
+Erros nomeados: `403` sem `AGENT_WRITE`; `400 AUTONOMOUS_TASK_HAS_NO_OWNER` (userId + agente autônomo é contradição); `404` quando o `userId` defensivo não bate com o dono real. Nunca invente `userId` de texto do usuário — use o id do vínculo canal→usuário da sua aplicação.
+
 #### Propriedades (somente leitura)
 
 | Propriedade | Tipo | Descrição |
@@ -348,7 +376,18 @@ const { providers } = await manageAgentCredentialMitra({ action: 'list_providers
 const { models } = await manageAgentCredentialMitra({ action: 'list_models' });
 // 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
+// harness) — monte o seletor de reasoning a partir DAQUI, nunca hardcode.
+// Round-trip: os valores vêm em minúsculo e são aceitos na entrada COMO ESTÃO.
+
+// Com agentId: o que o PRÓXIMO TURNO daquele agente consegue rodar.
+// Agente com connection → catálogo da connection, SEMPRE (é ela que roda o
+// turno, mesmo que o caller tenha credencial própria). Sem connection →
+// fallback pro catálogo da credencial do usuário.
+const doAgente = await manageAgentCredentialMitra({ action: 'list_models', agentId: 'uuid-do-agente' });
+// Erros nomeados (err.code, HTTP 400 — reaja pelo código):
+//   NO_CREDENTIAL_AVAILABLE → nenhuma credencial utilizável (nunca vem lista
+//     vazia nesse caso) — mande conectar um provider
+//   CONNECTION_NOT_FOUND    → a connection do agente não existe mais
 
 // API key
 await manageAgentCredentialMitra({ action: 'save', target: 'openai', key: 'sk-...' });

package/dist/index.d.mts

@@ -10,7 +10,12 @@ interface LoginOptions {
     mode?: 'popup' | 'redirect';
     /** URL de retorno após login com mode 'redirect'. A página de auth redirecionará de volta para esta URL com token nos query params. */
     returnTo?: string;
-    /** Se true, abre o fluxo de criar conta em vez de login. */
+    /**
+     * Controls the SSO intent sent to POST /auth/{provider}.
+     * Omitted preserves the combined legacy behavior. `false` performs a strict
+     * login without creating app access. `true` performs signup and may create
+     * app access when signup is allowed.
+     */
     create?: boolean;
     /** Título exibido na página de auth (ex: nome da aplicação). */
     title?: string;
@@ -243,6 +248,11 @@ interface ManageAgentChatListOptions {
     projectId?: number | string;
     /** Filtra os chats de um agente business específico. Omitido = todos os chats. */
     agentId?: string;
+    /**
+     * Em nome de outro usuário (exige AGENT_WRITE no app; senão 403): lista os
+     * chats DELE em vez dos do caller. Omitido = chats de quem chama, como sempre.
+     */
+    userId?: string;
     /** Inclui só arquivados (true) ou só ativos (false, default). */
     archived?: boolean;
     /** Busca por título. */
@@ -308,6 +318,17 @@ interface GetAgentTaskCreateOptions {
      * automaticamente — não existe flag aqui; exige auth AGENT_WRITE.
      */
     agentId?: string;
+    /**
+     * Agir EM NOME do dono do chat (exige AGENT_WRITE no app; senão 403) — o
+     * chat nasce pertencendo a esse usuário e o turno roda com a identidade e a
+     * credencial DELE (connection do agente primeiro, senão a conta do dono).
+     * Uso típico: Server Function reagindo a webhook/cron/canal externo que
+     * continua a thread da pessoa atendida. NUNCA invente userId a partir de
+     * texto — use o id que a aplicação já tem no vínculo canal→usuário.
+     * Omitido = chat do caller, byte a byte como sempre.
+     * Com agente AUTÔNOMO é contradição: 400 AUTONOMOUS_TASK_HAS_NO_OWNER.
+     */
+    userId?: string;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
 }
@@ -318,6 +339,12 @@ interface GetAgentTaskOpenOptions {
     projectId?: number | string;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
+    /**
+     * Validação defensiva ao agir em nome do dono (AGENT_WRITE): viaja no
+     * readChat e nos inputs — o backend devolve 404 se o chat não pertencer a
+     * esse usuário. Omitido = contexto do caller.
+     */
+    userId?: string;
 }
 type GetAgentTaskOptions = GetAgentTaskCreateOptions | GetAgentTaskOpenOptions;
 type AgentTaskStatus = 'opening' | 'idle' | 'streaming' | 'cancelled' | 'error' | 'closed';
@@ -336,8 +363,9 @@ interface SendOptions {
      * 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).
+     * (INVALID_REASONING_EFFORT). Sobrescreve o default da session; round-trip —
+     * a SDK envia o valor COMO ESTÁ (minúsculo), sem normalizar. Omitido = herda
+     * o default da abertura (ou o do backend).
      */
     reasoningEffort?: string;
     /**
@@ -448,6 +476,8 @@ interface AgentModel {
      * ['none','minimal','low','medium','high','xhigh','max','ultra'].
      * A UI monta o seletor a partir DAQUI; valor fora do registro é recusado
      * pelo copilot (INVALID_REASONING_EFFORT).
+     * ROUND-TRIP: os valores vêm em minúsculo e são aceitos na entrada COMO
+     * ESTÃO — a SDK não normaliza (não maiusculize, não traduza).
      * ATENÇÃO: a lista de models vem VAZIA enquanto nenhuma credencial/connection
      * estiver conectada (o catálogo é escopado pelo que dá pra rodar) — o seletor
      * só existe depois de conectar um provider e escolher um modelo.
@@ -483,6 +513,7 @@ type ManageAgentCredentialOptions = {
     projectId?: number | string;
 } | {
     action: 'list_models';
+    agentId?: string;
     projectId?: number | string;
 } | {
     action: 'save';
@@ -656,7 +687,7 @@ declare function getAgentTaskMitra(options: GetAgentTaskOptions): AgentTaskSessi
  * Função ÚNICA `manageAgentCredentialMitra`, toda HTTP pela BFF no baseURL
  * normal (`/agentAiShortcut/*`) — herda fetchWithRefresh e o CORS do BFF:
  *   - list_providers → GET  /agentAiShortcut/listProviders?projectId=
- *   - list_models    → GET  /agentAiShortcut/listModels?projectId=
+ *   - list_models    → GET  /agentAiShortcut/listModels?projectId=&agentId=  (agentId opcional)
  *   - save           → POST /agentAiShortcut/saveCredential   {projectId, provider, key}
  *   - remove         → POST /agentAiShortcut/removeCredential {projectId, provider}
  *   - auth           → POST /agentAiShortcut/oauthStart       {projectId, provider}
@@ -681,6 +712,7 @@ declare function manageAgentCredentialMitra(options: {
 }): Promise<ListAgentProvidersResult>;
 declare function manageAgentCredentialMitra(options: {
     action: 'list_models';
+    agentId?: string;
     projectId?: number | string;
 }): Promise<ListAgentModelsResult>;
 declare function manageAgentCredentialMitra(options: {

package/dist/index.d.ts

@@ -10,7 +10,12 @@ interface LoginOptions {
     mode?: 'popup' | 'redirect';
     /** URL de retorno após login com mode 'redirect'. A página de auth redirecionará de volta para esta URL com token nos query params. */
     returnTo?: string;
-    /** Se true, abre o fluxo de criar conta em vez de login. */
+    /**
+     * Controls the SSO intent sent to POST /auth/{provider}.
+     * Omitted preserves the combined legacy behavior. `false` performs a strict
+     * login without creating app access. `true` performs signup and may create
+     * app access when signup is allowed.
+     */
     create?: boolean;
     /** Título exibido na página de auth (ex: nome da aplicação). */
     title?: string;
@@ -243,6 +248,11 @@ interface ManageAgentChatListOptions {
     projectId?: number | string;
     /** Filtra os chats de um agente business específico. Omitido = todos os chats. */
     agentId?: string;
+    /**
+     * Em nome de outro usuário (exige AGENT_WRITE no app; senão 403): lista os
+     * chats DELE em vez dos do caller. Omitido = chats de quem chama, como sempre.
+     */
+    userId?: string;
     /** Inclui só arquivados (true) ou só ativos (false, default). */
     archived?: boolean;
     /** Busca por título. */
@@ -308,6 +318,17 @@ interface GetAgentTaskCreateOptions {
      * automaticamente — não existe flag aqui; exige auth AGENT_WRITE.
      */
     agentId?: string;
+    /**
+     * Agir EM NOME do dono do chat (exige AGENT_WRITE no app; senão 403) — o
+     * chat nasce pertencendo a esse usuário e o turno roda com a identidade e a
+     * credencial DELE (connection do agente primeiro, senão a conta do dono).
+     * Uso típico: Server Function reagindo a webhook/cron/canal externo que
+     * continua a thread da pessoa atendida. NUNCA invente userId a partir de
+     * texto — use o id que a aplicação já tem no vínculo canal→usuário.
+     * Omitido = chat do caller, byte a byte como sempre.
+     * Com agente AUTÔNOMO é contradição: 400 AUTONOMOUS_TASK_HAS_NO_OWNER.
+     */
+    userId?: string;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
 }
@@ -318,6 +339,12 @@ interface GetAgentTaskOpenOptions {
     projectId?: number | string;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
+    /**
+     * Validação defensiva ao agir em nome do dono (AGENT_WRITE): viaja no
+     * readChat e nos inputs — o backend devolve 404 se o chat não pertencer a
+     * esse usuário. Omitido = contexto do caller.
+     */
+    userId?: string;
 }
 type GetAgentTaskOptions = GetAgentTaskCreateOptions | GetAgentTaskOpenOptions;
 type AgentTaskStatus = 'opening' | 'idle' | 'streaming' | 'cancelled' | 'error' | 'closed';
@@ -336,8 +363,9 @@ interface SendOptions {
      * 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).
+     * (INVALID_REASONING_EFFORT). Sobrescreve o default da session; round-trip —
+     * a SDK envia o valor COMO ESTÁ (minúsculo), sem normalizar. Omitido = herda
+     * o default da abertura (ou o do backend).
      */
     reasoningEffort?: string;
     /**
@@ -448,6 +476,8 @@ interface AgentModel {
      * ['none','minimal','low','medium','high','xhigh','max','ultra'].
      * A UI monta o seletor a partir DAQUI; valor fora do registro é recusado
      * pelo copilot (INVALID_REASONING_EFFORT).
+     * ROUND-TRIP: os valores vêm em minúsculo e são aceitos na entrada COMO
+     * ESTÃO — a SDK não normaliza (não maiusculize, não traduza).
      * ATENÇÃO: a lista de models vem VAZIA enquanto nenhuma credencial/connection
      * estiver conectada (o catálogo é escopado pelo que dá pra rodar) — o seletor
      * só existe depois de conectar um provider e escolher um modelo.
@@ -483,6 +513,7 @@ type ManageAgentCredentialOptions = {
     projectId?: number | string;
 } | {
     action: 'list_models';
+    agentId?: string;
     projectId?: number | string;
 } | {
     action: 'save';
@@ -656,7 +687,7 @@ declare function getAgentTaskMitra(options: GetAgentTaskOptions): AgentTaskSessi
  * Função ÚNICA `manageAgentCredentialMitra`, toda HTTP pela BFF no baseURL
  * normal (`/agentAiShortcut/*`) — herda fetchWithRefresh e o CORS do BFF:
  *   - list_providers → GET  /agentAiShortcut/listProviders?projectId=
- *   - list_models    → GET  /agentAiShortcut/listModels?projectId=
+ *   - list_models    → GET  /agentAiShortcut/listModels?projectId=&agentId=  (agentId opcional)
  *   - save           → POST /agentAiShortcut/saveCredential   {projectId, provider, key}
  *   - remove         → POST /agentAiShortcut/removeCredential {projectId, provider}
  *   - auth           → POST /agentAiShortcut/oauthStart       {projectId, provider}
@@ -681,6 +712,7 @@ declare function manageAgentCredentialMitra(options: {
 }): Promise<ListAgentProvidersResult>;
 declare function manageAgentCredentialMitra(options: {
     action: 'list_models';
+    agentId?: string;
     projectId?: number | string;
 }): Promise<ListAgentModelsResult>;
 declare function manageAgentCredentialMitra(options: {

package/dist/index.js

@@ -86,11 +86,12 @@ function stripToOriginPath(url) {
     return url.split("?")[0].split("#")[0];
   }
 }
-async function exchangeSsoCode(authUrl, provider, code, redirectUri, projectId) {
+async function exchangeSsoCode(authUrl, provider, code, redirectUri, projectId, create) {
   const data = await postBffAuth(buildBffAuthEndpoint(authUrl, `/${provider}`), {
     appId: String(projectId),
     code,
-    redirectUri
+    redirectUri,
+    ...create !== void 0 ? { create } : {}
   });
   const response = {
     token: data.token,
@@ -229,7 +230,10 @@ async function loginWithProvider(provider, options) {
       const startUrl = buildStartUrl(authPageUrl, provider, state, appId, authUrl);
       const { code, token } = await openOAuthPopup(startUrl, pageOrigin, state);
       if (code) {
-        return await exchangeSsoCode(authUrl, provider, code, redirectUri, projectId);
+        return await exchangeSsoCode(authUrl, provider, code, redirectUri, projectId, options == null ? void 0 : options.create);
+      }
+      if ((options == null ? void 0 : options.create) !== void 0) {
+        throw new Error("Explicit SSO intent requires an auth page that returns the authorization code.");
       }
       const response = normalizeResponse(token, authUrl);
       autoConfigureFromLogin(response, authUrl, projectId);
@@ -246,7 +250,14 @@ async function startSsoRedirect(provider, options) {
   const appId = String(projectId);
   const authPageUrl = await fetchSsoAuthPageUrl();
   const redirectUri = stripToOriginPath(authPageUrl);
-  persistRedirectContext({ state, provider, authUrl, projectId: appId, redirectUri });
+  persistRedirectContext({
+    state,
+    provider,
+    authUrl,
+    projectId: appId,
+    redirectUri,
+    ...(options == null ? void 0 : options.create) !== void 0 ? { create: options.create } : {}
+  });
   const startUrl = buildStartUrl(authPageUrl, provider, state, appId, authUrl, window.location.href);
   window.location.assign(startUrl);
   return new Promise(() => {
@@ -258,7 +269,14 @@ async function exchangeSsoCodeMitra(options) {
   if (!ctx || ctx.state !== options.state) {
     throw new Error("State inv\xE1lido no retorno do SSO (poss\xEDvel CSRF).");
   }
-  return exchangeSsoCode(ctx.authUrl, ctx.provider, options.code, ctx.redirectUri, ctx.projectId);
+  return exchangeSsoCode(
+    ctx.authUrl,
+    ctx.provider,
+    options.code,
+    ctx.redirectUri,
+    ctx.projectId,
+    ctx.create
+  );
 }
 async function loginWithGoogleMitra(options) {
   return loginWithProvider("google", options);
@@ -342,15 +360,18 @@ async function tryRefreshToken() {
   }
 }
 async function handleResponse(response) {
+  var _a, _b, _c, _d;
   const text = await response.text();
   const { data, isJson } = parseBody(text);
   if (!response.ok) {
     const fallback = !isJson && text ? `HTTP ${response.status} \u2014 ${text}` : `HTTP ${response.status}`;
-    const base = isJson && ((data == null ? void 0 : data.message) || (data == null ? void 0 : data.error)) || fallback;
+    const base = isJson && ((data == null ? void 0 : data.message) || ((_a = data == null ? void 0 : data.error) == null ? void 0 : _a.message) || (data == null ? void 0 : data.error)) || fallback;
     const msg = isJson && (data == null ? void 0 : data.hint) ? `${base} \u2014 ${data.hint}` : base;
+    const code = isJson && ((_d = (_c = data == null ? void 0 : data.error_code) != null ? _c : (_b = data == null ? void 0 : data.error) == null ? void 0 : _b.code) != null ? _d : data == null ? void 0 : data.code) || void 0;
     throw {
-      message: msg,
+      message: typeof msg === "string" ? msg : fallback,
       status: response.status,
+      ...code ? { code } : {},
       details: data
     };
   }
@@ -483,6 +504,7 @@ var AgentTaskSession = class {
     this._isNew = init.kind === "new";
     this._transport = (_a = init.transport) != null ? _a : "ws";
     this._projectId = init.projectId;
+    this._userId = init.userId;
     if (init.kind === "new") {
       this._agentType = (_b = init.agentType) != null ? _b : DEFAULT_AGENT_TYPE;
       this._initialName = init.name;
@@ -521,7 +543,7 @@ var AgentTaskSession = class {
   // ── Abertura de chat existente ─────────
   async _openExisting(taskId) {
     try {
-      const t = await readChatTask(taskId, this._projectId);
+      const t = await readChatTask(taskId, this._projectId, this._userId);
       this._task = toAgentChat(t);
       this._agentType = this._task.agentType;
       if (this._status === "opening") this._setStatus("idle");
@@ -546,9 +568,10 @@ var AgentTaskSession = class {
   }
   /**
    * Corpo do input `message` — idêntico no WS e no POST /inputs.
-   * reasoningEffort: da mensagem, senão o default da session; enviado em
-   * MAIÚSCULO (contrato do copilot). agentType por mensagem troca o modelo
-   * dentro do mesmo harness (Claude<->Codex é recusado com HARNESS_SWITCH).
+   * reasoningEffort: da mensagem, senão o default da session; round-trip com
+   * reasoningOptions do list_models — vai COMO ESTÁ (minúsculo), sem
+   * normalizar. agentType por mensagem troca o modelo dentro do mesmo harness
+   * (Claude<->Codex é recusado com HARNESS_SWITCH).
    */
   _buildMessageInput(prompt, options) {
     var _a;
@@ -556,7 +579,9 @@ var AgentTaskSession = class {
     return {
       type: "message",
       content: prompt,
-      ...effort ? { reasoningEffort: String(effort).toUpperCase() } : {},
+      // Round-trip com list_models: o valor de reasoningOptions vai COMO ESTÁ
+      // (minúsculo) — a SDK não normaliza.
+      ...effort ? { reasoningEffort: String(effort) } : {},
       ...(options == null ? void 0 : options.agentType) ? { agentType: options.agentType } : {}
     };
   }
@@ -573,7 +598,8 @@ var AgentTaskSession = class {
             projectId: this._projectId,
             title: this._initialName,
             agentType: this._agentType,
-            agentId: this._agentId
+            agentId: this._agentId,
+            userId: this._userId
           });
           this._task = toAgentChat(t);
           this._taskId = this._task.id;
@@ -721,6 +747,7 @@ var AgentTaskSession = class {
       throw new Error("AgentTaskSession: sem taskId \u2014 task ainda n\xE3o criada.");
     }
     if (isTokenExpiring()) await tryRefreshToken();
+    const payload = this._userId ? { ...body, userId: this._userId } : body;
     const doPost = async () => fetch(
       `${getTaskHttpBase()}/${encodeURIComponent(this._taskId)}/inputs`,
       {
@@ -729,7 +756,7 @@ var AgentTaskSession = class {
           "Content-Type": "application/json",
           Authorization: `Bearer ${getRawToken()}`
         },
-        body: JSON.stringify(body)
+        body: JSON.stringify(payload)
       }
     );
     let res = await doPost();
@@ -1051,14 +1078,23 @@ async function createChatTask(options) {
     // 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.
-    ...options.agentId ? { agentId: options.agentId } : {}
+    ...options.agentId ? { agentId: options.agentId } : {},
+    // 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).
+    ...options.userId ? { userId: options.userId } : {}
   });
   return env.result;
 }
-async function readChatTask(taskId, projectId) {
+async function readChatTask(taskId, projectId, userId) {
   const env = await http.get("/agentAiShortcut/readChat", {
     projectId: resolveProjectId(projectId),
-    taskId
+    taskId,
+    // Validação defensiva: com userId, o backend devolve 404 se o chat não
+    // pertencer àquele dono.
+    ...userId ? { userId } : {}
   });
   return env.result;
 }
@@ -1086,6 +1122,8 @@ async function manageAgentChatMitra(options) {
     const env = await http.get("/agentAiShortcut/listChats", {
       projectId,
       agentId: options.agentId,
+      // Em nome de outro usuário (AGENT_WRITE): lista os chats DELE, não os do caller.
+      userId: options.userId,
       archived: options.archived,
       search: options.search,
       page: options.page,
@@ -1121,7 +1159,8 @@ function getAgentTaskMitra(options) {
       kind: "existing",
       taskId: options.taskId,
       projectId: options.projectId,
-      transport: options.transport
+      transport: options.transport,
+      userId: options.userId
     });
   }
   if ("create" in options && options.create) {
@@ -1132,7 +1171,8 @@ function getAgentTaskMitra(options) {
       name: options.name,
       agentId: options.agentId,
       transport: options.transport,
-      reasoningEffort: options.reasoningEffort
+      reasoningEffort: options.reasoningEffort,
+      userId: options.userId
     });
   }
   throw new Error("getAgentTaskMitra: passe { create: true } ou { taskId }.");
@@ -1158,7 +1198,10 @@ async function manageAgentCredentialMitra(options) {
       return { providers: (_a = env.result) != null ? _a : [] };
     }
     case "list_models": {
-      const env = await http.get("/agentAiShortcut/listModels", { projectId });
+      const env = await http.get("/agentAiShortcut/listModels", {
+        projectId,
+        ...options.agentId ? { agentId: options.agentId } : {}
+      });
       return { models: (_b = env.result) != null ? _b : [] };
     }
     case "save": {