@theokit/sdk 5.9.2 → 5.11.0

package/dist/{inject-session-O24XGRR6.js → inject-session-E5UDFVLI.js}

@@ -1,4 +1,4 @@
-import { enqueueSessionWrite } from './chunk-EXI7EHDN.js';
+import { enqueueSessionWrite } from './chunk-7Y23B7XX.js';
 import { invalidateSessionCache } from './chunk-2XC6KDJM.js';
 import './chunk-XERM7PDQ.js';
 import { SessionTranscript } from './chunk-FTZTZBCU.js';
@@ -23,5 +23,5 @@ async function injectSessionTurn(opts) {
 }
 
 export { injectSessionTurn };
-//# sourceMappingURL=inject-session-O24XGRR6.js.map
-//# sourceMappingURL=inject-session-O24XGRR6.js.map
+//# sourceMappingURL=inject-session-E5UDFVLI.js.map
+//# sourceMappingURL=inject-session-E5UDFVLI.js.map

package/dist/{inject-session-O24XGRR6.js.map → inject-session-E5UDFVLI.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-O24XGRR6.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":[],"mappings":";;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAM,oBAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAA,sBAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-E5UDFVLI.js","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/{inject-session-OMLFL2V3.cjs → inject-session-W4UKACYJ.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkFR6COQXZ_cjs = require('./chunk-FR6COQXZ.cjs');
+var chunkN7ZIPW2N_cjs = require('./chunk-N7ZIPW2N.cjs');
 var chunkYJNYDJ2T_cjs = require('./chunk-YJNYDJ2T.cjs');
 require('./chunk-ZAM7BJXJ.cjs');
 var chunkZWACQM5U_cjs = require('./chunk-ZWACQM5U.cjs');
@@ -10,7 +10,7 @@ require('./chunk-6LHQPOMI.cjs');
 
 // src/internal/session/inject-session.ts
 async function injectSessionTurn(opts) {
-  await chunkFR6COQXZ_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
+  await chunkN7ZIPW2N_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
     const prior = await opts.store.readRecords(opts.loc.agentId);
     const transcript = chunkZWACQM5U_cjs.SessionTranscript.fromRecords(prior, {
       cwd: opts.loc.cwd,
@@ -25,5 +25,5 @@ async function injectSessionTurn(opts) {
 }
 
 exports.injectSessionTurn = injectSessionTurn;
-//# sourceMappingURL=inject-session-OMLFL2V3.cjs.map
-//# sourceMappingURL=inject-session-OMLFL2V3.cjs.map
+//# sourceMappingURL=inject-session-W4UKACYJ.cjs.map
+//# sourceMappingURL=inject-session-W4UKACYJ.cjs.map

package/dist/{inject-session-OMLFL2V3.cjs.map → inject-session-W4UKACYJ.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-OMLFL2V3.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/internal/session/inject-session.ts"],"names":["enqueueSessionWrite","SessionTranscript","invalidateSessionCache"],"mappings":";;;;;;;;;;;AAWA,eAAsB,kBAAkB,IAAA,EAMtB;AAChB,EAAA,MAAMA,sCAAoB,IAAA,CAAK,GAAA,CAAI,KAAK,IAAA,CAAK,GAAA,CAAI,SAAS,YAAY;AACpE,IAAA,MAAM,QAAQ,MAAM,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,IAAI,OAAO,CAAA;AAC3D,IAAA,MAAM,UAAA,GAAaC,mCAAA,CAAkB,WAAA,CAAY,KAAA,EAAO;AAAA,MACtD,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA;AAAA,MACd,WAAW,IAAA,CAAK,SAAA;AAAA,MAChB,KAAA,EAAO,IAAA,CAAK,GAAA,CAAI,KAAA,IAAS;AAAA,KAC1B,CAAA;AACD,IAAA,UAAA,CAAW,cAAA,CAAe,KAAK,QAAQ,CAAA;AACvC,IAAA,UAAA,CAAW,mBAAA,CAAoB,EAAE,IAAA,EAAM,IAAA,CAAK,eAAe,CAAA;AAC3D,IAAA,MAAM,IAAA,CAAK,KAAA,CAAM,aAAA,CAAc,IAAA,CAAK,GAAA,CAAI,OAAA,EAAS,UAAA,CAAW,OAAA,EAAQ,CAAE,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAA;AACzF,IAAAC,wCAAA,CAAuB,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,IAAA,CAAK,IAAI,OAAO,CAAA;AAAA,EACvD,CAAC,CAAA;AACH","file":"inject-session-W4UKACYJ.cjs","sourcesContent":["/**\n * M51 (agent-builder) — inject a SYNTHETIC user+assistant pair into a session's persisted transcript\n * WITHOUT running an LLM turn. This is the Codex review-exit mechanism (`exit_success.xml` appended to\n * the parent thread history so follow-ups like \"fix finding 2\" work): the pair chains onto the DAG\n * leaf (M50 pattern) and the in-memory cache is invalidated so the NEXT send re-hydrates with it.\n */\nimport type { SessionStore } from \"../../types/session-store.js\";\nimport { SessionTranscript } from \"../persistence/session-transcript.js\";\nimport { enqueueSessionWrite, invalidateSessionCache } from \"./agent-session.js\";\nimport type { CompactLocation } from \"./compact-session.js\";\n\nexport async function injectSessionTurn(opts: {\n  store: SessionStore;\n  loc: CompactLocation;\n  sessionId: string;\n  userText: string;\n  assistantText: string;\n}): Promise<void> {\n  await enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {\n    const prior = await opts.store.readRecords(opts.loc.agentId);\n    const transcript = SessionTranscript.fromRecords(prior, {\n      cwd: opts.loc.cwd,\n      sessionId: opts.sessionId,\n      model: opts.loc.model ?? \"unknown\",\n    });\n    transcript.appendUserTurn(opts.userText);\n    transcript.appendAssistantTurn({ text: opts.assistantText });\n    await opts.store.appendRecords(opts.loc.agentId, transcript.records().slice(prior.length));\n    invalidateSessionCache(opts.loc.cwd, opts.loc.agentId);\n  });\n}\n"]}

package/dist/internal/budget/normalize-usage.d.ts

@@ -0,0 +1,81 @@
+/**
+ * normalizeUsage — convert provider-shaped raw `usage` object to
+ * canonical `TokenUsage`. Ports Hermes Agent's `normalize_usage`
+ * (reference/peer-agent/agent/usage_pricing.py:672-742).
+ *
+ * Handles 3 API shapes:
+ *   - Anthropic Messages: 4 explicit buckets (input/output/cache_read/cache_creation).
+ *   - OpenAI Chat Completions: prompt_tokens INCLUDES cache; subtract cached_tokens.
+ *   - OpenAI Responses (Codex): input_tokens INCLUDES cache; same subtraction.
+ *
+ * Edge cases:
+ *   - a peer#10266 — OpenAI-compat proxies (OpenRouter, a peer vendor AI Gateway,
+ *     a peer) routing Claude expose Anthropic-style top-level fields
+ *     (cache_read_input_tokens / cache_creation_input_tokens). Both
+ *     locations are checked with top-level fallback.
+ *   - Null/undefined fields → 0 via `int()` coerce.
+ *   - String token counts → parsed via int.
+ *   - Negative values → clamped to 0 (defensive against proxy bugs).
+ *
+ * @internal
+ */
+export type ApiMode = "anthropic_messages" | "openai_chat_completions" | "openai_responses";
+/**
+ * Guess which usage shape a provider reports, from its name alone.
+ *
+ * Matching is case-insensitive and exact — `"anthropic"`, `"claude"` and `"bedrock_anthropic"`
+ * give `"anthropic_messages"`; `"openai-codex"` and `"codex"` give `"openai_responses"`. Every
+ * other name, including ones this SDK has never seen, falls through to
+ * `"openai_chat_completions"`. There is no unknown result, so a wrong guess is silent: it is
+ * read as a Chat Completions payload, whose fields are absent, and the tokens come back as 0.
+ *
+ * The default is right for the OpenAI-compatible majority (openai, openrouter, deepseek, and the
+ * compat endpoints of google, ollama and lmstudio). When it is not, pass `apiMode` to
+ * `normalizeUsage` explicitly instead of relying on the name.
+ */
+export declare function inferApiMode(provider: string): ApiMode;
+/**
+ * Convert a provider's raw `usage` object into the SDK's canonical `TokenUsage`.
+ *
+ * Never throws and never reports failure. `null`, `undefined` and any non-object argument return
+ * all-zero usage, which is indistinguishable from a real response that used no tokens — so this
+ * is not the place to detect a malformed payload.
+ *
+ * `opts.apiMode` selects the reader; when omitted it is derived from `opts.provider` via
+ * `inferApiMode`, whose fallback is Chat Completions. Pass it explicitly for any provider whose
+ * name does not identify its wire shape.
+ *
+ * The shapes differ in one way that matters: Anthropic reports cache tokens in buckets separate
+ * from `input_tokens`, while both OpenAI shapes report a prompt total that already includes
+ * them. For the OpenAI readers the cache buckets are subtracted, so `inputTokens` is always the
+ * uncached portion and `inputTokens + cacheReadTokens + cacheWriteTokens` reconstructs the
+ * provider's prompt total. The subtraction is floored at 0, so a payload whose cache counts
+ * exceed its prompt total yields 0 rather than a negative.
+ *
+ * Every field is coerced: numbers are truncated toward zero, numeric strings are parsed, negative
+ * and non-finite values become 0, and anything else becomes 0.
+ *
+ * `totalTokens` is computed here as input + output + both cache buckets; a `total_tokens` the
+ * provider sent is ignored. Reasoning tokens are reported separately but are NOT added again —
+ * providers already count them inside output. `cacheReadTokens`, `cacheWriteTokens` and
+ * `reasoningTokens` are omitted from the result when they are 0, so absent means zero, not
+ * unknown.
+ *
+ * Chat Completions also accepts Anthropic-style top-level `cache_read_input_tokens` /
+ * `cache_creation_input_tokens`, which OpenAI-compatible proxies emit when they route Claude.
+ * The nested `prompt_tokens_details` values win; the top-level fields are consulted only when
+ * those are 0 or missing.
+ */
+export declare function normalizeUsage(rawUsage: unknown, opts: {
+    provider: string;
+    apiMode?: ApiMode;
+}): TokenUsage;
+/** The prompt of a Chat Completions `usage` object, split the way {@link splitChatCompletionsPrompt} reports it. */
+export interface ChatCompletionsPromptSplit {
+    /** `prompt_tokens` minus both cache buckets, floored at 0; absent when `prompt_tokens` is. */
+    readonly inputTokens?: number;
+    /** Absent when the payload carries neither cache-read field. */
+    readonly cacheReadTokens?: number;
+    /** Absent when the payload carries neither cache-write field. */
+    readonly cacheWriteTokens?: number;
+}

package/dist/internal/llm/anthropic-shared.d.ts

@@ -20,6 +20,8 @@ export interface AnthropicResponseLike {
     usage?: {
         input_tokens?: number;
         output_tokens?: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
     };
 }
 export declare function extractAnthropicText(response: AnthropicResponseLike): string;
@@ -62,6 +64,8 @@ export declare function handleAnthropicResponse(args: {
     stopReason: LlmStopReason;
     inputTokens?: number;
     outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
 }>;
 export declare function consumeAnthropicResponse(response: Response): Promise<{
     text: string;
@@ -69,6 +73,8 @@ export declare function consumeAnthropicResponse(response: Response): Promise<{
     stopReason: LlmStopReason;
     inputTokens?: number;
     outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
 }>;
 export declare function parseHttpErrorBody(response: Response): Promise<unknown>;
 export interface AnthropicTextBlock {

package/dist/internal/llm/openai.d.ts

@@ -70,6 +70,7 @@ interface OpenAIDeltaChunk {
          */
         prompt_tokens_details?: {
             cached_tokens?: number;
+            cache_write_tokens?: number;
         };
         completion_tokens_details?: {
             reasoning_tokens?: number;
@@ -106,11 +107,8 @@ declare class OpenAIStreamAccumulator {
     private readonly allowedToolNames?;
     private text;
     private stopReason;
-    private inputTokens?;
-    private outputTokens?;
-    private cacheReadTokens?;
-    private cacheWriteTokens?;
-    private reasoningTokens?;
+    /** The stream's `usage` object, a later chunk replacing an earlier one per top-level field. */
+    private usage;
     private readonly toolCalls;
     /** R7: present only when recovery is enabled AND the request declares tools — holds suspected
      *  leaked-dialect content back from the `text_delta` stream. `undefined` ⇒ stream immediately. */

package/dist/internal/llm/openrouter-system.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -83,14 +83,15 @@ export interface LlmMessage {
  * annotation in the Anthropic wire body, which lets Anthropic bill
  * subsequent same-content requests at the cache-read rate (1-3x discount).
  *
- * For providers that don't support prompt caching (OpenAI, OpenRouter, etc),
- * the array is joined into a single string at the wire boundary so the
- * upstream contract stays unchanged. Back-compat: `LlmRequest.system` still
+ * OpenRouter receives the blocks as `content` parts of the `system` message,
+ * with `cache_control` on each cacheable part. Every other chat-completions
+ * provider (OpenAI and the compatible ones) gets the array joined into a
+ * single string at the wire boundary. Back-compat: `LlmRequest.system` still
  * accepts a plain `string` (pre-T3.5 callers compile unchanged).
  */
 export interface LlmSystemBlock {
     text: string;
-    /** When `true`, ask the provider to cache this block (Anthropic only). */
+    /** When `true`, ask the provider to cache this block (Anthropic, and OpenRouter content parts). */
     cacheable?: boolean;
 }
 /**
@@ -204,11 +205,15 @@ export interface LlmFinish {
     stopReason: LlmStopReason;
     text: string;
     toolCalls: LlmToolCallPart[];
+    /**
+     * Uncached input tokens, the way Anthropic reports them. The chat-completions client subtracts
+     * the cache buckets from the provider's cache-inclusive `prompt_tokens` to match.
+     */
     inputTokens?: number;
     outputTokens?: number;
     /** Cache read tokens (Anthropic prompt caching / OpenAI cached). ADR D376. */
     cacheReadTokens?: number;
-    /** Cache creation tokens (Anthropic only). ADR D376. */
+    /** Cache creation tokens (Anthropic, and OpenRouter's `cache_write_tokens`). ADR D376. */
     cacheWriteTokens?: number;
     /** Reasoning tokens (OpenAI o-series). ADR D376. */
     reasoningTokens?: number;

package/dist/internal/memory/dreaming/phases.d.ts

@@ -6,6 +6,8 @@ export interface Cluster {
 }
 export interface ClusterResult {
     clusters: Cluster[];
+    /** How many input facts past the per-sweep cap were not clustered; 0 when none were. */
+    factsLeftOut: number;
 }
 /**
  * Light phase — drop facts whose embedding is too similar to one already kept.

package/dist/internal/memory/dreaming/run.d.ts

@@ -6,5 +6,10 @@ export interface DreamingResult {
     clustersCreated: number;
     notesWritten: number;
     diaryEntryHash: string | undefined;
+    /**
+     * Deduplicated facts past the per-sweep cap that were not clustered. Set on `"ok"`, 0 on
+     * `"skipped"`, and absent on `"error"`, where the sweep cannot say how many it left out.
+     */
+    factsLeftOut?: number;
 }
 export declare function runDreamingSweep(options: DreamingOptions): Promise<DreamingResult>;

package/dist/internal/memory/sdk-memory-peer-loader.d.ts

@@ -44,6 +44,8 @@ export interface SdkMemoryModule {
         duplicatesRemoved: number;
         clustersCreated: number;
         notesWritten: number;
+        /** Optional: a peer older than the one that reports the count leaves it out. */
+        factsLeftOut?: number;
     }>;
     /** Mirrors @theokit/sdk-memory's IndexManager class (static open). */
     readonly IndexManager: {

package/dist/internal/memory/storage/fact-ceiling.d.cts

@@ -0,0 +1,19 @@
+import { ConfigurationError } from "../../../errors.js";
+/**
+ * The ceiling a caller declared, or `undefined` when none was declared.
+ *
+ * Validated before anything touches disk, because a ceiling that cannot be met (0, a negative or
+ * fractional number, a string, `null`) would otherwise surface later as a refusal of every write
+ * that names the wrong cause.
+ *
+ * @throws ConfigurationError with code `invalid_memory_ceiling` when the value is declared and is
+ *   not a positive safe integer.
+ */
+export declare function resolveMaxFacts(value: unknown): number | undefined;
+/**
+ * The refusal of a new fact at a store's declared ceiling: where the store is, how many facts it
+ * holds, the ceiling, and what to consolidate. `remedy` is the store-specific way to make room.
+ *
+ * Returned, not thrown, so each writer throws it at the point where it has written nothing.
+ */
+export declare function ceilingReachedError(where: string, count: number, maxFacts: number, remedy: string): ConfigurationError;

package/dist/internal/memory/storage/fact-ceiling.d.ts

@@ -0,0 +1,19 @@
+import { ConfigurationError } from "../../../errors.js";
+/**
+ * The ceiling a caller declared, or `undefined` when none was declared.
+ *
+ * Validated before anything touches disk, because a ceiling that cannot be met (0, a negative or
+ * fractional number, a string, `null`) would otherwise surface later as a refusal of every write
+ * that names the wrong cause.
+ *
+ * @throws ConfigurationError with code `invalid_memory_ceiling` when the value is declared and is
+ *   not a positive safe integer.
+ */
+export declare function resolveMaxFacts(value: unknown): number | undefined;
+/**
+ * The refusal of a new fact at a store's declared ceiling: where the store is, how many facts it
+ * holds, the ceiling, and what to consolidate. `remedy` is the store-specific way to make room.
+ *
+ * Returned, not thrown, so each writer throws it at the point where it has written nothing.
+ */
+export declare function ceilingReachedError(where: string, count: number, maxFacts: number, remedy: string): ConfigurationError;

package/dist/internal/memory/storage/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunkX7Z2FEI7_cjs = require('../../../chunk-X7Z2FEI7.cjs');
+var chunkFYEHYQ7T_cjs = require('../../../chunk-FYEHYQ7T.cjs');
 var chunkTMKTSYDS_cjs = require('../../../chunk-TMKTSYDS.cjs');
-var chunkVZ2JZ2EH_cjs = require('../../../chunk-VZ2JZ2EH.cjs');
+var chunkZD66GFH5_cjs = require('../../../chunk-ZD66GFH5.cjs');
 require('../../../chunk-KRD3GQAA.cjs');
 require('../../../chunk-MUUQ2WFJ.cjs');
 require('../../../chunk-SWALPLFQ.cjs');
@@ -10,6 +10,7 @@ require('../../../chunk-GM54F4FE.cjs');
 require('../../../chunk-SA6K24NB.cjs');
 require('../../../chunk-ZWACQM5U.cjs');
 require('../../../chunk-P22BZE7G.cjs');
+require('../../../chunk-ASK2OQM5.cjs');
 require('../../../chunk-ZF2LDKQQ.cjs');
 require('../../../chunk-JLRLCBJ4.cjs');
 require('../../../chunk-UNFBHV46.cjs');
@@ -19,23 +20,23 @@ require('../../../chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "appendDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkX7Z2FEI7_cjs.appendDiaryEntry; }
+  get: function () { return chunkFYEHYQ7T_cjs.appendDiaryEntry; }
 });
 Object.defineProperty(exports, "diaryPath", {
   enumerable: true,
-  get: function () { return chunkX7Z2FEI7_cjs.diaryPath; }
+  get: function () { return chunkFYEHYQ7T_cjs.diaryPath; }
 });
 Object.defineProperty(exports, "entryHash", {
   enumerable: true,
-  get: function () { return chunkX7Z2FEI7_cjs.entryHash; }
+  get: function () { return chunkFYEHYQ7T_cjs.entryHash; }
 });
 Object.defineProperty(exports, "readAllSqliteFacts", {
   enumerable: true,
-  get: function () { return chunkX7Z2FEI7_cjs.readAllSqliteFacts; }
+  get: function () { return chunkFYEHYQ7T_cjs.readAllSqliteFacts; }
 });
 Object.defineProperty(exports, "renderDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkX7Z2FEI7_cjs.renderDiaryEntry; }
+  get: function () { return chunkFYEHYQ7T_cjs.renderDiaryEntry; }
 });
 Object.defineProperty(exports, "persistActiveMemoryTranscript", {
   enumerable: true,
@@ -43,99 +44,107 @@ Object.defineProperty(exports, "persistActiveMemoryTranscript", {
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_BYTES", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.MEMORY_INDEX_MAX_BYTES; }
+  get: function () { return chunkZD66GFH5_cjs.MEMORY_INDEX_MAX_BYTES; }
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_LINES", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.MEMORY_INDEX_MAX_LINES; }
+  get: function () { return chunkZD66GFH5_cjs.MEMORY_INDEX_MAX_LINES; }
 });
 Object.defineProperty(exports, "appendFact", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.appendFact; }
+  get: function () { return chunkZD66GFH5_cjs.appendFact; }
 });
 Object.defineProperty(exports, "appendFactToMarkdown", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.appendFactToMarkdown; }
+  get: function () { return chunkZD66GFH5_cjs.appendFactToMarkdown; }
 });
 Object.defineProperty(exports, "asMemoryRoot", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.asMemoryRoot; }
+  get: function () { return chunkZD66GFH5_cjs.asMemoryRoot; }
+});
+Object.defineProperty(exports, "ceilingReachedError", {
+  enumerable: true,
+  get: function () { return chunkZD66GFH5_cjs.ceilingReachedError; }
 });
 Object.defineProperty(exports, "claudeProjectMemoryDir", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.claudeProjectMemoryDir; }
+  get: function () { return chunkZD66GFH5_cjs.claudeProjectMemoryDir; }
 });
 Object.defineProperty(exports, "collectMarkdownFiles", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.collectMarkdownFiles; }
+  get: function () { return chunkZD66GFH5_cjs.collectMarkdownFiles; }
 });
 Object.defineProperty(exports, "defaultIndexPath", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.defaultIndexPath; }
+  get: function () { return chunkZD66GFH5_cjs.defaultIndexPath; }
 });
 Object.defineProperty(exports, "discoverSessionFiles", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.discoverSessionFiles; }
+  get: function () { return chunkZD66GFH5_cjs.discoverSessionFiles; }
 });
 Object.defineProperty(exports, "discoverWikiFiles", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.discoverWikiFiles; }
+  get: function () { return chunkZD66GFH5_cjs.discoverWikiFiles; }
 });
 Object.defineProperty(exports, "indexBudgetWarning", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.indexBudgetWarning; }
+  get: function () { return chunkZD66GFH5_cjs.indexBudgetWarning; }
 });
 Object.defineProperty(exports, "lanceStoragePath", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.lanceStoragePath; }
+  get: function () { return chunkZD66GFH5_cjs.lanceStoragePath; }
 });
 Object.defineProperty(exports, "memoryIndexRoot", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.memoryIndexRoot; }
+  get: function () { return chunkZD66GFH5_cjs.memoryIndexRoot; }
 });
 Object.defineProperty(exports, "memoryMdPath", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.memoryMdPath; }
+  get: function () { return chunkZD66GFH5_cjs.memoryMdPath; }
 });
 Object.defineProperty(exports, "memoryReadRoots", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.memoryReadRoots; }
+  get: function () { return chunkZD66GFH5_cjs.memoryReadRoots; }
 });
 Object.defineProperty(exports, "notesDir", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.notesDir; }
+  get: function () { return chunkZD66GFH5_cjs.notesDir; }
 });
 Object.defineProperty(exports, "projectMemoryDir", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.projectMemoryDir; }
+  get: function () { return chunkZD66GFH5_cjs.projectMemoryDir; }
 });
 Object.defineProperty(exports, "readFacts", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.readFacts; }
+  get: function () { return chunkZD66GFH5_cjs.readFacts; }
 });
 Object.defineProperty(exports, "readFactsFromMarkdown", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.readFactsFromMarkdown; }
+  get: function () { return chunkZD66GFH5_cjs.readFactsFromMarkdown; }
+});
+Object.defineProperty(exports, "resolveMaxFacts", {
+  enumerable: true,
+  get: function () { return chunkZD66GFH5_cjs.resolveMaxFacts; }
 });
 Object.defineProperty(exports, "resolveMemoryRoot", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.resolveMemoryRoot; }
+  get: function () { return chunkZD66GFH5_cjs.resolveMemoryRoot; }
 });
 Object.defineProperty(exports, "sessionSummaryPath", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.sessionSummaryPath; }
+  get: function () { return chunkZD66GFH5_cjs.sessionSummaryPath; }
 });
 Object.defineProperty(exports, "sessionsDir", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.sessionsDir; }
+  get: function () { return chunkZD66GFH5_cjs.sessionsDir; }
 });
 Object.defineProperty(exports, "wikiDir", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.wikiDir; }
+  get: function () { return chunkZD66GFH5_cjs.wikiDir; }
 });
 Object.defineProperty(exports, "writeSessionSummary", {
   enumerable: true,
-  get: function () { return chunkVZ2JZ2EH_cjs.writeSessionSummary; }
+  get: function () { return chunkZD66GFH5_cjs.writeSessionSummary; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/internal/memory/storage/index.d.cts

@@ -20,6 +20,7 @@ export { defaultIndexPath } from "../index-db.js";
 export { collectMarkdownFiles, type DiscoveredFile } from "../index-manager-helpers.js";
 export { lanceStoragePath } from "../lance-index.js";
 export { readAllSqliteFacts, type SqliteFactRow } from "../migrate-sqlite-to-lance.js";
+export { ceilingReachedError, resolveMaxFacts } from "./fact-ceiling.js";
 export { appendFact, appendFactToMarkdown, memoryMdPath, notesDir, readFacts, readFactsFromMarkdown, } from "./markdown-store.js";
 export { asMemoryRoot, claudeProjectMemoryDir, indexBudgetWarning, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, type MemoryLocationConfig, type MemoryRoot, memoryIndexRoot, memoryReadRoots, projectMemoryDir, resolveMemoryRoot, } from "./memory-root.js";
 export { discoverSessionFiles, type SessionFile } from "./session-loader.js";

package/dist/internal/memory/storage/index.d.ts

@@ -20,6 +20,7 @@ export { defaultIndexPath } from "../index-db.js";
 export { collectMarkdownFiles, type DiscoveredFile } from "../index-manager-helpers.js";
 export { lanceStoragePath } from "../lance-index.js";
 export { readAllSqliteFacts, type SqliteFactRow } from "../migrate-sqlite-to-lance.js";
+export { ceilingReachedError, resolveMaxFacts } from "./fact-ceiling.js";
 export { appendFact, appendFactToMarkdown, memoryMdPath, notesDir, readFacts, readFactsFromMarkdown, } from "./markdown-store.js";
 export { asMemoryRoot, claudeProjectMemoryDir, indexBudgetWarning, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, type MemoryLocationConfig, type MemoryRoot, memoryIndexRoot, memoryReadRoots, projectMemoryDir, resolveMemoryRoot, } from "./memory-root.js";
 export { discoverSessionFiles, type SessionFile } from "./session-loader.js";

package/dist/internal/memory/storage/index.js

@@ -1,6 +1,6 @@
-export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-N7KYUNFO.js';
+export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-W2ZVTEOD.js';
 export { persistActiveMemoryTranscript } from '../../../chunk-OR6XIWLB.js';
-export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryIndexRoot, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-47Z6LP3I.js';
+export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, ceilingReachedError, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryIndexRoot, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMaxFacts, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-X3LOJJMO.js';
 import '../../../chunk-KVNWIAO4.js';
 import '../../../chunk-FD2UT76F.js';
 import '../../../chunk-4QCJAJAG.js';
@@ -8,6 +8,7 @@ import '../../../chunk-5DD4NJN3.js';
 import '../../../chunk-UKMBRMGT.js';
 import '../../../chunk-FTZTZBCU.js';
 import '../../../chunk-XZHJYSPB.js';
+import '../../../chunk-RGQICWFU.js';
 import '../../../chunk-Q5EWJPRY.js';
 import '../../../chunk-3JHIFQ4I.js';
 import '../../../chunk-B5MHRQJZ.js';

package/dist/internal/memory/storage/markdown-store.d.cts

@@ -29,7 +29,9 @@ export declare function readFactsFromMarkdown(cwd: string, config?: MemoryLocati
  * `modified` is stamped HERE and never read from `fact`: a timestamp a caller can set is a
  * timestamp that can lie about when something was learned, and weighing recency is the point.
  */
-export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string): Promise<void>;
+export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string, options?: {
+    maxFacts?: number;
+}): Promise<void>;
 /**
  * Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig}: when memory is
  * disabled the call resolves to `[]` without touching disk. Configuration-aware entry point;

package/dist/internal/memory/storage/markdown-store.d.ts

@@ -29,7 +29,9 @@ export declare function readFactsFromMarkdown(cwd: string, config?: MemoryLocati
  * `modified` is stamped HERE and never read from `fact`: a timestamp a caller can set is a
  * timestamp that can lie about when something was learned, and weighing recency is the point.
  */
-export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string): Promise<void>;
+export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string, options?: {
+    maxFacts?: number;
+}): Promise<void>;
 /**
  * Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig}: when memory is
  * disabled the call resolves to `[]` without touching disk. Configuration-aware entry point;

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

@@ -9,6 +9,12 @@ export interface MemoryConfig {
      * See `storage/memory-root.ts` for why a relative value is refused rather than resolved.
      */
     directory?: string;
+    /**
+     * The most facts the write directory may hold. A new fact at the ceiling is refused with
+     * `memory_ceiling_reached`; a second observation of a stored fact is still admitted. Absent means
+     * no ceiling. The public contract is `MemorySettings.maxFacts` in `types/agent.ts`.
+     */
+    maxFacts?: number;
 }
 /**
  * What a fact IS, which is what decides whether it ages (#389).

package/dist/internal/persistence/index.cjs

@@ -4,7 +4,8 @@ var chunkVTYY7XL5_cjs = require('../../chunk-VTYY7XL5.cjs');
 var chunkRQMCOFAI_cjs = require('../../chunk-RQMCOFAI.cjs');
 var chunkA4RAL2ER_cjs = require('../../chunk-A4RAL2ER.cjs');
 var chunkP22BZE7G_cjs = require('../../chunk-P22BZE7G.cjs');
-var chunkOF2CLCTH_cjs = require('../../chunk-OF2CLCTH.cjs');
+var chunkR5YPDAKD_cjs = require('../../chunk-R5YPDAKD.cjs');
+var chunkASK2OQM5_cjs = require('../../chunk-ASK2OQM5.cjs');
 var chunkZF2LDKQQ_cjs = require('../../chunk-ZF2LDKQQ.cjs');
 var chunkJLRLCBJ4_cjs = require('../../chunk-JLRLCBJ4.cjs');
 var chunkTY56BKSK_cjs = require('../../chunk-TY56BKSK.cjs');
@@ -75,23 +76,23 @@ Object.defineProperty(exports, "openSqliteResilient", {
 });
 Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.JsonlParseError; }
+  get: function () { return chunkR5YPDAKD_cjs.JsonlParseError; }
 });
 Object.defineProperty(exports, "appendJsonl", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.appendJsonl; }
+  get: function () { return chunkR5YPDAKD_cjs.appendJsonl; }
 });
 Object.defineProperty(exports, "loadJsonl", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.loadJsonl; }
+  get: function () { return chunkR5YPDAKD_cjs.loadJsonl; }
 });
 Object.defineProperty(exports, "readJsonlIds", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.readJsonlIds; }
+  get: function () { return chunkR5YPDAKD_cjs.readJsonlIds; }
 });
 Object.defineProperty(exports, "withFileLock", {
   enumerable: true,
-  get: function () { return chunkOF2CLCTH_cjs.withFileLock; }
+  get: function () { return chunkASK2OQM5_cjs.withFileLock; }
 });
 Object.defineProperty(exports, "withCwdMutex", {
   enumerable: true,