@theokit/sdk 4.54.0 → 4.56.0

package/dist/{inject-session-DDR6X6PC.js → inject-session-BJMJH5BX.js}

@@ -1,4 +1,4 @@
-import { enqueueSessionWrite } from './chunk-DUIF54UP.js';
+import { enqueueSessionWrite } from './chunk-OHBIUXKM.js';
 import { invalidateSessionCache } from './chunk-WTMU7J4U.js';
 import './chunk-BMAZLQQ4.js';
 import { SessionTranscript } from './chunk-DZBSJX6J.js';
@@ -23,5 +23,5 @@ async function injectSessionTurn(opts) {
 }
 
 export { injectSessionTurn };
-//# sourceMappingURL=inject-session-DDR6X6PC.js.map
-//# sourceMappingURL=inject-session-DDR6X6PC.js.map
+//# sourceMappingURL=inject-session-BJMJH5BX.js.map
+//# sourceMappingURL=inject-session-BJMJH5BX.js.map

package/dist/{inject-session-DDR6X6PC.js.map → inject-session-BJMJH5BX.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-DDR6X6PC.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-BJMJH5BX.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-XLO3KTBM.cjs → inject-session-WQGGMCQY.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk5BJV5UPY_cjs = require('./chunk-5BJV5UPY.cjs');
+var chunkV2UUGUY4_cjs = require('./chunk-V2UUGUY4.cjs');
 var chunk4OTIXDMU_cjs = require('./chunk-4OTIXDMU.cjs');
 require('./chunk-CTCGWIUD.cjs');
 var chunkJHPGF3FP_cjs = require('./chunk-JHPGF3FP.cjs');
@@ -10,7 +10,7 @@ require('./chunk-NUKRL3I6.cjs');
 
 // src/internal/session/inject-session.ts
 async function injectSessionTurn(opts) {
-  await chunk5BJV5UPY_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
+  await chunkV2UUGUY4_cjs.enqueueSessionWrite(opts.loc.cwd, opts.loc.agentId, async () => {
     const prior = await opts.store.readRecords(opts.loc.agentId);
     const transcript = chunkJHPGF3FP_cjs.SessionTranscript.fromRecords(prior, {
       cwd: opts.loc.cwd,
@@ -25,5 +25,5 @@ async function injectSessionTurn(opts) {
 }
 
 exports.injectSessionTurn = injectSessionTurn;
-//# sourceMappingURL=inject-session-XLO3KTBM.cjs.map
-//# sourceMappingURL=inject-session-XLO3KTBM.cjs.map
+//# sourceMappingURL=inject-session-WQGGMCQY.cjs.map
+//# sourceMappingURL=inject-session-WQGGMCQY.cjs.map

package/dist/{inject-session-XLO3KTBM.cjs.map → inject-session-WQGGMCQY.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-XLO3KTBM.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-WQGGMCQY.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/llm/prompt-cache-key.d.ts

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

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

@@ -8,14 +8,80 @@ export interface ResponsesApiClientOptions {
     /** Injected fetch (refresh-aware / dynamic headers). Defaults to global `fetch`. */
     fetch?: typeof fetch;
     providerName?: string;
+    /**
+     * usetheokit/theokit-sdk#383 — carry the model's ENCRYPTED reasoning across the rounds of a turn.
+     * Forwarded from `ProviderProfile.encryptedReasoning`; default off. See
+     * {@link ResponsesBodyOptions.encryptedReasoning} for what it puts on the wire and why it is
+     * opt-in rather than universal.
+     */
+    encryptedReasoning?: boolean;
+}
+/**
+ * usetheokit/theokit-sdk#383 — one reasoning item the model produced, as it must be replayed.
+ *
+ * `encrypted_content` is opaque ciphertext only the provider can read; the SDK never inspects it,
+ * never logs it, and never persists it. It exists to be handed straight back.
+ */
+interface ResponsesReasoningItem {
+    id: string;
+    encrypted_content: string;
+}
+/** Options that shape the request body beyond what an `LlmRequest` carries. */
+export interface ResponsesBodyOptions {
+    /**
+     * usetheokit/theokit-sdk#383 — when `true`, add `include: ["reasoning.encrypted_content"]` and
+     * `reasoning.context: "all_turns"`, and replay the reasoning items captured from earlier rounds.
+     *
+     * **What it buys.** With `store: false` the provider keeps nothing between requests, so a model
+     * that reasoned its way to a tool call in round 1 starts round 2 with no memory of that reasoning
+     * and derives it again — paid for again, every round. `include` asks the provider to return the
+     * reasoning as ciphertext; replaying that ciphertext on the next request hands the chain of
+     * thought back. Codex does exactly this against the same endpoint (issue #383 captured the
+     * request), which is the evidence that the backend accepts both fields.
+     *
+     * **Why opt-in and not on for every `responses_api` provider.** `include` is a documented
+     * Responses-API field, but `reasoning.context` is not part of the public Responses API surface —
+     * it was observed on the ChatGPT Codex backend. A provider that validates its input strictly
+     * answers an unknown key with `400`, which turns a cost optimisation into a total outage for that
+     * provider. Scoping it to profiles that DECLARE support keeps every other provider's request
+     * byte-identical to what it was, and makes enabling it a statement someone made about a specific
+     * backend rather than a hope about all of them.
+     */
+    encryptedReasoning?: boolean;
+    /**
+     * usetheokit/theokit-sdk#383 — reasoning items captured from earlier rounds, keyed by the
+     * `call_id` of the tool call each batch preceded.
+     *
+     * Keying on `call_id` is what keeps the replay ORDERED and self-correcting. The provider requires
+     * a reasoning item to sit immediately before the output it produced, and the conversation history
+     * the loop replays is the authority on which tool calls survived and in what order — so emitting
+     * each batch just before its own `function_call` reproduces the original sequence without the
+     * transport having to track conversation positions. A batch whose tool call is no longer in
+     * history is simply never emitted.
+     */
+    reasoningByCallId?: ReadonlyMap<string, readonly ResponsesReasoningItem[]>;
 }
 /** Build the Responses-API request body from an `LlmRequest`. */
-export declare function buildResponsesBody(request: LlmRequest): Record<string, unknown>;
+export declare function buildResponsesBody(request: LlmRequest, options?: ResponsesBodyOptions): Record<string, unknown>;
 export declare class ResponsesApiClient implements LlmClient {
     private readonly options;
     readonly name: string;
     private readonly baseUrl;
     private readonly fetchImpl;
+    /**
+     * usetheokit/theokit-sdk#383 — reasoning ciphertext captured from earlier rounds, keyed by the
+     * `call_id` it preceded. Held on the CLIENT rather than threaded through `LlmRequest` because a
+     * round's reasoning is provider-shaped ciphertext with a provider-shaped ordering rule; the agent
+     * loop has no use for it and the same client instance serves every round of a turn. Insertion
+     * order is the eviction order (see {@link MAX_REMEMBERED_REASONING_CALLS}).
+     */
+    private readonly reasoningByCallId;
     constructor(options: ResponsesApiClientOptions);
+    /**
+     * usetheokit/theokit-sdk#383 — bind a batch of reasoning ciphertext to the tool call it produced,
+     * evicting the oldest binding once the cap is reached.
+     */
+    private rememberReasoning;
     stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
 }
+export {};

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

@@ -149,6 +149,21 @@ export interface LlmRequest {
      * is still forced to produce a closing summary.
      */
     toolChoice?: "auto" | "none" | "required";
+    /**
+     * usetheokit/theokit-sdk#383 — an opaque key identifying the conversation whose prompt prefix the
+     * provider may reuse across requests. Maps to the Responses-API `prompt_cache_key`.
+     *
+     * Set by the agent loop from the run's session identity and derived through
+     * `derivePromptCacheKey`, so it is STABLE across every round of a turn and every turn of a
+     * session, and DISTINCT between unrelated sessions. Both halves matter: a key that changes per
+     * round caches nothing, and a key shared across sessions asks the provider to match one
+     * conversation's prefix against another's.
+     *
+     * Absent ⇒ the field is omitted from the wire body (the pre-#383 request, byte for byte). It is
+     * a request-shaping hint only: no provider behaviour depends on its presence except the billing
+     * of the cached prefix.
+     */
+    promptCacheKey?: string;
 }
 /**
  * What a provider stream reports WHILE it is running. Tool calls are deliberately absent.

package/dist/internal/local-agent/real-local-run-tools.d.ts

@@ -10,18 +10,29 @@
  *
  * @internal
  */
-import type { AgentDefinition, AgentOptions, CustomTool, ModelSelection } from "../../types/agent.js";
+import type { AgentDefinition, AgentOptions, BuiltinToolName, CustomTool, ModelSelection } from "../../types/agent.js";
 import type { CustomToolSpec } from "../agent-loop/loop-types.js";
 /**
- * Resolve the effective custom-tool catalog for this run.
+ * Resolve the tool-catalog slice of `AgentLoopInputs` for this run: which custom tools the loop
+ * declares, and which SDK builtins it must NOT.
  *
- * Precedence (matches the mcpServers semantics — "fully replaces, not merged"):
+ * Precedence for the custom half (matches the mcpServers semantics — "fully replaces, not merged"):
  *  - `sendOptions.tools === undefined` → fall back to `agentOptions.tools`
  *  - `sendOptions.tools = []`         → explicitly clear (no custom tools)
  *  - `sendOptions.tools = [t1, ...]`  → use exactly these for this run
+ *
+ * usetheokit/theokit-sdk#381 added the builtin half, and it is why this is no longer named for
+ * custom tools alone. It rides here rather than at the call site because the withhold list is
+ * part of the same answer — what this run declares to the model — and because a run that
+ * withholds nothing must produce the same `AgentLoopInputs` it produced before the option existed,
+ * which is easiest to guarantee where the rest of the catalog is already assembled.
+ *
+ * Note the two halves are independent: an agent with no custom tools at all can still withhold a
+ * builtin, so the "no tools" early return carries the withhold list out with it.
  */
-export declare function buildCustomToolsInput(agentOptions: AgentOptions, sendOptions: {
+export declare function buildRunToolCatalogInput(agentOptions: AgentOptions, sendOptions: {
     tools?: CustomTool[];
 } | undefined, pluginManager: import("../plugins/manager.js").PluginManager | undefined, personalityToolWhitelist: ReadonlyArray<string> | undefined, agentId: string, personalityName: string | undefined, subagents: Record<string, AgentDefinition> | undefined, effectiveModel: ModelSelection | undefined): {
-    customTools: ReadonlyArray<CustomToolSpec>;
-} | Record<string, never>;
+    customTools?: ReadonlyArray<CustomToolSpec>;
+    withheldBuiltinTools?: ReadonlyArray<BuiltinToolName>;
+};

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

@@ -2,9 +2,21 @@ import { type MemoryConfig, type MemoryFact } from "../types.js";
 export declare function memoryDir(cwd: string): string;
 export declare function memoryMdPath(cwd: string): string;
 export declare function notesDir(cwd: string): string;
-/** Read facts from `MEMORY.md`'s `## Facts` section. Returns `[]` when missing. */
+/**
+ * Every memory in the store: the per-memory files, plus any legacy `## Facts` bullets still in
+ * `MEMORY.md`. Returns `[]` when the directory does not exist.
+ *
+ * Reading both is not transitional politeness. Those bullets are already on disk in consumers'
+ * repositories, and the store's own header invites editing them by hand — a converged writer that
+ * stopped reading them would delete what someone recorded, which is worse than the format it fixes.
+ */
 export declare function readFactsFromMarkdown(cwd: string): Promise<MemoryFact[]>;
-/** Append a fact to `MEMORY.md ## Facts`. Creates the section if missing. Atomic + serialized. */
+/**
+ * Write a fact as its own memory file and point the `MEMORY.md` index at it. Atomic + serialized.
+ *
+ * `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): Promise<void>;
 /** Configuration-aware accessors honoring the existing MemoryConfig contract. */
 export declare function readFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;

package/dist/internal/memory/storage/memory-file.d.ts

@@ -0,0 +1,54 @@
+/**
+ * One memory as a file, in the shape the Claude Code CLI reads.
+ *
+ * `@theokit/sdk` already writes native Claude Code `.jsonl` sessions — the README's differentiator
+ * is "point `local.sessionDir` at `~/.claude` and the Claude Code CLI can `--continue` a session
+ * your agent wrote". Memory had no such convergence: a fact was a bullet under `## Facts` with its
+ * kind in an HTML comment (#389), which that CLI reads as prose. Pointing a memory directory at
+ * `~/.claude/projects/<project>/memory/` produced nothing it could open.
+ *
+ * The contract here was measured against a real store rather than inferred from documentation. Of
+ * nine files, all nine carry `name`, `description` and `metadata.type`; six also carry
+ * `node_type`, `originSessionId` and `modified`, which the runtime stamps on write. So the minimum
+ * a reader must accept is the first three — refusing the rest would refuse memories the CLI itself
+ * accepts.
+ *
+ * `originSessionId` is deliberately not written. It identifies the session that learned the fact,
+ * and the append path has no session in scope; inventing one would be worse than omitting a field
+ * the format already treats as optional.
+ *
+ * @internal
+ */
+import { type MemoryKind } from "../types.js";
+/** The fields one memory file carries. */
+export interface MemoryFileFields {
+    /** Slug, and the file's basename. */
+    readonly name: string;
+    /** One-line summary — what the index shows and what recall ranks. */
+    readonly description: string;
+    /** `metadata.type`, absent when the file does not declare one this contract admits. */
+    readonly kind?: MemoryKind;
+    /** `metadata.modified`, an ISO 8601 instant stamped by whoever wrote the file. */
+    readonly modified?: string;
+    /** The markdown after the frontmatter. */
+    readonly body: string;
+}
+/**
+ * A readable, filesystem-safe slug for `text`.
+ *
+ * Readability is the goal — a directory of `h-3f2a…` files is a directory nobody browses — but it
+ * is not the floor. The text comes from whatever a caller learned, so anything that fails the safe
+ * grammar falls back to {@link safeFilenameForId}, which is total and always yields a valid
+ * component.
+ */
+export declare function slugForFact(text: string): string;
+/** Render one memory file. `description` is quoted so a colon in the text cannot break the block. */
+export declare function renderMemoryFile(fields: MemoryFileFields): string;
+/**
+ * Read one memory file, or `undefined` when the content is not one.
+ *
+ * `undefined` rather than a throw, and rather than a best-effort object: the directory holds
+ * hand-written notes and a `MEMORY.md` index alongside the memories, and turning any of those into
+ * a fact would put text into recall that nobody recorded as one.
+ */
+export declare function parseMemoryFile(raw: string): MemoryFileFields | undefined;

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

@@ -5,8 +5,36 @@ export interface MemoryConfig {
     scope?: "agent" | "user" | "team";
     storePath?: string;
 }
+/**
+ * What a fact IS, which is what decides whether it ages (#389).
+ *
+ * The four are the distinctions that matter for retention and recall: a preference stays true until
+ * the user changes their mind, a project fact goes stale when the code moves, a reference either
+ * resolves or 404s, and feedback records a correction that was given. Without them, recall ranks one
+ * undifferentiated corpus and pruning has no basis to prefer a durable fact over a transient one.
+ *
+ * A kind is never INFERRED. A wrong kind is worse than none, because it makes retention and recall
+ * confident about the wrong thing — so a fact whose author did not say stays untyped.
+ */
+export type MemoryKind = "user" | "feedback" | "project" | "reference";
+/** The four values {@link MemoryKind} admits, for runtime validation at the storage boundary. */
+export declare const MEMORY_KINDS: readonly MemoryKind[];
 export interface MemoryFact {
     text: string;
+    /**
+     * What this fact is (#389). Absent means untyped, which is what a hand-written bullet under
+     * `## Facts` stays — those files are already on disk in consumers' repositories and the store's
+     * own header invites editing them.
+     */
+    kind?: MemoryKind;
+    /**
+     * ISO 8601 instant this fact was last written, stamped BY THE SDK.
+     *
+     * Supplying it does nothing: a timestamp a caller can set is a timestamp that can lie about when
+     * something was learned, and the whole point is to weigh a note from this morning against one
+     * from four months ago. Absent on a fact written before this existed, or hand-added.
+     */
+    modified?: string;
 }
 export { redactSecrets } from "../security/index.js";
 /**

package/dist/models.cjs

@@ -2,7 +2,7 @@
 
 var chunkHY57ULY2_cjs = require('./chunk-HY57ULY2.cjs');
 var chunk3EE6LVWT_cjs = require('./chunk-3EE6LVWT.cjs');
-var chunkRM7Y65IG_cjs = require('./chunk-RM7Y65IG.cjs');
+var chunkNIRE5CNO_cjs = require('./chunk-NIRE5CNO.cjs');
 require('./chunk-5USCYPPI.cjs');
 require('./chunk-BVZW2B5V.cjs');
 require('./chunk-52NKC5HT.cjs');
@@ -36,11 +36,11 @@ function capsFromCatalog(m) {
 }
 function resolveModelCapabilities(modelId) {
   const bare = stripVariantSuffix(stripRoutingPrefix(modelId));
-  const fromIndex = chunkRM7Y65IG_cjs.getCatalogModelInfo(bare);
+  const fromIndex = chunkNIRE5CNO_cjs.getCatalogModelInfo(bare);
   if (fromIndex !== void 0) return capsFromCatalog(fromIndex);
   const withVendor = inferVendorPrefix(bare);
   if (withVendor !== bare) {
-    const vendored = chunkRM7Y65IG_cjs.getCatalogModelInfo(withVendor);
+    const vendored = chunkNIRE5CNO_cjs.getCatalogModelInfo(withVendor);
     if (vendored !== void 0) return capsFromCatalog(vendored);
   }
   return CONSERVATIVE_DEFAULTS;
@@ -132,7 +132,7 @@ function catalogTargets() {
   if (_catalogTargets !== void 0) return _catalogTargets;
   _catalogTargets = /* @__PURE__ */ new Map();
   try {
-    for (const entry of Object.values(chunkRM7Y65IG_cjs.loadProviderCatalog())) {
+    for (const entry of Object.values(chunkNIRE5CNO_cjs.loadProviderCatalog())) {
       const keys = [entry.id, ...entry.aliases ?? []];
       for (const k of keys) {
         if (!_catalogTargets.has(k)) _catalogTargets.set(k, { keys });
@@ -146,7 +146,7 @@ function resolvePatchKeys(externalId) {
   const mapped = MODELS_DEV_ID_MAP[externalId] ?? externalId;
   const fromCatalog = catalogTargets().get(mapped);
   if (fromCatalog !== void 0) return fromCatalog.keys;
-  const profile = chunkRM7Y65IG_cjs.getProviderProfile(mapped);
+  const profile = chunkNIRE5CNO_cjs.getProviderProfile(mapped);
   if (profile !== void 0) return [profile.name, ...profile.aliases ?? []];
   return void 0;
 }
@@ -163,9 +163,9 @@ function patchIndexFromApiJson(raw) {
       continue;
     }
     for (const [modelId, rawModel] of Object.entries(models)) {
-      const parsed = chunkRM7Y65IG_cjs.catalogModelSchema.safeParse(rawModel);
+      const parsed = chunkNIRE5CNO_cjs.catalogModelSchema.safeParse(rawModel);
       if (!parsed.success) continue;
-      for (const key of keys) chunkRM7Y65IG_cjs.patchModelInfo(`${key}/${modelId}`, parsed.data);
+      for (const key of keys) chunkNIRE5CNO_cjs.patchModelInfo(`${key}/${modelId}`, parsed.data);
       patched++;
     }
   }
@@ -206,7 +206,7 @@ function loadCacheIntoIndex(url = DEFAULT_URL) {
   }
 }
 async function refreshModelCatalog(opts = {}) {
-  chunkRM7Y65IG_cjs.registerBuiltins();
+  chunkNIRE5CNO_cjs.registerBuiltins();
   const kill = process.env.THEOKIT_DISABLE_MODELS_FETCH;
   if (kill !== void 0 && kill !== "" && kill !== "0" && kill.toLowerCase() !== "false") {
     return { source: "skipped", models: 0 };
@@ -269,7 +269,7 @@ async function refreshModelCatalog(opts = {}) {
   }
 }
 function getModelInfo(modelId) {
-  return chunkRM7Y65IG_cjs.getCatalogModelInfo(modelId);
+  return chunkNIRE5CNO_cjs.getCatalogModelInfo(modelId);
 }
 
 Object.defineProperty(exports, "parseModelId", {

package/dist/models.js

@@ -1,7 +1,7 @@
 import { Retry } from './chunk-NLTVXLGT.js';
 import { parseModelId } from './chunk-R7WIIPUR.js';
 export { parseModelId } from './chunk-R7WIIPUR.js';
-import { getCatalogModelInfo, registerBuiltins, catalogModelSchema, patchModelInfo, getProviderProfile, loadProviderCatalog } from './chunk-FXEUP75G.js';
+import { getCatalogModelInfo, registerBuiltins, catalogModelSchema, patchModelInfo, getProviderProfile, loadProviderCatalog } from './chunk-Q4CMI2LP.js';
 import './chunk-44MBDIHG.js';
 import './chunk-UQGQFBRL.js';
 import './chunk-3OR54XG4.js';

package/dist/providers.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk3KGLRRFC_cjs = require('./chunk-3KGLRRFC.cjs');
-require('./chunk-RM7Y65IG.cjs');
+var chunk6HTXPPHK_cjs = require('./chunk-6HTXPPHK.cjs');
+require('./chunk-NIRE5CNO.cjs');
 require('./chunk-5USCYPPI.cjs');
 require('./chunk-BVZW2B5V.cjs');
 require('./chunk-52NKC5HT.cjs');
@@ -13,11 +13,11 @@ require('./chunk-NUKRL3I6.cjs');
 
 Object.defineProperty(exports, "getProviderProfile", {
   enumerable: true,
-  get: function () { return chunk3KGLRRFC_cjs.getProviderProfile; }
+  get: function () { return chunk6HTXPPHK_cjs.getProviderProfile; }
 });
 Object.defineProperty(exports, "listProviders", {
   enumerable: true,
-  get: function () { return chunk3KGLRRFC_cjs.listProviders; }
+  get: function () { return chunk6HTXPPHK_cjs.listProviders; }
 });
 //# sourceMappingURL=providers.cjs.map
 //# sourceMappingURL=providers.cjs.map

package/dist/providers.js

@@ -1,5 +1,5 @@
-export { getProviderProfile, listProviders } from './chunk-SSQZA3DZ.js';
-import './chunk-FXEUP75G.js';
+export { getProviderProfile, listProviders } from './chunk-2BDH744Z.js';
+import './chunk-Q4CMI2LP.js';
 import './chunk-44MBDIHG.js';
 import './chunk-UQGQFBRL.js';
 import './chunk-3OR54XG4.js';

package/dist/sandbox/index.cjs

@@ -154,7 +154,7 @@ var RET_EPERM = SECCOMP_RET_ERRNO | EPERM & 65535;
 var SECCOMP_RET_KILL_PROCESS = 2147483648;
 var AF_UNIX = 1;
 var ALWAYS_DENIED = [101, 310, 311, 425, 426, 427];
-var NETWORK_DENIED = [42, 43, 288, 49, 50, 52, 51, 48, 44, 307, 299, 55, 54];
+var NETWORK_DENIED = [42, 43, 288, 49, 50, 48, 44, 307, 299];
 var SOCKET_SYSCALLS = [41, 53];
 var stmt = (code, k) => ({ code, jt: 0, jf: 0, k });
 var jmp = (code, k, jt, jf) => ({ code, jt, jf, k });