@theokit/sdk 4.53.1 → 4.55.0

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,6 +27,25 @@ 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";

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/post-run-lifecycle.d.ts

@@ -1 +1,16 @@
+/**
+ * Post-run side effects executed inside the per-agent send mutex (ADR D19):
+ *
+ *  1. Persist the assistant turn to the per-agent JSONL (ADR D18).
+ *  2. On status=finished, write a session-summary markdown for the
+ *     `corpus="sessions"` memory_search index (ADR D20).
+ *  3. Fire the `postRun` hook with the resolved status.
+ *  4. Flush pending session writes so dispose() never races the writer.
+ *
+ * Errors are swallowed at the call site so `agent.send()` callers observe
+ * failures through their own `run.wait()` / `stream()` surfaces. Mutex release
+ * is guaranteed via the final `flushSessionWrites` even on the cancelled path.
+ *
+ * Extracted from LocalAgent to keep that class under the G8 LoC budget.
+ */
 export declare function runPostRunLifecycle(inputs: PostRunLifecycleInputs): Promise<void>;

package/dist/internal/runtime/registry/agent-registry-store.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Persistent agent registry (ADR D17).
+ *
+ * Per-cwd JSON file at `.theokit/agents/registry.json`. Atomic writes via
+ * `replaceFileAtomic`. Secrets in `options` are stripped before persisting
+ * (D17 + reuses the cloud-config-serializer allow-list philosophy).
+ *
+ * Multi-process write race is the documented limitation: one SDK process per
+ * cwd (EC-10).
+ *
+ * @internal
+ */
 import type { ModelSelection } from "../../../types/agent-prims.js";
 export interface SerializedAgentOptions {
     name?: string;

package/dist/internal/runtime/registry/live-agent-registry.d.ts

@@ -19,6 +19,20 @@
  */
 import type { SDKAgent } from "../../../types/agent.js";
 export type EvictReason = "lru" | "idle" | "explicit";
+/**
+ * Knobs for {@link LiveAgentRegistry.configure}.
+ *
+ * The three numeric fields are a partial reconfigure — one left out keeps its current value.
+ * `onEvict` is NOT: it is assigned on every call, so `configure({ maxAgents: 200 })` clears a
+ * listener registered earlier. Re-pass the listener whenever you reconfigure.
+ *
+ * Two values are load-bearing zeroes. `maxAgents: 0` disables caching entirely, so every lookup
+ * misses and every agent is rebuilt; `idleTimeoutMs: 0` keeps the cache but leaves LRU as the only
+ * eviction, because the sweep is not started at all below that threshold. Negative numbers are
+ * clamped rather than rejected — up to 1000ms for `sweepIntervalMs`, up to 0 for the other two.
+ *
+ * @public
+ */
 export interface AgentRegistryOptions {
     /**
      * Maximum number of agents kept alive simultaneously. LRU eviction when
@@ -45,6 +59,29 @@ export interface AgentRegistryOptions {
      */
     onEvict?: (id: string, reason: EvictReason) => void;
 }
+/**
+ * An LRU-plus-idle cache of live `SDKAgent` instances, reached through `Agent.registry`.
+ *
+ * It exists for long-running servers that would otherwise build a fresh agent per conversation and
+ * never release one. Do not confuse it with the metadata registry in `agent-registry.ts`, which
+ * persists `RegisteredAgent` records to disk: that one is the address book, this one is the live
+ * cache, and they share nothing.
+ *
+ * The lifecycle rule that matters to callers: eviction — by LRU, by idle timeout, or by an explicit
+ * `evict` — calls `dispose()` on the agent. A reference you held onto before eviction is a disposed
+ * agent, not a detached one. `get` counts as a use and refreshes the entry's timestamp, so polling
+ * for an agent keeps it alive indefinitely.
+ *
+ * Idle eviction depends on a background sweep that only `configure` starts. A registry nobody
+ * configured caches with the documented defaults but evicts by LRU alone, so entries can sit past
+ * `idleTimeoutMs` indefinitely; call `configure` — even with no changes — to arm the sweep.
+ *
+ * Failures on the eviction path are swallowed and reported to the diagnostics channel — a throwing
+ * `dispose()` or a throwing `onEvict` listener must not stop the sweep. Configuration is
+ * process-wide and last-call-wins.
+ *
+ * @public
+ */
 export declare class LiveAgentRegistry {
     #private;
     /**

package/dist/internal/scorers/llm-judge.d.ts

@@ -6,8 +6,13 @@
  * structured judge prompt, parses score from the response. Returns 0 (with
  * diagnostic reason) on any parse failure.
  *
- * @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 type { ModelSelection } from "../../types/agent.js";
 import type { Score } from "../../types/eval.js";
 import type { ProviderRoutingSettings } from "../../types/providers.js";
 export interface LlmJudgeOptions {

package/dist/internal/security/index.cjs

@@ -1,52 +1,53 @@
 'use strict';
 
 require('../../chunk-MUUQ2WFJ.cjs');
-var chunkZT57WTUJ_cjs = require('../../chunk-ZT57WTUJ.cjs');
+var chunkR3UPQFKK_cjs = require('../../chunk-R3UPQFKK.cjs');
 require('../../chunk-VKJ7V7EB.cjs');
-require('../../chunk-LPVIRJVF.cjs');
-var chunkBM6N4KHO_cjs = require('../../chunk-BM6N4KHO.cjs');
+require('../../chunk-K3FW2XZD.cjs');
+var chunkJTB5Q42C_cjs = require('../../chunk-JTB5Q42C.cjs');
+require('../../chunk-NUKRL3I6.cjs');
 
 
 
 Object.defineProperty(exports, "ForbiddenPathError", {
   enumerable: true,
-  get: function () { return chunkZT57WTUJ_cjs.ForbiddenPathError; }
+  get: function () { return chunkR3UPQFKK_cjs.ForbiddenPathError; }
 });
 Object.defineProperty(exports, "PathTraversalError", {
   enumerable: true,
-  get: function () { return chunkZT57WTUJ_cjs.PathTraversalError; }
+  get: function () { return chunkR3UPQFKK_cjs.PathTraversalError; }
 });
 Object.defineProperty(exports, "assertNoSymlinkEscape", {
   enumerable: true,
-  get: function () { return chunkZT57WTUJ_cjs.assertNoSymlinkEscape; }
+  get: function () { return chunkR3UPQFKK_cjs.assertNoSymlinkEscape; }
 });
 Object.defineProperty(exports, "isForbiddenPath", {
   enumerable: true,
-  get: function () { return chunkZT57WTUJ_cjs.isForbiddenPath; }
+  get: function () { return chunkR3UPQFKK_cjs.isForbiddenPath; }
 });
 Object.defineProperty(exports, "safePathJoin", {
   enumerable: true,
-  get: function () { return chunkZT57WTUJ_cjs.safePathJoin; }
+  get: function () { return chunkR3UPQFKK_cjs.safePathJoin; }
 });
 Object.defineProperty(exports, "sanitizeIdentifier", {
   enumerable: true,
-  get: function () { return chunkZT57WTUJ_cjs.sanitizeIdentifier; }
+  get: function () { return chunkR3UPQFKK_cjs.sanitizeIdentifier; }
 });
 Object.defineProperty(exports, "validateArtifactPath", {
   enumerable: true,
-  get: function () { return chunkZT57WTUJ_cjs.validateArtifactPath; }
+  get: function () { return chunkR3UPQFKK_cjs.validateArtifactPath; }
 });
 Object.defineProperty(exports, "addPattern", {
   enumerable: true,
-  get: function () { return chunkBM6N4KHO_cjs.addPattern; }
+  get: function () { return chunkJTB5Q42C_cjs.addPattern; }
 });
 Object.defineProperty(exports, "maskToken", {
   enumerable: true,
-  get: function () { return chunkBM6N4KHO_cjs.maskToken; }
+  get: function () { return chunkJTB5Q42C_cjs.maskToken; }
 });
 Object.defineProperty(exports, "redactSecrets", {
   enumerable: true,
-  get: function () { return chunkBM6N4KHO_cjs.redactSecrets; }
+  get: function () { return chunkJTB5Q42C_cjs.redactSecrets; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/internal/security/index.d.cts

@@ -6,6 +6,9 @@
  * `internal/runtime/agent-session-store.ts`,
  * `internal/memory/migrate-sqlite-to-lance.ts`.
  *
- * @internal
+ * Semver-exempt: the `@theokit/sdk/internal/security` sub-path exists for packages extracted out of
+ * this one and is NOT covered by the package's semver contract. It IS declared in `package.json`
+ * `exports`, so every name below must survive into the published declarations.
  */
+export { assertNoSymlinkEscape, ForbiddenPathError, isForbiddenPath, PathTraversalError, safePathJoin, sanitizeIdentifier, validateArtifactPath, } from "./path-guard.js";
 export { addPattern, maskToken, redactSecrets } from "./redact.js";

package/dist/internal/security/index.d.ts

@@ -6,6 +6,9 @@
  * `internal/runtime/agent-session-store.ts`,
  * `internal/memory/migrate-sqlite-to-lance.ts`.
  *
- * @internal
+ * Semver-exempt: the `@theokit/sdk/internal/security` sub-path exists for packages extracted out of
+ * this one and is NOT covered by the package's semver contract. It IS declared in `package.json`
+ * `exports`, so every name below must survive into the published declarations.
  */
+export { assertNoSymlinkEscape, ForbiddenPathError, isForbiddenPath, PathTraversalError, safePathJoin, sanitizeIdentifier, validateArtifactPath, } from "./path-guard.js";
 export { addPattern, maskToken, redactSecrets } from "./redact.js";

package/dist/internal/security/index.js

@@ -1,7 +1,8 @@
 import '../../chunk-FD2UT76F.js';
-export { ForbiddenPathError, PathTraversalError, assertNoSymlinkEscape, isForbiddenPath, safePathJoin, sanitizeIdentifier, validateArtifactPath } from '../../chunk-SK4QLUBK.js';
+export { ForbiddenPathError, PathTraversalError, assertNoSymlinkEscape, isForbiddenPath, safePathJoin, sanitizeIdentifier, validateArtifactPath } from '../../chunk-QARJGQSA.js';
 import '../../chunk-RIAM53CP.js';
-import '../../chunk-U4UJHOSH.js';
-export { addPattern, maskToken, redactSecrets } from '../../chunk-5F5NWKPN.js';
+import '../../chunk-IDCKSLYH.js';
+export { addPattern, maskToken, redactSecrets } from '../../chunk-T7XEKOVW.js';
+import '../../chunk-T7O6K6PX.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map