@theokit/agents 14.2.0 → 14.3.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @theokit/agents
 
+## 14.3.0
+
+### Minor Changes
+
+- 4b23f36: The environment variables this package reads are now a CLOSED list in the README, gated both ways.
+
+  An operator exported a variable and nothing happened, and there was no way to tell "this runtime does
+  not read it" from "it read it and my value was wrong". `rules/foreign-config-surfaces.md` settles
+  that for `.claude/` file surfaces in one sentence — _a surface is read, or it is refused with a
+  reason about this product; it is never accepted and ignored_ — and the environment was the largest
+  surface that sentence did not cover.
+
+  **The list is closed, and that is the part worth having.** A variable absent from the table is not
+  read by this package — not "undocumented", not "read somewhere else". One sentence answers for every
+  variable anyone could export, including the ones nobody enumerated.
+
+  | Variable                  | Security | What it changes                                                     |
+  | ------------------------- | -------- | ------------------------------------------------------------------- |
+  | `PROGRAMDATA`             | no       | where the machine-wide operator policy is looked for on Windows     |
+  | `THEOKIT_CODEX_CLIENT_ID` | **yes**  | which OAuth client the Codex device authorisation is issued against |
+  | `THEOKIT_DEBUG`           | no       | debug logging (the logs can carry request shapes)                   |
+
+  **Three, not two.** `THEOKIT_CODEX_CLIENT_ID` is read through a constant rather than a literal
+  (`src/auth/device-provider.ts:97`, constant at `:93`), so it is invisible to any scan matching only
+  `process.env.X` — and it is the one of the three that touches a credential path. A gate that missed
+  it would have signed off on an incomplete list, producing from inside the gate the exact silence the
+  list exists to remove.
+
+  **The security column is a decision per row, not a keyword match.** A name containing `AWS` can be a
+  plain address, and a name matching nothing can disable a control.
+
+  `node scripts/check-env-verdicts.mjs` fails in **both** directions — a variable read and not listed,
+  and a variable listed that nothing reads any more. The second is the quieter failure: after a
+  refactor deletes the only read, the table keeps advertising a variable that does nothing, and no
+  operator can detect that by experiment. The gate uses node's stdlib only, makes no network call, and
+  reads nothing outside this repository.
+
 ## 14.2.0
 
 ### Minor Changes

package/README.md

@@ -154,6 +154,33 @@ file that arrives with the repository.
 This is distinct from the session auto-memory at `~/.claude/projects/`: each subagent reads and
 writes its own `MEMORY.md`, not the operator's.
 
+## Environment variables
+
+**This list is CLOSED.** A variable that is not in this table is not read by this package — not
+"undocumented", not "read somewhere else": not read. That is the whole point of writing it down.
+`rules/foreign-config-surfaces.md` settles the same question for `.claude/` file surfaces in one
+sentence — *a surface is read, or it is refused with a reason about this product; it is never
+accepted and ignored* — and this is that sentence applied to the environment.
+
+The reason the guarantee is worth more than a list of three: it answers for every variable anyone
+could export, including the ones nobody enumerated, so an operator who sets something and sees no
+change knows which of the two worlds they are in.
+
+| Variable | Security | What it changes | Read at |
+|---|---|---|---|
+| `PROGRAMDATA` | no | Where the machine-wide operator policy is looked for on Windows. Changing it moves which policy file governs the run. | `src/config/operator-policy.ts:119` |
+| `THEOKIT_CODEX_CLIENT_ID` | **yes** | Overrides the OAuth client id used for the Codex device flow. It selects which OAuth client the device authorisation is issued against, so it is a credential-path decision rather than a convenience one. | `src/auth/device-provider.ts:97`, via the constant at `:93` |
+| `THEOKIT_DEBUG` | no | Turns on debug logging. Log output can contain request shapes, so treat the logs as sensitive even though the switch is not. | `src/debug-log.ts:10` |
+
+The `Security` column is a decision per row, not a keyword match on the name. A name containing
+`AWS` can be a plain address, and a name matching nothing can disable a control — so each row was
+judged rather than classified.
+
+`node scripts/check-env-verdicts.mjs` fails the build in **both** directions: a variable this package
+reads and this table omits, and a variable this table lists that nothing reads any more. Without the
+second direction the table would keep advertising a variable after a refactor deleted its only read,
+which is a worse failure than never having documented it.
+
 ## Boundaries this package keeps
 
 - It does **not** call an LLM provider, run a tool-dispatch loop, or own the conversation store.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/agents",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "description": "AI agents as first-class citizens of the TheoKit pipeline. The AgentBuilder.create() authoring chain compiles to the @theokit/sdk runtime.",
   "repository": {
     "type": "git",