@theokit/sdk 4.52.1 → 4.53.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 4.53.0
+
+### Minor Changes
+
+- 5cc5a81: Adds the `@theokit/sdk/mcp-auth` subpath: the OAuth PKCE flow for remote MCP servers
+  (`runPkceFlow`, `refreshAccessToken`) plus the token storage the two of them need
+  (`getTokens`, `setTokens`, `lockedRefresh`).
+
+  The implementation already existed and was tested; nothing exported it. A consumer
+  connecting to an MCP server that requires OAuth had to write RFC 7636 PKCE by hand — not
+  because the package lacked the code, but because there was no way in.
+
+  `lockedRefresh` ships alongside deliberately: two callers noticing an expired token at the
+  same moment will both refresh, and under a rotating refresh token the second one loses.
+
+- 5112ac3: Two fixes on the transcript persistence path.
+
+  `readJsonlTail`'s `sinceMarker` matched the marker as a substring of the raw line, so a
+  transcript entry whose own text contained the marker word truncated the read there. The
+  caller asks for everything after the last compaction and silently got less. The marker is
+  now matched as a record FIELD (`subtype`, then `type`), which is what it always meant.
+
+  `appendJsonl` created the transcript directory with the umask, so under `umask 002` it was
+  born `0775` — group-writable — while the file inside it was carefully pinned to `0600`. A
+  private file in a directory others can write can be replaced wholesale. The directory is now
+  created `0700`, matching the file, and matching what `assertSecureModes` demands of the
+  shared `~/.theokit` tree.
+
+### Patch Changes
+
+- cbb70c5: Security: the MCP OAuth token store now locks down its directory, and the shared permission gate stops refusing every store on Windows.
+
+  `setTokens` wrote through `atomicWriteJson`, whose parent-directory `mkdir` carries no mode, so `~/.theokit` was born 0775 under the common umask 002. The `chmod 600` on `mcp-tokens.json` then protects the wrong thing: write permission on a DIRECTORY is permission to unlink and recreate its contents, so another local user could replace the file wholesale — and the secret is a refresh token, so replacing it changes which account the agent authenticates as. The read path had no permission check at all, so the swap would be picked up silently.
+
+  The directory is created 0700 and `chmod`-ed unconditionally, because `mkdir`'s mode applies only at creation and the machines that need this fix already have the loose directory. Reads go through `assertSecureModes` — the same gate the credential file uses, deliberately the same implementation rather than a second dialect of the same rule.
+
+  Separately, `assertSecureModes` was unconditional and Windows has no POSIX mode bits: `statSync().mode` is synthetic there, so the gate refused every valid store and the credential path was unreadable on that platform. It now returns early on `win32`.
+
+  Behaviour change worth knowing: `getTokens` now THROWS `CredentialError` on a group- or world-writable store directory where it previously returned the tokens. That is intentional — returning them would hand back what may be an attacker's refresh token as if it were the user's — but a consumer catching nothing around `getTokens` will see the error surface. The fix on the operator side is `chmod 700 ~/.theokit`.
+
 ## 4.52.1
 
 ### Patch Changes
@@ -433,7 +473,7 @@
 
   The profile shipped `originator: "codex_cli_rs"` — the value the official Codex CLI sends for itself.
   Presenting another vendor's client name is a false statement of identity, and it diverged from the
-  prior art this provider was adapted from: OpenCode sends its own name against the same endpoint,
+  prior art: third-party clients send their own name against the same endpoint,
   which also shows the route is not restricted to the official client.
 
   A test pinned the old value as the contract, which is how it survived review — correcting the
@@ -1037,7 +1077,7 @@ cwd })` previously compiled and was silently ignored — it hydrated the process
 
 ### Minor Changes
 
-- Data-provider fleet (agent-builder M45): 9 new first-party builtins on a data-only `openAiCompatibleProfile` base — `google` (DIRECT Gemini via the OpenAI-compat endpoint, `GOOGLE_API_KEY`/`GEMINI_API_KEY`; distinct from the `gemini` OpenRouter passthrough), `mistral`, `groq`, `cohere` (via `api.cohere.ai/compatibility/v1`), `deepinfra`, `together` (alias `togetherai`), `xai` (alias `grok`), `perplexity`, `cerebras` — each ~10 lines with source-cited values. Two defects fixed: the chat_completions URL-join no longer doubles version segments (`…/v1/v1/chat/completions` — every version-suffixed catalog baseUrl was broken for streaming) via version-segment detection + a data-only `ProviderProfile.chatCompletionsPath` escape (existing builtins byte-identical, contract-asserted), and Google is finally reachable (the `google-gemini` catalog entry was silently skipped by an alias collision). The `anthropic_messages` transport now consumes `extraHeaders` + the provider `transform` (mirror of the M41 chat_completions wiring) and the anthropic builtin ships `anthropic-beta: interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14` (the sanctioned behavior delta); openrouter gains theokit's own attribution headers (`HTTP-Referer: https://usetheo.dev`, `X-Title: theokit`); cerebras sends `X-Cerebras-3rd-Party-Integration: theokit`. A table-driven contract suite asserts identity + the EXACT wire URL and headers per provider. Values adapted from OpenCode (MIT); see NOTICE.
+- Data-provider fleet (agent-builder M45): 9 new first-party builtins on a data-only `openAiCompatibleProfile` base — `google` (DIRECT Gemini via the OpenAI-compat endpoint, `GOOGLE_API_KEY`/`GEMINI_API_KEY`; distinct from the `gemini` OpenRouter passthrough), `mistral`, `groq`, `cohere` (via `api.cohere.ai/compatibility/v1`), `deepinfra`, `together` (alias `togetherai`), `xai` (alias `grok`), `perplexity`, `cerebras` — each ~10 lines with source-cited values. Two defects fixed: the chat_completions URL-join no longer doubles version segments (`…/v1/v1/chat/completions` — every version-suffixed catalog baseUrl was broken for streaming) via version-segment detection + a data-only `ProviderProfile.chatCompletionsPath` escape (existing builtins byte-identical, contract-asserted), and Google is finally reachable (the `google-gemini` catalog entry was silently skipped by an alias collision). The `anthropic_messages` transport now consumes `extraHeaders` + the provider `transform` (mirror of the M41 chat_completions wiring) and the anthropic builtin ships `anthropic-beta: interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14` (the sanctioned behavior delta); openrouter gains theokit's own attribution headers (`HTTP-Referer: https://usetheo.dev`, `X-Title: theokit`); cerebras sends `X-Cerebras-3rd-Party-Integration: theokit`. A table-driven contract suite asserts identity + the EXACT wire URL and headers per provider.
 
 ## 4.13.1
 
@@ -1049,7 +1089,7 @@ cwd })` previously compiled and was silently ignored — it hydrated the process
 
 ### Minor Changes
 
-- Model catalog enrichment (agent-builder M44): the vendored `provider-catalog.json` now carries OPTIONAL per-model data (`models` block — models.dev shape verbatim: `cost{input,output,cache_read,cache_write}` USD-per-1M, `limit{context,input,output}`, `modalities`, `tool_call`/`reasoning`/`structured_output`/`cache_control`, `release_date`, `status`), loaded into an internal model-info index keyed `provider/model` (entry id + aliases). Fully additive: entries without `models` behave byte-identically, `ProviderProfile` is untouched, the 10 builtins + all 43 catalog entries keep resolving, and a malformed model sub-entry drops that model with WARN keeping the provider. DRY reconciliation: `resolveModelCapabilities` is now catalog-backed (the hand-curated EXACT map migrated into the catalog and was deleted — parity-tested over the full old-map snapshot), and `getPricingEntry` gains a step-5 catalog fallback on total LiteLLM miss (provenance `pricingVersion:"catalog-vendored"`; the LiteLLM snapshot keeps absolute precedence — and the new drift advisory caught a real stale rate: `openai/o3` corrected 10/40 → 2/8). New on `@theokit/sdk/models`: `getModelInfo(modelId)` (the enriched per-model view) and `refreshModelCatalog({url?, force?})` — an EXPLICIT opt-in models.dev refresh with a 1h-TTL atomic disk cache under `~/.theokit/cache/models-dev/`, kill-switch `THEOKIT_DISABLE_MODELS_FETCH`, and the vendored catalog as offline fallback; startup and requests never touch the network. Mechanism adapted from OpenCode's models.dev consumption (MIT); see NOTICE. Maintenance: `scripts/refresh-catalog.mjs` regenerates the curated vendored subset (30 models, +36KB).
+- Model catalog enrichment (agent-builder M44): the vendored `provider-catalog.json` now carries OPTIONAL per-model data (`models` block — models.dev shape verbatim: `cost{input,output,cache_read,cache_write}` USD-per-1M, `limit{context,input,output}`, `modalities`, `tool_call`/`reasoning`/`structured_output`/`cache_control`, `release_date`, `status`), loaded into an internal model-info index keyed `provider/model` (entry id + aliases). Fully additive: entries without `models` behave byte-identically, `ProviderProfile` is untouched, the 10 builtins + all 43 catalog entries keep resolving, and a malformed model sub-entry drops that model with WARN keeping the provider. DRY reconciliation: `resolveModelCapabilities` is now catalog-backed (the hand-curated EXACT map migrated into the catalog and was deleted — parity-tested over the full old-map snapshot), and `getPricingEntry` gains a step-5 catalog fallback on total LiteLLM miss (provenance `pricingVersion:"catalog-vendored"`; the LiteLLM snapshot keeps absolute precedence — and the new drift advisory caught a real stale rate: `openai/o3` corrected 10/40 → 2/8). New on `@theokit/sdk/models`: `getModelInfo(modelId)` (the enriched per-model view) and `refreshModelCatalog({url?, force?})` — an EXPLICIT opt-in models.dev refresh with a 1h-TTL atomic disk cache under `~/.theokit/cache/models-dev/`, kill-switch `THEOKIT_DISABLE_MODELS_FETCH`, and the vendored catalog as offline fallback; startup and requests never touch the network. Maintenance: `scripts/refresh-catalog.mjs` regenerates the curated vendored subset (30 models, +36KB).
 
 ## 4.12.2
 
@@ -1067,19 +1107,19 @@ cwd })` previously compiled and was silently ignored — it hydrated the process
 
 ### Minor Changes
 
-- Codex provider as a builtin (agent-builder M43): a new first-class `openai-chatgpt` builtin `ProviderProfile` routes `openai-chatgpt/<model>` ids to the ChatGPT "Codex" backend (`https://chatgpt.com/backend-api/codex`, `responses_api`). Its `transform.fetch` resolves the LIVE credential from the ambient store per HTTP request — a freshly-refreshed Bearer + a dynamic `ChatGPT-Account-Id` header — so a mid-turn token expiry refreshes transparently with NO agent rebuild, and a not-logged-in request fails fast (no placeholder on the wire). The ambient store is `~/.theokit/auth.json` with a `THEOKIT_HOME` override so a consumer points it at its own store. Two account_id lifecycle fixes ship alongside: `ensureFreshCredential` now PRESERVES a stored `account_id` across refresh (OpenAI's refresh JWTs carry no top-level `account_id`), and `openaiDeviceLogin` JWT-extracts `chatgpt_account_id` at login. Protocol values + the OAuth config adapted from OpenCode (MIT); see NOTICE. Consumers add a provider in one SDK file; the Codex backend needs zero provider logic in the app.
+- Codex provider as a builtin (agent-builder M43): a new first-class `openai-chatgpt` builtin `ProviderProfile` routes `openai-chatgpt/<model>` ids to the ChatGPT "Codex" backend (`https://chatgpt.com/backend-api/codex`, `responses_api`). Its `transform.fetch` resolves the LIVE credential from the ambient store per HTTP request — a freshly-refreshed Bearer + a dynamic `ChatGPT-Account-Id` header — so a mid-turn token expiry refreshes transparently with NO agent rebuild, and a not-logged-in request fails fast (no placeholder on the wire). The ambient store is `~/.theokit/auth.json` with a `THEOKIT_HOME` override so a consumer points it at its own store. Two account_id lifecycle fixes ship alongside: `ensureFreshCredential` now PRESERVES a stored `account_id` across refresh (OpenAI's refresh JWTs carry no top-level `account_id`), and `openaiDeviceLogin` JWT-extracts `chatgpt_account_id` at login. Consumers add a provider in one SDK file; the Codex backend needs zero provider logic in the app.
 
 ## 4.11.1
 
 ### Patch Changes
 
-- Auth subsystem review fixes (agent-builder M42), grounded in OpenCode's provider-auth model: (1) an oauth provider that resolves NO credential now fails fast with a `ConfigurationError` (the `MissingCredentialError` analog) instead of putting the `__oauth_lazy_token__` placeholder on the wire — OpenCode never sends a placeholder; (2) `resolveCredential` no longer attributes a provider-less or mismatched-provider stored key to the requested provider (fail-closed — prevents cross-vendor key exposure, e.g. an Anthropic key POSTed to api.openai.com). The credential store/engine mechanics are unchanged.
+- Auth subsystem review fixes (agent-builder M42), grounded in the provider-auth model: (1) an oauth provider that resolves NO credential now fails fast with a `ConfigurationError` (the `MissingCredentialError` analog) instead of putting the `__oauth_lazy_token__` placeholder on the wire — a placeholder is never sent; (2) `resolveCredential` no longer attributes a provider-less or mismatched-provider stored key to the requested provider (fail-closed — prevents cross-vendor key exposure, e.g. an Anthropic key POSTed to api.openai.com). The credential store/engine mechanics are unchanged.
 
 ## 4.11.0
 
 ### Minor Changes
 
-- Auth subsystem (agent-builder M42): a new `@theokit/sdk/auth` sub-entry ships a credential store + OAuth engine, promoted DOWN from agent-builder's hardened M37 code, generalized to `provider: string` + a caller-supplied `CredentialStoreConfig` (no hardcoded client IDs). Public surface (`import { … } from "@theokit/sdk/auth"`): `resolveCredential(name)` returns a fresh (transparently-refreshed) `ResolvedCredential`; the credential store (`writeCredential`/`readAuthFile`/`readStoredOAuth`/`authFilePath`/`credentialHome`/`CredentialError`), the OAuth engine (`exchangeCode`/`refreshOAuthTokens`/`ensureFreshCredential`/`persistOAuthTokens`), the device flows (`deviceLogin`/`openaiDeviceLogin`/`requestDeviceCode`/`pollDeviceToken`/`requestOpenAIUsercode`/`parseJwtClaims`/`extractAccountId`), and the contract types (`CredentialStoreConfig`, `ResolvedCredential`, `StoredOAuthCredential`, `OAuthProviderConfig`, `OAuthTokens`, `HttpDeps`, `DeviceOAuthConfig`, `OpenAIDeviceConfig`, …). It sits at a dedicated sub-entry (DTS via tsc) — the same isolation as `@theokit/sdk/messages` / `/subscription` / `/sanitize` — because rollup-plugin-dts cannot bundle the modules into the main barrel. The credential store does an atomic O_EXCL + rename + fsync write at mode 0600 with 0700/0600 mode gates; the OAuth engine implements RFC 8628 device-grant + the OpenAI two-step headless flow + token exchange/refresh with in-flight-refresh coalescing (keyed by store path, rejected promise evicted — single-use refresh tokens are never double-spent) and a no-token-in-error discipline. The router's lazy-sentinel path now covers `oauth_device_code` / `oauth_external` so an oauth provider builds a client whose M41 `transform.fetch(ctx)` owns the fresh bearer at stream time — a mid-turn expiry refreshes without rebuilding the agent, and plain (api-key/env) profiles resolve byte-for-byte unchanged. Device-grant + JWT extraction + OpenAI two-step adapted from OpenCode (MIT); see NOTICE.
+- Auth subsystem (agent-builder M42): a new `@theokit/sdk/auth` sub-entry ships a credential store + OAuth engine, promoted DOWN from agent-builder's hardened M37 code, generalized to `provider: string` + a caller-supplied `CredentialStoreConfig` (no hardcoded client IDs). Public surface (`import { … } from "@theokit/sdk/auth"`): `resolveCredential(name)` returns a fresh (transparently-refreshed) `ResolvedCredential`; the credential store (`writeCredential`/`readAuthFile`/`readStoredOAuth`/`authFilePath`/`credentialHome`/`CredentialError`), the OAuth engine (`exchangeCode`/`refreshOAuthTokens`/`ensureFreshCredential`/`persistOAuthTokens`), the device flows (`deviceLogin`/`openaiDeviceLogin`/`requestDeviceCode`/`pollDeviceToken`/`requestOpenAIUsercode`/`parseJwtClaims`/`extractAccountId`), and the contract types (`CredentialStoreConfig`, `ResolvedCredential`, `StoredOAuthCredential`, `OAuthProviderConfig`, `OAuthTokens`, `HttpDeps`, `DeviceOAuthConfig`, `OpenAIDeviceConfig`, …). It sits at a dedicated sub-entry (DTS via tsc) — the same isolation as `@theokit/sdk/messages` / `/subscription` / `/sanitize` — because rollup-plugin-dts cannot bundle the modules into the main barrel. The credential store does an atomic O_EXCL + rename + fsync write at mode 0600 with 0700/0600 mode gates; the OAuth engine implements RFC 8628 device-grant + the OpenAI two-step headless flow + token exchange/refresh with in-flight-refresh coalescing (keyed by store path, rejected promise evicted — single-use refresh tokens are never double-spent) and a no-token-in-error discipline. The router's lazy-sentinel path now covers `oauth_device_code` / `oauth_external` so an oauth provider builds a client whose M41 `transform.fetch(ctx)` owns the fresh bearer at stream time — a mid-turn expiry refreshes without rebuilding the agent, and plain (api-key/env) profiles resolve byte-for-byte unchanged.
 
 ## 4.10.1
 
@@ -1091,7 +1131,7 @@ cwd })` previously compiled and was silently ignored — it hydrated the process
 
 ### Minor Changes
 
-- Provider `transform` seam (agent-builder M41): `ProviderProfile` gains an optional `transform` (dynamic `headers(ctx)` + refresh-aware `fetch(ctx)`), fed through `selectTransport` into the `chat_completions` + `responses_api` transports — a provider can now own its per-request auth/headers. A profile without `transform` takes the static path byte-for-byte. Contract-shape adaptation of OpenCode's provider `auth.loader` (MIT).
+- Provider `transform` seam (agent-builder M41): `ProviderProfile` gains an optional `transform` (dynamic `headers(ctx)` + refresh-aware `fetch(ctx)`), fed through `selectTransport` into the `chat_completions` + `responses_api` transports — a provider can now own its per-request auth/headers. A profile without `transform` takes the static path byte-for-byte.
 
 ## 4.9.1
 
@@ -1103,7 +1143,7 @@ cwd })` previously compiled and was silently ignored — it hydrated the process
 
 ### Minor Changes
 
-- `responses_api` transport (agent-builder M40): a `ResponsesApiClient` for the OpenAI Responses API (ChatGPT Codex backend + any responses provider). The `responses_api` apiMode was declared but had no transport (`selectTransport` threw); this ships it — body build + SSE state machine, consuming `baseUrl` + `extraHeaders`. Protocol shape adapted from OpenCode's `openai-responses.ts` (MIT), recorded fixtures as golden tests.
+- `responses_api` transport (agent-builder M40): a `ResponsesApiClient` for the OpenAI Responses API (ChatGPT Codex backend + any responses provider). The `responses_api` apiMode was declared but had no transport (`selectTransport` threw); this ships it — body build + SSE state machine, consuming `baseUrl` + `extraHeaders`. Recorded fixtures serve as golden tests.
 
 ## 4.8.0
 

package/LICENSE

@@ -137,8 +137,8 @@
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
-  <a href="https://usetheo.dev">
-    <img src="https://usetheo.dev/logo-128.png" alt="Theo" height="80" />
+  <a href="https://github.com/usetheokit/theokit-sdk">
+    <img src="https://raw.githubusercontent.com/usetheodev/theokit-sdk/main/assets/logo.png" alt="TheoKit" height="96" />
   </a>
 </p>
 
@@ -13,7 +13,7 @@
     Same agent surface, local or cloud. No vendor lock-in.
   </p>
   <p align="center">
-    <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square"></a>
+    <a href="https://github.com/usetheokit/theokit-sdk/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-DE2329?style=flat-square"></a>
     <img alt="TypeScript" src="https://img.shields.io/badge/typescript-5.8%2B-3178C6?style=flat-square&logo=typescript&logoColor=white">
     <img alt="Node" src="https://img.shields.io/badge/node-22.12%2B-339933?style=flat-square&logo=node.js&logoColor=white">
     <img alt="Status" src="https://img.shields.io/badge/status-public%20beta-orange?style=flat-square">
@@ -24,11 +24,11 @@
 
 > **Public beta.** APIs may change before general availability.
 
-For the full reference, see the [root README](https://github.com/usetheodev/theokit-sdk#readme) and the [**Harness Capability Map**](https://github.com/usetheodev/theokit-sdk/blob/main/wiki/reference/harness-capability-map.md). The exported TypeScript types are the canonical contract.
+For the full reference, see the [root README](https://github.com/usetheokit/theokit-sdk#readme). The exported TypeScript types are the canonical contract.
 
 ## Capability map
 
-New here? The [**Theo Harness Capability Map**](https://github.com/usetheodev/theokit-sdk/blob/main/wiki/reference/harness-capability-map.md) is the discovery front-door — every harness primitive with its import path, signature, and a one-line example (find `compactTranscript`, `buildRepoMap`, `isTransientError`, `@theokit/sdk/persistence`, ... without reading source). The exported TypeScript types are the canonical contract.
+New here? The exported TypeScript types are the discovery front-door and the canonical contract — every harness primitive with its import path, signature and JSDoc example (`compactTranscript`, `buildRepoMap`, `isTransientError`, `@theokit/sdk/persistence`, ...), surfaced by your editor.
 
 It also **ships inside this package** — no network needed, and pinned to the version you installed:
 

package/bin/theokit-migrate-config.mjs

@@ -7,6 +7,7 @@
 //
 // Usage: theokit-migrate-config [--cwd <path>] [--apply] [--no-backup] [--help]
 
+import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -53,10 +54,18 @@ manual edits). Atomic write per file (crash mid-write is safe).
   );
 }
 
-/** Atomic write: tmpfile + rename. Mirrors atomicWriteText in the SDK. */
+/**
+ * Atomic write: tmpfile + rename. Mirrors atomicWriteText in the SDK.
+ *
+ * The suffix comes from `randomBytes`, matching `atomicWriteTempPath` in
+ * src/internal/persistence/atomic-write.ts — `<file>.<pid>.<16 hex>.tmp`. It used
+ * `Math.random()`, which this comment already claimed it did not: a temp name in a
+ * directory an attacker can also write to is guessable, and the window between
+ * choosing the name and `rename` is where a symlink gets planted.
+ */
 async function atomicWriteText(filePath, content) {
   await mkdir(join(filePath, ".."), { recursive: true });
-  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+  const tmp = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
   await writeFile(tmp, content, "utf8");
   await rename(tmp, filePath);
 }

package/dist/{agent-BiCINq25.d.ts → agent-B9HXlwID.d.ts}

@@ -1299,8 +1299,8 @@ interface ProviderTransformContext {
  * M41 — the one OPTIONAL behavior seam on a provider profile. It lets a provider own its per-request auth:
  * `fetch` is the universal seam (a provider that returns its own fetch fully controls headers + refresh, for
  * every transport that accepts a fetch); `headers` is a convenience merged over `extraHeaders` on transports
- * that carry them (responses_api). This is the CONTRACT-shape adaptation of OpenCode's provider `auth.loader`
- * (MIT © 2025 opencode — `packages/core/src/plugin/provider/*.ts`), retargeted to theokit's transport model.
+ * that carry them (responses_api). A provider owns its per-request auth material plus transparent token
+ * refresh, expressed against theokit's transport model.
  * Closes the gap where a `ProviderProfile` could only declare STATIC headers.
  *
  * @public
@@ -1510,9 +1510,25 @@ interface LocalOptions {
         enabled: boolean;
     };
     /**
-     * SE40 — base directory for the native Claude-shaped session transcript
-     * (`<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl`). Default `~/.theokit`.
+     * Directory for the native Claude-shaped session transcript
+     * (`<sessionDir>/projects/<encoded-cwd>/<agentId>.jsonl`). Default `~/.theokit`.
      * Set to `~/.claude` to write sessions the Claude Code CLI can `--continue`.
+     *
+     * **This is not the working directory** — that is {@link LocalOptions.cwd},
+     * four lines above. Only transcripts are written here.
+     *
+     * Introduced in #301 as the unambiguous name for what `baseDir` always meant.
+     */
+    sessionDir?: string;
+    /**
+     * @deprecated Renamed to {@link LocalOptions.sessionDir} (#301). Still honoured,
+     * and `sessionDir` wins when both are set.
+     *
+     * "Base directory" reads as the directory the agent works in, sitting in an
+     * interface whose `cwd` is the one that actually means that. Setting it to
+     * `"./"` — which is what the name invites — runs without error and writes
+     * `./projects/<encoded-cwd>/<agentId>.jsonl` into the caller's repository root.
+     * Nothing warns, because nothing is wrong from the code's point of view.
      */
     baseDir?: string;
     /**
@@ -1820,10 +1836,7 @@ interface AgentOptions {
      *
      * `'run'` (DEFAULT, and the historical behaviour) spawns a client per `send` and drops it when the
      * run ends. `'session'` pools clients per `(agentId, server, config)` and keeps them across turns,
-     * which is what the reference does — Codex holds its MCP runtime in `SessionServices`
-     * (`codex-rs/core/src/state/service.rs:51-58`; theokit#155 corrected the earlier
-     * `core/src/state/service.rs:116`, which named a parameter of `install_mcp_runtime`, not the
-     * owning field). Measured cost of the per-run path: 193 / 138 / 134 ms of spawn + handshake on
+     * which keeps the MCP runtime alive across turns. Measured cost of the per-run path: 193 / 138 / 134 ms of spawn + handshake on
      * every turn.
      *
      * Opt-in rather than default because it changes the FAILURE model: a server that dies mid-session

package/dist/agent-FFVV4U5N.js

@@ -0,0 +1,50 @@
+export { Agent } from './chunk-G3JWXOGY.js';
+import './chunk-GOVJO4YE.js';
+import './chunk-PGP7IOJ2.js';
+import './chunk-2SFBB54R.js';
+import './chunk-XROIW6BH.js';
+import './chunk-K2BQQ445.js';
+import './chunk-B6HOIWQ6.js';
+import './chunk-LS3LMQ23.js';
+import './chunk-GBBDINFK.js';
+import './chunk-4QEC4CCS.js';
+import './chunk-BERBYXFH.js';
+import './chunk-SEL2ZQMT.js';
+import './chunk-HKCKOAIO.js';
+import './chunk-34XOCZJO.js';
+import './chunk-PBZ7HMBP.js';
+import './chunk-KSWHTR54.js';
+import './chunk-FFM3SJTQ.js';
+import './chunk-OXNYIMZZ.js';
+import './chunk-FD2UT76F.js';
+import './chunk-U54XCYG3.js';
+import './chunk-NAF4L3T6.js';
+import './chunk-RP5HQVLD.js';
+import './chunk-6X6ID4MO.js';
+import './chunk-4NAKHID5.js';
+import './chunk-7AD3ZTZL.js';
+import './chunk-3WVMJY7F.js';
+import './chunk-R5YZACGK.js';
+import './chunk-POWRZSK4.js';
+import './chunk-N5CR3TJZ.js';
+import './chunk-NZL4BNFQ.js';
+import './chunk-MSFLYJDY.js';
+import './chunk-2XLKLVVR.js';
+import './chunk-V26QVGUG.js';
+import './chunk-4VPXM6UU.js';
+import './chunk-6AZDM6LK.js';
+import './chunk-UFIXH26P.js';
+import './chunk-HE4BIAOS.js';
+import './chunk-X2FR4OIT.js';
+import './chunk-HSQ5Q3I5.js';
+import './chunk-SSDD676S.js';
+import './chunk-3V7UJLQT.js';
+import './chunk-5NBUH3NO.js';
+import './chunk-OY7O3Q6R.js';
+import './chunk-SK4QLUBK.js';
+import './chunk-RIAM53CP.js';
+import './chunk-DGOG5NXR.js';
+import './chunk-U4UJHOSH.js';
+import './chunk-5F5NWKPN.js';
+//# sourceMappingURL=agent-FFVV4U5N.js.map
+//# sourceMappingURL=agent-FFVV4U5N.js.map

package/dist/{agent-RDHK6MVT.js.map → agent-FFVV4U5N.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-RDHK6MVT.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-FFVV4U5N.js"}

package/dist/agent-YLAHVHEH.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+var chunkF77UENR6_cjs = require('./chunk-F77UENR6.cjs');
+require('./chunk-2D43RD5D.cjs');
+require('./chunk-665SFFFR.cjs');
+require('./chunk-BV2MWEMV.cjs');
+require('./chunk-XPR366DL.cjs');
+require('./chunk-BUUUWQMB.cjs');
+require('./chunk-OUOXM36O.cjs');
+require('./chunk-2FYEVT2B.cjs');
+require('./chunk-3X6PM7DU.cjs');
+require('./chunk-4JBHSLQO.cjs');
+require('./chunk-D75S2X6I.cjs');
+require('./chunk-BDTVFIPB.cjs');
+require('./chunk-2ZPEDVLM.cjs');
+require('./chunk-OKLYRPKL.cjs');
+require('./chunk-HAWE74GQ.cjs');
+require('./chunk-RAHSWE5C.cjs');
+require('./chunk-SVO5WPZX.cjs');
+require('./chunk-2RW7K6FN.cjs');
+require('./chunk-MUUQ2WFJ.cjs');
+require('./chunk-6JSIEDKL.cjs');
+require('./chunk-FRITRLZQ.cjs');
+require('./chunk-B4YA6BRS.cjs');
+require('./chunk-NINIJCHU.cjs');
+require('./chunk-L5YO6PWL.cjs');
+require('./chunk-VJ26EKGJ.cjs');
+require('./chunk-WQ53UQL4.cjs');
+require('./chunk-C5DEO6OI.cjs');
+require('./chunk-3BK6YR5P.cjs');
+require('./chunk-Y4AXQOT4.cjs');
+require('./chunk-TTJ54H3E.cjs');
+require('./chunk-JIQRXKTA.cjs');
+require('./chunk-YLQQX5W2.cjs');
+require('./chunk-VGPXHHF3.cjs');
+require('./chunk-WJVHMTKB.cjs');
+require('./chunk-C4H6PB5J.cjs');
+require('./chunk-E7FJOO4G.cjs');
+require('./chunk-ADLLFY3H.cjs');
+require('./chunk-VYHJZVL5.cjs');
+require('./chunk-VUKQL3L2.cjs');
+require('./chunk-VF7X6HDR.cjs');
+require('./chunk-5YKNEMXR.cjs');
+require('./chunk-C6Y6CWYD.cjs');
+require('./chunk-ZN2DGEY3.cjs');
+require('./chunk-ZT57WTUJ.cjs');
+require('./chunk-VKJ7V7EB.cjs');
+require('./chunk-SZHU7A5B.cjs');
+require('./chunk-LPVIRJVF.cjs');
+require('./chunk-BM6N4KHO.cjs');
+
+
+
+Object.defineProperty(exports, "Agent", {
+  enumerable: true,
+  get: function () { return chunkF77UENR6_cjs.Agent; }
+});
+//# sourceMappingURL=agent-YLAHVHEH.cjs.map
+//# sourceMappingURL=agent-YLAHVHEH.cjs.map

package/dist/{agent-U2R2R5JP.cjs.map → agent-YLAHVHEH.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-U2R2R5JP.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-YLAHVHEH.cjs"}

package/dist/{agent-Zta1kvGH.d.cts → agent-nLqeXKIX.d.cts}

@@ -1299,8 +1299,8 @@ interface ProviderTransformContext {
  * M41 — the one OPTIONAL behavior seam on a provider profile. It lets a provider own its per-request auth:
  * `fetch` is the universal seam (a provider that returns its own fetch fully controls headers + refresh, for
  * every transport that accepts a fetch); `headers` is a convenience merged over `extraHeaders` on transports
- * that carry them (responses_api). This is the CONTRACT-shape adaptation of OpenCode's provider `auth.loader`
- * (MIT © 2025 opencode — `packages/core/src/plugin/provider/*.ts`), retargeted to theokit's transport model.
+ * that carry them (responses_api). A provider owns its per-request auth material plus transparent token
+ * refresh, expressed against theokit's transport model.
  * Closes the gap where a `ProviderProfile` could only declare STATIC headers.
  *
  * @public
@@ -1510,9 +1510,25 @@ interface LocalOptions {
         enabled: boolean;
     };
     /**
-     * SE40 — base directory for the native Claude-shaped session transcript
-     * (`<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl`). Default `~/.theokit`.
+     * Directory for the native Claude-shaped session transcript
+     * (`<sessionDir>/projects/<encoded-cwd>/<agentId>.jsonl`). Default `~/.theokit`.
      * Set to `~/.claude` to write sessions the Claude Code CLI can `--continue`.
+     *
+     * **This is not the working directory** — that is {@link LocalOptions.cwd},
+     * four lines above. Only transcripts are written here.
+     *
+     * Introduced in #301 as the unambiguous name for what `baseDir` always meant.
+     */
+    sessionDir?: string;
+    /**
+     * @deprecated Renamed to {@link LocalOptions.sessionDir} (#301). Still honoured,
+     * and `sessionDir` wins when both are set.
+     *
+     * "Base directory" reads as the directory the agent works in, sitting in an
+     * interface whose `cwd` is the one that actually means that. Setting it to
+     * `"./"` — which is what the name invites — runs without error and writes
+     * `./projects/<encoded-cwd>/<agentId>.jsonl` into the caller's repository root.
+     * Nothing warns, because nothing is wrong from the code's point of view.
      */
     baseDir?: string;
     /**
@@ -1820,10 +1836,7 @@ interface AgentOptions {
      *
      * `'run'` (DEFAULT, and the historical behaviour) spawns a client per `send` and drops it when the
      * run ends. `'session'` pools clients per `(agentId, server, config)` and keeps them across turns,
-     * which is what the reference does — Codex holds its MCP runtime in `SessionServices`
-     * (`codex-rs/core/src/state/service.rs:51-58`; theokit#155 corrected the earlier
-     * `core/src/state/service.rs:116`, which named a parameter of `install_mcp_runtime`, not the
-     * owning field). Measured cost of the per-run path: 193 / 138 / 134 ms of spawn + handshake on
+     * which keeps the MCP runtime alive across turns. Measured cost of the per-run path: 193 / 138 / 134 ms of spawn + handshake on
      * every turn.
      *
      * Opt-in rather than default because it changes the FAILURE model: a server that dies mid-session

package/dist/agent-session-store-DUGBAX5V.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+var chunkD75S2X6I_cjs = require('./chunk-D75S2X6I.cjs');
+require('./chunk-Y4AXQOT4.cjs');
+require('./chunk-C4H6PB5J.cjs');
+require('./chunk-BM6N4KHO.cjs');
+
+
+
+Object.defineProperty(exports, "appendCompactBoundaryRecord", {
+  enumerable: true,
+  get: function () { return chunkD75S2X6I_cjs.appendCompactBoundaryRecord; }
+});
+Object.defineProperty(exports, "persistTurn", {
+  enumerable: true,
+  get: function () { return chunkD75S2X6I_cjs.persistTurn; }
+});
+Object.defineProperty(exports, "readSessionMessages", {
+  enumerable: true,
+  get: function () { return chunkD75S2X6I_cjs.readSessionMessages; }
+});
+//# sourceMappingURL=agent-session-store-DUGBAX5V.cjs.map
+//# sourceMappingURL=agent-session-store-DUGBAX5V.cjs.map

package/dist/{agent-session-store-EPX2WQI4.cjs.map → agent-session-store-DUGBAX5V.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-session-store-EPX2WQI4.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-session-store-DUGBAX5V.cjs"}

package/dist/agent-session-store-TNCGL5RN.js

@@ -0,0 +1,6 @@
+export { appendCompactBoundaryRecord, persistTurn, readSessionMessages } from './chunk-BERBYXFH.js';
+import './chunk-N5CR3TJZ.js';
+import './chunk-6AZDM6LK.js';
+import './chunk-5F5NWKPN.js';
+//# sourceMappingURL=agent-session-store-TNCGL5RN.js.map
+//# sourceMappingURL=agent-session-store-TNCGL5RN.js.map

package/dist/{agent-session-store-JMU7ASDB.js.map → agent-session-store-TNCGL5RN.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-session-store-JMU7ASDB.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-session-store-TNCGL5RN.js"}

package/dist/agent.d.ts

@@ -45,7 +45,22 @@ export declare class Agent {
      */
     static create(options: AgentOptions): Promise<SDKAgent>;
     /**
-     * One-shot prompt: create an agent, send a single message, wait, dispose.
+     * One-shot prompt: create an agent, send a single message, wait, **dispose**.
+     *
+     * `Agent.prompt` is STATIC and owns the agent's whole lifecycle. To send to an
+     * agent you already hold, use the instance method — `agent.send(message)` —
+     * which keeps the conversation and does not dispose anything:
+     *
+     * ```ts
+     * const agent = await Agent.create({ ... });
+     * const run = await agent.send("first");     // NOT agent.prompt(...)
+     * const run2 = await agent.send("follow-up"); // full context retained
+     * ```
+     *
+     * There is no `agent.prompt()` (#302). The natural sentence for the second
+     * operation is "prompt the agent", so it is the method people reach for; the
+     * two differ in whether the agent survives the call, which is why they do not
+     * share a name.
      *
      * When `options.throwOnError === true`, rejects with `AgentRunError` if
      * the run terminates with `status: 'error'` (instead of resolving with the

package/dist/auth/index.cjs

@@ -1,10 +1,11 @@
 'use strict';
 
 var chunkFRITRLZQ_cjs = require('../chunk-FRITRLZQ.cjs');
-var chunkXK54DTRF_cjs = require('../chunk-XK54DTRF.cjs');
+var chunkVF7X6HDR_cjs = require('../chunk-VF7X6HDR.cjs');
+var chunk5YKNEMXR_cjs = require('../chunk-5YKNEMXR.cjs');
 var chunkC6Y6CWYD_cjs = require('../chunk-C6Y6CWYD.cjs');
-require('../chunk-2YGIBOUH.cjs');
-require('../chunk-SXSPMRSV.cjs');
+require('../chunk-LPVIRJVF.cjs');
+require('../chunk-BM6N4KHO.cjs');
 
 // src/internal/auth/oauth-device.ts
 var POLLING_SAFETY_MARGIN_MS = 3e3;
@@ -87,7 +88,7 @@ async function pollDeviceToken(config, grant, deps) {
       return {
         access: data.access_token,
         // Some device-grant providers (e.g. GitHub) issue no separate refresh token — reuse the access
-        // token as the refresh handle, mirroring OpenCode's copilot flow.
+        // token as the refresh handle.
         refresh: data.refresh_token ?? data.access_token,
         expires: deps.now() + expiresIn * 1e3,
         ...accountId !== void 0 ? { accountId } : {}
@@ -184,7 +185,7 @@ async function openaiDeviceLogin(config, deps, hooks) {
           "device poll returned no authorization_code"
         );
       }
-      const tokens = await chunkXK54DTRF_cjs.exchangeCode(
+      const tokens = await chunkVF7X6HDR_cjs.exchangeCode(
         config,
         { code: data.authorization_code, verifier: data.code_verifier },
         deps
@@ -230,53 +231,53 @@ Object.defineProperty(exports, "providerFromApiKeyPrefix", {
   enumerable: true,
   get: function () { return chunkFRITRLZQ_cjs.providerFromApiKeyPrefix; }
 });
-Object.defineProperty(exports, "CredentialError", {
+Object.defineProperty(exports, "ensureFreshCredential", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.CredentialError; }
+  get: function () { return chunkVF7X6HDR_cjs.ensureFreshCredential; }
 });
-Object.defineProperty(exports, "assertSecureModes", {
+Object.defineProperty(exports, "exchangeCode", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.assertSecureModes; }
+  get: function () { return chunkVF7X6HDR_cjs.exchangeCode; }
 });
-Object.defineProperty(exports, "authFilePath", {
+Object.defineProperty(exports, "persistOAuthTokens", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.authFilePath; }
+  get: function () { return chunkVF7X6HDR_cjs.persistOAuthTokens; }
 });
-Object.defineProperty(exports, "credentialHome", {
+Object.defineProperty(exports, "refreshOAuthTokens", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.credentialHome; }
+  get: function () { return chunkVF7X6HDR_cjs.refreshOAuthTokens; }
 });
-Object.defineProperty(exports, "ensureFreshCredential", {
+Object.defineProperty(exports, "resolveCredential", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.ensureFreshCredential; }
+  get: function () { return chunkVF7X6HDR_cjs.resolveCredential; }
 });
-Object.defineProperty(exports, "exchangeCode", {
+Object.defineProperty(exports, "CredentialError", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.exchangeCode; }
+  get: function () { return chunk5YKNEMXR_cjs.CredentialError; }
 });
-Object.defineProperty(exports, "persistOAuthTokens", {
+Object.defineProperty(exports, "assertSecureModes", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.persistOAuthTokens; }
+  get: function () { return chunk5YKNEMXR_cjs.assertSecureModes; }
 });
-Object.defineProperty(exports, "readAuthFile", {
+Object.defineProperty(exports, "authFilePath", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.readAuthFile; }
+  get: function () { return chunk5YKNEMXR_cjs.authFilePath; }
 });
-Object.defineProperty(exports, "readStoredOAuth", {
+Object.defineProperty(exports, "credentialHome", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.readStoredOAuth; }
+  get: function () { return chunk5YKNEMXR_cjs.credentialHome; }
 });
-Object.defineProperty(exports, "refreshOAuthTokens", {
+Object.defineProperty(exports, "readAuthFile", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.refreshOAuthTokens; }
+  get: function () { return chunk5YKNEMXR_cjs.readAuthFile; }
 });
-Object.defineProperty(exports, "resolveCredential", {
+Object.defineProperty(exports, "readStoredOAuth", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.resolveCredential; }
+  get: function () { return chunk5YKNEMXR_cjs.readStoredOAuth; }
 });
 Object.defineProperty(exports, "writeCredential", {
   enumerable: true,
-  get: function () { return chunkXK54DTRF_cjs.writeCredential; }
+  get: function () { return chunk5YKNEMXR_cjs.writeCredential; }
 });
 exports.deviceLogin = deviceLogin;
 exports.extractAccountId = extractAccountId;