@theokit/sdk 4.53.1 → 4.55.0

package/dist/{inject-session-GMBMJVNZ.js → inject-session-BJMJH5BX.js}

@@ -1,9 +1,10 @@
-import { enqueueSessionWrite } from './chunk-GOVJO4YE.js';
-import { invalidateSessionCache } from './chunk-4QEC4CCS.js';
-import './chunk-BERBYXFH.js';
-import { SessionTranscript } from './chunk-N5CR3TJZ.js';
-import './chunk-6AZDM6LK.js';
-import './chunk-5F5NWKPN.js';
+import { enqueueSessionWrite } from './chunk-OHBIUXKM.js';
+import { invalidateSessionCache } from './chunk-WTMU7J4U.js';
+import './chunk-BMAZLQQ4.js';
+import { SessionTranscript } from './chunk-DZBSJX6J.js';
+import './chunk-VF7EWVDG.js';
+import './chunk-T7XEKOVW.js';
+import './chunk-T7O6K6PX.js';
 
 // src/internal/session/inject-session.ts
 async function injectSessionTurn(opts) {
@@ -22,5 +23,5 @@ async function injectSessionTurn(opts) {
 }
 
 export { injectSessionTurn };
-//# sourceMappingURL=inject-session-GMBMJVNZ.js.map
-//# sourceMappingURL=inject-session-GMBMJVNZ.js.map
+//# sourceMappingURL=inject-session-BJMJH5BX.js.map
+//# sourceMappingURL=inject-session-BJMJH5BX.js.map

package/dist/inject-session-BJMJH5BX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-BJMJH5BX.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/inject-session-WQGGMCQY.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+var chunkV2UUGUY4_cjs = require('./chunk-V2UUGUY4.cjs');
+var chunk4OTIXDMU_cjs = require('./chunk-4OTIXDMU.cjs');
+require('./chunk-CTCGWIUD.cjs');
+var chunkJHPGF3FP_cjs = require('./chunk-JHPGF3FP.cjs');
+require('./chunk-I6TGFUCO.cjs');
+require('./chunk-JTB5Q42C.cjs');
+require('./chunk-NUKRL3I6.cjs');
+
+// src/internal/session/inject-session.ts
+async function injectSessionTurn(opts) {
+  await chunkV2UUGUY4_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
+    const prior = await opts.store.readRecords(opts.loc.agentId);
+    const transcript = chunkJHPGF3FP_cjs.SessionTranscript.fromRecords(prior, {
+      cwd: opts.loc.cwd,
+      sessionId: opts.sessionId,
+      model: opts.loc.model ?? "unknown"
+    });
+    transcript.appendUserTurn(opts.userText);
+    transcript.appendAssistantTurn({ text: opts.assistantText });
+    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));
+    chunk4OTIXDMU_cjs.invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);
+  });
+}
+
+exports.injectSessionTurn = injectSessionTurn;
+//# sourceMappingURL=inject-session-WQGGMCQY.cjs.map
+//# sourceMappingURL=inject-session-WQGGMCQY.cjs.map

package/dist/inject-session-WQGGMCQY.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-WQGGMCQY.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/internal/auth/auth-types.d.ts

@@ -5,8 +5,46 @@
  * origin — the codebase's established "leaf-type-only deps" pattern (see tsup.config.ts), which sidesteps
  * the rollup-dts cross-module resolution limitation that a value-module type export trips.
  *
- * @internal (re-exported from the package barrel as public)
+ * Every type here is re-exported from `@theokit/sdk/auth` and is therefore PUBLIC, under semver.
+ *
+ * This block sits directly above `CredentialStoreConfig` with no statement between them, so it is
+ * one of that declaration's leading comment ranges — an internal-visibility tag written here is
+ * scanned by `stripInternal` and deletes the interface from the emitted `.d.ts`. That is exactly
+ * what happened, and it is the same trap recorded in `src/auth/index.ts`
+ * (usetheodev/theokit-sdk#283). Do not name that tag anywhere in this file.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Where the credential store lives — the three path segments, plus an optional environment
+ * override.
+ *
+ * The store directory is `join(home, dirName)` and the file is `fileName` inside it. When
+ * `homeEnvVar` is set AND the caller's `env` map holds that variable non-blank, its trimmed value
+ * REPLACES the whole directory: `dirName` is not appended to it, mirroring how `CODEX_HOME` works.
+ * A blank or absent variable falls back to `join(home, dirName)`.
+ *
+ * `env` is always a parameter on the functions that take this config, never an ambient
+ * `process.env` read, and it defaults to an empty map — so a caller that forgets to pass it gets
+ * the non-overridden path rather than whatever the process happens to have.
+ *
+ * Nothing here is validated or created. A relative `home` stays relative to the process cwd, and
+ * the directory is created on first write, at mode 0700.
+ *
+ * The store this addresses holds live credentials in plaintext, so `dirName` should be a directory
+ * the SDK owns rather than one shared with unrelated state: reads enforce 0700 on the directory
+ * and 0600 on the file, and refuse when either is looser.
  */
+export interface CredentialStoreConfig {
+    /** Base home directory (e.g. `os.homedir()`). */
+    home: string;
+    /** The store subdirectory under `home` (e.g. `.agent-builder`, `.codex`). */
+    dirName: string;
+    /** The credential file name inside the store dir (e.g. `auth.json`). */
+    fileName: string;
+    /** Optional env var name that, when set + non-blank, overrides the full store dir. */
+    homeEnvVar?: string;
+}
 /**
  * The flat bearer surface every consumer holds. `kind:'api'` is the classic API-key path; `kind:'oauth'` is
  * an OAuth session whose `apiKey` is the CURRENT access token, so consumers keep passing a flat bearer
@@ -24,11 +62,45 @@ export interface ResolvedCredential {
     /** oauth only: epoch ms the access token expires. Drives the refresh in the oauth engine. */
     expiresAt?: number;
 }
+/**
+ * The API-key variant of the credential file, as it sits on disk.
+ *
+ * `api_key` is the key in PLAINTEXT. Nothing in this SDK encrypts, hashes or otherwise obscures
+ * it; the protection is filesystem permissions alone — `writeCredential` persists the file at
+ * mode 0600 inside a 0700 directory, and `readAuthFile` refuses to read a file readable by other
+ * users or a directory writable by them. On Windows that gate is skipped entirely, because the
+ * mode bits Node reports there do not describe the real ACLs.
+ *
+ * `type` and `provider` are both optional so that a legacy file written before the union existed
+ * — a bare `{ "provider": ..., "api_key": ... }` — still parses as this variant with no
+ * migration. `type` is never written: the api variant is persisted without the discriminant, and
+ * absence of `type` is what identifies it on the next read.
+ *
+ * The file schema is strict, so an unknown key makes the whole file fail to parse with a
+ * `CredentialError` naming the offending path.
+ */
 export interface StoredApiCredential {
     type?: "api";
     provider?: string;
     api_key: string;
 }
+/**
+ * The OAuth variant of the credential file, as it sits on disk.
+ *
+ * `access` and `refresh` are both stored in PLAINTEXT, under the same 0600 file / 0700 directory
+ * gate as the API-key variant and with no additional protection. The refresh token is the more
+ * durable of the two — an expired `access` is worth little, a leaked `refresh` mints new ones —
+ * and it is why `readStoredOAuth` is the only path that hands this shape out: the resolved
+ * credential every other consumer sees carries the access token and nothing else.
+ *
+ * `type: "oauth"` is the discriminant and is always written; a file without it reads back as the
+ * API-key variant. `provider`, `access` and `refresh` must be non-empty — `writeCredential`
+ * refuses an empty access or refresh token, and the read schema rejects empty strings.
+ *
+ * `expires` is epoch milliseconds for the ACCESS token only. Nothing here records when the
+ * refresh token expires, so a refresh failing because the grant itself lapsed is only observable
+ * at the token endpoint.
+ */
 export interface StoredOAuthCredential {
     type: "oauth";
     provider: string;
@@ -38,6 +110,16 @@ export interface StoredOAuthCredential {
     expires: number;
     account_id?: string;
 }
+/**
+ * Whatever the credential file turned out to hold — the two variants are discriminated by `type`.
+ *
+ * Narrow with `stored.type === "oauth"`, not by probing for a field. The API-key variant leaves
+ * `type` undefined rather than setting it to `"api"`, so `type !== "oauth"` is the reliable test
+ * for the API-key side and `type === "api"` misses every legacy file.
+ *
+ * Reading a file is what produces this value, and both variants carry a live secret in plaintext.
+ * Treat it as one: it should not be logged, serialized into telemetry, or put in an error message.
+ */
 export type StoredCredential = StoredApiCredential | StoredOAuthCredential;
 /** A provider's OAuth endpoints + client identity. Passed in (provider-agnostic). */
 export interface OAuthProviderConfig {

package/dist/internal/auth/credential-store.d.ts

@@ -1,4 +1,25 @@
 import { AuthenticationError } from "../../errors.js";
+/**
+ * M42 — the SDK credential store. Promoted DOWN from agent-builder's hardened `agents/lib/credentials.ts`
+ * (M37), generalized from a closed `openrouter|anthropic|openai` union to an open `provider: string` and
+ * driven by a caller-supplied {@link CredentialStoreConfig} (no hardcoded `.agent-builder`/`auth.json` /
+ * `AGENT_BUILDER_HOME`). The security-critical file mechanics are ported VERBATIM (ADR D3 of the M42 plan):
+ * atomic O_EXCL + rename + fsync write, 0700/0600 mode gates, `env` is always a PARAMETER (never an ambient
+ * `process.env` read).
+ *
+ * The env-precedence + key-prefix-inference + declared-provider rungs of the agent-builder resolver are
+ * APP POLICY and deliberately stay UP in the consumer; this module owns only the on-disk store + the
+ * `api|oauth` discriminated union. See {@link resolveCredential} (SDK) for the store-read + refresh path.
+ *
+ * Re-exported from `@theokit/sdk/auth`, and therefore PUBLIC, under semver.
+ *
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows, including the
+ * import right below this one. The tag that used to sit here deleted that import from the emitted
+ * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint
+ * (usetheodev/theokit-sdk#283 records the same trap on a declaration).
+ */
+import type { CredentialStoreConfig, StoredCredential, StoredOAuthCredential } from "./auth-types.js";
 /** The store directory, honoring an optional `homeEnvVar` override. */
 export declare function credentialHome(config: CredentialStoreConfig, env?: Record<string, string | undefined>): string;
 /** The credential file path inside the (possibly overridden) store directory. */
@@ -23,12 +44,6 @@ export declare function authFilePath(config: CredentialStoreConfig, env?: Record
 export declare class CredentialError extends AuthenticationError {
     readonly name: string;
 }
-/**
- * Read the credential file. Absent ⇒ `undefined` (the normal case). Present-but-wrong is a typed error
- * naming the file: a malformed credential store must not surface as a raw parse crash. Enforces the
- * 0700 dir / 0600 file mode gates (ported verbatim — a writable dir lets an attacker swap the file for a
- * symlink to their own account).
- */
 /**
  * The 0700-dir / 0600-file mode gates (ported verbatim). The DIRECTORY matters as much as the file:
  * `mkdirSync(mode)` applies only at creation, so a pre-existing store dir keeps whatever mode it had, and a
@@ -36,6 +51,12 @@ export declare class CredentialError extends AuthenticationError {
  * agent then runs on THEIR account.
  */
 export declare function assertSecureModes(dirPath: string, path: string): void;
+/**
+ * Read the credential file. Absent ⇒ `undefined` (the normal case). Present-but-wrong is a typed error
+ * naming the file: a malformed credential store must not surface as a raw parse crash. Enforces the
+ * 0700 dir / 0600 file mode gates (ported verbatim — a writable dir lets an attacker swap the file for a
+ * symlink to their own account).
+ */
 export declare function readAuthFile(config: CredentialStoreConfig, env?: Record<string, string | undefined>): StoredCredential | undefined;
 /**
  * Read the stored OAuth credential (with its refresh token), or `undefined` when the store is absent or
@@ -43,6 +64,13 @@ export declare function readAuthFile(config: CredentialStoreConfig, env?: Record
  * carry. Enforces the same 0600/0700 gates as every other read.
  */
 export declare function readStoredOAuth(config: CredentialStoreConfig, env?: Record<string, string | undefined>): StoredOAuthCredential | undefined;
+/**
+ * Persist a credential atomically at mode `0600`. Ported VERBATIM (ADR D3): write to a random-named temp
+ * file in the same directory with `wx` (O_EXCL), fsync, close, chmod, then `rename` (atomic on POSIX) —
+ * so a crash mid-write leaves whatever was there untouched, and a pre-planted symlink cannot capture the
+ * key. The api variant persists the unchanged `{provider, api_key}` (back-compat, no `type` key); the
+ * oauth variant persists `{type:'oauth', provider, access, refresh, expires, account_id?}`.
+ */
 export declare function writeCredential(cred: {
     provider: string;
     apiKey: string;

package/dist/internal/auth/oauth-device.d.ts

@@ -18,7 +18,6 @@ export declare function deviceLogin(config: DeviceOAuthConfig, deps: DeviceDeps,
         expiresIn: number;
     }) => void;
 }): Promise<OAuthTokens>;
-/** The OpenAI two-step device config: usercode + poll endpoints return an authorization_code (not tokens). */
 /** Step 1 (OpenAI) — request the user code. */
 export declare function requestOpenAIUsercode(config: OpenAIDeviceConfig, deps: Pick<DeviceDeps, "fetch">): Promise<{
     deviceAuthId: string;

package/dist/internal/auth/resolve-credential.d.ts

@@ -1,3 +1,39 @@
+/**
+ * M42 — `resolveCredential`: the public composition entrypoint over the credential store + oauth engine.
+ * Given a provider name + a {@link CredentialStoreConfig} (and, for oauth, an {@link OAuthProviderConfig}),
+ * read the store and return a FRESH `ResolvedCredential` — an api credential passes through by identity; an
+ * oauth credential is transparently refreshed when its access token is within the skew window. Returns
+ * `undefined` when the store holds no credential for `provider` (the caller then falls back to env / apiKeys).
+ *
+ * Mirrors agent-builder's `resolveFreshCredential` composition (store read → oauth → ensureFreshCredential),
+ * defaulting `fetch`/`now` to globals. This is the async surface an oauth provider's M41 `transform.fetch`
+ * calls at stream time, so a mid-turn token expiry refreshes without rebuilding the agent.
+ *
+ * Re-exported from `@theokit/sdk/auth`, and therefore PUBLIC, under semver.
+ *
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows, including the
+ * import right below this one. The tag that used to sit here deleted that import from the emitted
+ * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint
+ * (usetheodev/theokit-sdk#283 records the same trap on a declaration).
+ */
+import type { CredentialStoreConfig, OAuthProviderConfig, ResolvedCredential } from "./auth-types.js";
+/**
+ * Input to `resolveCredential`: which provider, which store, and what to inject.
+ *
+ * `env` and `deps` exist so nothing here reads ambient state. Omitting `env` does NOT fall back to
+ * `process.env` — the store's `homeEnvVar` override simply goes unread, so a credential written
+ * under a relocated home resolves as absent rather than as an error.
+ *
+ * `oauth` is required only to REFRESH an oauth credential. Without it an expired oauth entry cannot
+ * be renewed, and an api-key-only store needs it never.
+ *
+ * PUBLIC and under semver, despite the `internal/` directory: `src/auth/index.ts` re-exports this
+ * type, and `package.json` publishes that barrel as the '@theokit/sdk/auth' subpath. The directory
+ * name is not the authority — the `exports` map is. The semver-exempt class is the sub-paths
+ * declared under '@theokit/sdk/internal/*' ('internal/persistence', 'internal/security',
+ * 'internal/memory-adapters'); no `exports` entry reaches this file that way.
+ */
 export interface ResolveCredentialOptions {
     /** The provider whose stored credential to resolve. */
     provider: string;
@@ -13,4 +49,8 @@ export interface ResolveCredentialOptions {
         now?: () => number;
     };
 }
+/**
+ * Resolve a fresh credential for `provider` from the store, or `undefined` if the store holds none for it.
+ * oauth credentials are auto-refreshed when `opts.oauth` is supplied; api credentials pass through.
+ */
 export declare function resolveCredential(opts: ResolveCredentialOptions): Promise<ResolvedCredential | undefined>;

package/dist/internal/budget/tracker/budget.d.ts

@@ -18,19 +18,17 @@
  * `IterationBudget`. This is intentional — every send is its own iteration
  * round, not a long-running budget shared across sends.
  *
+ * NOTE on how exhaustion is signalled (B-140): by RETURN VALUE, never by
+ * throwing — `recordCompression()` answers `{ allowed: false, reason }` and
+ * `shouldContinue()` answers `false`. Running out of budget is an expected
+ * outcome of the loop, not an exceptional one, so it is not an exception
+ * (`rules/error-handling.md` § 2: never use exceptions for control flow).
+ * Three exported error classes for these cases (`IterationBudgetExhaustedError`,
+ * `CompressionExhaustedError`, `CompressionIneffectiveError`) survived here from
+ * an earlier design and were thrown by nothing; removed 2026-08-20. If you find
+ * yourself re-adding one, the question to settle first is whether the caller can
+ * act on the difference — because today it reads a reason string instead.
+ *
  * @internal
  */
-export declare class CompressionExhaustedError extends Error {
-    readonly name: string;
-}
-export declare class CompressionIneffectiveError extends Error {
-    readonly name: string;
-}
-export interface IterationBudgetOptions {
-    /** Total iterations before grace call. Default 8. */
-    maxIterations?: number;
-    /** Max compression attempts per session (D91). Default 3. */
-    maxCompressions?: number;
-    /** When true (default), one final iteration is allowed after budget exhausted. */
-    allowGraceCall?: boolean;
-}
+export {};

package/dist/internal/budget/usage-accumulator.d.ts

@@ -16,6 +16,21 @@ interface StepUsage {
     cacheWriteTokens?: number;
     reasoningTokens?: number;
 }
+/**
+ * Sums the per-step token counts of a multi-step run into one `TokenUsage`.
+ *
+ * Call `add` once per LLM finish, in any order, then `toTokenUsage` to read the total. The instance
+ * is a running sum, not a snapshot: `toTokenUsage` may be called repeatedly and reflects everything
+ * added so far, and there is no reset — start a new accumulator per run.
+ *
+ * Two shaping rules to expect in the output. The optional counters (cache read, cache write,
+ * reasoning) are omitted entirely when they sum to zero rather than reported as `0`. And the
+ * per-step `requests` array appears only when at least TWO steps were added, so a single-step run
+ * carries totals alone.
+ *
+ * `totalTokens` is input plus output only — cache and reasoning counts are reported separately and
+ * are not folded into it.
+ */
 export declare class UsageAccumulator {
     private input;
     private output;

package/dist/internal/llm/anthropic-shared.d.ts

@@ -25,12 +25,11 @@ export interface AnthropicResponseLike {
 export declare function extractAnthropicText(response: AnthropicResponseLike): string;
 export declare function extractAnthropicToolCalls(response: AnthropicResponseLike): LlmToolCallPart[];
 export declare function mapAnthropicStopReason(reason: string | null): LlmStopReason;
-export declare function toAnthropicWireMessage(message: LlmMessage): Record<string, unknown>;
 /**
- * Build the common body shape for Anthropic Messages requests. Caller
- * is responsible for adding wire-specific fields (`anthropic_version`,
- * `model`, `stream`, etc.).
+ * Convert an SDK `LlmMessage` to the Anthropic Messages wire shape.
+ * Identical across the three Anthropic-compatible clients (D289/D292).
  */
+export declare function toAnthropicWireMessage(message: LlmMessage): Record<string, unknown>;
 /**
  * Issue a POST to an Anthropic-compatible Messages endpoint with the
  * standard auth + content-type headers. Caller maps non-2xx via its own
@@ -79,6 +78,11 @@ export interface AnthropicTextBlock {
         type: "ephemeral";
     };
 }
+/**
+ * Build the common body shape for Anthropic Messages requests. Caller
+ * is responsible for adding wire-specific fields (`anthropic_version`,
+ * `model`, `stream`, etc.).
+ */
 export declare function buildAnthropicCommonBody(request: LlmRequest): {
     max_tokens: number;
     messages: Array<Record<string, unknown>>;

package/dist/internal/llm/model-identifier.d.ts

@@ -29,4 +29,30 @@ export interface ParsedModelId {
     /** Model name to send to the provider — prefix stripped. */
     name: string;
 }
+/**
+ * Split a model string into `{ provider, name }` at the FIRST `/`.
+ *
+ *   parseModelId("ollama/llama3.2:3b")             // { provider: "ollama",     name: "llama3.2:3b" }
+ *   parseModelId("openrouter/meta-llama/llama-3")  // { provider: "openrouter", name: "meta-llama/llama-3" }
+ *   parseModelId("claude-sonnet-4-6")              // { provider: undefined,    name: "claude-sonnet-4-6" }
+ *
+ * Pure and synchronous: no catalog lookup, no network, and no check that the
+ * provider or the model exists. The provider is lowercased and mapped through a
+ * small alias table (`llama-cpp` / `llama.cpp` to `llamacpp`, `lm-studio` /
+ * `lm_studio` to `lmstudio`); the name keeps its remaining slashes and any `:tag`
+ * suffix, which Ollama needs.
+ *
+ * Never throws and never returns an error shape. `provider: undefined` means "no
+ * usable prefix" and is the caller's cue to fall back to env-var detection.
+ *
+ * Traps:
+ *  - `undefined` or `""` yields `{ provider: undefined, name: "" }` — an EMPTY
+ *    name, not `undefined`. A caller forwarding `name` unchecked sends an empty
+ *    model id to the provider.
+ *  - A degenerate prefix is not an error. `"/foo"`, `"foo/"` and `" /x"` all come
+ *    back with `provider: undefined` and the ORIGINAL, untrimmed string as `name`;
+ *    trimming happens only when both halves are non-empty.
+ *  - Only the first `/` splits. `"openrouter/meta-llama/llama-3"` keeps
+ *    `meta-llama/llama-3` whole as the name.
+ */
 export declare function parseModelId(modelId: string | undefined): ParsedModelId;

package/dist/internal/llm/openai.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Real OpenAI Chat Completions client. Streams `/v1/chat/completions` and
+ * translates delta chunks into our provider-agnostic `LlmEvent`s.
+ *
+ * Uses native `fetch` only — no `openai` SDK dependency.
+ *
+ * @internal
+ */
 import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
 export interface OpenAIClientOptions {
     apiKey: string;

package/dist/internal/llm/prompt-cache-key.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/llm/responses.d.ts

@@ -8,14 +8,80 @@ export interface ResponsesApiClientOptions {
     /** Injected fetch (refresh-aware / dynamic headers). Defaults to global `fetch`. */
     fetch?: typeof fetch;
     providerName?: string;
+    /**
+     * usetheokit/theokit-sdk#383 — carry the model's ENCRYPTED reasoning across the rounds of a turn.
+     * Forwarded from `ProviderProfile.encryptedReasoning`; default off. See
+     * {@link ResponsesBodyOptions.encryptedReasoning} for what it puts on the wire and why it is
+     * opt-in rather than universal.
+     */
+    encryptedReasoning?: boolean;
+}
+/**
+ * usetheokit/theokit-sdk#383 — one reasoning item the model produced, as it must be replayed.
+ *
+ * `encrypted_content` is opaque ciphertext only the provider can read; the SDK never inspects it,
+ * never logs it, and never persists it. It exists to be handed straight back.
+ */
+interface ResponsesReasoningItem {
+    id: string;
+    encrypted_content: string;
+}
+/** Options that shape the request body beyond what an `LlmRequest` carries. */
+export interface ResponsesBodyOptions {
+    /**
+     * usetheokit/theokit-sdk#383 — when `true`, add `include: ["reasoning.encrypted_content"]` and
+     * `reasoning.context: "all_turns"`, and replay the reasoning items captured from earlier rounds.
+     *
+     * **What it buys.** With `store: false` the provider keeps nothing between requests, so a model
+     * that reasoned its way to a tool call in round 1 starts round 2 with no memory of that reasoning
+     * and derives it again — paid for again, every round. `include` asks the provider to return the
+     * reasoning as ciphertext; replaying that ciphertext on the next request hands the chain of
+     * thought back. Codex does exactly this against the same endpoint (issue #383 captured the
+     * request), which is the evidence that the backend accepts both fields.
+     *
+     * **Why opt-in and not on for every `responses_api` provider.** `include` is a documented
+     * Responses-API field, but `reasoning.context` is not part of the public Responses API surface —
+     * it was observed on the ChatGPT Codex backend. A provider that validates its input strictly
+     * answers an unknown key with `400`, which turns a cost optimisation into a total outage for that
+     * provider. Scoping it to profiles that DECLARE support keeps every other provider's request
+     * byte-identical to what it was, and makes enabling it a statement someone made about a specific
+     * backend rather than a hope about all of them.
+     */
+    encryptedReasoning?: boolean;
+    /**
+     * usetheokit/theokit-sdk#383 — reasoning items captured from earlier rounds, keyed by the
+     * `call_id` of the tool call each batch preceded.
+     *
+     * Keying on `call_id` is what keeps the replay ORDERED and self-correcting. The provider requires
+     * a reasoning item to sit immediately before the output it produced, and the conversation history
+     * the loop replays is the authority on which tool calls survived and in what order — so emitting
+     * each batch just before its own `function_call` reproduces the original sequence without the
+     * transport having to track conversation positions. A batch whose tool call is no longer in
+     * history is simply never emitted.
+     */
+    reasoningByCallId?: ReadonlyMap<string, readonly ResponsesReasoningItem[]>;
 }
 /** Build the Responses-API request body from an `LlmRequest`. */
-export declare function buildResponsesBody(request: LlmRequest): Record<string, unknown>;
+export declare function buildResponsesBody(request: LlmRequest, options?: ResponsesBodyOptions): Record<string, unknown>;
 export declare class ResponsesApiClient implements LlmClient {
     private readonly options;
     readonly name: string;
     private readonly baseUrl;
     private readonly fetchImpl;
+    /**
+     * usetheokit/theokit-sdk#383 — reasoning ciphertext captured from earlier rounds, keyed by the
+     * `call_id` it preceded. Held on the CLIENT rather than threaded through `LlmRequest` because a
+     * round's reasoning is provider-shaped ciphertext with a provider-shaped ordering rule; the agent
+     * loop has no use for it and the same client instance serves every round of a turn. Insertion
+     * order is the eviction order (see {@link MAX_REMEMBERED_REASONING_CALLS}).
+     */
+    private readonly reasoningByCallId;
     constructor(options: ResponsesApiClientOptions);
+    /**
+     * usetheokit/theokit-sdk#383 — bind a batch of reasoning ciphertext to the tool call it produced,
+     * evicting the oldest binding once the cap is reached.
+     */
+    private rememberReasoning;
     stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
 }
+export {};

package/dist/internal/llm/router.d.ts

@@ -23,6 +23,14 @@ export interface ProviderRouterOptions {
         attempt: number;
         retryAfterMs?: number;
     }) => void;
+    /**
+     * #332 — the endpoint THIS call should reach, from `ModelSelection.url`.
+     *
+     * It outranks the provider's base-URL env var deliberately. `OLLAMA_HOST` and friends are
+     * process-wide, so with the env var winning, whoever set it for one model would keep hijacking
+     * every other one — which is the bug this field exists to end, wearing a hat.
+     */
+    baseUrl?: string;
 }
 /**
  * Resolves the provider chain synchronously. Builtins are eagerly registered.

package/dist/internal/llm/types.d.ts

@@ -4,8 +4,19 @@
  * and yields a stream of `LlmEvent`s plus a final `LlmFinish` shape that
  * the agent loop converts into our `SDKMessage` events.
  *
- * @internal
+ * Semver-exempt: nothing here is declared in `package.json` `exports`. These types are nonetheless
+ * reachable from published declarations through the type graph, so they must be EMITTED.
+ *
+ * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,
+ * and TypeScript scans EVERY leading comment range of the declaration that follows. The tag that
+ * used to sit here deleted `LlmTool` from the emitted `.d.ts` while `LlmRequest`, which names it,
+ * survived — a declaration that does not compile for any consumer running type-aware lint.
  */
+export interface LlmTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
 export interface LlmTextPart {
     type: "text";
     text: string;
@@ -138,6 +149,21 @@ export interface LlmRequest {
      * is still forced to produce a closing summary.
      */
     toolChoice?: "auto" | "none" | "required";
+    /**
+     * usetheokit/theokit-sdk#383 — an opaque key identifying the conversation whose prompt prefix the
+     * provider may reuse across requests. Maps to the Responses-API `prompt_cache_key`.
+     *
+     * Set by the agent loop from the run's session identity and derived through
+     * `derivePromptCacheKey`, so it is STABLE across every round of a turn and every turn of a
+     * session, and DISTINCT between unrelated sessions. Both halves matter: a key that changes per
+     * round caches nothing, and a key shared across sessions asks the provider to match one
+     * conversation's prefix against another's.
+     *
+     * Absent ⇒ the field is omitted from the wire body (the pre-#383 request, byte for byte). It is
+     * a request-shaping hint only: no provider behaviour depends on its presence except the billing
+     * of the cached prefix.
+     */
+    promptCacheKey?: string;
 }
 /**
  * What a provider stream reports WHILE it is running. Tool calls are deliberately absent.

package/dist/internal/local-agent/real-local-run-provider.d.ts

@@ -1,8 +1,13 @@
 /**
  * Provider inference helpers for the real local run — extracted from
- * `real-local-run.ts` to keep it within the G8 LoC budget and give the two
- * pure "which provider?" heuristics one cohesive home.
+ * `real-local-run.ts` to keep it within the G8 LoC budget and give the
+ * "which provider?" heuristics one cohesive home.
+ *
+ * The precedence diagnostic joined them for the same two reasons: it answers the same question
+ * ("which provider, and was that what the caller asked for?"), and adding it inline pushed
+ * `real-local-run.ts` to 411 LoC against the 400 budget. The gate asked for a split and this is
+ * where the split already lives.
  *
  * @internal
  */
-export {};
+export declare function warnProviderPrecedenceOnce(asked: string | undefined, used: string): void;

package/dist/internal/local-agent/real-local-run-tools.d.ts

@@ -10,10 +10,29 @@
  *
  * @internal
  */
-import type { AgentDefinition, AgentOptions, CustomTool, ModelSelection } from "../../types/agent.js";
+import type { AgentDefinition, AgentOptions, BuiltinToolName, CustomTool, ModelSelection } from "../../types/agent.js";
 import type { CustomToolSpec } from "../agent-loop/loop-types.js";
-export declare function buildCustomToolsInput(agentOptions: AgentOptions, sendOptions: {
+/**
+ * Resolve the tool-catalog slice of `AgentLoopInputs` for this run: which custom tools the loop
+ * declares, and which SDK builtins it must NOT.
+ *
+ * Precedence for the custom half (matches the mcpServers semantics — "fully replaces, not merged"):
+ *  - `sendOptions.tools === undefined` → fall back to `agentOptions.tools`
+ *  - `sendOptions.tools = []`         → explicitly clear (no custom tools)
+ *  - `sendOptions.tools = [t1, ...]`  → use exactly these for this run
+ *
+ * usetheokit/theokit-sdk#381 added the builtin half, and it is why this is no longer named for
+ * custom tools alone. It rides here rather than at the call site because the withhold list is
+ * part of the same answer — what this run declares to the model — and because a run that
+ * withholds nothing must produce the same `AgentLoopInputs` it produced before the option existed,
+ * which is easiest to guarantee where the rest of the catalog is already assembled.
+ *
+ * Note the two halves are independent: an agent with no custom tools at all can still withhold a
+ * builtin, so the "no tools" early return carries the withhold list out with it.
+ */
+export declare function buildRunToolCatalogInput(agentOptions: AgentOptions, sendOptions: {
     tools?: CustomTool[];
 } | undefined, pluginManager: import("../plugins/manager.js").PluginManager | undefined, personalityToolWhitelist: ReadonlyArray<string> | undefined, agentId: string, personalityName: string | undefined, subagents: Record<string, AgentDefinition> | undefined, effectiveModel: ModelSelection | undefined): {
-    customTools: ReadonlyArray<CustomToolSpec>;
-} | Record<string, never>;
+    customTools?: ReadonlyArray<CustomToolSpec>;
+    withheldBuiltinTools?: ReadonlyArray<BuiltinToolName>;
+};

package/dist/internal/mcp/oauth.d.ts

@@ -1,3 +1,8 @@
+/**
+ * OAuth 2.1 PKCE flow runner for MCP HTTP servers. See ADR D41.
+ *
+ * @internal
+ */
 import type { McpOAuthConfig } from "../../types/mcp.js";
 import { type OAuthTokens } from "./token-storage.js";
 /**