@theokit/sdk 4.22.0 → 4.24.0

package/dist/eval.js

@@ -1594,6 +1594,44 @@ var init_plugin_guards = __esm({
   }
 });
 
+// src/compaction.ts
+function resolveEffectiveContextWindow(input) {
+  if (!(input.margin > 0) || input.margin > 1) {
+    throw new ContextWindowMarginError(input.margin);
+  }
+  const withMargin = (raw) => Math.floor(raw * input.margin);
+  if (input.override !== void 0) {
+    const clamped = input.catalog !== void 0 && input.override > input.catalog;
+    const raw = clamped ? input.catalog : input.override;
+    return { window: withMargin(raw), source: "override", clamped };
+  }
+  if (input.catalog !== void 0) {
+    return { window: withMargin(input.catalog), source: "catalog", clamped: false };
+  }
+  return { window: withMargin(input.floor ?? 0), source: "fallback", clamped: false };
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+var ContextWindowMarginError, CONTEXT_WINDOW_MARGIN, CONTEXT_WINDOW_FLOOR;
+var init_compaction = __esm({
+  "src/compaction.ts"() {
+    init_errors();
+    ContextWindowMarginError = class extends TheokitAgentError {
+      constructor(margin) {
+        super(
+          `context-window margin must be in (0, 1], got ${String(margin)}. A margin above 1 grows the assumed window and delays compaction past the real limit.`,
+          { code: "invalid_context_window_margin" }
+        );
+        this.margin = margin;
+      }
+      margin;
+    };
+    CONTEXT_WINDOW_MARGIN = 0.95;
+    CONTEXT_WINDOW_FLOOR = 128e3;
+  }
+});
+
 // src/types/run-events.ts
 function emitRunEvent(sink, event) {
   if (sink === void 0) return;
@@ -1606,6 +1644,18 @@ var init_run_events = __esm({
   "src/types/run-events.ts"() {
   }
 });
+
+// src/internal/global-singleton.ts
+function globalSingleton(key, create) {
+  const g = globalThis;
+  const sym = Symbol.for(key);
+  if (g[sym] === void 0) g[sym] = create();
+  return g[sym];
+}
+var init_global_singleton = __esm({
+  "src/internal/global-singleton.ts"() {
+  }
+});
 var MODALITIES, costSchema, limitSchema, modalitiesSchema, catalogModelSchema;
 var init_catalog_schema = __esm({
   "src/internal/providers/catalog-schema.ts"() {
@@ -1646,12 +1696,6 @@ var init_catalog_schema = __esm({
 });
 
 // src/internal/providers/registry.ts
-function globalSingleton(key, create) {
-  const g = globalThis;
-  const sym = Symbol.for(key);
-  if (g[sym] === void 0) g[sym] = create();
-  return g[sym];
-}
 function registerProvider(profile) {
   if (REGISTRY.has(profile.name)) {
     process.stderr.write(`[theokit-sdk] Provider "${profile.name}" overridden by user plugin.
@@ -1676,6 +1720,7 @@ function getProviderProfile(name) {
 var REGISTRY, ALIASES;
 var init_registry = __esm({
   "src/internal/providers/registry.ts"() {
+    init_global_singleton();
     REGISTRY = globalSingleton(
       "theokit-sdk.providers.registry",
       () => /* @__PURE__ */ new Map()
@@ -1683,12 +1728,6 @@ var init_registry = __esm({
     ALIASES = globalSingleton("theokit-sdk.providers.aliases", () => /* @__PURE__ */ new Map());
   }
 });
-function globalSingleton2(key, create) {
-  const g = globalThis;
-  const sym = Symbol.for(key);
-  if (g[sym] === void 0) g[sym] = create();
-  return g[sym];
-}
 function getCatalogModelInfo(key) {
   ensureModelIndexLoaded();
   return modelInfoIndex.get(key);
@@ -1777,32 +1816,24 @@ function registerCatalogProviders(opts) {
 var __dirname_resolved, modelInfoIndex, patchedModelKeys, indexState;
 var init_catalog_loader = __esm({
   "src/internal/providers/catalog-loader.ts"() {
+    init_global_singleton();
     init_catalog_schema();
     init_registry();
     __dirname_resolved = dirname(fileURLToPath(import.meta.url));
-    modelInfoIndex = globalSingleton2(
+    modelInfoIndex = globalSingleton(
       "theokit-sdk.providers.model-info-index",
       () => /* @__PURE__ */ new Map()
     );
-    patchedModelKeys = globalSingleton2(
+    patchedModelKeys = globalSingleton(
       "theokit-sdk.providers.model-info-patched",
       () => /* @__PURE__ */ new Set()
     );
-    indexState = globalSingleton2("theokit-sdk.providers.model-info-loaded", () => ({
+    indexState = globalSingleton("theokit-sdk.providers.model-info-loaded", () => ({
       loaded: false
     }));
   }
 });
 
-// src/compaction.ts
-function estimateTokens(text) {
-  return Math.ceil(text.length / 4);
-}
-var init_compaction = __esm({
-  "src/compaction.ts"() {
-  }
-});
-
 // src/internal/providers/builtin/anthropic.ts
 var ANTHROPIC;
 var init_anthropic = __esm({
@@ -2172,11 +2203,12 @@ function writeCredential(cred, config, env = {}) {
 var CredentialError, apiFileSchema, oauthFileSchema, fileSchema;
 var init_credential_store = __esm({
   "src/internal/auth/credential-store.ts"() {
-    CredentialError = class extends Error {
-      constructor(message) {
-        super(message);
-        this.name = "CredentialError";
-      }
+    init_errors();
+    CredentialError = class extends AuthenticationError {
+      // Field, not an assignment in the constructor: `AuthenticationError.name` is `override readonly`
+      // (`errors.ts:174`), so `this.name = …` does not compile. Caught by `tsc`, not by vitest — the
+      // suite was green with the broken assignment because the transpiler strips the type.
+      name = "CredentialError";
     };
     apiFileSchema = z.object({
       type: z.literal("api").optional(),
@@ -2598,12 +2630,6 @@ var init_builtin = __esm({
     })();
   }
 });
-function globalSingleton3(key, create) {
-  const g = globalThis;
-  const sym = Symbol.for(key);
-  if (g[sym] === void 0) g[sym] = create();
-  return g[sym];
-}
 function pluginsRoot() {
   return join(homedir(), ".theokit", "plugins", "model-providers");
 }
@@ -2695,8 +2721,9 @@ async function loadOne(dir, entryName) {
 var discoveryState;
 var init_discovery = __esm({
   "src/internal/providers/discovery.ts"() {
+    init_global_singleton();
     init_registry();
-    discoveryState = globalSingleton3("theokit-sdk.providers.discovered", () => ({
+    discoveryState = globalSingleton("theokit-sdk.providers.discovered", () => ({
       done: false
     }));
   }
@@ -4372,6 +4399,68 @@ var init_hermes_tool_extract = __esm({
   }
 });
 
+// src/internal/llm/openai-messages.ts
+function toOpenAIMessages(message) {
+  if (message.role === "system") return [systemMessage(message)];
+  if (message.role === "user") return userOrToolMessages(message);
+  return [assistantMessage(message)];
+}
+function systemMessage(message) {
+  return { role: "system", content: joinTextParts2(message) };
+}
+function joinTextParts2(message) {
+  return message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+}
+function userOrToolMessages(message) {
+  const out = [];
+  for (const part of message.content) {
+    if (part.type === "tool_result") {
+      out.push({
+        role: "tool",
+        tool_call_id: part.toolUseId,
+        // SE7 — this wire's tool role is string-only: text blocks flatten; an
+        // image block fails fast (ConfigurationError).
+        content: toStringToolResultContent(part.content, "openai")
+      });
+    }
+  }
+  const userText = joinTextParts2(message);
+  const imageParts = message.content.filter(
+    (p) => p.type === "image"
+  );
+  if (imageParts.length > 0) {
+    const content = [];
+    if (userText.length > 0) content.push({ type: "text", text: userText });
+    for (const img of imageParts) {
+      const url = img.source.type === "base64" ? `data:${img.source.media_type};base64,${img.source.data}` : img.source.url;
+      content.push({ type: "image_url", image_url: { url } });
+    }
+    out.push({ role: "user", content });
+  } else if (userText.length > 0) {
+    out.push({ role: "user", content: userText });
+  }
+  return out;
+}
+function assistantMessage(message) {
+  const text = joinTextParts2(message);
+  const toolCalls = message.content.filter((part) => part.type === "tool_use").map((part) => {
+    const tc = part;
+    return {
+      id: tc.id,
+      type: "function",
+      function: { name: tc.name, arguments: JSON.stringify(tc.input) }
+    };
+  });
+  const result = { role: "assistant", content: text };
+  if (toolCalls.length > 0) result.tool_calls = toolCalls;
+  return result;
+}
+var init_openai_messages = __esm({
+  "src/internal/llm/openai-messages.ts"() {
+    init_tool_result_content();
+  }
+});
+
 // src/internal/llm/openai.ts
 function deriveChatPath(baseUrl) {
   try {
@@ -4433,61 +4522,6 @@ function encodeOpenAIResponseFormat(rf) {
     }
   };
 }
-function toOpenAIMessages(message) {
-  if (message.role === "system") return [systemMessage(message)];
-  if (message.role === "user") return userOrToolMessages(message);
-  return [assistantMessage(message)];
-}
-function systemMessage(message) {
-  return { role: "system", content: joinTextParts2(message) };
-}
-function joinTextParts2(message) {
-  return message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
-}
-function userOrToolMessages(message) {
-  const out = [];
-  for (const part of message.content) {
-    if (part.type === "tool_result") {
-      out.push({
-        role: "tool",
-        tool_call_id: part.toolUseId,
-        // SE7 — this wire's tool role is string-only: text blocks flatten; an
-        // image block fails fast (ConfigurationError).
-        content: toStringToolResultContent(part.content, "openai")
-      });
-    }
-  }
-  const userText = joinTextParts2(message);
-  const imageParts = message.content.filter(
-    (p) => p.type === "image"
-  );
-  if (imageParts.length > 0) {
-    const content = [];
-    if (userText.length > 0) content.push({ type: "text", text: userText });
-    for (const img of imageParts) {
-      const url = img.source.type === "base64" ? `data:${img.source.media_type};base64,${img.source.data}` : img.source.url;
-      content.push({ type: "image_url", image_url: { url } });
-    }
-    out.push({ role: "user", content });
-  } else if (userText.length > 0) {
-    out.push({ role: "user", content: userText });
-  }
-  return out;
-}
-function assistantMessage(message) {
-  const text = joinTextParts2(message);
-  const toolCalls = message.content.filter((part) => part.type === "tool_use").map((part) => {
-    const tc = part;
-    return {
-      id: tc.id,
-      type: "function",
-      function: { name: tc.name, arguments: JSON.stringify(tc.input) }
-    };
-  });
-  const result = { role: "assistant", content: text };
-  if (toolCalls.length > 0) result.tool_calls = toolCalls;
-  return result;
-}
 var OpenAIClient, OpenAIStreamAccumulator, openAISystemText;
 var init_openai2 = __esm({
   "src/internal/llm/openai.ts"() {
@@ -4496,8 +4530,8 @@ var init_openai2 = __esm({
     init_openai_compatible2();
     init_finish();
     init_hermes_tool_extract();
+    init_openai_messages();
     init_sse();
-    init_tool_result_content();
     OpenAIClient = class {
       constructor(options) {
         this.options = options;
@@ -5586,6 +5620,14 @@ function selectTransport(profile, apiKey) {
     const ctx = { apiKey };
     return { fetch: profile.transform.fetch?.(ctx), headers: profile.transform.headers?.(ctx) };
   };
+  const comTransform = (opts, criar) => {
+    const t = applyTransform();
+    assertOAuthResolved(t);
+    if (t.fetch !== void 0) opts.fetch = t.fetch;
+    const merged = profile.extraHeaders !== void 0 || t.headers !== void 0 ? { ...profile.extraHeaders, ...t.headers } : void 0;
+    if (merged !== void 0) opts.extraHeaders = merged;
+    return criar(opts);
+  };
   const assertOAuthResolved = (t) => {
     if (apiKey !== "__oauth_lazy_token__") return;
     const auth = t.headers?.authorization ?? t.headers?.Authorization;
@@ -5614,12 +5656,7 @@ function selectTransport(profile, apiKey) {
     }
     const envOverride = resolveBaseUrlEnvOverride(profile.name);
     if (envOverride !== void 0) opts.baseUrl = envOverride;
-    const t = applyTransform();
-    assertOAuthResolved(t);
-    if (t.fetch !== void 0) opts.fetch = t.fetch;
-    const merged = profile.extraHeaders !== void 0 || t.headers !== void 0 ? { ...profile.extraHeaders, ...t.headers } : void 0;
-    if (merged !== void 0) opts.extraHeaders = merged;
-    return new OpenAIClient(opts);
+    return comTransform(opts, (o) => new OpenAIClient(o));
   }
   if (profile.apiMode === "anthropic_messages") {
     if (profile.name === "vertex") {
@@ -5628,12 +5665,7 @@ function selectTransport(profile, apiKey) {
     }
     const opts = { apiKey };
     opts.baseUrl = process.env.ANTHROPIC_API_BASE_URL ?? profile.baseUrl;
-    const t = applyTransform();
-    assertOAuthResolved(t);
-    if (t.fetch !== void 0) opts.fetch = t.fetch;
-    const merged = profile.extraHeaders !== void 0 || t.headers !== void 0 ? { ...profile.extraHeaders, ...t.headers } : void 0;
-    if (merged !== void 0) opts.extraHeaders = merged;
-    return new AnthropicClient(opts);
+    return comTransform(opts, (o) => new AnthropicClient(o));
   }
   if (profile.apiMode === "bedrock_anthropic") {
     const realKey = apiKey === "__bedrock_lazy_token__" ? void 0 : apiKey;
@@ -5790,202 +5822,52 @@ function buildCompressionPrompt(messages) {
 
 --- CONVERSATION TO SUMMARIZE ---
 ${formatted}
---- END ---`;
-}
-async function compressConversationWindow(opts) {
-  const userPrompt = buildCompressionPrompt(opts.messages);
-  let summary;
-  try {
-    summary = await opts.callLlm(opts.model, COMPRESSION_SYSTEM, userPrompt);
-  } catch (cause) {
-    throw new CompressionFailedError(
-      `Compression LLM call failed: ${cause instanceof Error ? cause.message : String(cause)}`,
-      { cause: cause instanceof Error ? cause : void 0 }
-    );
-  }
-  if (!summary || summary.trim().length === 0) {
-    throw new CompressionFailedError(
-      "Compression LLM returned empty summary \u2014 reduction ineffective."
-    );
-  }
-  return {
-    role: "system",
-    content: `[Compressed conversation summary]: ${summary.trim()}`
-  };
-}
-var CompressionFailedError, COMPRESSION_SYSTEM;
-var init_compression_summarizer = __esm({
-  "src/internal/runtime/compression/compression-summarizer.ts"() {
-    CompressionFailedError = class extends Error {
-      name = "CompressionFailedError";
-    };
-    COMPRESSION_SYSTEM = "You are a conversation summarizer. Produce a concise factual summary. Preserve all decisions, preferences, code snippets, and action items. Do not add commentary or opinions. Output ONLY the summary text.";
-  }
-});
-
-// src/internal/session/agent-session-store.ts
-function seedTranscript(prior, opts) {
-  return SessionTranscript.fromRecords(prior, opts);
-}
-function mapAgentTurn(steps) {
-  const assistant = {};
-  const toolResults = [];
-  const toolCalls = [];
-  for (const step of steps) {
-    if (step.type === "thinkingMessage") assistant.thinking = step.message.text;
-    else if (step.type === "assistantMessage") assistant.text = step.message.text;
-    else if (step.type === "toolCall")
-      toolCalls.push({
-        id: step.message.callId,
-        name: step.message.name,
-        input: step.message.args ?? {}
-      });
-    else
-      toolResults.push({
-        toolUseId: step.message.callId,
-        content: step.message.result,
-        isError: step.message.isError
-      });
-  }
-  if (toolCalls.length > 0) assistant.toolCalls = toolCalls;
-  return { assistant, toolResults };
-}
-function hasAssistantContent(a) {
-  return a.text !== void 0 || a.thinking !== void 0 || (a.toolCalls?.length ?? 0) > 0;
-}
-function appendConversation(transcript, conversation) {
-  for (const ct of conversation) {
-    if (ct.type !== "agentConversationTurn") continue;
-    const { assistant, toolResults } = mapAgentTurn(ct.turn.steps);
-    if (hasAssistantContent(assistant)) transcript.appendAssistantTurn(assistant);
-    if (toolResults.length > 0) transcript.appendToolResults(toolResults);
-  }
-}
-async function readSessionMessages(store, agentId) {
-  const records = await store.readRecords(agentId);
-  return reconstructMessages(records).map(narrowToSessionMessage);
-}
-function partToText(p) {
-  if (p.type === "text") return p.text ?? "";
-  if (p.type === "tool_use") return `[tool call] ${p.name ?? ""}`;
-  if (p.type === "tool_result") {
-    const body = typeof p.content === "string" ? p.content : JSON.stringify(p.content);
-    return `[tool result] ${body}`;
-  }
-  return "";
-}
-function narrowToSessionMessage(m) {
-  const role = m.role === "user" ? "user" : "assistant";
-  const text = m.content.map(partToText).filter((s) => s.length > 0).join("\n");
-  return { role, text };
-}
-function deltaRecords(transcript, priorLength) {
-  return transcript.records().slice(priorLength);
-}
-async function persistTurn(store, loc, sessionId, turn) {
-  const prior = await store.readRecords(loc.agentId);
-  const transcript = seedTranscript(prior, { cwd: loc.cwd, sessionId, model: loc.model });
-  transcript.appendUserTurn(turn.userText);
-  appendConversation(transcript, turn.conversation);
-  await store.appendRecords(loc.agentId, deltaRecords(transcript, prior.length));
-}
-var init_agent_session_store = __esm({
-  "src/internal/session/agent-session-store.ts"() {
-    init_session_transcript();
-  }
-});
-
-// src/internal/session/agent-session.ts
-function transcriptKey(cwd, agentId) {
-  return `${cwd}::${agentId}`;
-}
-function appendSessionMessage(agentId, message) {
-  const existing = sessions.get(agentId) ?? [];
-  existing.push(message);
-  sessions.set(agentId, existing);
-}
-function getSessionMessages(agentId) {
-  return sessions.get(agentId) ?? [];
-}
-function persistTurnToTranscript(store, loc, sessionId, turn, onCompact) {
-  const key = transcriptKey(loc.cwd, loc.agentId);
-  const chained = (pendingWrites.get(key) ?? Promise.resolve()).then(async () => {
-    try {
-      await persistTurn(store, loc, sessionId, turn);
-      const count = (recordCounts.get(key) ?? 0) + 1;
-      recordCounts.set(key, count);
-      if (turn.autoCompact !== void 0) {
-        const { autoCompactIfNeeded: autoCompactIfNeeded2 } = await Promise.resolve().then(() => (init_compact_session(), compact_session_exports));
-        const fired = await autoCompactIfNeeded2({
-          store,
-          loc,
-          sessionId,
-          usageTotal: turn.autoCompact.usageTotal,
-          contextWindow: turn.autoCompact.contextWindow,
-          turnCount: count,
-          summarize: turn.autoCompact.summarize
-        });
-        if (fired) onCompact?.();
-      }
-    } catch (cause) {
-      const msg = cause instanceof Error ? cause.message : String(cause);
-      process.stderr.write(
-        `[theokit-sdk] session transcript write failed (${loc.agentId}): ${msg}
-`
-      );
-    }
-  });
-  pendingWrites.set(
-    key,
-    chained.then(
-      () => void 0,
-      () => void 0
-    )
-  );
-}
-async function hydrateSession(agentId, loc) {
-  const key = transcriptKey(loc.cwd, agentId);
-  if (hydratedKeys.has(key)) return;
-  hydratedKeys.add(key);
-  const persisted = await readSessionMessages(loc.store, agentId);
-  if (persisted.length === 0) return;
-  sessions.set(agentId, persisted);
-}
-async function flushSessionWrites() {
-  while (pendingWrites.size > 0) {
-    const all = Array.from(pendingWrites.values());
-    pendingWrites.clear();
-    await Promise.all(all);
+--- END ---`;
+}
+async function compressConversationWindow(opts) {
+  const userPrompt = buildCompressionPrompt(opts.messages);
+  let summary;
+  try {
+    summary = await opts.callLlm(opts.model, COMPRESSION_SYSTEM, userPrompt);
+  } catch (cause) {
+    throw new CompressionFailedError(
+      `Compression LLM call failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause: cause instanceof Error ? cause : void 0 }
+    );
+  }
+  if (!summary || summary.trim().length === 0) {
+    throw new CompressionFailedError(
+      "Compression LLM returned empty summary \u2014 reduction ineffective."
+    );
   }
+  return {
+    role: "system",
+    content: `[Compressed conversation summary]: ${summary.trim()}`
+  };
 }
-function clearSession(agentId) {
-  sessions.delete(agentId);
+var CompressionFailedError, COMPRESSION_SYSTEM;
+var init_compression_summarizer = __esm({
+  "src/internal/runtime/compression/compression-summarizer.ts"() {
+    CompressionFailedError = class extends Error {
+      name = "CompressionFailedError";
+    };
+    COMPRESSION_SYSTEM = "You are a conversation summarizer. Produce a concise factual summary. Preserve all decisions, preferences, code snippets, and action items. Do not add commentary or opinions. Output ONLY the summary text.";
+  }
+});
+
+// src/internal/session/session-cache.ts
+function transcriptKey(cwd, agentId) {
+  return `${cwd}::${agentId}`;
 }
 function invalidateSessionCache(cwd, agentId) {
   sessions.delete(agentId);
   hydratedKeys.delete(transcriptKey(cwd, agentId));
 }
-function enqueueSessionWrite(cwd, agentId, fn) {
-  const key = transcriptKey(cwd, agentId);
-  const prior = pendingWrites.get(key) ?? Promise.resolve();
-  const result = prior.then(fn);
-  pendingWrites.set(
-    key,
-    result.then(
-      () => void 0,
-      () => void 0
-    )
-  );
-  return result;
-}
-var sessions, hydratedKeys, pendingWrites, recordCounts;
-var init_agent_session = __esm({
-  "src/internal/session/agent-session.ts"() {
-    init_agent_session_store();
+var sessions, hydratedKeys;
+var init_session_cache = __esm({
+  "src/internal/session/session-cache.ts"() {
     sessions = /* @__PURE__ */ new Map();
     hydratedKeys = /* @__PURE__ */ new Set();
-    pendingWrites = /* @__PURE__ */ new Map();
-    recordCounts = /* @__PURE__ */ new Map();
   }
 });
 
@@ -6147,7 +6029,7 @@ var init_compact_session = __esm({
     init_providers();
     init_compression_model_registry();
     init_compression_summarizer();
-    init_agent_session();
+    init_session_cache();
     COMPACT_SUMMARY_MARKER = "[[theokit:compact-summary]]";
     COMPACT_USER_MESSAGE_MAX_TOKENS = 2e4;
     autoCompactAttempts = (() => {
@@ -6158,6 +6040,165 @@ var init_compact_session = __esm({
     })();
   }
 });
+
+// src/internal/session/agent-session-store.ts
+function seedTranscript(prior, opts) {
+  return SessionTranscript.fromRecords(prior, opts);
+}
+function mapAgentTurn(steps) {
+  const assistant = {};
+  const toolResults = [];
+  const toolCalls = [];
+  for (const step of steps) {
+    if (step.type === "thinkingMessage") assistant.thinking = step.message.text;
+    else if (step.type === "assistantMessage") assistant.text = step.message.text;
+    else if (step.type === "toolCall")
+      toolCalls.push({
+        id: step.message.callId,
+        name: step.message.name,
+        input: step.message.args ?? {}
+      });
+    else
+      toolResults.push({
+        toolUseId: step.message.callId,
+        content: step.message.result,
+        isError: step.message.isError
+      });
+  }
+  if (toolCalls.length > 0) assistant.toolCalls = toolCalls;
+  return { assistant, toolResults };
+}
+function hasAssistantContent(a) {
+  return a.text !== void 0 || a.thinking !== void 0 || (a.toolCalls?.length ?? 0) > 0;
+}
+function appendConversation(transcript, conversation) {
+  for (const ct of conversation) {
+    if (ct.type !== "agentConversationTurn") continue;
+    const { assistant, toolResults } = mapAgentTurn(ct.turn.steps);
+    if (hasAssistantContent(assistant)) transcript.appendAssistantTurn(assistant);
+    if (toolResults.length > 0) transcript.appendToolResults(toolResults);
+  }
+}
+async function readSessionMessages(store, agentId) {
+  const records = await store.readRecords(agentId);
+  return reconstructMessages(records).map(narrowToSessionMessage);
+}
+function partToText(p) {
+  if (p.type === "text") return p.text ?? "";
+  if (p.type === "tool_use") return `[tool call] ${p.name ?? ""}`;
+  if (p.type === "tool_result") {
+    const body = typeof p.content === "string" ? p.content : JSON.stringify(p.content);
+    return `[tool result] ${body}`;
+  }
+  return "";
+}
+function narrowToSessionMessage(m) {
+  const role = m.role === "user" ? "user" : "assistant";
+  const text = m.content.map(partToText).filter((s) => s.length > 0).join("\n");
+  return { role, text };
+}
+function deltaRecords(transcript, priorLength) {
+  return transcript.records().slice(priorLength);
+}
+async function persistTurn(store, loc, sessionId, turn) {
+  const prior = await store.readRecords(loc.agentId);
+  const transcript = seedTranscript(prior, { cwd: loc.cwd, sessionId, model: loc.model });
+  transcript.appendUserTurn(turn.userText);
+  appendConversation(transcript, turn.conversation);
+  await store.appendRecords(loc.agentId, deltaRecords(transcript, prior.length));
+}
+var init_agent_session_store = __esm({
+  "src/internal/session/agent-session-store.ts"() {
+    init_session_transcript();
+  }
+});
+
+// src/internal/session/agent-session.ts
+function appendSessionMessage(agentId, message) {
+  const existing = sessions.get(agentId) ?? [];
+  existing.push(message);
+  sessions.set(agentId, existing);
+}
+function getSessionMessages(agentId) {
+  return sessions.get(agentId) ?? [];
+}
+function persistTurnToTranscript(store, loc, sessionId, turn, onCompact) {
+  const key = transcriptKey(loc.cwd, loc.agentId);
+  const chained = (pendingWrites.get(key) ?? Promise.resolve()).then(async () => {
+    try {
+      await persistTurn(store, loc, sessionId, turn);
+      const count = (recordCounts.get(key) ?? 0) + 1;
+      recordCounts.set(key, count);
+      if (turn.autoCompact !== void 0) {
+        const { autoCompactIfNeeded: autoCompactIfNeeded2 } = await Promise.resolve().then(() => (init_compact_session(), compact_session_exports));
+        const fired = await autoCompactIfNeeded2({
+          store,
+          loc,
+          sessionId,
+          usageTotal: turn.autoCompact.usageTotal,
+          contextWindow: turn.autoCompact.contextWindow,
+          turnCount: count,
+          summarize: turn.autoCompact.summarize
+        });
+        if (fired) onCompact?.();
+      }
+    } catch (cause) {
+      const msg = cause instanceof Error ? cause.message : String(cause);
+      process.stderr.write(
+        `[theokit-sdk] session transcript write failed (${loc.agentId}): ${msg}
+`
+      );
+    }
+  });
+  pendingWrites.set(
+    key,
+    chained.then(
+      () => void 0,
+      () => void 0
+    )
+  );
+}
+async function hydrateSession(agentId, loc) {
+  const key = transcriptKey(loc.cwd, agentId);
+  if (hydratedKeys.has(key)) return;
+  hydratedKeys.add(key);
+  const persisted = await readSessionMessages(loc.store, agentId);
+  if (persisted.length === 0) return;
+  sessions.set(agentId, persisted);
+}
+async function flushSessionWrites() {
+  while (pendingWrites.size > 0) {
+    const all = Array.from(pendingWrites.values());
+    pendingWrites.clear();
+    await Promise.all(all);
+  }
+}
+function clearSession(agentId) {
+  sessions.delete(agentId);
+}
+function enqueueSessionWrite(cwd, agentId, fn) {
+  const key = transcriptKey(cwd, agentId);
+  const prior = pendingWrites.get(key) ?? Promise.resolve();
+  const result = prior.then(fn);
+  pendingWrites.set(
+    key,
+    result.then(
+      () => void 0,
+      () => void 0
+    )
+  );
+  return result;
+}
+var pendingWrites, recordCounts;
+var init_agent_session = __esm({
+  "src/internal/session/agent-session.ts"() {
+    init_agent_session_store();
+    init_session_cache();
+    init_session_cache();
+    pendingWrites = /* @__PURE__ */ new Map();
+    recordCounts = /* @__PURE__ */ new Map();
+  }
+});
 async function withToolWhitelist(whitelist, fn) {
   return toolWhitelistStore.run(whitelist, fn);
 }
@@ -6252,10 +6293,10 @@ var init_context = __esm({
   }
 });
 
-// src/goal-loop.ts
+// src/internal/runtime/lifecycle/goal-marker.ts
 var GOAL_CONTINUATION_MARKER;
-var init_goal_loop = __esm({
-  "src/goal-loop.ts"() {
+var init_goal_marker = __esm({
+  "src/internal/runtime/lifecycle/goal-marker.ts"() {
     GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
   }
 });
@@ -6429,7 +6470,7 @@ ${lastResponse.slice(-1e3)}`
 }
 var init_run_until = __esm({
   "src/internal/runtime/lifecycle/run-until.ts"() {
-    init_goal_loop();
+    init_goal_marker();
   }
 });
 
@@ -10600,6 +10641,7 @@ function parseDecisionFromStdout(stdout) {
 }
 
 // src/internal/runtime/lifecycle/post-run-lifecycle.ts
+init_compaction();
 init_run_events();
 
 // src/internal/memory/storage/session-summary-writer.ts
@@ -10669,6 +10711,12 @@ function resolveActiveMemorySummaryForSend(legacySummary, portPathEnabled) {
   return legacySummary;
 }
 
+// src/internal/runtime/lifecycle/context-budget-event.ts
+function buildContextBudgetEvent(model, resolved) {
+  if (resolved.source !== "fallback") return void 0;
+  return { type: "compaction_fallback", model, window: resolved.window };
+}
+
 // src/internal/runtime/lifecycle/post-run-lifecycle.ts
 async function runPostRunLifecycle(inputs) {
   const {
@@ -10694,18 +10742,15 @@ async function runPostRunLifecycle(inputs) {
     appendSessionMessage(agentId, { role: "assistant", text: result.result });
   }
   const conversation = await safeConversation(run);
-  const contextWindow = getCatalogModelInfo(model)?.limit?.context;
-  if (contextWindow === void 0) {
-    const g = globalThis;
-    const sym = /* @__PURE__ */ Symbol.for("theokit-sdk.compact.no-cw-warned");
-    const warned3 = g[sym] ??= /* @__PURE__ */ new Set();
-    if (!warned3.has(model)) {
-      warned3.add(model);
-      process.stderr.write(
-        `[theokit-sdk] auto-compaction disabled: model "${model}" has no context-window entry in the catalog
-`
-      );
-    }
+  const resolvedWindow = resolveEffectiveContextWindow({
+    catalog: getCatalogModelInfo(model)?.limit?.context,
+    margin: CONTEXT_WINDOW_MARGIN,
+    floor: CONTEXT_WINDOW_FLOOR
+  });
+  const contextWindow = resolvedWindow.window;
+  const budgetEvent = buildContextBudgetEvent(model, resolvedWindow);
+  if (budgetEvent !== void 0 && onRunEvent !== void 0) {
+    emitRunEvent(onRunEvent, budgetEvent);
   }
   const lastRequestUsage = result.usage?.requests?.at(-1)?.totalTokens;
   const usageForTrigger = lastRequestUsage ?? result.usage?.totalTokens;
@@ -15677,6 +15722,71 @@ function registerPluginProviderProfiles(entries) {
 
 // src/internal/local-agent/real-local-run.ts
 init_async_local_storage();
+
+// src/internal/local-agent/mcp-pool.ts
+var DEFAULT_IDLE_TTL_MS = 6e5;
+function configKey(config) {
+  return JSON.stringify(
+    config,
+    (_k, v) => v !== null && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(
+      Object.entries(v).sort(([a], [b]) => a < b ? -1 : 1)
+    ) : v
+  );
+}
+var McpClientPool = class {
+  entries = /* @__PURE__ */ new Map();
+  idleTtlMs;
+  now;
+  constructor(options = {}) {
+    this.idleTtlMs = options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+    this.now = options.now ?? Date.now;
+  }
+  /**
+   * Return the pooled client for `(sessionId, serverName, config)`, creating it via `factory` on
+   * first use. Every call refreshes idleness — the TTL measures time SINCE LAST USE, not age.
+   *
+   * Synchronous by design: `createMcpClient` is itself synchronous (the handshake happens later, on
+   * `initialize`), so there is no `await` between the lookup and the insert and two concurrent runs
+   * in the same session cannot both miss the cache.
+   */
+  acquire(sessionId, serverName, config, factory) {
+    const key = `${sessionId}\0${serverName}\0${configKey(config)}`;
+    const existing = this.entries.get(key);
+    if (existing !== void 0) {
+      existing.lastUsedAt = this.now();
+      return existing.client;
+    }
+    const client = factory();
+    this.entries.set(key, { client, sessionId, lastUsedAt: this.now() });
+    return client;
+  }
+  /**
+   * Close and forget every client of ONE session. Scoped deliberately: clearing the whole map would
+   * tear down the servers of every concurrent conversation.
+   */
+  disposeSession(sessionId, close) {
+    for (const [key, entry] of this.entries) {
+      if (entry.sessionId !== sessionId) continue;
+      close(entry.client);
+      this.entries.delete(key);
+    }
+  }
+  /** Close and forget every client idle for longer than the TTL. */
+  reapIdle(close) {
+    const cutoff = this.now() - this.idleTtlMs;
+    for (const [key, entry] of this.entries) {
+      if (entry.lastUsedAt > cutoff) continue;
+      close(entry.client);
+      this.entries.delete(key);
+    }
+  }
+  /** Live pooled-client count — for observability and tests. */
+  size() {
+    return this.entries.size;
+  }
+};
+
+// src/internal/local-agent/real-local-run.ts
 init_real_local_run_provider();
 
 // src/a2a/subagent.ts
@@ -16095,12 +16205,23 @@ function buildLoopInputs(options, runId, userText, userImages) {
     ...options.agentOptions.memoryProvider !== void 0 ? { memoryProvider: options.agentOptions.memoryProvider } : {}
   };
 }
+var sessionMcpPool = new McpClientPool();
+function disposeSessionMcpClients(agentId) {
+  sessionMcpPool.disposeSession(agentId, (client) => {
+    void client.close();
+  });
+}
 function buildMcpMap(options) {
   const map = /* @__PURE__ */ new Map();
   const inline = options.sendOptions.mcpServers ?? options.agentOptions.mcpServers;
   if (inline === void 0) return map;
+  const pooled = options.agentOptions.mcpLifecycle === "session";
+  if (pooled) sessionMcpPool.reapIdle((c) => void c.close());
   for (const [name, config] of Object.entries(inline)) {
-    map.set(name, createMcpClient(name, config));
+    map.set(
+      name,
+      pooled ? sessionMcpPool.acquire(options.agentId, name, config, () => createMcpClient(name, config)) : createMcpClient(name, config)
+    );
   }
   return map;
 }
@@ -17165,7 +17286,9 @@ async function loadDriver(filePath) {
   }
   try {
     const mod = await (driverLoaderOverrides?.nodeSqlite?.() ?? Promise.resolve(
-      process.getBuiltinModule?.("node:sqlite") ?? (() => {
+      process.getBuiltinModule?.(
+        "node:sqlite"
+      ) ?? (() => {
         throw new Error("node:sqlite built-in unavailable (Node < 22.3)");
       })()
     ));
@@ -18215,7 +18338,8 @@ var LocalAgentMemory = class {
       const message = cause instanceof Error ? cause.message : String(cause);
       const g = globalThis;
       const sym = /* @__PURE__ */ Symbol.for("theokit-sdk.memory.warned");
-      const warned3 = g[sym] ??= /* @__PURE__ */ new Set();
+      g[sym] ??= /* @__PURE__ */ new Set();
+      const warned3 = g[sym];
       if (!warned3.has(message)) {
         warned3.add(message);
         process.stderr.write(`[theokit-sdk] memory tools unavailable: ${message}
@@ -19399,6 +19523,7 @@ var LocalAgent = class {
     liveAgentRegistry.forget(this.agentId);
     this.lifecycleAbortController.abort();
     await withCwdMutex(`agent-send:${this.agentId}`, () => Promise.resolve());
+    disposeSessionMcpClients(this.agentId);
     await flushSessionWrites();
     await flushRegistrySaves(this.workspaceCwd);
   }
@@ -19699,8 +19824,8 @@ async function getRegisteredAgentOrThrow(agentId) {
 // src/agent.ts
 init_errors();
 init_discovery();
-init_agent_session();
 init_agent_factory_registry();
+init_agent_session();
 var streamObjectImport;
 var Agent = class _Agent {
   constructor() {
@@ -19992,26 +20117,26 @@ var Agent = class _Agent {
       reg = getRegisteredAgent(agentId);
     }
     if (reg === void 0 || reg.runtime !== "local") {
-      throw new UnknownAgentError(`No local agent "${agentId}" registered \u2014 compact targets local sessions.`);
+      throw new UnknownAgentError(
+        `No local agent "${agentId}" registered \u2014 compact targets local sessions.`
+      );
     }
-    const cwd = reg.cwd ?? process.cwd();
-    const optModel = reg.options.model;
-    const model = reg.model?.id ?? (typeof optModel === "string" ? optModel : optModel?.id) ?? "unknown";
     const { compactSessionTranscript: compactSessionTranscript2, buildDefaultSummarizer: buildDefaultSummarizer2 } = await Promise.resolve().then(() => (init_compact_session(), compact_session_exports));
-    const { FsSessionStore: FsSessionStore2 } = await Promise.resolve().then(() => (init_fs_session_store(), fs_session_store_exports));
-    const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await Promise.resolve().then(() => (init_session_transcript(), session_transcript_exports));
-    const baseDir = reg.options.local?.baseDir !== void 0 ? expandTilde2(reg.options.local.baseDir) : defaultBaseDir2();
-    const store = new FsSessionStore2({ baseDir, cwd });
-    return enqueueSessionWrite(cwd, agentId, () => compactSessionTranscript2({
-      store,
-      loc: { cwd, agentId, model },
-      sessionId: agentId,
-      trigger: options.trigger ?? "manual",
-      summarize: options.summarize ?? buildDefaultSummarizer2({
-        agentModel: model,
-        ...reg.options.apiKey !== void 0 ? { apiKey: reg.options.apiKey } : {}
+    const { cwd, model, store } = await abrirStoreLocal(reg);
+    return enqueueSessionWrite(
+      cwd,
+      agentId,
+      () => compactSessionTranscript2({
+        store,
+        loc: { cwd, agentId, model },
+        sessionId: agentId,
+        trigger: options.trigger ?? "manual",
+        summarize: options.summarize ?? buildDefaultSummarizer2({
+          agentModel: model,
+          ...reg.options.apiKey !== void 0 ? { apiKey: reg.options.apiKey } : {}
+        })
       })
-    }));
+    );
   }
   /**
    * M51 — inject a SYNTHETIC user+assistant pair into a LOCAL session's persisted transcript WITHOUT
@@ -20028,16 +20153,12 @@ var Agent = class _Agent {
       reg = getRegisteredAgent(agentId);
     }
     if (reg === void 0 || reg.runtime !== "local") {
-      throw new UnknownAgentError(`No local agent "${agentId}" registered \u2014 injectSessionTurn targets local sessions.`);
+      throw new UnknownAgentError(
+        `No local agent "${agentId}" registered \u2014 injectSessionTurn targets local sessions.`
+      );
     }
-    const cwd = reg.cwd ?? process.cwd();
-    const optModel = reg.options.model;
-    const model = reg.model?.id ?? (typeof optModel === "string" ? optModel : optModel?.id) ?? "unknown";
     const { injectSessionTurn: injectSessionTurn2 } = await Promise.resolve().then(() => (init_inject_session(), inject_session_exports));
-    const { FsSessionStore: FsSessionStore2 } = await Promise.resolve().then(() => (init_fs_session_store(), fs_session_store_exports));
-    const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await Promise.resolve().then(() => (init_session_transcript(), session_transcript_exports));
-    const baseDir = reg.options.local?.baseDir !== void 0 ? expandTilde2(reg.options.local.baseDir) : defaultBaseDir2();
-    const store = new FsSessionStore2({ baseDir, cwd });
+    const { cwd, model, store } = await abrirStoreLocal(reg);
     await injectSessionTurn2({
       store,
       loc: { cwd, agentId, model },
@@ -20079,6 +20200,15 @@ setAgentFacade({
   resume: (agentId, options) => Agent.resume(agentId, options),
   batch: (prompts, options) => Agent.batch(prompts, options)
 });
+async function abrirStoreLocal(reg) {
+  const cwd = reg.cwd ?? process.cwd();
+  const optModel = reg.options.model;
+  const model = reg.model?.id ?? (typeof optModel === "string" ? optModel : optModel?.id) ?? "unknown";
+  const { FsSessionStore: FsSessionStore2 } = await Promise.resolve().then(() => (init_fs_session_store(), fs_session_store_exports));
+  const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await Promise.resolve().then(() => (init_session_transcript(), session_transcript_exports));
+  const baseDir = reg.options.local?.baseDir !== void 0 ? expandTilde2(reg.options.local.baseDir) : defaultBaseDir2();
+  return { cwd, model, store: new FsSessionStore2({ baseDir, cwd }) };
+}
 var JsonlParseError = class extends Error {
   constructor(message, line) {
     super(message);