@theokit/sdk 4.15.4 → 4.16.1

package/dist/internal/runtime/compression/compression-summarizer.d.ts

@@ -17,6 +17,7 @@
  *
  * @internal
  */
+export type { CompressibleMessage };
 /**
  * Typed error thrown when the compression LLM call fails or returns
  * an empty/ineffective summary. The caller catches and handles per

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

@@ -17,6 +17,15 @@ import type { SessionMessage } from "./session-types.js";
 export interface PersistTurnInput {
     userText: string;
     conversation: readonly ConversationTurn[];
+    /**
+     * M50 — when supplied, size-driven auto-compaction runs in the SAME write chain after the turn
+     * persists (usage real vs the model's context window; summarizer injected by the caller).
+     */
+    autoCompact?: {
+        usageTotal?: number | undefined;
+        contextWindow?: number | undefined;
+        summarize: (messages: readonly import("../../compaction.js").CompressibleMessage[]) => Promise<string>;
+    };
 }
 /**
  * The per-agent transcript metadata used to seed a {@link SessionTranscript}. The

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

@@ -0,0 +1,78 @@
+/**
+ * M50 (agent-builder) — session-transcript compaction, Codex-faithful.
+ *
+ * Mirrors the vendored Codex mechanism (`codex-rs/core/src/compact.rs`):
+ *   - 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);
+ *   - persistence is APPEND-ONLY: a `compact_boundary` record becomes the new DAG root and the
+ *     replacement messages are chained onto it — resume replays boundary→replacement→suffix
+ *     (equivalent of `CompactedItem.replacement_history`, rollout is never truncated);
+ *   - a failing summarizer leaves the transcript UNTOUCHED (typed error; no partial state).
+ *
+ * The summarizer is dependency-injected: tests pass a deterministic fake; the public
+ * `Agent.compact` wires the ADR-D440 compression summarizer (its first real caller).
+ */
+import { type CompressibleMessage } from "../../compaction.js";
+import type { SessionStore } from "../../types/session-store.js";
+/** Textual marker prefixing every compact summary (Codex `SUMMARY_PREFIX` analog). */
+export declare const COMPACT_SUMMARY_MARKER = "[[theokit:compact-summary]]";
+/** Budget of VERBATIM user messages preserved in the replacement (Codex `COMPACT_USER_MESSAGE_MAX_TOKENS`). */
+export declare const COMPACT_USER_MESSAGE_MAX_TOKENS = 20000;
+export interface CompactLocation {
+    cwd: string;
+    agentId: string;
+    model?: string;
+}
+export interface CompactResult {
+    preTokens: number;
+    postTokens: number;
+}
+/** Is this message a summary produced by a PRIOR compaction? (filtered from verbatim preservation). */
+export declare function isCompactSummary(content: string): boolean;
+/**
+ * Compact one session transcript: summarize the reconstructed history, then append (append-only)
+ * a `compact_boundary` + the replacement chain (recent user messages verbatim + marker'd summary).
+ *
+ * @throws whatever `summarize` throws — with the transcript guaranteed untouched.
+ */
+export declare function compactSessionTranscript(opts: {
+    store: SessionStore;
+    loc: CompactLocation;
+    sessionId: string;
+    trigger: "manual" | "auto";
+    summarize: (messages: readonly CompressibleMessage[]) => Promise<string>;
+}): Promise<CompactResult>;
+/**
+ * Build the default summarizer for `Agent.compact`: the D440 `compressConversationWindow`
+ * (aux-LLM summarization with typed failure) driven by a router-resolved LLM client. The
+ * compression model resolves via the D440 registry with the agent's own model as fallback.
+ */
+export declare function buildDefaultSummarizer(opts: {
+    agentModel: string;
+    apiKey?: string;
+}): (messages: readonly CompressibleMessage[]) => Promise<string>;
+/**
+ * Should auto-compaction fire? Codex parity: `token_limit_reached` when real usage crosses 90% of
+ * the model's context window (`context_window.rs:74-79`; limit default `(cw*9)/10`,
+ * `openai_models.rs:459-469`). Missing inputs (no usage reported / model absent from the catalog)
+ * NEVER fire — fail-safe toward "do nothing".
+ */
+export declare function shouldAutoCompact(opts: {
+    usageTotal?: number | undefined;
+    contextWindow?: number | undefined;
+}): boolean;
+/**
+ * Fire auto-compaction when the threshold is crossed — at most ONE attempt per turn per agent
+ * (anti-cascade: a failing summarizer or a non-reducing summary must not loop). Returns whether a
+ * compaction actually happened. Failures WARN and leave the transcript untouched.
+ */
+export declare function autoCompactIfNeeded(opts: {
+    store: SessionStore;
+    loc: CompactLocation;
+    sessionId: string;
+    usageTotal?: number | undefined;
+    contextWindow?: number | undefined;
+    turnCount: number;
+    summarize: (messages: readonly CompressibleMessage[]) => Promise<string>;
+}): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.15.4",
+  "version": "4.16.1",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheodev/theokit-sdk#readme",

package/dist/{cron-DY0uC1ng.d.ts → cron-B_vVYc-_.d.ts}

@@ -2,6 +2,98 @@ import * as zod from 'zod';
 import { ZodType } from 'zod';
 import { M as ModelSelection, ac as SDKUserMessage, ae as SendOptions, b as Run, G as GenerateOptions, n as GenerateRunResult, _ as RunToCompletionOptions, $ as RunToCompletionResult, S as SDKMessage, al as StreamToCompletionResult, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor, u as MessageOrigin } from './run-DFM1H2jW.js';
 
+/**
+ * `SessionRecord` — the native on-disk transcript record shape (SE40).
+ *
+ * The theokit session format IS the Claude Code record shape: a
+ * `uuid`/`parentUuid` DAG of records with structured
+ * `text`/`tool_use`/`tool_result`/`thinking` blocks. This is the contract the
+ * pluggable {@link SessionStore} seam operates over.
+ *
+ * DIP-correct home (SE46): the contract lives in the domain `types/` layer;
+ * the application-layer DAG core (`internal/persistence/session-transcript.ts`)
+ * re-exports it for back-compat while owning the record builders + reader.
+ *
+ * @public
+ */
+/** One transcript record (one JSONL line). `message` absent on `system` (compact_boundary) records. */
+interface SessionRecord {
+    type: "user" | "assistant" | "system";
+    uuid: string;
+    parentUuid: string | null;
+    sessionId: string;
+    timestamp: string;
+    isSidechain?: boolean;
+    userType?: string;
+    cwd?: string;
+    version?: string;
+    subtype?: string;
+    compactMetadata?: {
+        preTokens: number;
+        trigger: string;
+    };
+    message?: Record<string, unknown>;
+}
+
+/**
+ * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
+ *
+ * A minimal, two-method port so an external store (Postgres / Redis / KV /
+ * durable object) can be the **primary store AND resume source** — the
+ * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
+ * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
+ * NOT that removed ~10-method adapter: the seam is JUST record read/append over
+ * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
+ * delete / objective methods).
+ *
+ * The SDK ships a real default implementation, `FsSessionStore`, that reads and
+ * append-writes the native Claude-shaped `.jsonl` transcript — omitting
+ * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
+ * consumer change). Injected via `local.sessionStore` for external stores.
+ *
+ * Consistency contract: `appendRecords` is append-only and ordering-preserving.
+ * The FS default serializes appends per agent with a cross-process file lock;
+ * external implementations own (and MUST document) their own concurrency
+ * guarantees for two hosts appending to the same `agentId`.
+ *
+ * @public
+ */
+
+/**
+ * The pluggable session-store seam. Exactly two methods over the native
+ * {@link SessionRecord} shape.
+ *
+ * @public
+ */
+interface SessionStore {
+    /**
+     * Return every persisted record for `agentId`, in append order. A session
+     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
+     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
+     * records via the native DAG reader, so the shape MUST be the exact
+     * {@link SessionRecord} the SDK writes.
+     *
+     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
+     * MUST throw a typed error rather than silently returning `[]` — a silent
+     * empty read would masquerade as "no history" and drop the conversation.
+     */
+    readRecords(agentId: string): Promise<SessionRecord[]>;
+    /**
+     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
+     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
+     * format is an append-only `parentUuid` DAG (compaction is a new-root
+     * `compact_boundary` record, still an append).
+     *
+     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
+     * is never blocked by store I/O — an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write). An external store that
+     * must guarantee durability should make `appendRecords` resilient (retry /
+     * durable write) internally. This differs from {@link SessionStore.readRecords},
+     * which MUST throw on failure (a resume cannot proceed on a silent partial history).
+     */
+    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+}
+
 /**
  * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
  *
@@ -233,98 +325,6 @@ declare class Skill {
     static create(spec: CreateSkillSpec): InlineSkill;
 }
 
-/**
- * `SessionRecord` — the native on-disk transcript record shape (SE40).
- *
- * The theokit session format IS the Claude Code record shape: a
- * `uuid`/`parentUuid` DAG of records with structured
- * `text`/`tool_use`/`tool_result`/`thinking` blocks. This is the contract the
- * pluggable {@link SessionStore} seam operates over.
- *
- * DIP-correct home (SE46): the contract lives in the domain `types/` layer;
- * the application-layer DAG core (`internal/persistence/session-transcript.ts`)
- * re-exports it for back-compat while owning the record builders + reader.
- *
- * @public
- */
-/** One transcript record (one JSONL line). `message` absent on `system` (compact_boundary) records. */
-interface SessionRecord {
-    type: "user" | "assistant" | "system";
-    uuid: string;
-    parentUuid: string | null;
-    sessionId: string;
-    timestamp: string;
-    isSidechain?: boolean;
-    userType?: string;
-    cwd?: string;
-    version?: string;
-    subtype?: string;
-    compactMetadata?: {
-        preTokens: number;
-        trigger: string;
-    };
-    message?: Record<string, unknown>;
-}
-
-/**
- * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
- *
- * A minimal, two-method port so an external store (Postgres / Redis / KV /
- * durable object) can be the **primary store AND resume source** — the
- * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
- * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
- * NOT that removed ~10-method adapter: the seam is JUST record read/append over
- * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
- * delete / objective methods).
- *
- * The SDK ships a real default implementation, `FsSessionStore`, that reads and
- * append-writes the native Claude-shaped `.jsonl` transcript — omitting
- * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
- * consumer change). Injected via `local.sessionStore` for external stores.
- *
- * Consistency contract: `appendRecords` is append-only and ordering-preserving.
- * The FS default serializes appends per agent with a cross-process file lock;
- * external implementations own (and MUST document) their own concurrency
- * guarantees for two hosts appending to the same `agentId`.
- *
- * @public
- */
-
-/**
- * The pluggable session-store seam. Exactly two methods over the native
- * {@link SessionRecord} shape.
- *
- * @public
- */
-interface SessionStore {
-    /**
-     * Return every persisted record for `agentId`, in append order. A session
-     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
-     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
-     * records via the native DAG reader, so the shape MUST be the exact
-     * {@link SessionRecord} the SDK writes.
-     *
-     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
-     * MUST throw a typed error rather than silently returning `[]` — a silent
-     * empty read would masquerade as "no history" and drop the conversation.
-     */
-    readRecords(agentId: string): Promise<SessionRecord[]>;
-    /**
-     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
-     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
-     * format is an append-only `parentUuid` DAG (compaction is a new-root
-     * `compact_boundary` record, still an append).
-     *
-     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
-     * is never blocked by store I/O — an `appendRecords` rejection is logged to
-     * stderr, NOT thrown to the caller (best-effort write). An external store that
-     * must guarantee durability should make `appendRecords` resilient (retry /
-     * durable write) internally. This differs from {@link SessionStore.readRecords},
-     * which MUST throw on failure (a resume cannot proceed on a silent partial history).
-     */
-    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
-}
-
 /**
  * `BudgetTracker` — runtime contract for budget/usage tracking in the
  * agent loop (SDK 2.0 Phase 2 / T2.1 — ADR D1 interface inversion).

package/dist/{cron-ElTj1cSH.d.cts → cron-Dj8FAU5V.d.cts}

@@ -2,6 +2,98 @@ import * as zod from 'zod';
 import { ZodType } from 'zod';
 import { M as ModelSelection, ac as SDKUserMessage, ae as SendOptions, b as Run, G as GenerateOptions, n as GenerateRunResult, _ as RunToCompletionOptions, $ as RunToCompletionResult, S as SDKMessage, al as StreamToCompletionResult, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor, u as MessageOrigin } from './run-DFM1H2jW.cjs';
 
+/**
+ * `SessionRecord` — the native on-disk transcript record shape (SE40).
+ *
+ * The theokit session format IS the Claude Code record shape: a
+ * `uuid`/`parentUuid` DAG of records with structured
+ * `text`/`tool_use`/`tool_result`/`thinking` blocks. This is the contract the
+ * pluggable {@link SessionStore} seam operates over.
+ *
+ * DIP-correct home (SE46): the contract lives in the domain `types/` layer;
+ * the application-layer DAG core (`internal/persistence/session-transcript.ts`)
+ * re-exports it for back-compat while owning the record builders + reader.
+ *
+ * @public
+ */
+/** One transcript record (one JSONL line). `message` absent on `system` (compact_boundary) records. */
+interface SessionRecord {
+    type: "user" | "assistant" | "system";
+    uuid: string;
+    parentUuid: string | null;
+    sessionId: string;
+    timestamp: string;
+    isSidechain?: boolean;
+    userType?: string;
+    cwd?: string;
+    version?: string;
+    subtype?: string;
+    compactMetadata?: {
+        preTokens: number;
+        trigger: string;
+    };
+    message?: Record<string, unknown>;
+}
+
+/**
+ * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
+ *
+ * A minimal, two-method port so an external store (Postgres / Redis / KV /
+ * durable object) can be the **primary store AND resume source** — the
+ * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
+ * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
+ * NOT that removed ~10-method adapter: the seam is JUST record read/append over
+ * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
+ * delete / objective methods).
+ *
+ * The SDK ships a real default implementation, `FsSessionStore`, that reads and
+ * append-writes the native Claude-shaped `.jsonl` transcript — omitting
+ * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
+ * consumer change). Injected via `local.sessionStore` for external stores.
+ *
+ * Consistency contract: `appendRecords` is append-only and ordering-preserving.
+ * The FS default serializes appends per agent with a cross-process file lock;
+ * external implementations own (and MUST document) their own concurrency
+ * guarantees for two hosts appending to the same `agentId`.
+ *
+ * @public
+ */
+
+/**
+ * The pluggable session-store seam. Exactly two methods over the native
+ * {@link SessionRecord} shape.
+ *
+ * @public
+ */
+interface SessionStore {
+    /**
+     * Return every persisted record for `agentId`, in append order. A session
+     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
+     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
+     * records via the native DAG reader, so the shape MUST be the exact
+     * {@link SessionRecord} the SDK writes.
+     *
+     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
+     * MUST throw a typed error rather than silently returning `[]` — a silent
+     * empty read would masquerade as "no history" and drop the conversation.
+     */
+    readRecords(agentId: string): Promise<SessionRecord[]>;
+    /**
+     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
+     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
+     * format is an append-only `parentUuid` DAG (compaction is a new-root
+     * `compact_boundary` record, still an append).
+     *
+     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
+     * is never blocked by store I/O — an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write). An external store that
+     * must guarantee durability should make `appendRecords` resilient (retry /
+     * durable write) internally. This differs from {@link SessionStore.readRecords},
+     * which MUST throw on failure (a resume cannot proceed on a silent partial history).
+     */
+    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+}
+
 /**
  * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
  *
@@ -233,98 +325,6 @@ declare class Skill {
     static create(spec: CreateSkillSpec): InlineSkill;
 }
 
-/**
- * `SessionRecord` — the native on-disk transcript record shape (SE40).
- *
- * The theokit session format IS the Claude Code record shape: a
- * `uuid`/`parentUuid` DAG of records with structured
- * `text`/`tool_use`/`tool_result`/`thinking` blocks. This is the contract the
- * pluggable {@link SessionStore} seam operates over.
- *
- * DIP-correct home (SE46): the contract lives in the domain `types/` layer;
- * the application-layer DAG core (`internal/persistence/session-transcript.ts`)
- * re-exports it for back-compat while owning the record builders + reader.
- *
- * @public
- */
-/** One transcript record (one JSONL line). `message` absent on `system` (compact_boundary) records. */
-interface SessionRecord {
-    type: "user" | "assistant" | "system";
-    uuid: string;
-    parentUuid: string | null;
-    sessionId: string;
-    timestamp: string;
-    isSidechain?: boolean;
-    userType?: string;
-    cwd?: string;
-    version?: string;
-    subtype?: string;
-    compactMetadata?: {
-        preTokens: number;
-        trigger: string;
-    };
-    message?: Record<string, unknown>;
-}
-
-/**
- * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
- *
- * A minimal, two-method port so an external store (Postgres / Redis / KV /
- * durable object) can be the **primary store AND resume source** — the
- * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
- * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
- * NOT that removed ~10-method adapter: the seam is JUST record read/append over
- * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
- * delete / objective methods).
- *
- * The SDK ships a real default implementation, `FsSessionStore`, that reads and
- * append-writes the native Claude-shaped `.jsonl` transcript — omitting
- * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
- * consumer change). Injected via `local.sessionStore` for external stores.
- *
- * Consistency contract: `appendRecords` is append-only and ordering-preserving.
- * The FS default serializes appends per agent with a cross-process file lock;
- * external implementations own (and MUST document) their own concurrency
- * guarantees for two hosts appending to the same `agentId`.
- *
- * @public
- */
-
-/**
- * The pluggable session-store seam. Exactly two methods over the native
- * {@link SessionRecord} shape.
- *
- * @public
- */
-interface SessionStore {
-    /**
-     * Return every persisted record for `agentId`, in append order. A session
-     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
-     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
-     * records via the native DAG reader, so the shape MUST be the exact
-     * {@link SessionRecord} the SDK writes.
-     *
-     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
-     * MUST throw a typed error rather than silently returning `[]` — a silent
-     * empty read would masquerade as "no history" and drop the conversation.
-     */
-    readRecords(agentId: string): Promise<SessionRecord[]>;
-    /**
-     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
-     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
-     * format is an append-only `parentUuid` DAG (compaction is a new-root
-     * `compact_boundary` record, still an append).
-     *
-     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
-     * is never blocked by store I/O — an `appendRecords` rejection is logged to
-     * stderr, NOT thrown to the caller (best-effort write). An external store that
-     * must guarantee durability should make `appendRecords` resilient (retry /
-     * durable write) internally. This differs from {@link SessionStore.readRecords},
-     * which MUST throw on failure (a resume cannot proceed on a silent partial history).
-     */
-    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
-}
-
 /**
  * `BudgetTracker` — runtime contract for budget/usage tracking in the
  * agent loop (SDK 2.0 Phase 2 / T2.1 — ADR D1 interface inversion).