@theokit/sdk 4.53.0 → 4.54.0

package/dist/internal/persistence/sqlite-wal.d.cts

@@ -1 +1,54 @@
+/**
+ * SQLite WAL mode helper with NFS/SMB/FUSE fallback to DELETE (ADR D63).
+ *
+ * WAL is faster (concurrent readers + one writer) but unsupported on some
+ * network/FUSE filesystems. Try WAL; if the pragma returns something else
+ * or throws, fall back to DELETE journal mode. Warn one time per label.
+ *
+ * This block is the MODULE header and must stay at offset 0. Sitting below the import it became a
+ * leading comment of the first declaration instead, which is how its tag deleted `PragmaCapable`
+ * from the emitted `.d.ts` while `applyWalWithFallback` — which names it — survived.
+ */
+/**
+ * The narrow slice of a SQLite handle this module needs: anything with a `pragma()` method, which
+ * `better-sqlite3` satisfies without being named here.
+ *
+ * Not exported, but it appears in the signature of `applyWalWithFallback`, so it is emitted into
+ * the published declarations and a consumer can structurally satisfy it.
+ */
+interface PragmaCapable {
+    pragma: (statement: string, options?: {
+        simple?: boolean;
+    }) => unknown;
+}
+/**
+ * What journal mode a connection ended up in after `applyWalWithFallback`.
+ *
+ * `mode` is the mode actually in effect, never the one that was requested. `fellBack` is `true`
+ * only when WAL was attempted and refused — either the pragma threw or it reported a mode other
+ * than `wal` — and the connection was put into DELETE instead.
+ *
+ * `fellBack: true` is normal on NFS, SMB and FUSE, where WAL needs shared memory the filesystem
+ * does not provide. It is not an error and nothing further is required of the caller; the
+ * consequence is slower concurrent access, since DELETE mode does not allow readers alongside a
+ * writer. Treat it as a signal about the storage, not about the database.
+ *
+ * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for
+ * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.
+ */
+export interface WalApplyResult {
+    /** Final journal_mode actually in effect. */
+    mode: "wal" | "delete";
+    /** True if we wanted WAL but the filesystem refused. */
+    fellBack: boolean;
+}
+/**
+ * Apply WAL mode with DELETE fallback. Idempotent — safe to call multiple
+ * times on the same connection.
+ *
+ * @param db   any `pragma()`-capable SQLite handle (e.g., `better-sqlite3`)
+ * @param label short identifier used in the warning (e.g., "memory-index")
+ *
+ */
+export declare function applyWalWithFallback(db: PragmaCapable, label: string): WalApplyResult;
 export {};

package/dist/internal/persistence/sqlite-wal.d.ts

@@ -1 +1,54 @@
+/**
+ * SQLite WAL mode helper with NFS/SMB/FUSE fallback to DELETE (ADR D63).
+ *
+ * WAL is faster (concurrent readers + one writer) but unsupported on some
+ * network/FUSE filesystems. Try WAL; if the pragma returns something else
+ * or throws, fall back to DELETE journal mode. Warn one time per label.
+ *
+ * This block is the MODULE header and must stay at offset 0. Sitting below the import it became a
+ * leading comment of the first declaration instead, which is how its tag deleted `PragmaCapable`
+ * from the emitted `.d.ts` while `applyWalWithFallback` — which names it — survived.
+ */
+/**
+ * The narrow slice of a SQLite handle this module needs: anything with a `pragma()` method, which
+ * `better-sqlite3` satisfies without being named here.
+ *
+ * Not exported, but it appears in the signature of `applyWalWithFallback`, so it is emitted into
+ * the published declarations and a consumer can structurally satisfy it.
+ */
+interface PragmaCapable {
+    pragma: (statement: string, options?: {
+        simple?: boolean;
+    }) => unknown;
+}
+/**
+ * What journal mode a connection ended up in after `applyWalWithFallback`.
+ *
+ * `mode` is the mode actually in effect, never the one that was requested. `fellBack` is `true`
+ * only when WAL was attempted and refused — either the pragma threw or it reported a mode other
+ * than `wal` — and the connection was put into DELETE instead.
+ *
+ * `fellBack: true` is normal on NFS, SMB and FUSE, where WAL needs shared memory the filesystem
+ * does not provide. It is not an error and nothing further is required of the caller; the
+ * consequence is slower concurrent access, since DELETE mode does not allow readers alongside a
+ * writer. Treat it as a signal about the storage, not about the database.
+ *
+ * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for
+ * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.
+ */
+export interface WalApplyResult {
+    /** Final journal_mode actually in effect. */
+    mode: "wal" | "delete";
+    /** True if we wanted WAL but the filesystem refused. */
+    fellBack: boolean;
+}
+/**
+ * Apply WAL mode with DELETE fallback. Idempotent — safe to call multiple
+ * times on the same connection.
+ *
+ * @param db   any `pragma()`-capable SQLite handle (e.g., `better-sqlite3`)
+ * @param label short identifier used in the warning (e.g., "memory-index")
+ *
+ */
+export declare function applyWalWithFallback(db: PragmaCapable, label: string): WalApplyResult;
 export {};

package/dist/internal/persistence/transcript-ops.d.cts

@@ -70,7 +70,6 @@ export declare function forkTranscript(src: string, dst: string, options?: ForkT
 export interface ReadJsonlTailOptions {
     /** Maximum records to return, counted from the END. */
     readonly maxRecords?: number;
-    /** Stop once a line contains this marker (exclusive). */
     /**
      * Start the window AFTER the last record whose `subtype` (or `type`) equals this.
      *
@@ -81,4 +80,11 @@ export interface ReadJsonlTailOptions {
     /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */
     readonly _stats?: boolean;
 }
+/**
+ * Read the LAST records of a JSONL file without loading the whole thing.
+ *
+ * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session
+ * transcript grows without bound; loading megabytes to show the last three turns is the cost this
+ * exists to avoid — and a `slice` over a full read would be that same cost with a better name.
+ */
 export declare function readJsonlTail<T = Record<string, unknown>>(path: string, options?: ReadJsonlTailOptions): T[];

package/dist/internal/persistence/transcript-ops.d.ts

@@ -70,7 +70,6 @@ export declare function forkTranscript(src: string, dst: string, options?: ForkT
 export interface ReadJsonlTailOptions {
     /** Maximum records to return, counted from the END. */
     readonly maxRecords?: number;
-    /** Stop once a line contains this marker (exclusive). */
     /**
      * Start the window AFTER the last record whose `subtype` (or `type`) equals this.
      *
@@ -81,4 +80,11 @@ export interface ReadJsonlTailOptions {
     /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */
     readonly _stats?: boolean;
 }
+/**
+ * Read the LAST records of a JSONL file without loading the whole thing.
+ *
+ * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session
+ * transcript grows without bound; loading megabytes to show the last three turns is the cost this
+ * exists to avoid — and a `slice` over a full read would be that same cost with a better name.
+ */
 export declare function readJsonlTail<T = Record<string, unknown>>(path: string, options?: ReadJsonlTailOptions): T[];

package/dist/internal/plugins/types.d.cts

@@ -11,7 +11,7 @@
  * @public
  */
 import type { Plugin as PluginType } from "../../types/plugin.js";
-export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
+export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, MemoryProviderFactory, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
 export type Plugin = PluginType;
 /**
  * Identity helper for plugin authors. TS-only convenience — preserves

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

@@ -11,7 +11,7 @@
  * @public
  */
 import type { Plugin as PluginType } from "../../types/plugin.js";
-export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
+export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, MemoryProviderFactory, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
 export type Plugin = PluginType;
 /**
  * Identity helper for plugin authors. TS-only convenience — preserves

package/dist/internal/providers/builtin/cerebras.d.ts

@@ -1,5 +1,5 @@
 /**
- * M45 — Cerebras. Integration header adapted from OpenCode's `cerebras.ts` (MIT — value changed to
- * `theokit`, never `opencode`: the header attributes TRAFFIC). Models per models.dev (2026-07 snapshot).
+ * M45 — Cerebras. The integration header value is theokit's own: the header attributes TRAFFIC.
+ * Models per models.dev (2026-07 snapshot).
  */
 export declare const CEREBRAS: import("../types.js").ProviderProfile;

package/dist/internal/providers/builtin/deepinfra.d.ts

@@ -1,2 +1,2 @@
-/** M45 — DeepInfra. OpenAI-compat surface under /v1/openai (models.dev `deepinfra`, OpenCode profile map). */
+/** M45 — DeepInfra. OpenAI-compat surface under /v1/openai (models.dev `deepinfra`). */
 export declare const DEEPINFRA: import("../types.js").ProviderProfile;

package/dist/internal/providers/builtin/openai-chatgpt.d.ts

@@ -1,2 +1,14 @@
+/**
+ * M43 — the ChatGPT "Codex" backend as a first-class builtin `ProviderProfile`. Migrated from the
+ * agent-builder M40 workaround; the SDK now owns the provider, so a consumer only selects
+ * `openai-chatgpt/<model>` and logs in — ZERO provider logic in the consumer.
+ *
+ * The provider-auth model (see the codex-provider-in-sdk blueprint):
+ * - static profile + a `transform.fetch` that resolves the LIVE credential per HTTP request (fresh Bearer +
+ *   dynamic `ChatGPT-Account-Id`), so a mid-turn expiry refreshes transparently with NO agent rebuild;
+ * - the protocol values (endpoint, models, oauth config, `originator` header) are SDK-owned constants.
+ *
+ * @internal
+ */
 import type { ProviderProfile } from "../types.js";
 export declare const OPENAI_CHATGPT: ProviderProfile;

package/dist/internal/providers/catalog-loader.d.ts

@@ -38,6 +38,14 @@ export interface CatalogEntry {
      */
     models?: Record<string, CatalogModel>;
 }
+/**
+ * Look up per-model catalog data by `provider/model` key.
+ *
+ * Semver-exempt: not declared in `package.json` `exports`, but re-exported by
+ * `catalog-source-models-dev.ts`, whose declaration is reachable from published entries — so it
+ * must be EMITTED.
+ */
+export declare function getCatalogModelInfo(key: string): CatalogModel | undefined;
 interface LoadOptions {
     _testInjectMalformed?: boolean;
 }

package/dist/internal/providers/catalog-schema.d.ts

@@ -1,4 +1,31 @@
 import { z } from "zod";
+/**
+ * M44 — the per-model catalog sub-schema. Field names mirror models.dev VERBATIM (snake_case) so
+ * `scripts/refresh-catalog.mjs` regenerates the vendored data mechanically from `api.json` with zero
+ * renaming (ADR D1).
+ * TOLERANT by design: every field optional, unknown keys ignored — models.dev adds fields over time and
+ * additive drift must never break the loader (Blueprint §6.4).
+ *
+ * theokit extensions beyond models.dev: `structured_output` / `cache_control` (both already exist on the
+ * SDK's `ModelCapabilities`; models.dev has no such flags).
+ *
+ * Semver-exempt: nothing here is declared in `package.json` `exports`. `MODALITIES` is nonetheless
+ * reachable from published declarations through the type graph, so it 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 the `MODALITIES` declaration below from the emitted `.d.ts`.
+ */
+export declare const MODALITIES: readonly ["text", "audio", "image", "video", "pdf"];
+/**
+ * One input or output medium a model accepts or produces.
+ *
+ * The union is derived from `MODALITIES`, so it is closed: a models.dev entry whose
+ * `modalities.input` or `modalities.output` array contains a string outside this set fails
+ * `catalogModelSchema.safeParse`, and `patchIndexFromApiJson` drops that single model rather
+ * than the whole payload. Widening the catalog to a new medium means adding it to `MODALITIES`
+ * first — nothing else in the schema enumerates media.
+ */
 export type Modality = (typeof MODALITIES)[number];
 declare const costSchema: z.ZodObject<{
     input: z.ZodNumber;
@@ -48,6 +75,34 @@ export declare const catalogModelSchema: z.ZodObject<{
         deprecated: "deprecated";
     }>>;
 }, z.core.$loose>;
+/**
+ * One model entry as it is stored in the vendored catalog and as models.dev publishes it.
+ *
+ * Every field is optional, so an entry that carries only `name` still parses. Reading a value
+ * therefore means handling `undefined` at each level — `model.cost?.cache_read`, not
+ * `model.cost.cache_read`. Field names are models.dev's own snake_case, kept verbatim so the
+ * refresh script can copy `api.json` across without renaming.
+ *
+ * The schema is loose rather than strict: unknown keys survive parsing and stay on the returned
+ * object instead of being rejected or dropped. That is what lets models.dev add a field without
+ * breaking the loader — the cost is that a typo in a key name parses silently, so a caller
+ * cannot use "it parsed" as evidence that a field it expected was present.
+ *
+ * `structured_output` and `cache_control` are theokit's own additions; models.dev publishes
+ * neither.
+ */
 export type CatalogModel = z.infer<typeof catalogModelSchema>;
+/**
+ * Per-token pricing for one model, in USD per 1M tokens (models.dev's unit — not per token, and
+ * not per 1K).
+ *
+ * `input` and `output` are required and non-negative; the two cache buckets are optional and
+ * absent for models that do not price caching separately. Absent is not zero: a missing
+ * `cache_read` means the catalog says nothing about the cost of a cache hit, so a caller that
+ * defaults it to 0 is asserting free cache reads on its own authority.
+ *
+ * Like `CatalogModel`, the shape is loose — unknown pricing keys published upstream are kept on
+ * the parsed value.
+ */
 export type CatalogModelCost = z.infer<typeof costSchema>;
 export {};

package/dist/internal/providers/catalog-source-models-dev.d.ts

@@ -1,4 +1,21 @@
 import { getCatalogModelInfo } from "./catalog-loader.js";
+/**
+ * Arguments to `refreshModelCatalog`, the SDK's only network trigger for model metadata.
+ *
+ * `url` wins over the `THEOKIT_MODELS_URL` environment variable, which in turn wins over
+ * `https://models.dev/api.json`. A non-default URL gets its own cache file, named by a hash of
+ * the URL, so switching sources never reads another source's cache.
+ *
+ * `force` skips only the freshness check — it does not skip the kill switch. When
+ * `THEOKIT_DISABLE_MODELS_FETCH` is set to anything other than an empty string, `"0"` or
+ * `"false"`, the call returns `source: "skipped"` with no fetch and no cache read, whatever
+ * `force` says.
+ *
+ * Without `force`, a cache file whose mtime is under an hour old is served directly and no
+ * request is made.
+ *
+ * `deps` exists so tests can drive the fetch and the clock; production leaves it unset.
+ */
 export interface RefreshModelCatalogOptions {
     /** Override the source URL (`THEOKIT_MODELS_URL` env also honored). */
     url?: string;
@@ -10,13 +27,32 @@ export interface RefreshModelCatalogOptions {
         now?: () => number;
     };
 }
+/**
+ * What `refreshModelCatalog` did. It never throws on a failed refresh, so this is the only place
+ * the outcome is reported.
+ *
+ * `source` is `"network"` only when a request succeeded, its body parsed as JSON, and the models
+ * were patched in. Every failure path — kill switch aside — returns `"cache"`: an HTTP error
+ * after retries, a timeout, an unparseable body, or a patch that threw. `"cache"` therefore means
+ * "serving what was already there", which may be a fresh cache, a stale one, or nothing but the
+ * vendored catalog. Read `models` to tell those apart. `"skipped"` means the kill switch was set.
+ *
+ * `models` counts the models patched into the index during this call, not the catalog's size. It
+ * counts each model once even when the provider has aliases and the model is written under several
+ * index keys, and it excludes models whose payload failed schema validation and models under
+ * providers the SDK does not know. It is 0 whenever there was no cache to fall back on, and 0 for
+ * `"skipped"`.
+ *
+ * A cache write that fails is logged and otherwise ignored: the result can still say `"network"`
+ * with the data live in memory and nothing on disk.
+ */
 export interface RefreshModelCatalogResult {
     /** Where the data came from: a fresh network fetch, the still-fresh disk cache, or skipped entirely. */
     source: "network" | "cache" | "skipped";
     /** How many models were patched into the index. */
     models: number;
 }
-/** The cache file for a source URL (custom URLs get a hash-suffixed name, mirroring OpenCode). */
+/** The cache file for a source URL (custom URLs get a hash-suffixed name). */
 export declare function cachePathFor(url: string): string;
 /**
  * Load an existing disk cache into the index (called by refresh when fresh, or opportunistically by a

package/dist/internal/runtime/concurrency/delegation-depth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * #364 — how deep the current delegation chain already is, delivered through the CALL.
+ *
+ * ## The bug this replaces
+ *
+ * `maxDelegationDepth` was checked once, at tool-CONSTRUCTION time, against a `_parentDepth`
+ * argument that nothing in the SDK ever incremented. Constructing a tool says nothing about how
+ * deep it will later be invoked, so with the documented call — `SubAgent.create(spec)` — the test
+ * was `1 > maxDepth`, false for every spec that did not ask for depth 0. A subagent whose tools
+ * include another subagent recursed unbounded, which is precisely what the guard exists to stop.
+ * The only path that ever tripped it was a caller threading the number by hand.
+ *
+ * ## Why the async scope closes it
+ *
+ * Depth is a property of the RUN, not of the object. A child's run loop — and therefore every tool
+ * it dispatches — executes inside the async continuation of its parent's handler, so a value
+ * published on that context is exactly what a nested dispatch needs to read. This is the same seam
+ * `subagent-credentials.ts` uses, and for the same reason: what survives every layer that rebuilds
+ * a tool object is the call, never the object.
+ *
+ * It is kept in its own module rather than folded into the credentials payload because depth is a
+ * separate concern with a separate lifetime — the credentials scope is opened once per run by the
+ * run loop, while depth is opened per delegation by the dispatching tool.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/runtime/concurrency/subagent-credentials.d.ts

@@ -32,4 +32,36 @@
  *
  * @internal
  */
-export {};
+import type { ModelSelection } from "../../../types/agent-prims.js";
+import type { Plugin } from "../../plugins/types.js";
+/**
+ * Credentials a parent agent hands down to its subagent tools so the child inherits the parent's
+ * auth (and, absent an explicit `spec.model`, its model).
+ *
+ * Declared here rather than in `a2a/subagent.ts` so the delivery mechanism owns the payload shape
+ * and the dependency runs one way (`a2a/subagent` -> this module). `a2a/subagent.ts` briefly
+ * re-exported it "for back-compat"; knip proved there was no back-compat surface to preserve — the
+ * type was never in the public barrel nor the exports map — so the re-export was deleted.
+ *
+ * Emitted rather than erased: `a2a/subagent.d.ts` imports it by name, and that entry IS published,
+ * so erasing this declaration ships a `.d.ts` that does not compile. Not being in the exports map
+ * is what keeps it out of the semver contract; erasure is not what does that.
+ */
+export interface InheritedCredentials {
+    readonly apiKey?: string;
+    readonly model?: ModelSelection;
+    /**
+     * The parent's shell-sandbox posture (`local.sandboxOptions.enabled`), handed down so a delegated
+     * child of a sandboxed parent stays sandboxed unless its role explicitly opts out. Without this a
+     * child ran unsandboxed whenever its role omitted `sandbox` — a default-open the sandbox wiring
+     * exists to prevent.
+     */
+    readonly sandbox?: boolean;
+    /**
+     * #55 — the parent's code-registered plugins (e.g. a `PermissionPlugin`) handed down so the child
+     * runs under the SAME policy. Without this, a delegated child's inner tool calls escape the
+     * parent's argument-level permission gate. First-party delegation path only — never exposed to
+     * third-party tool `ctx`.
+     */
+    readonly plugins?: readonly Plugin[];
+}

package/dist/internal/runtime/context/context-discovery-runner.d.ts

@@ -12,7 +12,22 @@
  *
  * @internal
  */
+import type { AggregatorSource } from "./context-aggregator.js";
 import { type DiscoverySpec } from "./context-discovery.js";
+/**
+ * Input to the context-discovery run: where to walk, how much of each file to keep, and which
+ * trust boundary an `@import` may not cross.
+ *
+ * `cwd` and `maxBytesPerFile` are required because neither has a safe default — an unset root walks
+ * the wrong tree, and an unset cap lets one large file consume the context window.
+ *
+ * `importRoot` is the field to reach for when the caller's trust boundary is narrower than the
+ * repository. Left unset, the repository IS the boundary (`gitRoot ?? cwd`), which is the honest
+ * default for a document found by walking the repository — but it does mean an `@import` can pull
+ * in any file the repo contains.
+ *
+ * @public — re-exported from '@theokit/sdk/context', and therefore under semver.
+ */
 export interface DiscoveryRunnerOptions {
     /** Workspace root passed to all discovery scopes. */
     readonly cwd: string;
@@ -34,3 +49,32 @@ export interface DiscoveryRunnerOptions {
      */
     readonly importRoot?: string;
 }
+/**
+ * Find, read and parse every context file the specs describe, and return them ready for the
+ * aggregator.
+ *
+ * Specs are processed in the order given — `opts.specs` when supplied, otherwise
+ * `DEFAULT_DISCOVERY_SPECS` — and within a spec, in the order its scope resolves paths. The
+ * returned array carries `priority` on each source; it is NOT sorted here, so the aggregator is
+ * what applies the ordering.
+ *
+ * A path already emitted is skipped, across specs as well as within one. Paths arrive resolved
+ * through `realpath`, so two specs pointing at the same physical file through a symlink produce
+ * one source rather than two.
+ *
+ * Missing and unreadable files are not errors: a file that does not exist is simply not matched,
+ * and one that fails to read or parse is dropped and the run continues. A frontmatter file whose
+ * activation conditions do not hold — `enabled: false`, or a scope that no touched file matches —
+ * is dropped the same way. So a shorter result than expected means "nothing qualified", and this
+ * function will not tell you which of those it was.
+ *
+ * Reads the filesystem and nothing else. No network, no writes, and no mutation of `opts`.
+ *
+ * Privacy: `<source name="">` is built from the path RELATIVE to the git root (or `cwd` when
+ * there is no git root), never an absolute path, so a home directory never reaches the prompt.
+ * `@import` resolution is bounded by `opts.importRoot`, defaulting to that same root — a document
+ * cannot pull in a file from outside the repository.
+ *
+ * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.
+ */
+export declare function runDiscovery(opts: DiscoveryRunnerOptions): Promise<AggregatorSource[]>;

package/dist/internal/runtime/context/context-discovery.d.ts

@@ -19,3 +19,61 @@
 export type DiscoveryScope = "cwd-only" | "git-root-walk" | "globbed";
 /** Parser to apply once file is read. */
 export type DiscoveryParser = "plain-markdown" | "mdc" | "frontmatter-zod" | "rules-frontmatter";
+/**
+ * One kind of context file the runner knows how to find and read. The shipped registry is
+ * `DEFAULT_DISCOVERY_SPECS`; a caller supplies its own array to change the set.
+ *
+ * `scope` decides how `pattern` is used and how many files a single spec can yield:
+ * `cwd-only` looks for one path and stops, `git-root-walk` collects a match in every directory
+ * from `cwd` up to the git root (nearest first), and `globbed` expands `pattern` as a glob
+ * relative to `cwd`. So `pattern` is a filename for the first two and a glob for the third —
+ * putting a glob on a walk scope silently finds nothing.
+ *
+ * `priority` orders the merged prompt, ascending, and is a plain number rather than an index, so
+ * a new spec can be slotted between two existing ones. Lower means earlier and therefore more
+ * general; later content wins on conflict.
+ *
+ * `parser` must match the file format — `plain-markdown` reads the whole file, `mdc` and
+ * `rules-frontmatter` parse frontmatter and can DECLINE the file when its activation conditions
+ * do not hold, and `frontmatter-zod` is the legacy path the runner currently skips entirely.
+ *
+ * `followImports` is honored only by `plain-markdown`, and turns `@path` directives in the body
+ * into inlined content bounded by the import root. Setting it on a frontmatter parser does
+ * nothing.
+ *
+ * `id` names the source in `<source name="">` and in telemetry. When one spec matches files in
+ * several directories, the runner suffixes it with the path relative to the git root to keep them
+ * apart.
+ *
+ * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.
+ */
+export interface DiscoverySpec {
+    /** Stable identifier — used as `<source name="">` and telemetry key. */
+    readonly id: string;
+    /** Priority for merge (lower = earlier in prompt). */
+    readonly priority: number;
+    /** Filename (cwd-only/git-root-walk) or glob (globbed). */
+    readonly pattern: string;
+    readonly scope: DiscoveryScope;
+    readonly parser: DiscoveryParser;
+    /** Whether to follow `@path` import directives (CLAUDE.md / GEMINI.md). */
+    readonly followImports: boolean;
+}
+/**
+ * The context files theokit looks for out of the box, in the order they are concatenated.
+ *
+ * Two things follow from the ordering. `AGENTS.md` comes first at priority 10 and `THEO.md` last,
+ * so theokit-specific instruction wins over the vendor-neutral file on conflict. And the array is
+ * consumed in the order written — the runner does not re-sort it — so a caller passing its own
+ * array is responsible for keeping `priority` and array position consistent.
+ *
+ * `CLAUDE.md` and `GEMINI.md` are the only two entries with `followImports: true`, which means
+ * they are the only files whose `@path` directives pull other files into the prompt. Those
+ * imports cannot escape the import root.
+ *
+ * Frozen only by type: `ReadonlyArray` is a compile-time constraint, and the array and its
+ * elements are not deep-frozen at runtime. Build a new array rather than mutating this one.
+ *
+ * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.
+ */
+export declare const DEFAULT_DISCOVERY_SPECS: ReadonlyArray<DiscoverySpec>;

package/dist/internal/runtime/context/context-rules-frontmatter.d.ts

@@ -21,10 +21,79 @@
  *
  * Glob + YAML subset are shared with the MDC parser (DRY, no new dependency).
  *
- * @internal
+ * 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 { z } from "zod";
+/**
+ * YAML frontmatter schema for `.theokit/rules/*.md` files.
+ *
+ * Every field is optional, and unknown keys are dropped rather than rejected — `safeParse` failing
+ * therefore means a declared key had the wrong TYPE (`paths` as a bare string, `enabled` as the
+ * string `"false"`), never that an unexpected key was present.
+ *
+ * Exported because {@link RulesFrontmatter} is inferred from it and appears in the signature of
+ * {@link shouldActivateRule}, which `@theokit/sdk/context` publishes: the constant has to reach the
+ * emitted declarations for that inferred type to resolve in a consumer's project.
+ */
+export declare const RulesFrontmatterSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    alwaysApply: z.ZodOptional<z.ZodBoolean>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 export type RulesFrontmatter = z.infer<typeof RulesFrontmatterSchema>;
 export interface RulesParseResult {
     readonly frontmatter: RulesFrontmatter;
     readonly body: string;
 }
+/**
+ * Split a `.theokit/rules/*.md` document into its frontmatter and its body.
+ *
+ * A file with no `---` fence is not an error: the whole text becomes the body and the frontmatter
+ * is synthesised as `{ alwaysApply: true }`, so a plain markdown rule with no metadata applies
+ * unconditionally. That default is the one thing to know before adding a fence — adding one and
+ * omitting both `alwaysApply` and a path pattern turns an always-on rule into a dormant one.
+ *
+ * `undefined` means the fence was there and its contents did not survive: YAML the lite parser
+ * could not read, or a shape the schema rejected (`paths` as a bare string rather than a list,
+ * `enabled` as `"false"` rather than `false`). It never throws, and it does not say WHICH of the
+ * two happened — the caller drops the file and counts it.
+ *
+ * Unknown frontmatter keys are dropped rather than rejected, so a misspelled `alwaysAply` parses
+ * fine and simply has no effect.
+ *
+ * Nothing here decides whether the rule applies; that is `shouldActivateRule`.
+ *
+ * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.
+ */
+export declare function parseRules(content: string): RulesParseResult | undefined;
+/**
+ * Decide whether a parsed rule applies to this turn, given the files in scope.
+ *
+ * Checked in strict order, first match wins:
+ *
+ *   1. `enabled: false` — never applies, whatever else the frontmatter says. This overrides
+ *      `alwaysApply: true`, which is the point of having it.
+ *   2. `alwaysApply: true` — applies, and `inScopePaths` is not consulted.
+ *   3. otherwise — applies only if some pattern from `paths` or `globs` matches some path in
+ *      `inScopePaths`. The two lists are a union, not alternatives; `globs` exists for
+ *      Cursor compatibility and behaves identically.
+ *
+ * A scoped rule with an EMPTY `inScopePaths` never applies. That is the case worth planning for:
+ * `contextPaths` is empty on a plain `agent.send()`, so a rule scoped by path stays dormant until
+ * the caller declares which files the turn is about. It is quiet — a dormant rule looks exactly
+ * like a rule that was never written.
+ *
+ * A rule with a fence but no patterns and no `alwaysApply` also never applies, since step 3 has
+ * nothing to match.
+ *
+ * `description` is not consulted. It is a note for humans, not an activation condition.
+ *
+ * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.
+ */
+export declare function shouldActivateRule(fm: RulesFrontmatter, inScopePaths: ReadonlyArray<string>): boolean;

package/dist/internal/runtime/fixtures/fixture-mode.d.ts

@@ -13,4 +13,18 @@
  *
  * @internal
  */
-export {};
+/**
+ * The provider credentials `shouldUseRealLocalRuntime` consults by name.
+ *
+ * Exported so the "Missing API key" refusal can name the ones the caller actually set (#338 item
+ * 5). The list used to live only inside the predicate below, which meant a caller with
+ * `OPENROUTER_API_KEY` set and `THEOKIT_API_KEY` unset was refused by a message naming neither —
+ * the SDK checks this exact variable a few lines down to decide the runtime, so the environment
+ * looks configured to the person who set it up. Reported as a three-hour diagnosis.
+ *
+ * One list, two readers: a variable added here is recognised by the predicate AND named by the
+ * error on the same commit, which is the only way the two stay in step.
+ */
+export declare const PROVIDER_CREDENTIAL_ENV_VARS: readonly string[];
+/** Those of {@link PROVIDER_CREDENTIAL_ENV_VARS} that are non-empty in this process. */
+export declare function presentProviderCredentialEnvVars(): readonly string[];

package/dist/internal/runtime/lifecycle/env-policy.d.ts

@@ -3,9 +3,7 @@
  *
  * Every subprocess the SDK spawns previously inherited the FULL `process.env`,
  * so API keys, tokens and passwords leaked into hook scripts and shell tools.
- * `resolveChildEnv` computes the env a child receives under an explicit policy,
- * modeled on codex's `ShellEnvironmentPolicy`
- * (reference: codex/codex-rs/protocol/src/shell_environment.rs).
+ * `resolveChildEnv` computes the env a child receives under an explicit policy.
  *
  * Modes:
  *  - `inherit-scrubbed` (DEFAULT) — inherit all parent vars EXCEPT secret-like