@theokit/sdk 4.22.0 → 4.24.0

package/dist/index.cjs

@@ -1707,6 +1707,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 exports.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;
@@ -1765,6 +1803,18 @@ var init_session_summary_writer = __esm({
     MAX_TURN_CHARS = 2e3;
   }
 });
+
+// src/internal/global-singleton.ts
+function globalSingleton(key2, create) {
+  const g = globalThis;
+  const sym = Symbol.for(key2);
+  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"() {
@@ -1805,12 +1855,6 @@ var init_catalog_schema = __esm({
 });
 
 // src/internal/providers/registry.ts
-function globalSingleton(key2, create) {
-  const g = globalThis;
-  const sym = Symbol.for(key2);
-  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.
@@ -1838,6 +1882,7 @@ function listProviders() {
 var REGISTRY, ALIASES;
 var init_registry = __esm({
   "src/internal/providers/registry.ts"() {
+    init_global_singleton();
     REGISTRY = globalSingleton(
       "theokit-sdk.providers.registry",
       () => /* @__PURE__ */ new Map()
@@ -1845,12 +1890,6 @@ var init_registry = __esm({
     ALIASES = globalSingleton("theokit-sdk.providers.aliases", () => /* @__PURE__ */ new Map());
   }
 });
-function globalSingleton2(key2, create) {
-  const g = globalThis;
-  const sym = Symbol.for(key2);
-  if (g[sym] === void 0) g[sym] = create();
-  return g[sym];
-}
 function getCatalogModelInfo(key2) {
   ensureModelIndexLoaded();
   return modelInfoIndex.get(key2);
@@ -1952,33 +1991,25 @@ function registerCatalogProviders(opts) {
 var __dirname_resolved, modelInfoIndex, patchedModelKeys, indexState, _capabilitiesCache;
 var init_catalog_loader = __esm({
   "src/internal/providers/catalog-loader.ts"() {
+    init_global_singleton();
     init_catalog_schema();
     init_registry();
     __dirname_resolved = path.dirname(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))));
-    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
     }));
     _capabilitiesCache = null;
   }
 });
 
-// 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({
@@ -2348,11 +2379,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 exports.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 = zod.z.object({
       type: zod.z.literal("api").optional(),
@@ -2774,12 +2806,6 @@ var init_builtin = __esm({
     })();
   }
 });
-function globalSingleton3(key2, create) {
-  const g = globalThis;
-  const sym = Symbol.for(key2);
-  if (g[sym] === void 0) g[sym] = create();
-  return g[sym];
-}
 function pluginsRoot() {
   return path.join(os.homedir(), ".theokit", "plugins", "model-providers");
 }
@@ -2871,8 +2897,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
     }));
   }
@@ -4549,6 +4576,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 {
@@ -4610,61 +4699,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"() {
@@ -4673,8 +4707,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;
@@ -5763,6 +5797,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;
@@ -5791,12 +5833,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") {
@@ -5805,12 +5842,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;
@@ -6000,194 +6032,44 @@ var init_compression_summarizer = __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 };
+// src/internal/session/session-cache.ts
+function transcriptKey(cwd, agentId) {
+  return `${cwd}::${agentId}`;
 }
-function hasAssistantContent(a) {
-  return a.text !== void 0 || a.thinking !== void 0 || (a.toolCalls?.length ?? 0) > 0;
+function invalidateSessionCache(cwd, agentId) {
+  sessions.delete(agentId);
+  hydratedKeys.delete(transcriptKey(cwd, agentId));
 }
-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);
+var sessions, hydratedKeys;
+var init_session_cache = __esm({
+  "src/internal/session/session-cache.ts"() {
+    sessions = /* @__PURE__ */ new Map();
+    hydratedKeys = /* @__PURE__ */ new Set();
   }
+});
+
+// src/internal/session/compact-session.ts
+var compact_session_exports = {};
+__export(compact_session_exports, {
+  COMPACT_SUMMARY_MARKER: () => COMPACT_SUMMARY_MARKER,
+  COMPACT_USER_MESSAGE_MAX_TOKENS: () => COMPACT_USER_MESSAGE_MAX_TOKENS,
+  autoCompactIfNeeded: () => autoCompactIfNeeded,
+  buildDefaultSummarizer: () => buildDefaultSummarizer,
+  compactSessionTranscript: () => compactSessionTranscript,
+  isCompactSummary: () => isCompactSummary,
+  resolveSummarizerRoute: () => resolveSummarizerRoute,
+  shouldAutoCompact: () => shouldAutoCompact
+});
+function isCompactSummary(content) {
+  return content.startsWith(COMPACT_SUMMARY_MARKER) || content.startsWith("[[theokit:goal-continuation]]");
 }
-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 key2 = transcriptKey(loc.cwd, loc.agentId);
-  const chained = (pendingWrites.get(key2) ?? Promise.resolve()).then(async () => {
-    try {
-      await persistTurn(store, loc, sessionId, turn);
-      const count = (recordCounts.get(key2) ?? 0) + 1;
-      recordCounts.set(key2, 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(
-    key2,
-    chained.then(
-      () => void 0,
-      () => void 0
-    )
-  );
-}
-async function hydrateSession(agentId, loc) {
-  const key2 = transcriptKey(loc.cwd, agentId);
-  if (hydratedKeys.has(key2)) return;
-  hydratedKeys.add(key2);
-  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 invalidateSessionCache(cwd, agentId) {
-  sessions.delete(agentId);
-  hydratedKeys.delete(transcriptKey(cwd, agentId));
-}
-function enqueueSessionWrite(cwd, agentId, fn) {
-  const key2 = transcriptKey(cwd, agentId);
-  const prior = pendingWrites.get(key2) ?? Promise.resolve();
-  const result = prior.then(fn);
-  pendingWrites.set(
-    key2,
-    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();
-    sessions = /* @__PURE__ */ new Map();
-    hydratedKeys = /* @__PURE__ */ new Set();
-    pendingWrites = /* @__PURE__ */ new Map();
-    recordCounts = /* @__PURE__ */ new Map();
-  }
-});
-
-// src/internal/session/compact-session.ts
-var compact_session_exports = {};
-__export(compact_session_exports, {
-  COMPACT_SUMMARY_MARKER: () => COMPACT_SUMMARY_MARKER,
-  COMPACT_USER_MESSAGE_MAX_TOKENS: () => COMPACT_USER_MESSAGE_MAX_TOKENS,
-  autoCompactIfNeeded: () => autoCompactIfNeeded,
-  buildDefaultSummarizer: () => buildDefaultSummarizer,
-  compactSessionTranscript: () => compactSessionTranscript,
-  isCompactSummary: () => isCompactSummary,
-  resolveSummarizerRoute: () => resolveSummarizerRoute,
-  shouldAutoCompact: () => shouldAutoCompact
-});
-function isCompactSummary(content) {
-  return content.startsWith(COMPACT_SUMMARY_MARKER) || content.startsWith("[[theokit:goal-continuation]]");
-}
-function plainText(content) {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return void 0;
-  const texts = content.filter(
-    (p) => p !== null && typeof p === "object" && p.type === "text" && typeof p.text === "string"
-  ).map((p) => p.text);
-  return texts.length > 0 ? texts.join("\n") : void 0;
+function plainText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return void 0;
+  const texts = content.filter(
+    (p) => p !== null && typeof p === "object" && p.type === "text" && typeof p.text === "string"
+  ).map((p) => p.text);
+  return texts.length > 0 ? texts.join("\n") : void 0;
 }
 async function compactSessionTranscript(opts) {
   const prior = await opts.store.readRecords(opts.loc.agentId);
@@ -6324,7 +6206,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 = (() => {
@@ -6335,6 +6217,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 key2 = transcriptKey(loc.cwd, loc.agentId);
+  const chained = (pendingWrites.get(key2) ?? Promise.resolve()).then(async () => {
+    try {
+      await persistTurn(store, loc, sessionId, turn);
+      const count = (recordCounts.get(key2) ?? 0) + 1;
+      recordCounts.set(key2, 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(
+    key2,
+    chained.then(
+      () => void 0,
+      () => void 0
+    )
+  );
+}
+async function hydrateSession(agentId, loc) {
+  const key2 = transcriptKey(loc.cwd, agentId);
+  if (hydratedKeys.has(key2)) return;
+  hydratedKeys.add(key2);
+  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 key2 = transcriptKey(cwd, agentId);
+  const prior = pendingWrites.get(key2) ?? Promise.resolve();
+  const result = prior.then(fn);
+  pendingWrites.set(
+    key2,
+    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);
 }
@@ -6546,7 +6587,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)");
       })()
     ));
@@ -7452,190 +7495,71 @@ var init_index_manager = __esm({
             score: 0,
             textScore: 0,
             snippet: truncateSnippet(String(row.text ?? "")),
-            source: String(row.source),
-            citation: `${path}:${startLine}-${endLine}`
-          };
-        });
-      }
-      // ───── persistence helpers ─────────────────────────────────────────
-      loadFilesIndex() {
-        const rows = this.db.prepare("SELECT id, path, hash FROM files").all();
-        return new Map(rows.map((row) => [row.path, { id: row.id, hash: row.hash }]));
-      }
-      upsertFile(absPath, relPath, hash, mtimeMs, source = "memory") {
-        const stmt = this.db.prepare(
-          `INSERT INTO files (path, rel_path, mtime, hash, source) VALUES (?, ?, ?, ?, ?)
-       ON CONFLICT(path) DO UPDATE SET hash = excluded.hash, mtime = excluded.mtime, source = excluded.source
-       RETURNING id`
-        );
-        const row = stmt.get(absPath, relPath, Math.floor(mtimeMs), hash, source);
-        return row.id;
-      }
-      deleteChunksForFile(fileId) {
-        this.db.prepare("DELETE FROM chunks WHERE file_id = ?").run(fileId);
-      }
-      insertChunk(fileId, startLine, endLine, text, hash) {
-        this.db.prepare(
-          "INSERT INTO chunks (file_id, start_line, end_line, text, hash) VALUES (?, ?, ?, ?, ?)"
-        ).run(fileId, startLine, endLine, text, hash);
-      }
-      close() {
-        this.db.close();
-      }
-    };
-  }
-});
-
-// src/internal/personality/context.ts
-var context_exports = {};
-__export(context_exports, {
-  currentPersonalityContext: () => currentPersonalityContext,
-  warnPersonalitySwitchInsideFork: () => warnPersonalitySwitchInsideFork,
-  withPersonalityContext: () => withPersonalityContext
-});
-function withPersonalityContext(ctx, fn) {
-  return storage.run(ctx, fn);
-}
-function currentPersonalityContext() {
-  return storage.getStore();
-}
-function warnPersonalitySwitchInsideFork(agentId) {
-  warnOnce(
-    `personality-switch-in-fork-${agentId}`,
-    `[theokit-sdk] usePersonality is a no-op inside a fork (D168). Subagents inherit the parent's active personality at fork-construction time.`
-  );
-}
-var storage;
-var init_context = __esm({
-  "src/internal/personality/context.ts"() {
-    init_hooks_source();
-    storage = new async_hooks.AsyncLocalStorage();
-  }
-});
-
-// src/internal/judge/parse-verdict.ts
-function parseVerdict(text) {
-  const trimmed = text.trim();
-  if (trimmed.startsWith(DONE_PREFIX)) {
-    return {
-      verdict: "done",
-      reason: trimmed.slice(DONE_PREFIX.length).trim(),
-      parseFailed: false
-    };
-  }
-  if (trimmed.startsWith(CONTINUE_PREFIX)) {
-    return {
-      verdict: "continue",
-      reason: trimmed.slice(CONTINUE_PREFIX.length).trim(),
-      parseFailed: false
-    };
-  }
-  if (trimmed.startsWith(SKIPPED_PREFIX)) {
-    return {
-      verdict: "skipped",
-      reason: trimmed.slice(SKIPPED_PREFIX.length).trim(),
-      parseFailed: false
-    };
-  }
-  return {
-    verdict: "continue",
-    reason: `judge response malformed: "${trimmed.slice(0, 100)}"`,
-    parseFailed: true
-  };
-}
-var DONE_PREFIX, CONTINUE_PREFIX, SKIPPED_PREFIX;
-var init_parse_verdict = __esm({
-  "src/internal/judge/parse-verdict.ts"() {
-    DONE_PREFIX = "DONE:";
-    CONTINUE_PREFIX = "CONTINUE:";
-    SKIPPED_PREFIX = "SKIPPED:";
-  }
-});
-
-// src/internal/judge/judge-call.ts
-var judge_call_exports = {};
-__export(judge_call_exports, {
-  composeJudgePrompt: () => composeJudgePrompt,
-  judgeCallImpl: () => judgeCallImpl
-});
-async function judgeCallImpl(ctx, options, deps) {
-  const prompt = composeJudgePrompt(ctx);
-  const apiKey = options?.apiKey ?? process.env.OPENROUTER_API_KEY;
-  if (apiKey === void 0) {
-    return {
-      verdict: "continue",
-      reason: "judge unavailable: OPENROUTER_API_KEY missing and no override passed via options.apiKey",
-      parseFailed: true
-    };
-  }
-  const judgeModel = options?.judgeModel ?? "openai/gpt-4o-mini";
-  let auxAgent;
-  try {
-    auxAgent = await deps.create({
-      apiKey,
-      model: { id: judgeModel },
-      tools: [],
-      local: {},
-      metadata: { forkOrigin: "judge" }
-    });
-    const run = await auxAgent.send(prompt);
-    const result = await run.wait();
-    return parseVerdict(result.result ?? "");
-  } catch (err) {
-    return {
-      verdict: "continue",
-      reason: `judge call failed: ${err instanceof Error ? err.message : String(err)}`,
-      parseFailed: true
-    };
-  } finally {
-    if (auxAgent !== void 0) {
-      try {
-        await auxAgent.dispose();
-      } catch {
+            source: String(row.source),
+            citation: `${path}:${startLine}-${endLine}`
+          };
+        });
       }
-    }
+      // ───── persistence helpers ─────────────────────────────────────────
+      loadFilesIndex() {
+        const rows = this.db.prepare("SELECT id, path, hash FROM files").all();
+        return new Map(rows.map((row) => [row.path, { id: row.id, hash: row.hash }]));
+      }
+      upsertFile(absPath, relPath, hash, mtimeMs, source = "memory") {
+        const stmt = this.db.prepare(
+          `INSERT INTO files (path, rel_path, mtime, hash, source) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(path) DO UPDATE SET hash = excluded.hash, mtime = excluded.mtime, source = excluded.source
+       RETURNING id`
+        );
+        const row = stmt.get(absPath, relPath, Math.floor(mtimeMs), hash, source);
+        return row.id;
+      }
+      deleteChunksForFile(fileId) {
+        this.db.prepare("DELETE FROM chunks WHERE file_id = ?").run(fileId);
+      }
+      insertChunk(fileId, startLine, endLine, text, hash) {
+        this.db.prepare(
+          "INSERT INTO chunks (file_id, start_line, end_line, text, hash) VALUES (?, ?, ?, ?, ?)"
+        ).run(fileId, startLine, endLine, text, hash);
+      }
+      close() {
+        this.db.close();
+      }
+    };
   }
-}
-function composeJudgePrompt(ctx) {
-  const subgoals = ctx.subgoals !== void 0 && ctx.subgoals.length > 0 ? ctx.subgoals.join(", ") : "(none)";
-  return `You are a goal judge. Determine if this goal is satisfied.
-
-Goal: ${ctx.goal}
-Subgoals: ${subgoals}
-Last agent response: ${ctx.lastResponse}
-
-Respond with EXACTLY one of:
-- DONE: <reason>
-- CONTINUE: <what's left>
-- SKIPPED: <why not applicable>
+});
 
-Be strict. If unclear, prefer CONTINUE.`;
+// src/internal/personality/context.ts
+var context_exports = {};
+__export(context_exports, {
+  currentPersonalityContext: () => currentPersonalityContext,
+  warnPersonalitySwitchInsideFork: () => warnPersonalitySwitchInsideFork,
+  withPersonalityContext: () => withPersonalityContext
+});
+function withPersonalityContext(ctx, fn) {
+  return storage.run(ctx, fn);
 }
-var init_judge_call = __esm({
-  "src/internal/judge/judge-call.ts"() {
-    init_parse_verdict();
+function currentPersonalityContext() {
+  return storage.getStore();
+}
+function warnPersonalitySwitchInsideFork(agentId) {
+  warnOnce(
+    `personality-switch-in-fork-${agentId}`,
+    `[theokit-sdk] usePersonality is a no-op inside a fork (D168). Subagents inherit the parent's active personality at fork-construction time.`
+  );
+}
+var storage;
+var init_context = __esm({
+  "src/internal/personality/context.ts"() {
+    init_hooks_source();
+    storage = new async_hooks.AsyncLocalStorage();
   }
 });
 
-// src/goal-loop.ts
-function runGoalLoop(agent, goal, options, depsOverride) {
-  async function* wrap() {
-    const { runUntilImpl: runUntilImpl2 } = await Promise.resolve().then(() => (init_run_until(), run_until_exports));
-    const deps = depsOverride ?? await (async () => {
-      const { judgeCallImpl: judgeCallImpl2 } = await Promise.resolve().then(() => (init_judge_call(), judge_call_exports));
-      const { getAgentFacade: getAgentFacade2 } = await Promise.resolve().then(() => (init_agent_factory_registry(), agent_factory_registry_exports));
-      const create = getAgentFacade2().create;
-      return {
-        judge: (ctx, opts) => judgeCallImpl2(ctx, opts, { create })
-      };
-    })();
-    return yield* runUntilImpl2(agent, goal, options, deps);
-  }
-  return wrap();
-}
+// src/internal/runtime/lifecycle/goal-marker.ts
 exports.GOAL_CONTINUATION_MARKER = void 0;
-var init_goal_loop = __esm({
-  "src/goal-loop.ts"() {
+var init_goal_marker = __esm({
+  "src/internal/runtime/lifecycle/goal-marker.ts"() {
     exports.GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
   }
 });
@@ -7809,7 +7733,111 @@ ${lastResponse.slice(-1e3)}`
 }
 var init_run_until = __esm({
   "src/internal/runtime/lifecycle/run-until.ts"() {
-    init_goal_loop();
+    init_goal_marker();
+  }
+});
+
+// src/internal/judge/parse-verdict.ts
+function parseVerdict(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith(DONE_PREFIX)) {
+    return {
+      verdict: "done",
+      reason: trimmed.slice(DONE_PREFIX.length).trim(),
+      parseFailed: false
+    };
+  }
+  if (trimmed.startsWith(CONTINUE_PREFIX)) {
+    return {
+      verdict: "continue",
+      reason: trimmed.slice(CONTINUE_PREFIX.length).trim(),
+      parseFailed: false
+    };
+  }
+  if (trimmed.startsWith(SKIPPED_PREFIX)) {
+    return {
+      verdict: "skipped",
+      reason: trimmed.slice(SKIPPED_PREFIX.length).trim(),
+      parseFailed: false
+    };
+  }
+  return {
+    verdict: "continue",
+    reason: `judge response malformed: "${trimmed.slice(0, 100)}"`,
+    parseFailed: true
+  };
+}
+var DONE_PREFIX, CONTINUE_PREFIX, SKIPPED_PREFIX;
+var init_parse_verdict = __esm({
+  "src/internal/judge/parse-verdict.ts"() {
+    DONE_PREFIX = "DONE:";
+    CONTINUE_PREFIX = "CONTINUE:";
+    SKIPPED_PREFIX = "SKIPPED:";
+  }
+});
+
+// src/internal/judge/judge-call.ts
+var judge_call_exports = {};
+__export(judge_call_exports, {
+  composeJudgePrompt: () => composeJudgePrompt,
+  judgeCallImpl: () => judgeCallImpl
+});
+async function judgeCallImpl(ctx, options, deps) {
+  const prompt = composeJudgePrompt(ctx);
+  const apiKey = options?.apiKey ?? process.env.OPENROUTER_API_KEY;
+  if (apiKey === void 0) {
+    return {
+      verdict: "continue",
+      reason: "judge unavailable: OPENROUTER_API_KEY missing and no override passed via options.apiKey",
+      parseFailed: true
+    };
+  }
+  const judgeModel = options?.judgeModel ?? "openai/gpt-4o-mini";
+  let auxAgent;
+  try {
+    auxAgent = await deps.create({
+      apiKey,
+      model: { id: judgeModel },
+      tools: [],
+      local: {},
+      metadata: { forkOrigin: "judge" }
+    });
+    const run = await auxAgent.send(prompt);
+    const result = await run.wait();
+    return parseVerdict(result.result ?? "");
+  } catch (err) {
+    return {
+      verdict: "continue",
+      reason: `judge call failed: ${err instanceof Error ? err.message : String(err)}`,
+      parseFailed: true
+    };
+  } finally {
+    if (auxAgent !== void 0) {
+      try {
+        await auxAgent.dispose();
+      } catch {
+      }
+    }
+  }
+}
+function composeJudgePrompt(ctx) {
+  const subgoals = ctx.subgoals !== void 0 && ctx.subgoals.length > 0 ? ctx.subgoals.join(", ") : "(none)";
+  return `You are a goal judge. Determine if this goal is satisfied.
+
+Goal: ${ctx.goal}
+Subgoals: ${subgoals}
+Last agent response: ${ctx.lastResponse}
+
+Respond with EXACTLY one of:
+- DONE: <reason>
+- CONTINUE: <what's left>
+- SKIPPED: <why not applicable>
+
+Be strict. If unclear, prefer CONTINUE.`;
+}
+var init_judge_call = __esm({
+  "src/internal/judge/judge-call.ts"() {
+    init_parse_verdict();
   }
 });
 
@@ -13277,6 +13305,7 @@ function parseDecisionFromStdout(stdout) {
 }
 
 // src/internal/runtime/lifecycle/post-run-lifecycle.ts
+init_compaction();
 init_run_events();
 init_session_summary_writer();
 init_catalog_loader();
@@ -13304,6 +13333,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 {
@@ -13329,18 +13364,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;
@@ -18312,6 +18344,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 key2 = `${sessionId}\0${serverName}\0${configKey(config)}`;
+    const existing = this.entries.get(key2);
+    if (existing !== void 0) {
+      existing.lastUsedAt = this.now();
+      return existing.client;
+    }
+    const client = factory();
+    this.entries.set(key2, { 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 [key2, entry] of this.entries) {
+      if (entry.sessionId !== sessionId) continue;
+      close(entry.client);
+      this.entries.delete(key2);
+    }
+  }
+  /** Close and forget every client idle for longer than the TTL. */
+  reapIdle(close) {
+    const cutoff = this.now() - this.idleTtlMs;
+    for (const [key2, entry] of this.entries) {
+      if (entry.lastUsedAt > cutoff) continue;
+      close(entry.client);
+      this.entries.delete(key2);
+    }
+  }
+  /** 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
@@ -18730,12 +18827,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;
 }
@@ -19864,7 +19972,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}
@@ -21049,6 +21158,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);
   }
@@ -21349,8 +21459,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() {
@@ -21642,26 +21752,26 @@ var Agent = class _Agent {
       reg = getRegisteredAgent(agentId);
     }
     if (reg === void 0 || reg.runtime !== "local") {
-      throw new exports.UnknownAgentError(`No local agent "${agentId}" registered \u2014 compact targets local sessions.`);
+      throw new exports.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
@@ -21678,16 +21788,12 @@ var Agent = class _Agent {
       reg = getRegisteredAgent(agentId);
     }
     if (reg === void 0 || reg.runtime !== "local") {
-      throw new exports.UnknownAgentError(`No local agent "${agentId}" registered \u2014 injectSessionTurn targets local sessions.`);
+      throw new exports.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 },
@@ -21729,6 +21835,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 }) };
+}
 
 // src/agent-factory.ts
 function createAgentFactory(common) {
@@ -22843,7 +22958,24 @@ var EventBus = class {
 
 // src/index.ts
 init_generate_object();
-init_goal_loop();
+
+// src/goal-loop.ts
+init_goal_marker();
+function runGoalLoop(agent, goal, options, depsOverride) {
+  async function* wrap() {
+    const { runUntilImpl: runUntilImpl2 } = await Promise.resolve().then(() => (init_run_until(), run_until_exports));
+    const deps = depsOverride ?? await (async () => {
+      const { judgeCallImpl: judgeCallImpl2 } = await Promise.resolve().then(() => (init_judge_call(), judge_call_exports));
+      const { getAgentFacade: getAgentFacade2 } = await Promise.resolve().then(() => (init_agent_factory_registry(), agent_factory_registry_exports));
+      const create = getAgentFacade2().create;
+      return {
+        judge: (ctx, opts) => judgeCallImpl2(ctx, opts, { create })
+      };
+    })();
+    return yield* runUntilImpl2(agent, goal, options, deps);
+  }
+  return wrap();
+}
 
 // src/internal/budget/tracker/budget-tracker-counter.ts
 function createCounterBudgetTracker(options = {}) {