@agentchatham/cli 2.39.0 → 2.40.0

package/CLAUDE.md

@@ -103,6 +103,40 @@ Rules:
 7. Create `src/providers/<name>/errors.ts` — export `create<Name>ErrorTracker()`,
    wire it into the adapter, and add the harness to `test/errors/conformance.test.ts`
 
+## File-backed credentials
+
+Most harnesses take their credential as an env var and nothing else. A harness
+whose credential is a *file* implements `ProviderAdapter.prepareCredentials(env)`,
+which is called on every agent start (before `checkAuth`, so the preflight
+inspects what a turn will actually use) and again before bootstrap scripts run —
+with the child env there, not `process.env`, which is why it takes an env rather
+than reading the ambient one.
+
+Codex is the only one today (`providers/codex/authFile.ts`). Three rules its
+implementation exists to keep, and any future one should copy:
+
+- **Write on every start.** A start after a cold boot must not depend on a file
+  an earlier run left behind.
+- **Remove what you wrote, and only that.** A credential disconnected in the
+  console must not leave the agent working off a stale file; a developer's own
+  `codex login` on their own host must survive. A marker file next to the
+  credential is what tells the two apart.
+- **Decide precedence in one place.** `planCodexAuth` answers "which credential
+  would a turn use" for the writer, the preflight and the adapter alike — they
+  cannot disagree about it, and the adapter withholds `apiKey` on the strength of
+  the same answer that put the file on disk.
+
+**Bumping `@openai/codex-sdk` requires re-measuring the harness.** Four
+behaviours of the codex binary are load-bearing here and none of them is
+guaranteed by an API: which credential wins when both are present, that an
+expired `auth.json` still beats an API key, that Codex never writes back over
+`auth.json`, and which fields the file must carry to load at all. Two of them
+fail *silently and dangerously* if a future version changes them — a credential
+that keeps working after the user disconnected it, or one that can no longer be
+removed. `test/providers/codex/harnessAssumptions.test.ts` pins the version and
+lists how to re-verify each; it fails when the pin moves, so the check happens at
+the one moment someone is certainly looking.
+
 ## Error classification
 
 Each harness classifies its own errors in `src/providers/<name>/errors.ts`, because

package/README.md

@@ -143,7 +143,29 @@ so land here too, tagged `[sdk]`.
 
 ### Codex
 
-Requires an OpenAI API key. Either set `OPENAI_API_KEY` or run `codex login` once (writes `~/.codex/auth.json`).
+Two credentials, and an unexpired **Codex Token** wins over an API key.
+
+- **`CODEX_AUTH_JSON` — the Codex Token.** The contents of a `~/.codex/auth.json`
+  produced by `codex login`, connected on the console's Models page, which
+  sanitises it in the browser and delivers it here as an ordinary secret. The CLI
+  writes it to `${CODEX_HOME:-~/.codex}/auth.json` (`0600`, in a `0700`
+  directory, atomically) on every agent start and before bootstrap runs, and
+  removes the file it wrote once the secret is gone or the token has expired —
+  otherwise the agent goes on working off a credential the user disconnected.
+  It runs Codex on the user's ChatGPT subscription instead of billing per token.
+
+  Its access token lives about 10 days and **is never refreshed**: the refresh
+  token is dropped in the browser before encryption, so we cannot rotate it even
+  by accident — a rotation is single-use and would invalidate every other copy,
+  including the one on the user's own laptop. The expiry is read from the access
+  token's own `exp`, and the last 5 minutes count as expired (Codex spends them
+  attempting a refresh that cannot succeed). When it lapses, the user re-pastes.
+
+- **`OPENAI_API_KEY`** — used when no Codex Token is connected, or once it has
+  expired. Billed per request.
+
+Locally, `codex login` on this host still works and is honoured when neither of
+the two is set. A file the CLI did not write is never deleted.
 
 ### Claude