@theokit/sdk 4.52.1 → 4.53.1

package/dist/internal/persistence/session-writer.d.cts

@@ -88,4 +88,17 @@ export interface SessionWriterLease {
  * detect. Tying the renewal to a real write means the record tracks **progress**, not mere existence.
  */
 export declare const HEARTBEAT_WINDOW_MS = 30000;
+/**
+ * Does the session have a writer **right now**? A query that does NOT take the lease.
+ *
+ * M95 — it exists because asking by taking creates the very contention it meant to detect: two
+ * processes querying a **free** session at the same time made one of them lose, and the consumer
+ * forked for no reason. Measured in adversarial review: `RACE: spurious forks = 1`.
+ *
+ * It is a snapshot, not a guarantee: between the query and the real acquisition someone may take
+ * the session. Callers needing the guarantee use {@link acquireSessionWriter}; callers needing to
+ * **decide an id before opening anything** use this, and handle the race where it shows up.
+ *
+ */
+export declare function sessionHasWriter(sessionPath: string): boolean;
 export declare function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease>;

package/dist/internal/persistence/session-writer.d.ts

@@ -88,4 +88,17 @@ export interface SessionWriterLease {
  * detect. Tying the renewal to a real write means the record tracks **progress**, not mere existence.
  */
 export declare const HEARTBEAT_WINDOW_MS = 30000;
+/**
+ * Does the session have a writer **right now**? A query that does NOT take the lease.
+ *
+ * M95 — it exists because asking by taking creates the very contention it meant to detect: two
+ * processes querying a **free** session at the same time made one of them lose, and the consumer
+ * forked for no reason. Measured in adversarial review: `RACE: spurious forks = 1`.
+ *
+ * It is a snapshot, not a guarantee: between the query and the real acquisition someone may take
+ * the session. Callers needing the guarantee use {@link acquireSessionWriter}; callers needing to
+ * **decide an id before opening anything** use this, and handle the race where it shows up.
+ *
+ */
+export declare function sessionHasWriter(sessionPath: string): boolean;
 export declare function acquireSessionWriter(sessionPath: string): Promise<SessionWriterLease>;

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

@@ -1 +1,9 @@
-export {};
+/**
+ * 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;

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

@@ -1 +1,9 @@
-export {};
+/**
+ * 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;

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

@@ -71,15 +71,14 @@ 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.
+     *
+     * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message
+     * mentioning the marker in its text truncated the read — silently, with a successful return.
+     */
     readonly sinceMarker?: string;
     /** 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

@@ -71,15 +71,14 @@ 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.
+     *
+     * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message
+     * mentioning the marker in its text truncated the read — silently, with a successful return.
+     */
     readonly sinceMarker?: string;
     /** 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/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/catalog-source-models-dev.d.ts

@@ -16,7 +16,7 @@ export interface RefreshModelCatalogResult {
     /** 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/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

package/dist/internal/security/index.cjs

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

package/dist/internal/security/index.js

@@ -1,7 +1,7 @@
 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-SK4QLUBK.js';
 import '../../chunk-RIAM53CP.js';
-import '../../chunk-HI4ZW62S.js';
-export { addPattern, maskToken, redactSecrets } from '../../chunk-4X3SBHPK.js';
+import '../../chunk-U4UJHOSH.js';
+export { addPattern, maskToken, redactSecrets } from '../../chunk-5F5NWKPN.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.
@@ -57,3 +93,28 @@ export declare function isForbiddenPath(input: string): boolean;
 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.
@@ -57,3 +93,28 @@ export declare function isForbiddenPath(input: string): boolean;
 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/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);

package/dist/internal/telemetry/tracer.d.ts

@@ -14,6 +14,30 @@ export interface OTelSpan {
     };
     isRecording(): boolean;
 }
+/**
+ * Telemetry handle returned by {@link createTelemetry}. Callers use this to
+ * start spans, add events, etc. When telemetry is disabled OR OTel is not
+ * installed, every method is a safe no-op.
+ *
+ */
+export interface TelemetryHandle {
+    readonly enabled: boolean;
+    readonly includeContent: boolean;
+    /** Start a span. Returns a no-op span if telemetry is disabled. */
+    startSpan(name: string, attrs?: Record<string, string | number | boolean>): OTelSpan;
+    /** Start a child span nested under `parent` (M3 #64). `undefined` parent →
+     *  a root span (parentless callers, or telemetry with no run span). */
+    startChildSpan(parent: OTelSpan | undefined, name: string, attrs?: Record<string, string | number | boolean>): OTelSpan;
+    /**
+     * Record a histogram observation. T0.1 ships
+     * `theokit_memory_recall_duration_ms`; downstream tasks add more.
+     * No-op when telemetry is disabled or when `@opentelemetry/api`'s metrics
+     * namespace is unavailable. ADR D34 — exporter errors are swallowed by `safe()`.
+     */
+    recordHistogram(name: string, valueMs: number, attrs?: Record<string, string | number | boolean>): void;
+    /** End all open spans on this handle (best-effort, used by Agent.dispose). */
+    endAll(): void;
+}
 export declare const NOOP_SPAN: OTelSpan;
 /** Exported for tests — resets the OTel cache and the warning-once latch. */
 export declare function _resetTelemetryCacheForTests(): void;

package/dist/judge-call-G5SGV2M2.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+var chunkELKO4ZLR_cjs = require('./chunk-ELKO4ZLR.cjs');
+require('./chunk-LPVIRJVF.cjs');
+require('./chunk-BM6N4KHO.cjs');
+
+
+
+Object.defineProperty(exports, "JudgeCredentialError", {
+  enumerable: true,
+  get: function () { return chunkELKO4ZLR_cjs.JudgeCredentialError; }
+});
+Object.defineProperty(exports, "composeJudgePrompt", {
+  enumerable: true,
+  get: function () { return chunkELKO4ZLR_cjs.composeJudgePrompt; }
+});
+Object.defineProperty(exports, "judgeCallImpl", {
+  enumerable: true,
+  get: function () { return chunkELKO4ZLR_cjs.judgeCallImpl; }
+});
+//# sourceMappingURL=judge-call-G5SGV2M2.cjs.map
+//# sourceMappingURL=judge-call-G5SGV2M2.cjs.map

package/dist/{judge-call-GVIJWQVE.cjs.map → judge-call-G5SGV2M2.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"judge-call-GVIJWQVE.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"judge-call-G5SGV2M2.cjs"}

package/dist/judge-call-MDIPTBJI.js

@@ -0,0 +1,5 @@
+export { JudgeCredentialError, composeJudgePrompt, judgeCallImpl } from './chunk-LTSTGCL6.js';
+import './chunk-U4UJHOSH.js';
+import './chunk-5F5NWKPN.js';
+//# sourceMappingURL=judge-call-MDIPTBJI.js.map
+//# sourceMappingURL=judge-call-MDIPTBJI.js.map

package/dist/{judge-call-QMKGC2ZK.js.map → judge-call-MDIPTBJI.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"judge-call-QMKGC2ZK.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"judge-call-MDIPTBJI.js"}