@theokit/sdk 4.53.0 → 4.54.0

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 chunkYTO5BRBD_cjs = require('../../chunk-YTO5BRBD.cjs');
+var chunkR3UPQFKK_cjs = require('../../chunk-R3UPQFKK.cjs');
 require('../../chunk-VKJ7V7EB.cjs');
-require('../../chunk-2YGIBOUH.cjs');
-var chunkSXSPMRSV_cjs = require('../../chunk-SXSPMRSV.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 chunkYTO5BRBD_cjs.ForbiddenPathError; }
+  get: function () { return chunkR3UPQFKK_cjs.ForbiddenPathError; }
 });
 Object.defineProperty(exports, "PathTraversalError", {
   enumerable: true,
-  get: function () { return chunkYTO5BRBD_cjs.PathTraversalError; }
+  get: function () { return chunkR3UPQFKK_cjs.PathTraversalError; }
 });
 Object.defineProperty(exports, "assertNoSymlinkEscape", {
   enumerable: true,
-  get: function () { return chunkYTO5BRBD_cjs.assertNoSymlinkEscape; }
+  get: function () { return chunkR3UPQFKK_cjs.assertNoSymlinkEscape; }
 });
 Object.defineProperty(exports, "isForbiddenPath", {
   enumerable: true,
-  get: function () { return chunkYTO5BRBD_cjs.isForbiddenPath; }
+  get: function () { return chunkR3UPQFKK_cjs.isForbiddenPath; }
 });
 Object.defineProperty(exports, "safePathJoin", {
   enumerable: true,
-  get: function () { return chunkYTO5BRBD_cjs.safePathJoin; }
+  get: function () { return chunkR3UPQFKK_cjs.safePathJoin; }
 });
 Object.defineProperty(exports, "sanitizeIdentifier", {
   enumerable: true,
-  get: function () { return chunkYTO5BRBD_cjs.sanitizeIdentifier; }
+  get: function () { return chunkR3UPQFKK_cjs.sanitizeIdentifier; }
 });
 Object.defineProperty(exports, "validateArtifactPath", {
   enumerable: true,
-  get: function () { return chunkYTO5BRBD_cjs.validateArtifactPath; }
+  get: function () { return chunkR3UPQFKK_cjs.validateArtifactPath; }
 });
 Object.defineProperty(exports, "addPattern", {
   enumerable: true,
-  get: function () { return chunkSXSPMRSV_cjs.addPattern; }
+  get: function () { return chunkJTB5Q42C_cjs.addPattern; }
 });
 Object.defineProperty(exports, "maskToken", {
   enumerable: true,
-  get: function () { return chunkSXSPMRSV_cjs.maskToken; }
+  get: function () { return chunkJTB5Q42C_cjs.maskToken; }
 });
 Object.defineProperty(exports, "redactSecrets", {
   enumerable: true,
-  get: function () { return chunkSXSPMRSV_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-XWCTBGYK.js';
+export { ForbiddenPathError, PathTraversalError, assertNoSymlinkEscape, isForbiddenPath, safePathJoin, sanitizeIdentifier, validateArtifactPath } from '../../chunk-QARJGQSA.js';
 import '../../chunk-RIAM53CP.js';
-import '../../chunk-HI4ZW62S.js';
-export { addPattern, maskToken, redactSecrets } from '../../chunk-4X3SBHPK.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

package/dist/internal/security/path-guard.d.cts

@@ -18,6 +18,15 @@
  * @internal
  */
 import { ConfigurationError } from "../../errors.js";
+/**
+ * Thrown when a path operation would escape its allowed base directory.
+ * Extends `ConfigurationError` (no new error hierarchy per ADR D65).
+ *
+ */
+export declare class PathTraversalError extends ConfigurationError {
+    readonly name: string;
+    constructor(input: string, resolvedPath: string);
+}
 /**
  * Thrown when an agent tool is asked to read or write a sensitive path
  * that the blocklist forbids (`.env`, `.git/`, `node_modules/`, `.theo/`,
@@ -32,6 +41,33 @@ export declare class ForbiddenPathError extends ConfigurationError {
     readonly name: string;
     constructor(path: string);
 }
+/**
+ * Join `base` with `...parts` and ensure the resolved absolute path stays
+ * under `base`. Resolves FIRST, then prefix-checks (ADR D80) — prevents
+ * normalized-escape bypasses like `subdir/.\\./bar`.
+ *
+ * Returns the safe absolute path. Throws `PathTraversalError` if escape.
+ *
+ */
+export declare function safePathJoin(base: string, ...parts: string[]): string;
+/**
+ * Assert that `path` — including every directory component in the chain —
+ * stays under `base` after symlink resolution. No-op when nothing on the
+ * path exists yet.
+ *
+ * Two-bug history:
+ *   1. **EC-1** (original fix, kept): a multi-level symlink chain A → B → C
+ *      must be resolved end-to-end. `realpathSync` does this in 1 syscall.
+ *   2. **Defence-in-depth** (added v1.x): the previous implementation only
+ *      called `lstatSync(path)` on the terminal component. If an INTERMEDIATE
+ *      directory was a symlink (`base/inner-symlink → /outside`), `lstat` on
+ *      `base/inner-symlink/file.txt` followed the symlink and reported the
+ *      regular file — escape went undetected. Fix: walk up to the nearest
+ *      existing ancestor and `realpath` THAT, then re-attach the suffix and
+ *      check the result against the canonical base.
+ *
+ */
+export declare function assertNoSymlinkEscape(path: string, base: string): void;
 /**
  * Decide whether a project-relative path points to a known-sensitive file
  * that a coding agent must not read or write.
@@ -54,6 +90,77 @@ export declare class ForbiddenPathError extends ConfigurationError {
  * @public
  */
 export declare function isForbiddenPath(input: string): boolean;
+/**
+ * T1.4 — validate a relative artifact path string BEFORE it is used to look
+ * up a fixture or to fetch from PaaS. Rejects every well-known traversal
+ * vector at the boundary, throwing `PathTraversalError`.
+ *
+ * Vectors rejected:
+ *  - classic `..` parent-directory traversal (any segment).
+ *  - backslash separators (Windows-style `..\\windows`).
+ *  - URL-encoded `%2e%2e` / `%2E%2E` (double-decoded traversal).
+ *  - NUL byte injection (`\x00`).
+ *  - Windows drive letter prefix (`C:`, `D:\\...`).
+ *  - Home-tilde expansion (`~/`, `~root/...`).
+ *  - Absolute paths starting with `/`.
+ *
+ * Does NOT touch the filesystem — the call is shape-only. Live symlink
+ * traversal protection happens via `assertNoSymlinkEscape` at the FS-resolve
+ * boundary.
+ *
+ * @param input - Caller-supplied artifact path.
+ * @throws `PathTraversalError` on any rejection.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/security` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function validateArtifactPath(input: string): void;
+/**
+ * Validate that `input` is a safe path component (skill name, agent ID,
+ * namespace, etc.) and return its lowercase form. Strict grammar
+ * `^[a-z0-9][a-z0-9-_]*$` rejects path separators, dots, null bytes,
+ * whitespace, unicode invisible chars, and any leading `-`/`_`.
+ *
+ * ONE error class leaves this function: `ConfigurationError` with code
+ * `invalid_identifier`, for every rejection — length out of range, a path
+ * separator, `..`, a space, a leading `-`, and a NUL / C0 control char / DEL
+ * alike. A caller can branch on that code and know it has covered the whole
+ * rejection surface.
+ *
+ * Before #368 the control-char branch threw `PathTraversalError` instead, which
+ * made the error CLASS a function of the attacker's bytes; the message still names
+ * the offending byte, which is the part that was worth keeping.
+ *
+ * @param input - User-supplied identifier candidate.
+ * @param options.maxLen - Maximum allowed length (default 64).
+ * @returns Lowercase form of `input`.
+ * @throws `ConfigurationError` with code `invalid_identifier` on every rejection.
+ */
 export declare function sanitizeIdentifier(input: string, options?: {
     maxLen?: number;
 }): string;
+/**
+ * Convert ANY opaque id (agent id, run id, conversation id, namespace, email,
+ * arbitrary string) into a deterministic, filesystem-safe filename component.
+ *
+ * Unlike {@link sanitizeIdentifier} (which THROWS on non-conforming input),
+ * this is a total function: it NEVER throws on a non-empty string. It returns
+ * the lowercased id verbatim when it already matches the safe grammar
+ * `^[a-z0-9][a-z0-9-_]*$` and fits `maxLen` (so UUIDs, hashes, and slugs stay
+ * human-readable), otherwise a deterministic `h-<16 hex>` sha256 token
+ * (collision-resistant and always a valid filename). The output charset is
+ * always `[a-z0-9_-]`, safe as a literal path segment on every filesystem.
+ *
+ * @param id - any opaque identifier (must be a non-empty string)
+ * @param options.maxLen - max length for the passthrough branch (default 128).
+ *   Ids longer than this are hashed; the hash token itself is always short.
+ * @throws ConfigurationError (code `invalid_filename_id`) only on empty input.
+ *
+ * @example
+ *   safeFilenameForId("550e8400-e29b-41d4-a716-446655440000") // passthrough
+ *   safeFilenameForId("user@example.com")                      // "h-<16hex>"
+ *
+ */
+export declare function safeFilenameForId(id: string, options?: {
+    maxLen?: number;
+}): string;

package/dist/internal/security/path-guard.d.ts

@@ -18,6 +18,15 @@
  * @internal
  */
 import { ConfigurationError } from "../../errors.js";
+/**
+ * Thrown when a path operation would escape its allowed base directory.
+ * Extends `ConfigurationError` (no new error hierarchy per ADR D65).
+ *
+ */
+export declare class PathTraversalError extends ConfigurationError {
+    readonly name: string;
+    constructor(input: string, resolvedPath: string);
+}
 /**
  * Thrown when an agent tool is asked to read or write a sensitive path
  * that the blocklist forbids (`.env`, `.git/`, `node_modules/`, `.theo/`,
@@ -32,6 +41,33 @@ export declare class ForbiddenPathError extends ConfigurationError {
     readonly name: string;
     constructor(path: string);
 }
+/**
+ * Join `base` with `...parts` and ensure the resolved absolute path stays
+ * under `base`. Resolves FIRST, then prefix-checks (ADR D80) — prevents
+ * normalized-escape bypasses like `subdir/.\\./bar`.
+ *
+ * Returns the safe absolute path. Throws `PathTraversalError` if escape.
+ *
+ */
+export declare function safePathJoin(base: string, ...parts: string[]): string;
+/**
+ * Assert that `path` — including every directory component in the chain —
+ * stays under `base` after symlink resolution. No-op when nothing on the
+ * path exists yet.
+ *
+ * Two-bug history:
+ *   1. **EC-1** (original fix, kept): a multi-level symlink chain A → B → C
+ *      must be resolved end-to-end. `realpathSync` does this in 1 syscall.
+ *   2. **Defence-in-depth** (added v1.x): the previous implementation only
+ *      called `lstatSync(path)` on the terminal component. If an INTERMEDIATE
+ *      directory was a symlink (`base/inner-symlink → /outside`), `lstat` on
+ *      `base/inner-symlink/file.txt` followed the symlink and reported the
+ *      regular file — escape went undetected. Fix: walk up to the nearest
+ *      existing ancestor and `realpath` THAT, then re-attach the suffix and
+ *      check the result against the canonical base.
+ *
+ */
+export declare function assertNoSymlinkEscape(path: string, base: string): void;
 /**
  * Decide whether a project-relative path points to a known-sensitive file
  * that a coding agent must not read or write.
@@ -54,6 +90,77 @@ export declare class ForbiddenPathError extends ConfigurationError {
  * @public
  */
 export declare function isForbiddenPath(input: string): boolean;
+/**
+ * T1.4 — validate a relative artifact path string BEFORE it is used to look
+ * up a fixture or to fetch from PaaS. Rejects every well-known traversal
+ * vector at the boundary, throwing `PathTraversalError`.
+ *
+ * Vectors rejected:
+ *  - classic `..` parent-directory traversal (any segment).
+ *  - backslash separators (Windows-style `..\\windows`).
+ *  - URL-encoded `%2e%2e` / `%2E%2E` (double-decoded traversal).
+ *  - NUL byte injection (`\x00`).
+ *  - Windows drive letter prefix (`C:`, `D:\\...`).
+ *  - Home-tilde expansion (`~/`, `~root/...`).
+ *  - Absolute paths starting with `/`.
+ *
+ * Does NOT touch the filesystem — the call is shape-only. Live symlink
+ * traversal protection happens via `assertNoSymlinkEscape` at the FS-resolve
+ * boundary.
+ *
+ * @param input - Caller-supplied artifact path.
+ * @throws `PathTraversalError` on any rejection.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/security` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function validateArtifactPath(input: string): void;
+/**
+ * Validate that `input` is a safe path component (skill name, agent ID,
+ * namespace, etc.) and return its lowercase form. Strict grammar
+ * `^[a-z0-9][a-z0-9-_]*$` rejects path separators, dots, null bytes,
+ * whitespace, unicode invisible chars, and any leading `-`/`_`.
+ *
+ * ONE error class leaves this function: `ConfigurationError` with code
+ * `invalid_identifier`, for every rejection — length out of range, a path
+ * separator, `..`, a space, a leading `-`, and a NUL / C0 control char / DEL
+ * alike. A caller can branch on that code and know it has covered the whole
+ * rejection surface.
+ *
+ * Before #368 the control-char branch threw `PathTraversalError` instead, which
+ * made the error CLASS a function of the attacker's bytes; the message still names
+ * the offending byte, which is the part that was worth keeping.
+ *
+ * @param input - User-supplied identifier candidate.
+ * @param options.maxLen - Maximum allowed length (default 64).
+ * @returns Lowercase form of `input`.
+ * @throws `ConfigurationError` with code `invalid_identifier` on every rejection.
+ */
 export declare function sanitizeIdentifier(input: string, options?: {
     maxLen?: number;
 }): string;
+/**
+ * Convert ANY opaque id (agent id, run id, conversation id, namespace, email,
+ * arbitrary string) into a deterministic, filesystem-safe filename component.
+ *
+ * Unlike {@link sanitizeIdentifier} (which THROWS on non-conforming input),
+ * this is a total function: it NEVER throws on a non-empty string. It returns
+ * the lowercased id verbatim when it already matches the safe grammar
+ * `^[a-z0-9][a-z0-9-_]*$` and fits `maxLen` (so UUIDs, hashes, and slugs stay
+ * human-readable), otherwise a deterministic `h-<16 hex>` sha256 token
+ * (collision-resistant and always a valid filename). The output charset is
+ * always `[a-z0-9_-]`, safe as a literal path segment on every filesystem.
+ *
+ * @param id - any opaque identifier (must be a non-empty string)
+ * @param options.maxLen - max length for the passthrough branch (default 128).
+ *   Ids longer than this are hashed; the hash token itself is always short.
+ * @throws ConfigurationError (code `invalid_filename_id`) only on empty input.
+ *
+ * @example
+ *   safeFilenameForId("550e8400-e29b-41d4-a716-446655440000") // passthrough
+ *   safeFilenameForId("user@example.com")                      // "h-<16hex>"
+ *
+ */
+export declare function safeFilenameForId(id: string, options?: {
+    maxLen?: number;
+}): string;

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

@@ -1,3 +1,74 @@
+/**
+ * Register an extra pattern for `redactSecrets` to mask, on top of the built-in vendor set.
+ *
+ * Additive and irreversible for the life of the process: patterns accumulate in module scope,
+ * builtins are never replaced or reordered, and there is no way to remove one. Registering the
+ * same regex twice registers it twice.
+ *
+ * Throws immediately when the regex has no `/g` flag. That is not pedantry — `String.replace`
+ * with a non-global regex substitutes only the FIRST match, so a pattern registered without it
+ * would mask the first credential in a payload and let every later one through, which reads as
+ * working.
+ *
+ * Extras run after the builtins and before the parametric `key=value` sweep, and each whole match
+ * is replaced by `maskToken` of that match. Anchor and bound the pattern with care: a regex that
+ * matches more than the secret masks more than the secret, and one that backtracks badly runs on
+ * every string crossing an output boundary.
+ *
+ * Registering a pattern does not enable redaction. When `THEOKIT_REDACT_SECRETS` was off at
+ * module load, `redactSecrets` returns its input untouched and extras never run.
+ *
+ * Also exposed publicly, and under semver, as `Security.addPattern` in `src/security.ts`; the
+ * direct export here additionally reaches the semver-exempt `@theokit/sdk/internal/security`
+ * sub-path.
+ */
+export declare function addPattern(re: RegExp): void;
+/**
+ * Mask one string, keeping enough of it to be recognizable in a log.
+ *
+ * Under 18 characters the whole string becomes the literal `***`; the length is not preserved and
+ * nothing of the input survives. From 18 characters up, the result is the first 6 characters, the
+ * literal `...`, and the last 4 — so exactly 10 characters of the input are RETAINED IN CLEAR and
+ * the middle is dropped. That is the trade the threshold encodes: short strings could be brute
+ * forced from a partial, long ones cannot, and the surviving prefix is usually the vendor tag
+ * (`sk-ant`, `ghp_de`) that tells an operator which credential misbehaved.
+ *
+ * Be clear about what this is and is not. It is a readability aid for logs, not an anonymizer and
+ * not a security boundary. The retained prefix and suffix identify the credential's issuer and
+ * often the credential itself to anyone who has seen it before, so a masked value still belongs in
+ * a trusted log and not in a bug report or a support ticket.
+ *
+ * It masks whatever it is handed. There is no check that the argument is a secret, so calling it
+ * on ordinary text mangles the text, and calling it on something the caller merely hopes is a
+ * secret proves nothing about what leaked.
+ *
+ * `redactSecrets` applies it to the ENTIRE match of a pattern, not to a captured group. For a
+ * match like `Bearer sk-ant-...` the first 6 characters retained are `Bearer`, not the key's
+ * prefix.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/security` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function maskToken(token: string): string;
+/**
+ * Redact known credential patterns from `text`. Default behavior masks
+ * builtins + extras + parametric `key=value` sinks.
+ *
+ * With `{ codeFile: true }` (D72), skips PARAM_PATTERN to avoid mangling
+ * `.env.example`, schema JSON, or test fixtures that legitimately contain
+ * prefix-like strings.
+ *
+ * Returns the redacted string. Coerces non-strings via JSON.stringify;
+ * EC-7 fix (edge-case review): wraps in try/catch so circular references
+ * never propagate — returns sentinel `"[unredactable: circular]"`.
+ *
+ * `null` and `undefined` return `""`. When redaction was switched off at module load via
+ * `THEOKIT_REDACT_SECRETS`, the coerced input is returned with no masking at all — the value is
+ * still stringified, but nothing is removed from it.
+ *
+ * Masking is best-effort against a list of known shapes. A credential in a format no pattern
+ * covers passes through unchanged, so a redacted string is not a string proven free of secrets.
+ */
 export declare function redactSecrets(text: unknown, opts?: {
     codeFile?: boolean;
 }): string;

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

@@ -1,3 +1,74 @@
+/**
+ * Register an extra pattern for `redactSecrets` to mask, on top of the built-in vendor set.
+ *
+ * Additive and irreversible for the life of the process: patterns accumulate in module scope,
+ * builtins are never replaced or reordered, and there is no way to remove one. Registering the
+ * same regex twice registers it twice.
+ *
+ * Throws immediately when the regex has no `/g` flag. That is not pedantry — `String.replace`
+ * with a non-global regex substitutes only the FIRST match, so a pattern registered without it
+ * would mask the first credential in a payload and let every later one through, which reads as
+ * working.
+ *
+ * Extras run after the builtins and before the parametric `key=value` sweep, and each whole match
+ * is replaced by `maskToken` of that match. Anchor and bound the pattern with care: a regex that
+ * matches more than the secret masks more than the secret, and one that backtracks badly runs on
+ * every string crossing an output boundary.
+ *
+ * Registering a pattern does not enable redaction. When `THEOKIT_REDACT_SECRETS` was off at
+ * module load, `redactSecrets` returns its input untouched and extras never run.
+ *
+ * Also exposed publicly, and under semver, as `Security.addPattern` in `src/security.ts`; the
+ * direct export here additionally reaches the semver-exempt `@theokit/sdk/internal/security`
+ * sub-path.
+ */
+export declare function addPattern(re: RegExp): void;
+/**
+ * Mask one string, keeping enough of it to be recognizable in a log.
+ *
+ * Under 18 characters the whole string becomes the literal `***`; the length is not preserved and
+ * nothing of the input survives. From 18 characters up, the result is the first 6 characters, the
+ * literal `...`, and the last 4 — so exactly 10 characters of the input are RETAINED IN CLEAR and
+ * the middle is dropped. That is the trade the threshold encodes: short strings could be brute
+ * forced from a partial, long ones cannot, and the surviving prefix is usually the vendor tag
+ * (`sk-ant`, `ghp_de`) that tells an operator which credential misbehaved.
+ *
+ * Be clear about what this is and is not. It is a readability aid for logs, not an anonymizer and
+ * not a security boundary. The retained prefix and suffix identify the credential's issuer and
+ * often the credential itself to anyone who has seen it before, so a masked value still belongs in
+ * a trusted log and not in a bug report or a support ticket.
+ *
+ * It masks whatever it is handed. There is no check that the argument is a secret, so calling it
+ * on ordinary text mangles the text, and calling it on something the caller merely hopes is a
+ * secret proves nothing about what leaked.
+ *
+ * `redactSecrets` applies it to the ENTIRE match of a pattern, not to a captured group. For a
+ * match like `Bearer sk-ant-...` the first 6 characters retained are `Bearer`, not the key's
+ * prefix.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/security` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function maskToken(token: string): string;
+/**
+ * Redact known credential patterns from `text`. Default behavior masks
+ * builtins + extras + parametric `key=value` sinks.
+ *
+ * With `{ codeFile: true }` (D72), skips PARAM_PATTERN to avoid mangling
+ * `.env.example`, schema JSON, or test fixtures that legitimately contain
+ * prefix-like strings.
+ *
+ * Returns the redacted string. Coerces non-strings via JSON.stringify;
+ * EC-7 fix (edge-case review): wraps in try/catch so circular references
+ * never propagate — returns sentinel `"[unredactable: circular]"`.
+ *
+ * `null` and `undefined` return `""`. When redaction was switched off at module load via
+ * `THEOKIT_REDACT_SECRETS`, the coerced input is returned with no masking at all — the value is
+ * still stringified, but nothing is removed from it.
+ *
+ * Masking is best-effort against a list of known shapes. A credential in a format no pattern
+ * covers passes through unchanged, so a redacted string is not a string proven free of secrets.
+ */
 export declare function redactSecrets(text: unknown, opts?: {
     codeFile?: boolean;
 }): string;

package/dist/internal/session/agent-session.d.ts

@@ -23,12 +23,23 @@ export declare const MAX_CACHED_SESSIONS = 32;
  */
 export declare function discardSession(cwd: string, agentId: string): number;
 export declare function getSessionMessages(agentId: string): SessionMessage[];
-export declare function clearSession(agentId: string): void;
 /**
- * M50 review F1 — drop BOTH the message cache and the hydration marker so the NEXT send re-hydrates
- * from disk. Without this, a compaction only helps after a process restart: the live process keeps
- * sending the full pre-compact history (the cache is read synchronously by every send).
+ * Drop the in-memory message cache for `agentId` and NOTHING else — the hydration marker in
+ * `hydratedKeys` deliberately stays.
+ *
+ * That asymmetry is the feature, not an oversight, and it is what separates this from
+ * `invalidateSessionCache`, which drops both. The single caller is the personality switch's
+ * `reset: true` path (`internal/personality/switch.ts`): leaving the marker set makes
+ * `hydrateSession` return early, so the next send starts from an EMPTY context instead of
+ * replaying the pre-reset transcript off disk. Clearing the marker here would re-hydrate the
+ * conversation the reset was asked to discard.
+ *
+ * The same shape read as a bug one function up: `forgetBookkeeping` documents an evicted session
+ * coming back empty as "silent amnesia". The difference is intent — eviction wants the transcript
+ * back, a reset does not. Anyone reaching for this to invalidate a cache wants
+ * `invalidateSessionCache(cwd, agentId)` instead.
  */
+export declare function clearSession(agentId: string): void;
 /**
  * M50 review F5 — run `fn` serialized on the SAME per-(cwd,agentId) write chain the per-turn
  * persistence uses, so a manual `Agent.compact` can never interleave with an in-flight turn's

package/dist/internal/session/compact-session.d.ts

@@ -1,7 +1,7 @@
 /**
- * M50 (agent-builder) — session-transcript compaction, Codex-faithful.
+ * M50 (agent-builder) — session-transcript compaction.
  *
- * Mirrors the vendored Codex mechanism (`codex-rs/core/src/compact.rs`):
+ * The mechanism:
  *   - the replacement history = recent USER messages verbatim (newest→oldest under a token budget;
  *     prior summaries filtered by marker) + ONE summary message with a textual marker prefix,
  *     injected as `role:"user"` (`build_compacted_history`, compact.rs:589-663);