@theokit/agents 6.2.0 → 6.3.1

package/dist/auth.d.ts

@@ -1,4 +1,4 @@
-import { OAuthProviderConfig, CredentialStoreConfig, ResolvedCredential, ensureFreshCredential, OpenAIDeviceConfig, openaiDeviceLogin, OAuthTokens } from '@theokit/sdk/auth';
+import { OAuthProviderConfig, CredentialStoreConfig, ResolvedCredential, ensureFreshCredential, OpenAIDeviceConfig, openaiDeviceLogin, OAuthTokens, DeviceDeps } from '@theokit/sdk/auth';
 export { CredentialError, CredentialStoreConfig, DeviceCodeGrant, DeviceDeps, DeviceOAuthConfig, OAuthProviderConfig, OAuthTokens, OpenAIDeviceConfig, ResolveCredentialOptions, ResolvedCredential, authFilePath, credentialHome, deviceLogin, openaiDeviceLogin, pollDeviceToken, readAuthFile, readStoredOAuth, requestDeviceCode, writeCredential } from '@theokit/sdk/auth';
 
 /**
@@ -54,4 +54,116 @@ declare class AuthProvider {
     persist(provider: string, tokens: OAuthTokens, env?: Record<string, string | undefined>): string;
 }
 
-export { AuthProvider };
+/**
+ * M111 — device auth plug-and-play: um provider é um objeto com métodos ROTULADOS, e um login cabe
+ * numa chamada.
+ *
+ * ## O problema, medido
+ *
+ * O M110 fez o device flow RFC 8628 atravessar esta camada. Ele não tocou a ergonomia: para
+ * autenticar no Codex, o consumidor precisava saber que existem **duas** formas de device flow,
+ * copiar um `clientId` e três URLs da OpenAI para dentro do próprio código, montar
+ * `{ fetch, sleep, now }`, chamar `deviceLogin` e **lembrar** de chamar `persist` — e esquecer o
+ * último custa um round-trip OAuth completo que não guarda nada. O docblock de `AuthProvider`
+ * instruía exatamente isso: *"the caller persists them via `AuthProvider.persist`"*.
+ *
+ * ## O desenho veio de medição contra três peers, e refutou a proposta original
+ *
+ * - **`codex`** — `codex-rs/login/src/device_code_auth.rs:234` tem `run_device_code_login`, que
+ *   retorna `()`: **nada** sai para o chamador persistir, e as duas metades granulares continuam
+ *   públicas. `loginWithDevice` é a cópia dessa forma.
+ * - **`opencode`** — cada provider é um objeto com `methods: [{ label, type, authorize }]`, e três
+ *   providers escritos por autores diferentes convergem em **3 métodos rotulados** cada. O rótulo é o
+ *   que a UI mostra: transforma escolha de protocolo em escolha de frase legível.
+ * - **REJEITADO — discriminante `kind`.** Nenhum dos três discrimina protocolo por campo. A medição
+ *   que fecha o caso: no `opencode`, browser e headless do Codex carregam o **mesmo** `type: 'oauth'`
+ *   — logo o `type` classifica **espécie de credencial**, não protocolo. Um `kind` com despacho
+ *   interno seria um `switch`, exatamente o defeito que este milestone remove do consumidor.
+ *   Aqui, cada método aponta para a **sua própria** função.
+ *
+ * ## Por que a identidade pública mora AQUI
+ *
+ * `codex` exporta `CLIENT_ID` do crate que implementa o flow (`login/src/lib.rs:32`) e o CLI o
+ * **importa**; o `opencode` o declara dentro do plugin. Os dois chegaram ao mesmo lugar
+ * independentemente — e com o mesmo valor que o consumidor tinha copiado. Enquanto morasse no
+ * consumidor, todo projeto que quisesse Codex copiaria quatro constantes públicas: é violação de DRY
+ * através da fronteira, com dois donos do mesmo fato.
+ */
+/**
+ * Uma forma rotulada de obter credencial dentro de um provider.
+ *
+ * UNIÃO DISCRIMINADA, não um campo `authorize?` opcional. Com opcional, `{ label, type: 'oauth' }`
+ * seria representável — um método OAuth que não sabe autorizar, detectado só em runtime, no meio do
+ * login do usuário. É a alternativa que o M110 já rejeitou por escrito ao recusar "um tipo só com
+ * campos opcionais": tornaria representável um config inválido e moveria a detecção do compilador
+ * para o runtime.
+ */
+type AuthMethod = {
+    /** O que a interface mostra ao usuário. É a peça que torna o fluxo escolhível sem saber o protocolo. */
+    readonly label: string;
+    readonly type: 'oauth';
+    /** A função DESTE método. Sem discriminante: o método aponta para a sua, não para um `switch`. */
+    readonly authorize: (deps: DeviceDeps, hooks: PromptHooks) => Promise<OAuthTokens>;
+} | {
+    readonly label: string;
+    readonly type: 'api';
+};
+/** O que o consumidor liga à sua UI para mostrar o código que o usuário digita no outro dispositivo. */
+interface PromptHooks {
+    onPrompt: (p: {
+        userCode: string;
+        verificationUri: string;
+        expiresIn?: number;
+    }) => void;
+}
+/** Um provider de autenticação: identidade pública + as formas rotuladas de autenticar nele. */
+interface DeviceAuthProvider {
+    readonly name: string;
+    readonly oauth: OAuthProviderConfig;
+    readonly methods: readonly AuthMethod[];
+}
+/**
+ * Override do `clientId` por ambiente — adotado do `codex`, que exporta `CLIENT_ID` **e**
+ * `CLIENT_ID_OVERRIDE_ENV_VAR` (`login/src/lib.rs:32-33`). Dissolve o falso dilema entre constante
+ * fixa (inflexível) e parâmetro obrigatório (que devolve a cópia ao consumidor): default no pacote,
+ * escape para quem precisa.
+ */
+declare const CODEX_CLIENT_ID_ENV_VAR = "THEOKIT_CODEX_CLIENT_ID";
+/**
+ * O provider do Codex, montado e **congelado**.
+ *
+ * Congelado porque é identidade pública COMPARTILHADA no processo: um consumidor que a mutasse
+ * mudaria o login de todos os outros. `Object.freeze` é raso, então a lista de métodos é congelada
+ * separadamente — sem isso, `CODEX_PROVIDER.methods.push(...)` passaria.
+ */
+declare const CODEX_PROVIDER: DeviceAuthProvider;
+/**
+ * Opções do Facade. `deps` e `env` viajam juntos num objeto em vez de dois parâmetros posicionais:
+ * ambos são opcionais e raramente usados, e seis posicionais é assinatura que o chamador erra em
+ * silêncio (o lint do monorepo cobra 5 como teto — o teto existe por este motivo).
+ */
+interface LoginWithDeviceOptions {
+    /** Injeção de I/O para teste. Omitido, usa `fetch`/`setTimeout`/`Date.now` reais. */
+    readonly deps?: Partial<DeviceDeps>;
+    /** Ambiente lido pelo store para resolver o diretório da credencial. */
+    readonly env?: Record<string, string | undefined>;
+}
+/**
+ * Autoriza **e** persiste, numa chamada. Devolve onde a credencial ficou e a conta atribuída —
+ * **nunca** material de token.
+ *
+ * A forma vem de `run_device_code_login` (`codex`), que retorna `()`: se nada sai para o chamador,
+ * não há passo que ele possa esquecer. As duas metades continuam públicas em `AuthProvider`
+ * (`deviceLogin` / `persist`) para quem precisa da granularidade — mesma escolha que o `codex` faz ao
+ * manter `request_device_code` e `complete_device_code_login` públicas ao lado do Facade.
+ *
+ * Delega verbatim: `method.authorize` roda o flow e `AuthProvider.persist` grava. Copiar a sequência
+ * em vez de chamá-la criaria um segundo oráculo sobre o mesmo fato, e dois oráculos divergem no
+ * primeiro fix aplicado a um lado só.
+ */
+declare function loginWithDevice(provider: DeviceAuthProvider, method: AuthMethod, store: CredentialStoreConfig, hooks: PromptHooks, opts?: LoginWithDeviceOptions): Promise<{
+    path: string;
+    accountId?: string;
+}>;
+
+export { type AuthMethod, AuthProvider, CODEX_CLIENT_ID_ENV_VAR, CODEX_PROVIDER, type DeviceAuthProvider, type PromptHooks, loginWithDevice };

package/dist/auth.js

@@ -123,14 +123,87 @@ var AuthProvider = class _AuthProvider {
 
 // src/auth-entry.ts
 import { authFilePath as authFilePath2, CredentialError, credentialHome, readAuthFile, readStoredOAuth as readStoredOAuth2, writeCredential } from "@theokit/sdk/auth";
-import { deviceLogin, openaiDeviceLogin as openaiDeviceLogin2, pollDeviceToken, requestDeviceCode } from "@theokit/sdk/auth";
+import { deviceLogin, openaiDeviceLogin as openaiDeviceLogin3, pollDeviceToken, requestDeviceCode } from "@theokit/sdk/auth";
+
+// src/auth/device-provider.ts
+import { openaiDeviceLogin as openaiDeviceLogin2 } from "@theokit/sdk/auth";
+var CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+var CODEX_ISSUER = "https://auth.openai.com";
+var CODEX_CLIENT_ID_ENV_VAR = "THEOKIT_CODEX_CLIENT_ID";
+var CODEX_OAUTH = {
+  provider: "openai",
+  clientId: process.env[CODEX_CLIENT_ID_ENV_VAR] ?? CODEX_CLIENT_ID,
+  authorizeEndpoint: `${CODEX_ISSUER}/oauth/authorize`,
+  tokenEndpoint: `${CODEX_ISSUER}/oauth/token`,
+  scopes: [
+    "openid",
+    "profile",
+    "email",
+    "offline_access"
+  ],
+  redirectUri: `${CODEX_ISSUER}/deviceauth/callback`
+};
+var CODEX_DEVICE = {
+  ...CODEX_OAUTH,
+  deviceUsercodeEndpoint: `${CODEX_ISSUER}/api/accounts/deviceauth/usercode`,
+  devicePollEndpoint: `${CODEX_ISSUER}/api/accounts/deviceauth/token`,
+  verificationUri: `${CODEX_ISSUER}/codex/device`
+};
+var CODEX_PROVIDER = Object.freeze({
+  name: "openai",
+  oauth: Object.freeze(CODEX_OAUTH),
+  methods: Object.freeze([
+    Object.freeze({
+      label: "ChatGPT Pro/Plus (headless device code)",
+      type: "oauth",
+      // Aponta para a variante da OpenAI. Um provider RFC 8628 apontaria para `deviceLogin`, e é
+      // assim que as duas formas coexistem sem discriminante.
+      authorize: /* @__PURE__ */ __name((deps, hooks) => openaiDeviceLogin2(CODEX_DEVICE, deps, hooks), "authorize")
+    }),
+    Object.freeze({
+      label: "Manually enter API Key",
+      type: "api"
+    })
+  ])
+});
+function comDefaults(deps) {
+  return {
+    fetch: deps?.fetch ?? fetch,
+    sleep: deps?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    now: deps?.now ?? Date.now
+  };
+}
+__name(comDefaults, "comDefaults");
+async function loginWithDevice(provider, method, store, hooks, opts = {}) {
+  if (provider.methods.length === 0) {
+    throw new TypeError(`o provider "${provider.name}" declara nenhum m\xE9todo de autentica\xE7\xE3o \u2014 n\xE3o h\xE1 o que escolher`);
+  }
+  if (!provider.methods.includes(method)) {
+    throw new TypeError(`o m\xE9todo "${method.label}" n\xE3o pertence ao provider "${provider.name}"`);
+  }
+  if (method.type !== "oauth") {
+    throw new TypeError(`o m\xE9todo "${method.label}" \xE9 de chave (api key), n\xE3o \xE9 um m\xE9todo de device \u2014 use o caminho de chave`);
+  }
+  const tokens = await method.authorize(comDefaults(opts.deps), hooks);
+  const path = new AuthProvider(provider.oauth, store).persist(provider.name, tokens, opts.env);
+  return tokens.accountId === void 0 ? {
+    path
+  } : {
+    path,
+    accountId: tokens.accountId
+  };
+}
+__name(loginWithDevice, "loginWithDevice");
 export {
   AuthProvider,
+  CODEX_CLIENT_ID_ENV_VAR,
+  CODEX_PROVIDER,
   CredentialError,
   authFilePath2 as authFilePath,
   credentialHome,
   deviceLogin,
-  openaiDeviceLogin2 as openaiDeviceLogin,
+  loginWithDevice,
+  openaiDeviceLogin3 as openaiDeviceLogin,
   pollDeviceToken,
   readAuthFile,
   readStoredOAuth2 as readStoredOAuth,

package/dist/auth.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/auth/auth-provider.ts","../src/auth-entry.ts"],"sourcesContent":["import {\n  authFilePath,\n  ensureFreshCredential,\n  openaiDeviceLogin,\n  persistOAuthTokens,\n  readStoredOAuth,\n} from '@theokit/sdk/auth'\nimport type {\n  CredentialStoreConfig,\n  OAuthProviderConfig,\n  OAuthTokens,\n  OpenAIDeviceConfig,\n  ResolvedCredential,\n} from '@theokit/sdk/auth'\nimport { withFileLock } from '@theokit/sdk/persistence'\n\n/**\n * M60 — `AuthProvider`, the OO contract that unifies the SDK's free OAuth-lifecycle functions\n * (`openaiDeviceLogin` → `persistOAuthTokens` → `ensureFreshCredential`). Those are stateful across a\n * SHARED `config` (`OAuthProviderConfig`) + `store` (`CredentialStoreConfig`); this class holds that\n * state so a consumer authors `new AuthProvider(config, store).persist(...)` / `.ensureFresh(...)`\n * instead of threading `config`/`store` through every call — the `SDK → Theokit → AgentBuilder`\n * boundary applied to the auth domain (ENRICH, per blueprint D2: auth carries orchestration + state).\n *\n * It DELEGATES, never reimplements (parsimony Rung 9): each method forwards verbatim to the SDK\n * function, so login → persist → refresh produces byte-identical state to calling the SDK directly.\n *\n * SECRET-SAFETY (hard rule): this class NEVER logs, stringifies, or otherwise surfaces token material.\n * Methods return exactly what the SDK returns and add no observability — a token is data that flows\n * through, never something this layer emits. The parity/secret tests pin both properties.\n */\n\n/** The HTTP deps of `ensureFreshCredential` (`{ fetch, now }`) — typed off the SDK to avoid drift. */\ntype EnsureFreshHttpDeps = Parameters<typeof ensureFreshCredential>[2]\n/** The device-flow deps + prompt hook of `openaiDeviceLogin` — typed off the SDK. */\ntype DeviceLoginDeps = Parameters<typeof openaiDeviceLogin>[1]\ntype DeviceLoginHooks = Parameters<typeof openaiDeviceLogin>[2]\n\n/**\n * Falha de refresh, classificada — porque a decisão de tentar de novo depende da classe, não do texto.\n *\n * M74: repetir um `invalid_grant` não é resiliência, é ruído. O refresh token foi revogado e nenhuma\n * tentativa muda isso; o usuário que revogou o login espera três backoffs para ler uma mensagem que já\n * era conhecida na primeira resposta. Rede e 5xx são o oposto: quase sempre passam na segunda.\n *\n * SECRET-SAFETY: a mensagem nunca carrega material de token — só a classe e o motivo.\n */\nexport class RefreshFailure extends Error {\n  constructor(\n    message: string,\n    /** `true` ⇒ vale tentar de novo com backoff. `false` ⇒ terminal, falha na primeira. */\n    readonly transitorio: boolean,\n  ) {\n    super(message)\n    this.name = 'RefreshFailure'\n  }\n}\n\n/**\n * O que conta como transitório. Lista NOMEADA de propósito: é decisão de produto que envelhece, e\n * espalhá-la em `if` faz cada sítio envelhecer sozinho.\n */\nconst MOTIVOS_TRANSITORIOS = [\n  'ETIMEDOUT',\n  'ECONNRESET',\n  'ECONNREFUSED',\n  'EAI_AGAIN',\n  'ENOTFOUND',\n  'AbortError',\n]\n\n/** Classifica uma falha de refresh. `invalid_grant` é terminal; rede e 5xx são transitórios. */\nexport function classificarFalhaDeRefresh(err: unknown): RefreshFailure {\n  const texto = err instanceof Error ? `${err.name}: ${err.message}` : String(err)\n  if (/invalid_grant|invalid_request|unauthorized_client/i.test(texto)) {\n    return new RefreshFailure(\n      'o refresh token não é mais válido — refaça o login. Tentar de novo não muda o resultado.',\n      false,\n    )\n  }\n  const transitorio =\n    MOTIVOS_TRANSITORIOS.some((m) => texto.includes(m)) ||\n    /\\b(5\\d{2})\\b|timeout|network/i.test(texto)\n  return new RefreshFailure(\n    transitorio ? 'falha transitória ao refrescar a credencial' : 'falha ao refrescar a credencial',\n    transitorio,\n  )\n}\n\n/** Espera com jitter: backoff exponencial ±25%, para dois processos não retentarem em uníssono. */\nexport function esperaComJitter(tentativa: number, baseMs = 200, aleatorio = Math.random): number {\n  const base = baseMs * 2 ** tentativa\n  return Math.round(base * (0.75 + aleatorio() * 0.5))\n}\n\nexport class AuthProvider {\n  constructor(\n    private readonly config: OAuthProviderConfig,\n    private readonly store: CredentialStoreConfig,\n  ) {}\n\n  /**\n   * Refresh a resolved credential if stale. Delegates to `ensureFreshCredential` with the held\n   * `config` + `store`; `env` (for reading the store's env overrides) + the `{ fetch, now }` HTTP deps\n   * thread through. Returns the fresh `ResolvedCredential` — never logs the rotated token.\n   */\n  async ensureFresh(\n    resolved: ResolvedCredential,\n    deps: EnsureFreshHttpDeps,\n    env?: Record<string, string | undefined>,\n  ): Promise<ResolvedCredential> {\n    if (resolved.kind !== 'oauth') {\n      // Chave de API não expira: nenhum lock, nenhuma releitura, nenhum I/O. Manter o caminho quente\n      // livre é o que torna o resolvedor por-run barato (M74, Risco 1).\n      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- `CredentialStoreConfig` do subpath /auth resolve sob tsc; o projeto type-aware do eslint o lê como error-typed.\n      return ensureFreshCredential(resolved, { config: this.config, store: this.store, env }, deps)\n    }\n\n    const caminho: string = authFilePath(this.store, env)\n\n    // SINGLE-FLIGHT in-process, ANTES do lock (M74, EC-2 do edge-case review).\n    //\n    // `withFileLock` (proper-lockfile) NÃO é reentrante: se uma run começar de dentro de um contexto\n    // que já segura o lock — uma run aninhada, ou um time disparando membros enquanto o pai refresca —\n    // a segunda aquisição espera até o timeout e o sintoma é \"a run travou\", sem erro nenhum. Com o\n    // resolvedor por-run do M74 isso deixa de ser hipotético: `ensureFresh` passa a ser chamado de\n    // dentro do stream. A promise em voo faz a reentrância resolver por composição, não por lock.\n    const emVoo = AuthProvider.refreshEmVoo.get(caminho)\n    if (emVoo !== undefined) return emVoo\n\n    const promessa = this.refrescarSobLock(caminho, resolved, deps, env)\n    AuthProvider.refreshEmVoo.set(caminho, promessa)\n    try {\n      return await promessa\n    } finally {\n      AuthProvider.refreshEmVoo.delete(caminho)\n    }\n  }\n\n  /** Refresh em voo por caminho de store — a chave é o arquivo, não a instância. */\n  private static readonly refreshEmVoo = new Map<string, Promise<ResolvedCredential>>()\n\n  /**\n   * O refresh propriamente dito, serializado entre PROCESSOS e com re-leitura.\n   *\n   * A re-leitura não é detalhe: sem ela o lock apenas serializa, e o segundo processo decide com o\n   * estado que leu ANTES de esperar — refrescando de novo e invalidando o token que o primeiro acabou\n   * de gravar. É o double-checked locking clássico, e é o que o teste de dois processos pega.\n   */\n  private refrescarSobLock(\n    caminho: string,\n    resolved: ResolvedCredential,\n    deps: EnsureFreshHttpDeps,\n    env?: Record<string, string | undefined>,\n  ): Promise<ResolvedCredential> {\n    /* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access -- os subpaths `/auth` e `/persistence` do SDK resolvem sob tsc (typecheck da raiz limpo); o projeto type-aware do eslint os lê como error-typed. Mesma nota que este arquivo já carregava para `CredentialStoreConfig`. */\n    return withFileLock(caminho, async () => {\n      // RE-LEITURA depois de adquirir o lock: outro processo pode ter refrescado enquanto esperávamos.\n      const doDisco = readStoredOAuth(this.store, env)\n      const atual =\n        doDisco !== undefined\n          ? { ...resolved, apiKey: doDisco.access, expiresAt: doDisco.expires }\n          : resolved\n      // Retry SÓ no transitório. Um `invalid_grant` falha na PRIMEIRA: o token foi revogado e nenhuma\n      // tentativa muda isso — insistir só atrasa a mensagem que o usuário precisa ler.\n      //\n      // Este laço já existiu e foi APAGADO por um lint-fix meu que reescreveu o bloco inteiro; o\n      // review pegou (`tentativas de POST = 1`, contra as 3 que a DoD exige). Testar o classificador\n      // isolado prova que ele classifica, não que está LIGADO — por isso há um gate estrutural.\n      const MAX_TENTATIVAS = 3\n      for (let tentativa = 0; ; tentativa++) {\n        try {\n          return await ensureFreshCredential(\n            atual,\n            { config: this.config, store: this.store, env },\n            deps,\n          )\n        } catch (err) {\n          const falha = classificarFalhaDeRefresh(err)\n          if (!falha.transitorio || tentativa >= MAX_TENTATIVAS - 1) throw falha\n          await new Promise((resolve) => setTimeout(resolve, esperaComJitter(tentativa)))\n        }\n      }\n    }) as Promise<ResolvedCredential>\n    /* eslint-enable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */\n  }\n\n  /**\n   * Run the headless OpenAI device-login flow. Delegates to `openaiDeviceLogin` (which JWT-extracts the\n   * account id). `deviceConfig` is passed per-call because it is a distinct endpoint set from the\n   * refresh `config`. Returns `OAuthTokens` — the caller persists them via {@link AuthProvider.persist}.\n   */\n  deviceLogin(\n    deviceConfig: OpenAIDeviceConfig,\n    deps: DeviceLoginDeps,\n    hooks: DeviceLoginHooks,\n  ): Promise<OAuthTokens> {\n    return openaiDeviceLogin(deviceConfig, deps, hooks)\n  }\n\n  /**\n   * Persist freshly-obtained tokens through the held `store`. Delegates to `persistOAuthTokens` and\n   * returns the credential-file path (never the token). `env` selects the store's home override.\n   */\n  persist(provider: string, tokens: OAuthTokens, env?: Record<string, string | undefined>): string {\n    return persistOAuthTokens(provider, tokens, this.store, env)\n  }\n}\n","// M60 — `@theokit/agents/auth`: the OO auth contract. `AuthProvider` (ENRICH — it holds the shared\n// `config`+`store` state and delegates to the SDK's free OAuth-lifecycle functions), plus the auth\n// domain's types re-exported so a consumer types the whole surface from the Theokit layer, never\n// reaching back to `@theokit/sdk/auth`.\nexport { AuthProvider } from './auth/auth-provider.js'\n\n// M73 — \"enriquecer nunca reduz\". A mecânica de store do SDK atravessa como PASS-THROUGH PURO.\n//\n// Antes disto, este subpath exportava 1 valor e 6 tipos enquanto `@theokit/sdk/auth` exportava 19\n// símbolos: nenhuma função atravessava. Como o consumidor tem regra INQUEBRÁVEL de nunca importar\n// `@theokit/sdk*` direto, **reimplementar era a única saída legal** — e o agent-builder reescreveu\n// seis destes nomes, ~120 linhas de mecânica duplicada. A lacuna era daqui, não indisciplina de lá.\n//\n// PURO, e não wrapper (parsimony Rung 9): estas são funções de I/O sem estado a segurar. A camada\n// enriquece onde há orquestração — é o que `AuthProvider` faz com o par `config`+`store`. Envolver\n// isto acrescentaria indireção sem nada dentro, e **quebraria `instanceof`**: o consumidor faz\n// `err instanceof CredentialError`, o que só vale enquanto a classe for a MESMA referência do SDK.\n// `tests/unit/auth-parity.test.ts` trava essa identidade com `toBe`.\n//\n// `resolveCredential` NÃO atravessa, de propósito: o SDK e o agent-builder têm funções DIFERENTES com\n// esse nome (sync vs async, lança vs `undefined`, lê env vs não lê, infere provider vs recusa), e o\n// próprio SDK declara que a precedência de env, a inferência por prefixo e o provider declarado são\n// app policy do consumidor (`internal/auth/credential-store.ts`). Expor os dois no mesmo escopo seria\n// convite a importar o errado, com falha silenciosa.\nexport {\n  authFilePath,\n  CredentialError,\n  credentialHome,\n  readAuthFile,\n  readStoredOAuth,\n  writeCredential,\n} from '@theokit/sdk/auth'\n\n// M110 — o device flow **RFC 8628** atravessa, pelo MESMO argumento do M73 acima, sobre símbolos que\n// aquele milestone não cobriu.\n//\n// Medido: o SDK implementa o padrão (`deviceLogin`, `requestDeviceCode`, `pollDeviceToken`,\n// `DeviceOAuthConfig`), e este subpath re-exportava **apenas** a variante da OpenAI\n// (`openaiDeviceLogin`, `OpenAIDeviceConfig`). Um consumidor que precisasse do padrão tinha duas\n// saídas: violar a regra INQUEBRÁVEL, ou reimplementar o RFC. É literalmente a frase do M73 — *\"a\n// lacuna era daqui, não indisciplina de lá\"* — reencenada num subsistema vizinho.\n//\n// PURO, não wrapper, pelo critério que o M73 escreveu: são funções de I/O sem estado a segurar.\n// `DeviceDeps` já é injetável, então um consumidor testa o próprio provider sem rede.\n//\n// As duas formas COEXISTEM e nada é unificado: `DeviceOAuthConfig` tem **um** `deviceCodeEndpoint`\n// (RFC), e `OpenAIDeviceConfig` tem **dois** (`deviceUsercodeEndpoint` → `devicePollEndpoint`, com\n// PKCE). Fundi-las quebraria o Codex — o provider que este trabalho existe para facilitar.\n// E `openaiDeviceLogin` atravessa JUNTO, o que a medição do M110 mostrou faltar: ele era **importado**\n// aqui para uso interno do `AuthProvider` e nunca re-exportado. Consequência — o flow do Codex só era\n// alcançável construindo um `AuthProvider` (que exige `config`+`store`), quando o pedido concreto era\n// *\"facilitar usar o provider Codex\"*. Exportá-lo é o mesmo argumento das linhas acima, aplicado à\n// variante que já existia.\nexport { deviceLogin, openaiDeviceLogin, pollDeviceToken, requestDeviceCode } from '@theokit/sdk/auth'\nexport type { DeviceCodeGrant, DeviceOAuthConfig } from '@theokit/sdk/auth'\nexport type { ResolveCredentialOptions } from '@theokit/sdk/auth'\nexport type {\n  CredentialStoreConfig,\n  DeviceDeps,\n  OAuthProviderConfig,\n  OAuthTokens,\n  OpenAIDeviceConfig,\n  ResolvedCredential,\n} from '@theokit/sdk/auth'\n"],"mappings":"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","names":["authFilePath","ensureFreshCredential","openaiDeviceLogin","persistOAuthTokens","readStoredOAuth","withFileLock","RefreshFailure","Error","message","transitorio","name","MOTIVOS_TRANSITORIOS","classificarFalhaDeRefresh","err","texto","String","test","some","m","includes","esperaComJitter","tentativa","baseMs","aleatorio","Math","random","base","round","AuthProvider","config","store","ensureFresh","resolved","deps","env","kind","ensureFreshCredential","caminho","authFilePath","emVoo","refreshEmVoo","get","undefined","promessa","refrescarSobLock","set","delete","Map","withFileLock","doDisco","readStoredOAuth","atual","apiKey","access","expiresAt","expires","MAX_TENTATIVAS","falha","Promise","resolve","setTimeout","deviceLogin","deviceConfig","hooks","openaiDeviceLogin","persist","provider","tokens","persistOAuthTokens","authFilePath","CredentialError","credentialHome","readAuthFile","readStoredOAuth","writeCredential","deviceLogin","openaiDeviceLogin","pollDeviceToken","requestDeviceCode"]}
+{"version":3,"sources":["../src/auth/auth-provider.ts","../src/auth-entry.ts","../src/auth/device-provider.ts"],"sourcesContent":["import {\n  authFilePath,\n  ensureFreshCredential,\n  openaiDeviceLogin,\n  persistOAuthTokens,\n  readStoredOAuth,\n} from '@theokit/sdk/auth'\nimport type {\n  CredentialStoreConfig,\n  OAuthProviderConfig,\n  OAuthTokens,\n  OpenAIDeviceConfig,\n  ResolvedCredential,\n} from '@theokit/sdk/auth'\nimport { withFileLock } from '@theokit/sdk/persistence'\n\n/**\n * M60 — `AuthProvider`, the OO contract that unifies the SDK's free OAuth-lifecycle functions\n * (`openaiDeviceLogin` → `persistOAuthTokens` → `ensureFreshCredential`). Those are stateful across a\n * SHARED `config` (`OAuthProviderConfig`) + `store` (`CredentialStoreConfig`); this class holds that\n * state so a consumer authors `new AuthProvider(config, store).persist(...)` / `.ensureFresh(...)`\n * instead of threading `config`/`store` through every call — the `SDK → Theokit → AgentBuilder`\n * boundary applied to the auth domain (ENRICH, per blueprint D2: auth carries orchestration + state).\n *\n * It DELEGATES, never reimplements (parsimony Rung 9): each method forwards verbatim to the SDK\n * function, so login → persist → refresh produces byte-identical state to calling the SDK directly.\n *\n * SECRET-SAFETY (hard rule): this class NEVER logs, stringifies, or otherwise surfaces token material.\n * Methods return exactly what the SDK returns and add no observability — a token is data that flows\n * through, never something this layer emits. The parity/secret tests pin both properties.\n */\n\n/** The HTTP deps of `ensureFreshCredential` (`{ fetch, now }`) — typed off the SDK to avoid drift. */\ntype EnsureFreshHttpDeps = Parameters<typeof ensureFreshCredential>[2]\n/** The device-flow deps + prompt hook of `openaiDeviceLogin` — typed off the SDK. */\ntype DeviceLoginDeps = Parameters<typeof openaiDeviceLogin>[1]\ntype DeviceLoginHooks = Parameters<typeof openaiDeviceLogin>[2]\n\n/**\n * Falha de refresh, classificada — porque a decisão de tentar de novo depende da classe, não do texto.\n *\n * M74: repetir um `invalid_grant` não é resiliência, é ruído. O refresh token foi revogado e nenhuma\n * tentativa muda isso; o usuário que revogou o login espera três backoffs para ler uma mensagem que já\n * era conhecida na primeira resposta. Rede e 5xx são o oposto: quase sempre passam na segunda.\n *\n * SECRET-SAFETY: a mensagem nunca carrega material de token — só a classe e o motivo.\n */\nexport class RefreshFailure extends Error {\n  constructor(\n    message: string,\n    /** `true` ⇒ vale tentar de novo com backoff. `false` ⇒ terminal, falha na primeira. */\n    readonly transitorio: boolean,\n  ) {\n    super(message)\n    this.name = 'RefreshFailure'\n  }\n}\n\n/**\n * O que conta como transitório. Lista NOMEADA de propósito: é decisão de produto que envelhece, e\n * espalhá-la em `if` faz cada sítio envelhecer sozinho.\n */\nconst MOTIVOS_TRANSITORIOS = [\n  'ETIMEDOUT',\n  'ECONNRESET',\n  'ECONNREFUSED',\n  'EAI_AGAIN',\n  'ENOTFOUND',\n  'AbortError',\n]\n\n/** Classifica uma falha de refresh. `invalid_grant` é terminal; rede e 5xx são transitórios. */\nexport function classificarFalhaDeRefresh(err: unknown): RefreshFailure {\n  const texto = err instanceof Error ? `${err.name}: ${err.message}` : String(err)\n  if (/invalid_grant|invalid_request|unauthorized_client/i.test(texto)) {\n    return new RefreshFailure(\n      'o refresh token não é mais válido — refaça o login. Tentar de novo não muda o resultado.',\n      false,\n    )\n  }\n  const transitorio =\n    MOTIVOS_TRANSITORIOS.some((m) => texto.includes(m)) ||\n    /\\b(5\\d{2})\\b|timeout|network/i.test(texto)\n  return new RefreshFailure(\n    transitorio ? 'falha transitória ao refrescar a credencial' : 'falha ao refrescar a credencial',\n    transitorio,\n  )\n}\n\n/** Espera com jitter: backoff exponencial ±25%, para dois processos não retentarem em uníssono. */\nexport function esperaComJitter(tentativa: number, baseMs = 200, aleatorio = Math.random): number {\n  const base = baseMs * 2 ** tentativa\n  return Math.round(base * (0.75 + aleatorio() * 0.5))\n}\n\nexport class AuthProvider {\n  constructor(\n    private readonly config: OAuthProviderConfig,\n    private readonly store: CredentialStoreConfig,\n  ) {}\n\n  /**\n   * Refresh a resolved credential if stale. Delegates to `ensureFreshCredential` with the held\n   * `config` + `store`; `env` (for reading the store's env overrides) + the `{ fetch, now }` HTTP deps\n   * thread through. Returns the fresh `ResolvedCredential` — never logs the rotated token.\n   */\n  async ensureFresh(\n    resolved: ResolvedCredential,\n    deps: EnsureFreshHttpDeps,\n    env?: Record<string, string | undefined>,\n  ): Promise<ResolvedCredential> {\n    if (resolved.kind !== 'oauth') {\n      // Chave de API não expira: nenhum lock, nenhuma releitura, nenhum I/O. Manter o caminho quente\n      // livre é o que torna o resolvedor por-run barato (M74, Risco 1).\n      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- `CredentialStoreConfig` do subpath /auth resolve sob tsc; o projeto type-aware do eslint o lê como error-typed.\n      return ensureFreshCredential(resolved, { config: this.config, store: this.store, env }, deps)\n    }\n\n    const caminho: string = authFilePath(this.store, env)\n\n    // SINGLE-FLIGHT in-process, ANTES do lock (M74, EC-2 do edge-case review).\n    //\n    // `withFileLock` (proper-lockfile) NÃO é reentrante: se uma run começar de dentro de um contexto\n    // que já segura o lock — uma run aninhada, ou um time disparando membros enquanto o pai refresca —\n    // a segunda aquisição espera até o timeout e o sintoma é \"a run travou\", sem erro nenhum. Com o\n    // resolvedor por-run do M74 isso deixa de ser hipotético: `ensureFresh` passa a ser chamado de\n    // dentro do stream. A promise em voo faz a reentrância resolver por composição, não por lock.\n    const emVoo = AuthProvider.refreshEmVoo.get(caminho)\n    if (emVoo !== undefined) return emVoo\n\n    const promessa = this.refrescarSobLock(caminho, resolved, deps, env)\n    AuthProvider.refreshEmVoo.set(caminho, promessa)\n    try {\n      return await promessa\n    } finally {\n      AuthProvider.refreshEmVoo.delete(caminho)\n    }\n  }\n\n  /** Refresh em voo por caminho de store — a chave é o arquivo, não a instância. */\n  private static readonly refreshEmVoo = new Map<string, Promise<ResolvedCredential>>()\n\n  /**\n   * O refresh propriamente dito, serializado entre PROCESSOS e com re-leitura.\n   *\n   * A re-leitura não é detalhe: sem ela o lock apenas serializa, e o segundo processo decide com o\n   * estado que leu ANTES de esperar — refrescando de novo e invalidando o token que o primeiro acabou\n   * de gravar. É o double-checked locking clássico, e é o que o teste de dois processos pega.\n   */\n  private refrescarSobLock(\n    caminho: string,\n    resolved: ResolvedCredential,\n    deps: EnsureFreshHttpDeps,\n    env?: Record<string, string | undefined>,\n  ): Promise<ResolvedCredential> {\n    /* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access -- os subpaths `/auth` e `/persistence` do SDK resolvem sob tsc (typecheck da raiz limpo); o projeto type-aware do eslint os lê como error-typed. Mesma nota que este arquivo já carregava para `CredentialStoreConfig`. */\n    return withFileLock(caminho, async () => {\n      // RE-LEITURA depois de adquirir o lock: outro processo pode ter refrescado enquanto esperávamos.\n      const doDisco = readStoredOAuth(this.store, env)\n      const atual =\n        doDisco !== undefined\n          ? { ...resolved, apiKey: doDisco.access, expiresAt: doDisco.expires }\n          : resolved\n      // Retry SÓ no transitório. Um `invalid_grant` falha na PRIMEIRA: o token foi revogado e nenhuma\n      // tentativa muda isso — insistir só atrasa a mensagem que o usuário precisa ler.\n      //\n      // Este laço já existiu e foi APAGADO por um lint-fix meu que reescreveu o bloco inteiro; o\n      // review pegou (`tentativas de POST = 1`, contra as 3 que a DoD exige). Testar o classificador\n      // isolado prova que ele classifica, não que está LIGADO — por isso há um gate estrutural.\n      const MAX_TENTATIVAS = 3\n      for (let tentativa = 0; ; tentativa++) {\n        try {\n          return await ensureFreshCredential(\n            atual,\n            { config: this.config, store: this.store, env },\n            deps,\n          )\n        } catch (err) {\n          const falha = classificarFalhaDeRefresh(err)\n          if (!falha.transitorio || tentativa >= MAX_TENTATIVAS - 1) throw falha\n          await new Promise((resolve) => setTimeout(resolve, esperaComJitter(tentativa)))\n        }\n      }\n    }) as Promise<ResolvedCredential>\n    /* eslint-enable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */\n  }\n\n  /**\n   * Run the headless OpenAI device-login flow. Delegates to `openaiDeviceLogin` (which JWT-extracts the\n   * account id). `deviceConfig` is passed per-call because it is a distinct endpoint set from the\n   * refresh `config`. Returns `OAuthTokens` — the caller persists them via {@link AuthProvider.persist}.\n   */\n  deviceLogin(\n    deviceConfig: OpenAIDeviceConfig,\n    deps: DeviceLoginDeps,\n    hooks: DeviceLoginHooks,\n  ): Promise<OAuthTokens> {\n    return openaiDeviceLogin(deviceConfig, deps, hooks)\n  }\n\n  /**\n   * Persist freshly-obtained tokens through the held `store`. Delegates to `persistOAuthTokens` and\n   * returns the credential-file path (never the token). `env` selects the store's home override.\n   */\n  persist(provider: string, tokens: OAuthTokens, env?: Record<string, string | undefined>): string {\n    return persistOAuthTokens(provider, tokens, this.store, env)\n  }\n}\n","// M60 — `@theokit/agents/auth`: the OO auth contract. `AuthProvider` (ENRICH — it holds the shared\n// `config`+`store` state and delegates to the SDK's free OAuth-lifecycle functions), plus the auth\n// domain's types re-exported so a consumer types the whole surface from the Theokit layer, never\n// reaching back to `@theokit/sdk/auth`.\nexport { AuthProvider } from './auth/auth-provider.js'\n\n// M73 — \"enriquecer nunca reduz\". A mecânica de store do SDK atravessa como PASS-THROUGH PURO.\n//\n// Antes disto, este subpath exportava 1 valor e 6 tipos enquanto `@theokit/sdk/auth` exportava 19\n// símbolos: nenhuma função atravessava. Como o consumidor tem regra INQUEBRÁVEL de nunca importar\n// `@theokit/sdk*` direto, **reimplementar era a única saída legal** — e o agent-builder reescreveu\n// seis destes nomes, ~120 linhas de mecânica duplicada. A lacuna era daqui, não indisciplina de lá.\n//\n// PURO, e não wrapper (parsimony Rung 9): estas são funções de I/O sem estado a segurar. A camada\n// enriquece onde há orquestração — é o que `AuthProvider` faz com o par `config`+`store`. Envolver\n// isto acrescentaria indireção sem nada dentro, e **quebraria `instanceof`**: o consumidor faz\n// `err instanceof CredentialError`, o que só vale enquanto a classe for a MESMA referência do SDK.\n// `tests/unit/auth-parity.test.ts` trava essa identidade com `toBe`.\n//\n// `resolveCredential` NÃO atravessa, de propósito: o SDK e o agent-builder têm funções DIFERENTES com\n// esse nome (sync vs async, lança vs `undefined`, lê env vs não lê, infere provider vs recusa), e o\n// próprio SDK declara que a precedência de env, a inferência por prefixo e o provider declarado são\n// app policy do consumidor (`internal/auth/credential-store.ts`). Expor os dois no mesmo escopo seria\n// convite a importar o errado, com falha silenciosa.\nexport {\n  authFilePath,\n  CredentialError,\n  credentialHome,\n  readAuthFile,\n  readStoredOAuth,\n  writeCredential,\n} from '@theokit/sdk/auth'\n\n// M110 — o device flow **RFC 8628** atravessa, pelo MESMO argumento do M73 acima, sobre símbolos que\n// aquele milestone não cobriu.\n//\n// Medido: o SDK implementa o padrão (`deviceLogin`, `requestDeviceCode`, `pollDeviceToken`,\n// `DeviceOAuthConfig`), e este subpath re-exportava **apenas** a variante da OpenAI\n// (`openaiDeviceLogin`, `OpenAIDeviceConfig`). Um consumidor que precisasse do padrão tinha duas\n// saídas: violar a regra INQUEBRÁVEL, ou reimplementar o RFC. É literalmente a frase do M73 — *\"a\n// lacuna era daqui, não indisciplina de lá\"* — reencenada num subsistema vizinho.\n//\n// PURO, não wrapper, pelo critério que o M73 escreveu: são funções de I/O sem estado a segurar.\n// `DeviceDeps` já é injetável, então um consumidor testa o próprio provider sem rede.\n//\n// As duas formas COEXISTEM e nada é unificado: `DeviceOAuthConfig` tem **um** `deviceCodeEndpoint`\n// (RFC), e `OpenAIDeviceConfig` tem **dois** (`deviceUsercodeEndpoint` → `devicePollEndpoint`, com\n// PKCE). Fundi-las quebraria o Codex — o provider que este trabalho existe para facilitar.\n// E `openaiDeviceLogin` atravessa JUNTO, o que a medição do M110 mostrou faltar: ele era **importado**\n// aqui para uso interno do `AuthProvider` e nunca re-exportado. Consequência — o flow do Codex só era\n// alcançável construindo um `AuthProvider` (que exige `config`+`store`), quando o pedido concreto era\n// *\"facilitar usar o provider Codex\"*. Exportá-lo é o mesmo argumento das linhas acima, aplicado à\n// variante que já existia.\nexport {\n  deviceLogin,\n  openaiDeviceLogin,\n  pollDeviceToken,\n  requestDeviceCode,\n} from '@theokit/sdk/auth'\nexport type { DeviceCodeGrant, DeviceOAuthConfig } from '@theokit/sdk/auth'\nexport type { ResolveCredentialOptions } from '@theokit/sdk/auth'\nexport type {\n  CredentialStoreConfig,\n  DeviceDeps,\n  OAuthProviderConfig,\n  OAuthTokens,\n  OpenAIDeviceConfig,\n  ResolvedCredential,\n} from '@theokit/sdk/auth'\n\n// M111 — device auth PLUG-AND-PLAY. O M110 fez o flow RFC 8628 atravessar; ele não tocou a ergonomia.\n//\n// Para autenticar no Codex, o consumidor tinha de saber que existem DUAS formas de device flow, copiar\n// um `clientId` e três URLs da OpenAI para dentro do próprio código, montar `{fetch, sleep, now}`,\n// chamar `deviceLogin` e LEMBRAR de chamar `persist` — esquecer o último custa um round-trip OAuth\n// completo que não guarda nada.\n//\n// O desenho veio de medição contra três peers e REFUTOU a proposta original (um descritor plano com\n// discriminante `kind`): nenhum dos três discrimina protocolo por campo. `AuthMethod` é união\n// discriminada e cada método aponta para a SUA função — sem `switch`, e sem tornar representável um\n// método OAuth que não sabe autorizar.\n//\n// ENRIQUECE, não é pass-through: `loginWithDevice` orquestra `authorize` + `persist` (a forma de\n// `run_device_code_login` do codex, que retorna `()`), e `CODEX_PROVIDER` é identidade pública que\n// antes cada consumidor copiava — dois donos do mesmo fato é violação de DRY através da fronteira.\nexport { CODEX_CLIENT_ID_ENV_VAR, CODEX_PROVIDER, loginWithDevice } from './auth/device-provider.js'\nexport type { AuthMethod, DeviceAuthProvider, PromptHooks } from './auth/device-provider.js'\n","import type {\n  CredentialStoreConfig,\n  DeviceDeps,\n  OAuthProviderConfig,\n  OAuthTokens,\n  OpenAIDeviceConfig,\n} from '@theokit/sdk/auth'\nimport { openaiDeviceLogin } from '@theokit/sdk/auth'\n\nimport { AuthProvider } from './auth-provider.js'\n\n/**\n * M111 — device auth plug-and-play: um provider é um objeto com métodos ROTULADOS, e um login cabe\n * numa chamada.\n *\n * ## O problema, medido\n *\n * O M110 fez o device flow RFC 8628 atravessar esta camada. Ele não tocou a ergonomia: para\n * autenticar no Codex, o consumidor precisava saber que existem **duas** formas de device flow,\n * copiar um `clientId` e três URLs da OpenAI para dentro do próprio código, montar\n * `{ fetch, sleep, now }`, chamar `deviceLogin` e **lembrar** de chamar `persist` — e esquecer o\n * último custa um round-trip OAuth completo que não guarda nada. O docblock de `AuthProvider`\n * instruía exatamente isso: *\"the caller persists them via `AuthProvider.persist`\"*.\n *\n * ## O desenho veio de medição contra três peers, e refutou a proposta original\n *\n * - **`codex`** — `codex-rs/login/src/device_code_auth.rs:234` tem `run_device_code_login`, que\n *   retorna `()`: **nada** sai para o chamador persistir, e as duas metades granulares continuam\n *   públicas. `loginWithDevice` é a cópia dessa forma.\n * - **`opencode`** — cada provider é um objeto com `methods: [{ label, type, authorize }]`, e três\n *   providers escritos por autores diferentes convergem em **3 métodos rotulados** cada. O rótulo é o\n *   que a UI mostra: transforma escolha de protocolo em escolha de frase legível.\n * - **REJEITADO — discriminante `kind`.** Nenhum dos três discrimina protocolo por campo. A medição\n *   que fecha o caso: no `opencode`, browser e headless do Codex carregam o **mesmo** `type: 'oauth'`\n *   — logo o `type` classifica **espécie de credencial**, não protocolo. Um `kind` com despacho\n *   interno seria um `switch`, exatamente o defeito que este milestone remove do consumidor.\n *   Aqui, cada método aponta para a **sua própria** função.\n *\n * ## Por que a identidade pública mora AQUI\n *\n * `codex` exporta `CLIENT_ID` do crate que implementa o flow (`login/src/lib.rs:32`) e o CLI o\n * **importa**; o `opencode` o declara dentro do plugin. Os dois chegaram ao mesmo lugar\n * independentemente — e com o mesmo valor que o consumidor tinha copiado. Enquanto morasse no\n * consumidor, todo projeto que quisesse Codex copiaria quatro constantes públicas: é violação de DRY\n * através da fronteira, com dois donos do mesmo fato.\n */\n\n/**\n * Uma forma rotulada de obter credencial dentro de um provider.\n *\n * UNIÃO DISCRIMINADA, não um campo `authorize?` opcional. Com opcional, `{ label, type: 'oauth' }`\n * seria representável — um método OAuth que não sabe autorizar, detectado só em runtime, no meio do\n * login do usuário. É a alternativa que o M110 já rejeitou por escrito ao recusar \"um tipo só com\n * campos opcionais\": tornaria representável um config inválido e moveria a detecção do compilador\n * para o runtime.\n */\nexport type AuthMethod =\n  | {\n      /** O que a interface mostra ao usuário. É a peça que torna o fluxo escolhível sem saber o protocolo. */\n      readonly label: string\n      readonly type: 'oauth'\n      /** A função DESTE método. Sem discriminante: o método aponta para a sua, não para um `switch`. */\n      readonly authorize: (deps: DeviceDeps, hooks: PromptHooks) => Promise<OAuthTokens>\n    }\n  | {\n      readonly label: string\n      readonly type: 'api'\n    }\n\n/** O que o consumidor liga à sua UI para mostrar o código que o usuário digita no outro dispositivo. */\nexport interface PromptHooks {\n  onPrompt: (p: { userCode: string; verificationUri: string; expiresIn?: number }) => void\n}\n\n/** Um provider de autenticação: identidade pública + as formas rotuladas de autenticar nele. */\nexport interface DeviceAuthProvider {\n  readonly name: string\n  readonly oauth: OAuthProviderConfig\n  readonly methods: readonly AuthMethod[]\n}\n\n/** Identificadores PÚBLICOS do Codex CLI da OpenAI (publicados na fonte MIT do OpenCode). Não são segredo. */\nconst CODEX_CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann'\nconst CODEX_ISSUER = 'https://auth.openai.com'\n\n/**\n * Override do `clientId` por ambiente — adotado do `codex`, que exporta `CLIENT_ID` **e**\n * `CLIENT_ID_OVERRIDE_ENV_VAR` (`login/src/lib.rs:32-33`). Dissolve o falso dilema entre constante\n * fixa (inflexível) e parâmetro obrigatório (que devolve a cópia ao consumidor): default no pacote,\n * escape para quem precisa.\n */\nexport const CODEX_CLIENT_ID_ENV_VAR = 'THEOKIT_CODEX_CLIENT_ID'\n\nconst CODEX_OAUTH: OAuthProviderConfig = {\n  provider: 'openai',\n  clientId: process.env[CODEX_CLIENT_ID_ENV_VAR] ?? CODEX_CLIENT_ID,\n  authorizeEndpoint: `${CODEX_ISSUER}/oauth/authorize`,\n  tokenEndpoint: `${CODEX_ISSUER}/oauth/token`,\n  scopes: ['openid', 'profile', 'email', 'offline_access'],\n  redirectUri: `${CODEX_ISSUER}/deviceauth/callback`,\n}\n\n/**\n * A config do device flow da OpenAI — **dois** endpoints, com PKCE. É a variante NÃO-padrão, e é por\n * isso que ela não se funde com `DeviceOAuthConfig` (RFC 8628, **um** endpoint).\n */\nconst CODEX_DEVICE: OpenAIDeviceConfig = {\n  ...CODEX_OAUTH,\n  deviceUsercodeEndpoint: `${CODEX_ISSUER}/api/accounts/deviceauth/usercode`,\n  devicePollEndpoint: `${CODEX_ISSUER}/api/accounts/deviceauth/token`,\n  verificationUri: `${CODEX_ISSUER}/codex/device`,\n}\n\n/**\n * O provider do Codex, montado e **congelado**.\n *\n * Congelado porque é identidade pública COMPARTILHADA no processo: um consumidor que a mutasse\n * mudaria o login de todos os outros. `Object.freeze` é raso, então a lista de métodos é congelada\n * separadamente — sem isso, `CODEX_PROVIDER.methods.push(...)` passaria.\n */\nexport const CODEX_PROVIDER: DeviceAuthProvider = Object.freeze({\n  name: 'openai',\n  oauth: Object.freeze(CODEX_OAUTH),\n  methods: Object.freeze([\n    Object.freeze({\n      label: 'ChatGPT Pro/Plus (headless device code)',\n      type: 'oauth' as const,\n      // Aponta para a variante da OpenAI. Um provider RFC 8628 apontaria para `deviceLogin`, e é\n      // assim que as duas formas coexistem sem discriminante.\n      authorize: (deps: DeviceDeps, hooks: PromptHooks): Promise<OAuthTokens> =>\n        openaiDeviceLogin(CODEX_DEVICE, deps, hooks),\n    }),\n    Object.freeze({\n      label: 'Manually enter API Key',\n      type: 'api' as const,\n    }),\n  ]),\n})\n\n/**\n * Opções do Facade. `deps` e `env` viajam juntos num objeto em vez de dois parâmetros posicionais:\n * ambos são opcionais e raramente usados, e seis posicionais é assinatura que o chamador erra em\n * silêncio (o lint do monorepo cobra 5 como teto — o teto existe por este motivo).\n */\nexport interface LoginWithDeviceOptions {\n  /** Injeção de I/O para teste. Omitido, usa `fetch`/`setTimeout`/`Date.now` reais. */\n  readonly deps?: Partial<DeviceDeps>\n  /** Ambiente lido pelo store para resolver o diretório da credencial. */\n  readonly env?: Record<string, string | undefined>\n}\n\n/** Defaults das deps de I/O. `deps` é opcional na superfície ergonômica; a injeção fica para o teste. */\nfunction comDefaults(deps?: Partial<DeviceDeps>): DeviceDeps {\n  return {\n    fetch: deps?.fetch ?? fetch,\n    sleep: deps?.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))),\n    now: deps?.now ?? Date.now,\n  }\n}\n\n/**\n * Autoriza **e** persiste, numa chamada. Devolve onde a credencial ficou e a conta atribuída —\n * **nunca** material de token.\n *\n * A forma vem de `run_device_code_login` (`codex`), que retorna `()`: se nada sai para o chamador,\n * não há passo que ele possa esquecer. As duas metades continuam públicas em `AuthProvider`\n * (`deviceLogin` / `persist`) para quem precisa da granularidade — mesma escolha que o `codex` faz ao\n * manter `request_device_code` e `complete_device_code_login` públicas ao lado do Facade.\n *\n * Delega verbatim: `method.authorize` roda o flow e `AuthProvider.persist` grava. Copiar a sequência\n * em vez de chamá-la criaria um segundo oráculo sobre o mesmo fato, e dois oráculos divergem no\n * primeiro fix aplicado a um lado só.\n */\nexport async function loginWithDevice(\n  provider: DeviceAuthProvider,\n  method: AuthMethod,\n  store: CredentialStoreConfig,\n  hooks: PromptHooks,\n  opts: LoginWithDeviceOptions = {},\n): Promise<{ path: string; accountId?: string }> {\n  // VALIDAÇÃO NA FRONTEIRA, antes de qualquer I/O. As três recusas abaixo acontecem sem tocar a rede\n  // e sem tocar o disco: falhar depois de gravar deixaria credencial parcial, e a próxima execução\n  // leria um estado que nunca foi válido.\n  if (provider.methods.length === 0) {\n    throw new TypeError(\n      `o provider \"${provider.name}\" declara nenhum método de autenticação — não há o que escolher`,\n    )\n  }\n  if (!provider.methods.includes(method)) {\n    throw new TypeError(`o método \"${method.label}\" não pertence ao provider \"${provider.name}\"`)\n  }\n  if (method.type !== 'oauth') {\n    throw new TypeError(\n      `o método \"${method.label}\" é de chave (api key), não é um método de device — use o caminho de chave`,\n    )\n  }\n\n  const tokens = await method.authorize(comDefaults(opts.deps), hooks)\n  const path = new AuthProvider(provider.oauth, store).persist(provider.name, tokens, opts.env)\n  // O retorno NÃO carrega token: o consumidor precisa saber onde ficou e de quem é, não o segredo.\n  return tokens.accountId === undefined ? { path } : { path, accountId: tokens.accountId }\n}\n"],"mappings":"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","names":["authFilePath","ensureFreshCredential","openaiDeviceLogin","persistOAuthTokens","readStoredOAuth","withFileLock","RefreshFailure","Error","message","transitorio","name","MOTIVOS_TRANSITORIOS","classificarFalhaDeRefresh","err","texto","String","test","some","m","includes","esperaComJitter","tentativa","baseMs","aleatorio","Math","random","base","round","AuthProvider","config","store","ensureFresh","resolved","deps","env","kind","ensureFreshCredential","caminho","authFilePath","emVoo","refreshEmVoo","get","undefined","promessa","refrescarSobLock","set","delete","Map","withFileLock","doDisco","readStoredOAuth","atual","apiKey","access","expiresAt","expires","MAX_TENTATIVAS","falha","Promise","resolve","setTimeout","deviceLogin","deviceConfig","hooks","openaiDeviceLogin","persist","provider","tokens","persistOAuthTokens","authFilePath","CredentialError","credentialHome","readAuthFile","readStoredOAuth","writeCredential","deviceLogin","openaiDeviceLogin","pollDeviceToken","requestDeviceCode","openaiDeviceLogin","CODEX_CLIENT_ID","CODEX_ISSUER","CODEX_CLIENT_ID_ENV_VAR","CODEX_OAUTH","provider","clientId","process","env","authorizeEndpoint","tokenEndpoint","scopes","redirectUri","CODEX_DEVICE","deviceUsercodeEndpoint","devicePollEndpoint","verificationUri","CODEX_PROVIDER","Object","freeze","name","oauth","methods","label","type","authorize","deps","hooks","openaiDeviceLogin","comDefaults","fetch","sleep","ms","Promise","resolve","setTimeout","now","Date","loginWithDevice","method","store","opts","length","TypeError","includes","tokens","path","AuthProvider","persist","accountId","undefined"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/agents",
-  "version": "6.2.0",
+  "version": "6.3.1",
   "description": "AI agents as first-class citizens of the TheoKit pipeline. The fluent agent()/tool() builders compile to SDK Agent.create() (M31 builder-only authoring API).",
   "type": "module",
   "sideEffects": false,