@theokit/sdk 4.53.0 → 4.54.0

package/dist/{chunk-NZOR3N4E.js → chunk-TPTZA6NI.js}

@@ -1,34 +1,36 @@
-import { enqueueSessionWrite, hydrateSession, persistTurnToTranscript, flushSessionWrites, appendSessionMessage, getSessionMessages, discardSession, clearSession } from './chunk-I5OTK2RP.js';
-import { loadHookConfig, warnOnce, currentPersonalityContext, warnPersonalitySwitchInsideFork } from './chunk-OIBHY6JQ.js';
+import { enqueueSessionWrite, hydrateSession, persistTurnToTranscript, flushSessionWrites, appendSessionMessage, getSessionMessages, discardSession, clearSession } from './chunk-DUIF54UP.js';
+import { IndexManager, writeSessionSummary, memoryDir, appendFact, readFacts, legacyMemoryJsonPath, memoryMdPath, appendFactToMarkdown } from './chunk-DAPSQZT4.js';
+import { loadHookConfig, warnOnce, currentPersonalityContext, warnPersonalitySwitchInsideFork } from './chunk-YMA4S2WO.js';
 import { extractCodePlugins } from './chunk-2SFBB54R.js';
-import { submit, emitRunEvent } from './chunk-7TB5U7RK.js';
-import { FsSessionStore } from './chunk-634YVZLU.js';
-import { discoverProviderPlugins, getConfiguredBaseUrl, httpRequest, isFixtureApiKey, shouldUseRealLocalRuntime, CircuitBreaker, buildDefaultSummarizer, parseSseStream, resolveProviderChain, inferProviderFromApiKey, detectPrimaryProvider, tryFirstEvent, relayStream, renderToolResultContentText } from './chunk-2Y5NO2SY.js';
-import { IndexManager, writeSessionSummary, memoryDir, appendFact, readFacts, legacyMemoryJsonPath, memoryMdPath, appendFactToMarkdown } from './chunk-NOS7PTKP.js';
-import { resolveChildEnv } from './chunk-AM2CNBKE.js';
-import { DEFAULT_MAX_BYTES_PER_FILE, runDiscovery, truncateWithMarker } from './chunk-34XOCZJO.js';
-import { readVersionedJson, getTheokitHome, writeVersionedJson } from './chunk-L7EGRCKJ.js';
-import { createOpenAiCompatibleRuntime } from './chunk-EFXJ5C7X.js';
+import { submit, emitRunEvent } from './chunk-SUKXXLWD.js';
+import { createOpenAiCompatibleRuntime } from './chunk-XN7NOENA.js';
+import { FsSessionStore } from './chunk-GJ6RK75E.js';
+import { discoverProviderPlugins, getConfiguredBaseUrl, httpRequest, isFixtureApiKey, presentProviderCredentialEnvVars, CircuitBreaker, buildDefaultSummarizer, shouldUseRealLocalRuntime, parseSseStream, resolveProviderChain, inferProviderFromApiKey, detectPrimaryProvider, warnProviderPrecedenceOnce, tryFirstEvent, relayStream, renderToolResultContentText } from './chunk-VDEWG5TV.js';
+import { resolveChildEnv } from './chunk-HKCKOAIO.js';
+import { DEFAULT_MAX_BYTES_PER_FILE, runDiscovery, truncateWithMarker } from './chunk-5PHVENFV.js';
+import { readVersionedJson, getTheokitHome, writeVersionedJson } from './chunk-UPRJR6IP.js';
+import { toJsonSchema } from './chunk-4VPXM6UU.js';
 import { sanitizeToolInput } from './chunk-U54XCYG3.js';
-import { withInheritedSubAgentCredentials, subAgentToolsFromDefinitions } from './chunk-RP5HQVLD.js';
+import { withInheritedSubAgentCredentials, subAgentToolsFromDefinitions } from './chunk-RNB4APBZ.js';
 import { setAgentFacade } from './chunk-6X6ID4MO.js';
+import { escapeBlockBody, buildSkillsBlock, discoverSkills, stripSkillFrontmatter } from './chunk-4ERPXIVB.js';
 import { withToolWhitelist, checkToolWhitelist } from './chunk-7AD3ZTZL.js';
-import { mapWithConcurrency } from './chunk-ITQ4NO4P.js';
-import { defaultBaseDir, expandTilde } from './chunk-C4EU627W.js';
-import { withFileLock } from './chunk-HTK54K2J.js';
-import { withCwdMutex } from './chunk-2XLKLVVR.js';
-import { toJsonSchema } from './chunk-4VPXM6UU.js';
-import { atomicWriteJson } from './chunk-CHVSMEKM.js';
-import { loadSubagents } from './chunk-XGYI2KQH.js';
-import { resolveEffectiveContextWindow, CONTEXT_WINDOW_FLOOR, CONTEXT_WINDOW_MARGIN } from './chunk-KIX45IKP.js';
-import { parseModelId } from './chunk-X2FR4OIT.js';
-import { getCatalogModelInfo, registerBuiltins, getProviderProfile, registerProvider, isPatchedModelKey } from './chunk-2YWWPCGX.js';
-import { escapeBlockBody, buildSkillsBlock, discoverSkills, stripSkillFrontmatter } from './chunk-BXVSBYGW.js';
-import { validateArtifactPath, PathTraversalError, safePathJoin } from './chunk-XWCTBGYK.js';
+import { validateArtifactPath, PathTraversalError, safePathJoin } from './chunk-QARJGQSA.js';
 import { insideRoot, atOrInsideRoot } from './chunk-RIAM53CP.js';
-import { readWorkspaceDir, parseSimpleYaml } from './chunk-5XXUYU3M.js';
-import { AgentRunError, coerceToKnownAgentRunErrorCode, UnknownAgentError, ConfigurationError, AuthenticationError, UnsupportedRunOperationError, AgentDisposedError, NetworkError, TheokitAgentError } from './chunk-HI4ZW62S.js';
-import { diag, redactSecrets } from './chunk-4X3SBHPK.js';
+import { mapWithConcurrency } from './chunk-UC3HT2S4.js';
+import { expandTilde, defaultBaseDir } from './chunk-DZBSJX6J.js';
+import { withFileLock } from './chunk-CV7XMBHP.js';
+import { withCwdMutex } from './chunk-Q5EWJPRY.js';
+import { atomicWriteJson } from './chunk-VF7EWVDG.js';
+import { loadSubagents } from './chunk-2QKTVKH3.js';
+import { readWorkspaceDir, parseSimpleYaml } from './chunk-AG5JPQIY.js';
+import { resolveEffectiveContextWindow, CONTEXT_WINDOW_FLOOR, CONTEXT_WINDOW_MARGIN } from './chunk-F7AQV62G.js';
+import { parseModelId } from './chunk-R7WIIPUR.js';
+import { getProviderProfile } from './chunk-SSQZA3DZ.js';
+import { getCatalogModelInfo, registerBuiltins, getProviderProfile as getProviderProfile$1, registerProvider, isPatchedModelKey } from './chunk-FXEUP75G.js';
+import { AgentRunError, coerceToKnownAgentRunErrorCode, UnknownAgentError, ConfigurationError, AuthenticationError, AgentDisposedError, UnsupportedRunOperationError, NetworkError, TheokitAgentError } from './chunk-IDCKSLYH.js';
+import { resolveApiKey, API_KEY_ENV_VAR, redactSecrets } from './chunk-T7XEKOVW.js';
+import { diag } from './chunk-T7O6K6PX.js';
 import { stat, mkdir, readFile, readdir, access, unlink } from 'fs/promises';
 import { randomUUID, createHash } from 'crypto';
 import { join, dirname, resolve, isAbsolute } from 'path';
@@ -223,7 +225,7 @@ async function agentGenerate(agent, agentModel, agentApiKey, agentLocal, input,
   const { output, maxRetries, errorStrategy, ...sendOptions } = options;
   const run = await agent.send(input, sendOptions);
   const result = await run.wait();
-  const { generateObjectImpl, GenerateObjectError } = await import('./generate-object-TVQCW2IZ.js');
+  const { generateObjectImpl, GenerateObjectError } = await import('./generate-object-N5MDZUJI.js');
   const answer = structurableAnswerOrThrow(result, GenerateObjectError);
   const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
   const facade = getAgentFacade();
@@ -277,19 +279,6 @@ function structurableAnswerOrThrow(result, GenerateObjectError) {
   }
   return answer;
 }
-
-// src/internal/env.ts
-var API_KEY_ENV_VAR = "THEOKIT_API_KEY";
-function resolveApiKey(explicit) {
-  if (explicit !== void 0 && explicit.length > 0) {
-    return explicit;
-  }
-  const fromEnv = process.env[API_KEY_ENV_VAR];
-  if (fromEnv !== void 0 && fromEnv.length > 0) {
-    return fromEnv;
-  }
-  return void 0;
-}
 var PREFIX = {
   localAgent: "agent-",
   cloudAgent: "bc-",
@@ -568,10 +557,11 @@ function registerAgent(agent) {
 function getRegisteredAgent(agentId) {
   return agents.get(agentId);
 }
-function listRegisteredAgents(runtime, cwd) {
+function listRegisteredAgents(runtime, cwd, includeArchived = false) {
   let out = Array.from(agents.values());
   if (runtime !== void 0) out = out.filter((agent) => agent.runtime === runtime);
   if (cwd !== void 0) out = out.filter((agent) => resolveRegistryCwd(agent) === cwd);
+  if (!includeArchived) out = out.filter((agent) => !agent.archived);
   return out;
 }
 function updateRegisteredAgent(agentId, update) {
@@ -1721,7 +1711,7 @@ var RealCloudRun = class extends FixtureRunBase {
     }
     if (eventName === "result") {
       const update = {
-        finalStatus: parsed.status ?? "finished"
+        finalStatus: parsed.status === void 0 ? "finished" : toRunStatus(parsed.status)
       };
       if (typeof parsed.result === "string") update.finalText = parsed.result;
       return update;
@@ -1733,7 +1723,7 @@ var RealCloudRun = class extends FixtureRunBase {
       type: "status",
       agent_id: this.agentId,
       run_id: this.id,
-      status
+      status: toWireStatus(status)
     };
   }
   buildAssistantEvent(text) {
@@ -1755,6 +1745,43 @@ var RealCloudRun = class extends FixtureRunBase {
     this.transitionTo("error");
   }
 };
+var SERVER_STATUS_TO_RUN_STATUS = {
+  creating: "running",
+  running: "running",
+  finished: "finished",
+  error: "error",
+  cancelled: "cancelled",
+  expired: "error"
+};
+var WIRE_STATUSES = [
+  "CREATING",
+  "RUNNING",
+  "FINISHED",
+  "ERROR",
+  "CANCELLED",
+  "EXPIRED"
+];
+function toWireStatus(token) {
+  if (typeof token === "string") {
+    const upper = token.toUpperCase();
+    const match = WIRE_STATUSES.find((candidate) => candidate === upper);
+    if (match !== void 0) return match;
+  }
+  throw new NetworkError(
+    `Cloud Run stream reported an unrecognised status ${JSON.stringify(token)}; expected one of ${WIRE_STATUSES.join(", ")} (case-insensitive)`,
+    { code: "cloud_run_unknown_status" }
+  );
+}
+function toRunStatus(token) {
+  if (typeof token === "string") {
+    const mapped = SERVER_STATUS_TO_RUN_STATUS[token.toLowerCase()];
+    if (mapped !== void 0) return mapped;
+  }
+  throw new NetworkError(
+    `Cloud Run stream reported an unrecognised status ${JSON.stringify(token)}; expected one of ${Object.keys(SERVER_STATUS_TO_RUN_STATUS).join(", ")} (case-insensitive)`,
+    { code: "cloud_run_unknown_status" }
+  );
+}
 function safeParse(data2) {
   try {
     return JSON.parse(data2);
@@ -1820,6 +1847,7 @@ var CloudAgent = class {
     );
   }
   async send(message, options = {}) {
+    if (this.disposed) throw new AgentDisposedError(this.agentId);
     if (options.tools !== void 0 && options.tools.length > 0) {
       throw new ConfigurationError(
         "Custom inline tools are local-only in SDK v1.0 \u2014 cloud agents cannot serialize handler functions",
@@ -2073,6 +2101,25 @@ function isStdioCommandConfig(config) {
 function isLocalPath(command) {
   return command.startsWith("/") || command.startsWith("~/") || command.startsWith("./") || command.startsWith("../");
 }
+
+// src/internal/persistence/session-dir.ts
+function resolveSessionDir(local) {
+  if (local?.sessionDir !== void 0) {
+    if (local.baseDir !== void 0) {
+      diag(
+        "[theokit-sdk] local.sessionDir and local.baseDir are both set; using sessionDir. baseDir is the deprecated name for the same option (#301)."
+      );
+    }
+    return expandTilde(local.sessionDir);
+  }
+  if (local?.baseDir !== void 0) {
+    diag(
+      "[theokit-sdk] local.baseDir is deprecated; rename it to local.sessionDir (#301). It is the directory for session transcripts, not the working directory \u2014 that is local.cwd."
+    );
+    return expandTilde(local.baseDir);
+  }
+  return defaultBaseDir();
+}
 var SCHEMA_VERSION2 = 1;
 var FILE_NAME = "personality.json";
 function emptyState() {
@@ -3450,6 +3497,9 @@ var langsmithAdapter = {
 
 // src/internal/telemetry/adapters/posthog.ts
 var registeredHere6 = false;
+function presentEnv(value) {
+  return value !== void 0 && value.trim().length > 0 ? value : void 0;
+}
 var posthogAdapter = {
   moduleName: "posthog-node",
   displayName: "PostHog",
@@ -3459,12 +3509,12 @@ var posthogAdapter = {
     const ph = safeRequire("posthog-node");
     const otel = safeRequire("@opentelemetry/api");
     if (ph === void 0 || otel === void 0) return;
-    const key = process.env.POSTHOG_API_KEY ?? process.env.POSTHOG_PROJECT_API_KEY;
+    const key = presentEnv(process.env.POSTHOG_API_KEY) ?? presentEnv(process.env.POSTHOG_PROJECT_API_KEY);
     if (typeof key !== "string" || key.length === 0) {
       return;
     }
     const client = new ph.PostHog(key, {
-      host: process.env.POSTHOG_HOST ?? "https://us.i.posthog.com"
+      host: presentEnv(process.env.POSTHOG_HOST) ?? "https://us.i.posthog.com"
     });
     const provider = otel.trace.getTracerProvider();
     if (provider.addSpanProcessor === void 0) return;
@@ -3742,10 +3792,11 @@ var ProvidersManagerImpl = class {
   routes() {
     const resolved = [];
     const modelProvider = providerFromModel(this.model);
+    const modelId = this.model?.id;
     const seen = /* @__PURE__ */ new Set();
     if (this.providers?.routes !== void 0) {
       for (const route of this.providers.routes) {
-        const resolvedRoute = resolveRoute(route, modelProvider, this.plugins);
+        const resolvedRoute = resolveRoute(route, modelProvider, modelId, this.plugins);
         if (!seen.has(route.capability)) {
           seen.add(route.capability);
           resolved.push(resolvedRoute);
@@ -3761,9 +3812,9 @@ function providerFromModel(model) {
   if (id.includes(":")) return id.split(":")[0];
   return void 0;
 }
-function resolveRoute(route, modelProvider, plugins) {
+function resolveRoute(route, modelProvider, modelId, plugins) {
   if (route.capability === "chat" && modelProvider === route.provider) {
-    const modelName = extractModelName(modelProvider, route);
+    const modelName = extractModelName(modelProvider, modelId, route);
     const base = {
       capability: route.capability,
       provider: route.provider,
@@ -3785,13 +3836,11 @@ function resolveRoute(route, modelProvider, plugins) {
     reason: "explicit-route"
   };
 }
-function extractModelName(prefix, route) {
+function extractModelName(prefix, modelId, route) {
   if (route.model !== void 0) return route.model;
-  return prefix === route.provider ? defaultModelForProvider(prefix) : void 0;
-}
-function defaultModelForProvider(provider) {
-  if (provider === "anthropic") return "claude-3-7-sonnet";
-  return void 0;
+  if (prefix !== route.provider || modelId === void 0) return void 0;
+  const name = modelId.slice(modelId.indexOf(":") + 1);
+  return name.length > 0 ? name : void 0;
 }
 var MAX_MD_FILE_BYTES = 1048576;
 async function loadMarkdownEntities(opts) {
@@ -4109,7 +4158,6 @@ async function loadSources(config, cwd) {
       continue;
     }
     try {
-      await stat(absolute);
       const content = await readFile(absolute, "utf8");
       const tokens = tokenizeContent(content);
       results.push({ ...source, status: "included", tokens });
@@ -4224,6 +4272,21 @@ var PluginsManager = class {
       });
     }
   }
+  /**
+   * B-107 measured this guard as unreachable and it was REMOVED on 2026-08-20. The pre-push gate
+   * caught the regression the same hour: `tests/contract/plugins.contract.test.ts:69` drives
+   * `Agent.create` with `cloud` plus `plugins.paths` and requires a `ConfigurationError`.
+   *
+   * The measurement that said "unreachable" was a `tsc` probe returning TS2353 — `plugins.paths` is
+   * not in the declared `AgentOptions`. That proves the option is undeclarable in TypeScript; it
+   * does NOT prove the value cannot arrive. The contract test casts through a `ProposedAgentOptions`
+   * shape it declares itself, which is exactly what a JavaScript caller, a JSON config or an `as`
+   * cast does. Runtime boundary validation exists for values types cannot stop
+   * (`rules/architecture.md` § 1) — so "the type system forbids it" is never on its own a reason to
+   * delete a boundary check.
+   *
+   * Do not remove this again without making `tests/contract/plugins.contract.test.ts` go red first.
+   */
   assertCloudRules() {
     if (!this.cloud) return;
     if (this.localPaths !== void 0 && this.localPaths.length > 0) {
@@ -4871,7 +4934,13 @@ async function initLoopContext(inputs) {
 }
 async function safeListTools(client, serverName, sink) {
   try {
-    return await client.listTools();
+    const listed = await client.listTools();
+    emitRunEvent(sink, {
+      type: "mcp_server_ready",
+      serverName: serverName ?? "unknown",
+      tools: listed.map((tool) => tool.name)
+    });
+    return listed;
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
     const server = serverName ?? "unknown";
@@ -5023,13 +5092,12 @@ async function streamLlmTurn(inputs, ctx) {
   };
 }
 async function collectLlmEvents(generator, inputs, ctx) {
-  let accumulatedText = "";
   let errored = false;
   let finishValue;
   let thinking;
+  const partial = { text: "" };
   try {
-    const result = await runCollectorLoop(generator, inputs, ctx);
-    accumulatedText = result.accumulatedText;
+    const result = await runCollectorLoop(generator, inputs, ctx, partial);
     errored = result.errored;
     finishValue = result.finishValue;
     thinking = result.thinking;
@@ -5039,10 +5107,12 @@ async function collectLlmEvents(generator, inputs, ctx) {
       ctx.events.push(buildAssistantEvent(inputs, "[aborted]"));
     } else {
       registerLoopError(ctx, cause);
-      ctx.finalText = "";
+      ctx.finalText = partial.text;
+      if (partial.text !== "") ctx.events.push(buildAssistantEvent(inputs, partial.text));
     }
     errored = true;
   }
+  const accumulatedText = partial.text;
   return {
     accumulatedText,
     errored,
@@ -5073,8 +5143,7 @@ async function consumeStreamEvent(inputs, reasoning, event) {
   }
   return "";
 }
-async function runCollectorLoop(generator, inputs, ctx) {
-  let accumulatedText = "";
+async function runCollectorLoop(generator, inputs, ctx, partial) {
   const reasoning = { text: "", startedAt: void 0, signature: void 0 };
   let errored = false;
   let finishValue;
@@ -5088,16 +5157,16 @@ async function runCollectorLoop(generator, inputs, ctx) {
       }
       if (next.value.type === "error") {
         registerLoopError(ctx, next.value);
-        ctx.finalText = "";
+        ctx.finalText = partial.text;
         errored = true;
         break;
       }
-      accumulatedText += await consumeStreamEvent(inputs, reasoning, next.value);
+      partial.text += await consumeStreamEvent(inputs, reasoning, next.value);
     }
   } finally {
     thinking = await finalizeReasoning(inputs, ctx, reasoning);
   }
-  return { accumulatedText, errored, finishValue, ...thinking !== void 0 ? { thinking } : {} };
+  return { errored, finishValue, ...thinking !== void 0 ? { thinking } : {} };
 }
 async function consumeReasoningDelta(inputs, reasoning, delta) {
   if (delta.signature !== void 0) reasoning.signature = delta.signature;
@@ -5919,7 +5988,7 @@ function stripDateSuffix(model) {
   return model.replace(/-\d{4}-?\d{2}-?\d{2}$/, "");
 }
 function normalizeAnthropicDots(model) {
-  return model.replace(/(\d+)\.(\d+)/g, "$1-$2");
+  return model.replace(/(?<=\d)\.(?=\d)/g, "-");
 }
 function stripOpenRouterPrefix(modelId) {
   return modelId.startsWith("openrouter/") ? modelId.slice("openrouter/".length) : modelId;
@@ -6172,6 +6241,12 @@ async function runAgentLoop(inputs) {
     }
     if (budget.shouldContinue() === false && ctx.finalStatus === "finished" && ctx.finalText === "") {
       ctx.finalStatus = "error";
+      if (ctx.error === void 0) {
+        ctx.error = {
+          message: `Run stopped after ${budget.total} iteration(s) without producing a reply \u2014 the model was still calling tools when the budget ran out. Raise \`SendOptions.maxIterations\` (default 8), or inspect \`RunResult.stoppedAtIterationLimit\` to continue the run.`,
+          code: "iteration_limit_reached"
+        };
+      }
     }
     sendSpan?.setAttribute("status", ctx.finalStatus);
     if (ctx.stoppedByDoomLoop === true) sendSpan?.setAttribute("stoppedByDoomLoop", true);
@@ -6735,12 +6810,6 @@ var HttpMcpClient = class extends BaseMcpClient {
       ...this.config.headers ?? {}
     };
   }
-  /**
-   * Capture the session on the FIRST response that carries it (the `initialize`).
-   *
-   * Never overwritten by a later one: a server that re-issues mid-session would otherwise split
-   * the session in two, and the second half would not see the first half's state.
-   */
   /**
    * Read one JSON-RPC response, in either encoding the server may choose.
    *
@@ -6766,6 +6835,12 @@ var HttpMcpClient = class extends BaseMcpClient {
       code: "mcp_http_error"
     });
   }
+  /**
+   * Capture the session on the FIRST response that carries it (the `initialize`).
+   *
+   * Never overwritten by a later one: a server that re-issues mid-session would otherwise split
+   * the session in two, and the second half would not see the first half's state.
+   */
   captureSession(response) {
     if (this.sessionId !== void 0) return;
     const issued = response.headers.get("mcp-session-id");
@@ -7012,9 +7087,10 @@ function resolveRunProvider(options) {
 `);
   }
   const parsedModel = parseModelId(options.model?.id);
-  const modelInferredProvider = parsedModel.provider !== void 0 && getProviderProfile(parsedModel.provider) !== void 0 ? parsedModel.provider : void 0;
+  const modelInferredProvider = parsedModel.provider !== void 0 && getProviderProfile$1(parsedModel.provider) !== void 0 ? parsedModel.provider : void 0;
   const keyInferredProvider = inferProviderFromApiKey(options.agentOptions.apiKey);
   const primary = options.agentOptions.providers?.routes?.[0]?.provider ?? keyInferredProvider ?? modelInferredProvider ?? detectPrimaryProvider();
+  warnProviderPrecedenceOnce(modelInferredProvider, primary);
   const effectiveModelId = modelInferredProvider !== void 0 && modelInferredProvider === primary ? parsedModel.name : options.model?.id ?? "claude-sonnet-4-6";
   return { primary, effectiveModelId };
 }
@@ -7043,8 +7119,10 @@ function buildLoopInputs(options, runId, userText, userImages) {
   const credentialPoolStrategy = options.agentOptions.providers?.credentialPoolStrategy;
   const extractToolCallsFromContent = options.agentOptions.providers?.routes?.[0]?.extractToolCallsFromContent;
   const rateLimitSink = options.sendOptions.onRunEvent;
+  const modelBaseUrl = options.model?.url;
   const chain = resolveProviderChain({
     primary,
+    ...modelBaseUrl !== void 0 ? { baseUrl: modelBaseUrl } : {},
     ...fallback !== void 0 ? { fallback } : {},
     ...apiKeys !== void 0 ? { apiKeys } : {},
     ...credentialPoolStrategy !== void 0 ? { credentialPoolStrategy } : {},
@@ -8448,22 +8526,33 @@ var LocalAgentMemory = class {
 };
 
 // src/internal/local-agent/local-agent-memory-direct.ts
+async function createAvailableAdapters(entries, workspaceCwd) {
+  const available = [];
+  for (const entry of entries) {
+    const instance = await entry.createProvider(workspaceCwd);
+    if (instance.isAvailable() === false) {
+      diag(
+        `[theokit-sdk] memory adapter "${instance.id}" reports itself unavailable (plugin "${entry.pluginName}") \u2014 skipping it. Check its credentials.
+`
+      );
+      continue;
+    }
+    available.push(instance);
+  }
+  return available;
+}
 function buildAgentMemory(pluginManager, workspaceCwd, defaultContext) {
   let resolved;
   async function ensure() {
     if (resolved !== void 0) return resolved;
     const entries = pluginManager.aggregated.memoryProviders;
-    const created = [];
-    for (const entry of entries) {
-      const instance = await entry.createProvider(workspaceCwd);
-      created.push(instance);
-    }
+    const created = await createAvailableAdapters(entries, workspaceCwd);
     for (const adapter of created) {
       if (adapter.initialize !== void 0) {
         await adapter.initialize();
       }
     }
-    resolved = { adapters: created, initialized: true };
+    resolved = { adapters: created, initialized: true, registered: entries.length };
     return resolved;
   }
   function mergeContext(partial) {
@@ -8487,7 +8576,7 @@ function buildAgentMemory(pluginManager, workspaceCwd, defaultContext) {
     const r = await ensure();
     if (r.adapters.length === 0) {
       throw new ConfigurationError(
-        "No memory adapter registered. Pass a memory plugin in AgentOptions.plugins (e.g. supermemoryMemory({...})).",
+        r.registered === 0 ? "No memory adapter registered. Pass a memory plugin in AgentOptions.plugins (e.g. supermemoryMemory({...}))." : `All ${r.registered} registered memory adapter(s) reported themselves unavailable \u2014 see the warnings naming each one. Check their credentials.`,
         { code: "no_memory_adapter" }
       );
     }
@@ -8791,7 +8880,7 @@ function localAgentRunUntil(agent, goal, options) {
   async function* wrap() {
     const { runUntilImpl } = await import('./run-until-HEQOUVU6.js');
     const buildDeps = async () => {
-      const { judgeCallImpl } = await import('./judge-call-QMKGC2ZK.js');
+      const { judgeCallImpl } = await import('./judge-call-DWHAJATE.js');
       const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
       const create = getAgentFacade().create;
       return {
@@ -8812,19 +8901,19 @@ function localAgentRunUntil(agent, goal, options) {
 }
 function localAgentRunToCompletion(agent, message, options) {
   async function run() {
-    const { runToCompletionImpl } = await import('./run-to-completion-JDPIUKSH.js');
+    const { runToCompletionImpl } = await import('./run-to-completion-DRO77625.js');
     return runToCompletionImpl({ send: (m, o) => agent.send(m, o) }, message, options);
   }
   return run();
 }
 async function* localAgentStreamToCompletion(agent, message, options) {
-  const { streamToCompletionImpl } = await import('./stream-to-completion-DFJ5T3BK.js');
+  const { streamToCompletionImpl } = await import('./stream-to-completion-QV5HCL3J.js');
   return yield* streamToCompletionImpl({ send: (m, o) => agent.send(m, o) }, message, options);
 }
 async function localAgentFork(parent, options) {
   const { forkAgentImpl } = await import('./fork-agent-RSV4E3EA.js');
   const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
-  const { withPersonalityContext } = await import('./context-DCECDKWN.js');
+  const { withPersonalityContext } = await import('./context-FDOON2DB.js');
   const create = getAgentFacade().create;
   return withPersonalityContext(
     { slug: parent.personalitySlugSnapshot, isFork: true },
@@ -9074,6 +9163,15 @@ ${recalled}
 ${args.userText}`;
   return typeof args.original === "string" ? wrapped : { ...args.original, text: wrapped };
 }
+async function runCalledATool(run) {
+  try {
+    for await (const event of run.stream()) {
+      if (event.type === "tool_call") return true;
+    }
+  } catch {
+  }
+  return false;
+}
 function wrapRunWithPostReplyHook(args) {
   const handlers = args.pluginManager.hooksFor("post_assistant_reply");
   if (handlers.length === 0) return args.run;
@@ -9085,6 +9183,12 @@ function wrapRunWithPostReplyHook(args) {
       reply: replyText,
       agentId: args.agentId,
       runId: result.id,
+      // #358 — whether this reply is safely replayable. A consumer (the semantic cache) must not
+      // re-serve an answer produced by a tool call, and had nothing to key on. The run knows:
+      // `stream()` replays its buffered events after `wait()` (ADR 0006), so a `tool_call` among
+      // them is the signal. Computed here, inside a path that only runs when a hook is registered
+      // and is already fire-and-forget, so it never lands on the caller's critical path.
+      usedTools: await runCalledATool(args.run),
       ...args.options.memoryContext !== void 0 ? { memoryContext: args.options.memoryContext } : {}
     };
     void args.pluginManager.runPostAssistantReplyHooks(ctx);
@@ -9205,7 +9309,7 @@ async function executeSendLocked(inputs, message, options) {
 function buildCompletionCheckDeps() {
   return {
     judge: async (ctx, opts) => {
-      const { judgeCallImpl } = await import('./judge-call-QMKGC2ZK.js');
+      const { judgeCallImpl } = await import('./judge-call-DWHAJATE.js');
       const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
       return judgeCallImpl(ctx, opts, { create: getAgentFacade().create });
     }
@@ -9257,8 +9361,9 @@ var LocalAgent = class {
   options;
   workspaceCwd;
   /**
-   * SE40 — base dir for the native Claude-shaped session transcript. Default
-   * `~/.theokit`; set `local.baseDir: "~/.claude"` for Claude Code CLI interop.
+   * Directory for the native Claude-shaped session transcript. Default
+   * `~/.theokit`; set `local.sessionDir: "~/.claude"` for Claude Code CLI interop.
+   * (`local.baseDir` is the deprecated name for the same option — #301.)
    */
   transcriptBaseDir;
   /**
@@ -9308,7 +9413,7 @@ var LocalAgent = class {
     this.model = normalizeModel(options.model);
     this.options = options;
     this.workspaceCwd = resolveCwd(options.local?.cwd);
-    this.transcriptBaseDir = resolveBaseDir(options.local?.baseDir);
+    this.transcriptBaseDir = resolveSessionDir(options.local);
     this.sessionStore = options.local?.sessionStore ?? new FsSessionStore({ baseDir: this.transcriptBaseDir, cwd: this.workspaceCwd });
     this.settingSourcesIncludeProject = includesSetting(options, "project");
     this.settingSourcesIncludePlugins = includesSetting(options, "plugins");
@@ -9611,9 +9716,6 @@ var LocalAgent = class {
 function resolveCwd(cwd) {
   return (Array.isArray(cwd) ? cwd[0] : cwd) ?? process.cwd();
 }
-function resolveBaseDir(baseDir) {
-  return baseDir === void 0 ? defaultBaseDir() : expandTilde(baseDir);
-}
 function includesSetting(options, source) {
   const sources = options.local?.settingSources;
   return sources !== void 0 && (sources.includes(source) || sources.includes("all"));
@@ -9687,27 +9789,37 @@ async function maybeInjectHandoffTools(options) {
     tools: [...existingTools, ...handoffTools]
   };
 }
+function keyWillFlowToProvider(apiKey, provider) {
+  if (isFixtureApiKey(apiKey)) return false;
+  if (getConfiguredBaseUrl() !== void 0) return false;
+  if (provider === void 0) return false;
+  const profile = getProviderProfile(provider);
+  if (profile === void 0) return false;
+  return profile.authType !== "none";
+}
+function missingApiKeyMessage() {
+  const present = presentProviderCredentialEnvVars();
+  const base = `Missing API key \u2014 set ${API_KEY_ENV_VAR}, or pass \`apiKey\` to Agent.create()`;
+  if (present.length === 0) return `${base}.`;
+  return `${base}. ${present.join(" and ")} ${present.length === 1 ? "is" : "are"} set, but a provider credential is not read from the environment automatically \u2014 pass it explicitly, e.g. \`Agent.create({ apiKey: process.env.${present[0]}, ... })\`.`;
+}
 async function createLocalAgent(options) {
   const apiKey = resolveApiKey(options.apiKey);
   if (apiKey === void 0) {
-    throw new AuthenticationError("Missing API key", { code: "missing_api_key" });
+    throw new AuthenticationError(missingApiKeyMessage(), { code: "missing_api_key" });
   }
-  const willFlowToProvider = !isFixtureApiKey(apiKey) && !shouldUseRealLocalRuntime(apiKey);
+  const provider = providerFromModelId(normalizeModel(options.model)?.id);
+  const willFlowToProvider = keyWillFlowToProvider(apiKey, provider);
   const shape = validateApiKeyShape(apiKey, {
     strict: willFlowToProvider,
     // `options.model` is already normalized by `runCreateUnderSpan`; `normalizeModel`
     // here is the idempotent narrowing of the widened public type (`{id}` passes
     // through by reference) — cleaner than an `as` cast.
-    ...willFlowToProvider ? { provider: providerFromModelId(normalizeModel(options.model)?.id) } : {}
+    ...willFlowToProvider ? { provider } : {}
   });
   if (shape.malformed) {
     throw new AuthenticationError(shape.message, { code: "malformed_api_key" });
   }
-  if (!isFixtureApiKey(apiKey) && getConfiguredBaseUrl() === void 0 && !shouldUseRealLocalRuntime(apiKey)) {
-    throw new AuthenticationError("Invalid API key", {
-      code: "authentication_error"
-    });
-  }
   const agent = new LocalAgent(options);
   await agent.initialize();
   return agent;
@@ -9828,10 +9940,10 @@ async function setAgentName(agentId, name) {
   updateRegisteredAgent(agentId, { name });
   await flushRegistrySaves();
 }
-async function getRegisteredAgentOrThrow(agentId) {
+async function getRegisteredAgentOrThrow(agentId, cwd = process.cwd()) {
   let agent = getRegisteredAgent(agentId);
   if (agent === void 0) {
-    await hydrateRegistryFromDisk(process.cwd());
+    await hydrateRegistryFromDisk(cwd);
     agent = getRegisteredAgent(agentId);
   }
   if (agent === void 0) {
@@ -9839,6 +9951,22 @@ async function getRegisteredAgentOrThrow(agentId) {
   }
   return agent;
 }
+function paginateByKey(all, keyOf, limit, cursor, sortByKey) {
+  if (limit === void 0) return { items: [...all] };
+  const ordered = sortByKey ? [...all].sort((a, b) => {
+    const ka = keyOf(a);
+    const kb = keyOf(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  }) : [...all];
+  const startIndex = cursor === void 0 ? 0 : ordered.findIndex((item) => keyOf(item) === cursor) + 1;
+  const page = ordered.slice(startIndex, startIndex + limit);
+  const hasMore = startIndex + limit < ordered.length;
+  const last = page[page.length - 1];
+  return {
+    items: page,
+    ...hasMore && last !== void 0 ? { nextCursor: keyOf(last) } : {}
+  };
+}
 
 // src/agent.ts
 var streamObjectImport;
@@ -9892,7 +10020,22 @@ var Agent = class _Agent {
     }
   }
   /**
-   * One-shot prompt: create an agent, send a single message, wait, dispose.
+   * One-shot prompt: create an agent, send a single message, wait, **dispose**.
+   *
+   * `Agent.prompt` is STATIC and owns the agent's whole lifecycle. To send to an
+   * agent you already hold, use the instance method — `agent.send(message)` —
+   * which keeps the conversation and does not dispose anything:
+   *
+   * ```ts
+   * const agent = await Agent.create({ ... });
+   * const run = await agent.send("first");     // NOT agent.prompt(...)
+   * const run2 = await agent.send("follow-up"); // full context retained
+   * ```
+   *
+   * There is no `agent.prompt()` (#302). The natural sentence for the second
+   * operation is "prompt the agent", so it is the method people reach for; the
+   * two differ in whether the agent survives the call, which is why they do not
+   * share a name.
    *
    * When `options.throwOnError === true`, rejects with `AgentRunError` if
    * the run terminates with `status: 'error'` (instead of resolving with the
@@ -9963,7 +10106,7 @@ var Agent = class _Agent {
    * @public
    */
   static async generateObject(options) {
-    const { generateObjectImpl } = await import('./generate-object-TVQCW2IZ.js');
+    const { generateObjectImpl } = await import('./generate-object-N5MDZUJI.js');
     return generateObjectImpl(options, {
       create: (opts) => _Agent.create(opts),
       delete: (agentId) => _Agent.delete(agentId)
@@ -9987,7 +10130,7 @@ var Agent = class _Agent {
       delete: (agentId) => _Agent.delete(agentId)
     };
     async function* wrapper() {
-      streamObjectImport ??= import('./stream-object-QMNR3YFF.js');
+      streamObjectImport ??= import('./stream-object-L57K4OFS.js');
       const { streamObjectImpl } = await streamObjectImport;
       yield* streamObjectImpl(options, deps);
     }
@@ -10011,7 +10154,7 @@ var Agent = class _Agent {
    * @public
    */
   static async batch(prompts, options) {
-    const { batchImpl } = await import('./batch-NLIS4QTW.js');
+    const { batchImpl } = await import('./batch-2TGJMNCJ.js');
     return batchImpl(prompts, options, { create: (opts) => _Agent.create(opts) });
   }
   /**
@@ -10055,34 +10198,57 @@ var Agent = class _Agent {
     return fresh;
   }
   /**
-   * List agents (local or cloud). M107 — `cwd` is READ now, not ignored;
-   * `limit`/`cursor` still are not (see `tests/agent-list-cwd.test.ts`).
+   * List agents (local or cloud). M107 — `cwd` is READ, not ignored. B-115 (2026-08-19) —
+   * `includeArchived` and `limit`/`cursor` are READ too now; see `ListAgentsOptions`'s doc for the
+   * pagination contract and why the unlimited (no `limit`) case is unaffected.
    *
    * @public
    */
   static async list(options = {}) {
     const cwd = ("cwd" in options ? options.cwd : void 0) ?? process.cwd();
     await hydrateRegistryFromDisk(cwd);
-    const items = listRegisteredAgents(options.runtime, cwd).map((agent) => toAgentInfo(agent));
-    return { items };
+    const includeArchived = "includeArchived" in options ? options.includeArchived ?? false : false;
+    const agents2 = listRegisteredAgents(options.runtime, cwd, includeArchived);
+    const { items, nextCursor } = paginateByKey(
+      agents2,
+      (agent) => agent.agentId,
+      options.limit,
+      options.cursor,
+      /* sortByKey */
+      true
+    );
+    return {
+      items: items.map((agent) => toAgentInfo(agent)),
+      ...nextCursor !== void 0 ? { nextCursor } : {}
+    };
   }
   /**
-   * Get metadata for a single agent.
+   * Get metadata for a single agent. B-115 (2026-08-19) — `cwd` is READ now (see
+   * `GetAgentOptions`'s doc); it used to be accepted and silently ignored.
    *
    * @public
    */
-  static async get(agentId, _options = {}) {
-    const agent = await getRegisteredAgentOrThrow(agentId);
+  static async get(agentId, options = {}) {
+    const agent = await getRegisteredAgentOrThrow(agentId, options.cwd);
     return toAgentInfo(agent);
   }
   /**
-   * List runs for an agent.
+   * List runs for an agent. B-115 (2026-08-19) — `cwd` and `limit`/`cursor` are READ now (see
+   * `ListRunsOptions`'s doc); they used to be accepted and silently ignored.
    *
    * @public
    */
-  static async listRuns(agentId, _options = {}) {
-    await getRegisteredAgentOrThrow(agentId);
-    return { items: listRunsByAgent(agentId) };
+  static async listRuns(agentId, options = {}) {
+    await getRegisteredAgentOrThrow(agentId, options.cwd);
+    const { items, nextCursor } = paginateByKey(
+      listRunsByAgent(agentId),
+      (run) => run.id,
+      options.limit,
+      options.cursor,
+      /* sortByKey */
+      false
+    );
+    return { items, ...nextCursor !== void 0 ? { nextCursor } : {} };
   }
   /**
    * Get a single run.
@@ -10149,7 +10315,7 @@ var Agent = class _Agent {
         `No local agent "${agentId}" registered \u2014 compact targets local sessions.`
       );
     }
-    const { compactSessionTranscript, buildDefaultSummarizer: buildDefaultSummarizer2 } = await import('./compact-session-EJ36VH5I.js');
+    const { compactSessionTranscript, buildDefaultSummarizer: buildDefaultSummarizer2 } = await import('./compact-session-K5LXTBPJ.js');
     const { cwd, model, store } = await openLocalStore(reg);
     return enqueueSessionWrite(
       cwd,
@@ -10185,7 +10351,7 @@ var Agent = class _Agent {
         `No local agent "${agentId}" registered \u2014 injectSessionTurn targets local sessions.`
       );
     }
-    const { injectSessionTurn } = await import('./inject-session-HO7FYVCX.js');
+    const { injectSessionTurn } = await import('./inject-session-DDR6X6PC.js');
     const { cwd, model, store } = await openLocalStore(reg);
     await injectSessionTurn({
       store,
@@ -10224,7 +10390,7 @@ var Agent = class _Agent {
         `No local agent "${agentId}" registered \u2014 transcript targets local sessions.`
       );
     }
-    const { readSessionMessages } = await import('./agent-session-store-JMU7ASDB.js');
+    const { readSessionMessages } = await import('./agent-session-store-P6V3FINW.js');
     const { store } = await openLocalStore(reg);
     return readSessionMessages(store, agentId);
   }
@@ -10245,7 +10411,7 @@ var Agent = class _Agent {
    */
   static async describe(agentId) {
     const agent = await getRegisteredAgentOrThrow(agentId);
-    const { loadSubagents: loadSubagents2 } = await import('./subagents-loader-WN2SB6PV.js');
+    const { loadSubagents: loadSubagents2 } = await import('./subagents-loader-J54ESLDV.js');
     const settingSources = agent.options.local?.settingSources;
     const subagents = await loadSubagents2(
       agent.cwd ?? process.cwd(),
@@ -10312,12 +10478,13 @@ async function openLocalStore(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 import('./fs-session-store-LIKYT24K.js');
-  const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await import('./session-transcript-SKIRBEJE.js');
-  const baseDir = reg.options.local?.baseDir !== void 0 ? expandTilde2(reg.options.local.baseDir) : defaultBaseDir2();
+  const { FsSessionStore: FsSessionStore2 } = await import('./fs-session-store-IN7JTTXD.js');
+  const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await import('./session-transcript-AKDYYGXQ.js');
+  const configuredSessionDir = reg.options.local?.sessionDir ?? reg.options.local?.baseDir;
+  const baseDir = configuredSessionDir !== void 0 ? expandTilde2(configuredSessionDir) : defaultBaseDir2();
   return { cwd, model, store: new FsSessionStore2({ baseDir, cwd }) };
 }
 
-export { Agent, AgentBuilder, DEFAULT_AGENTIC_MODEL_ID, MEMORY_EMBEDDING_ADAPTERS, Tool, ToolError, UsageAccumulator, computeCost, generateCronId, getPricingEntry, openRouterMemoryEmbeddingProviderAdapter, resolveApiKey };
-//# sourceMappingURL=chunk-NZOR3N4E.js.map
-//# sourceMappingURL=chunk-NZOR3N4E.js.map
+export { Agent, AgentBuilder, DEFAULT_AGENTIC_MODEL_ID, MEMORY_EMBEDDING_ADAPTERS, Tool, ToolError, UsageAccumulator, computeCost, generateCronId, getPricingEntry, openRouterMemoryEmbeddingProviderAdapter };
+//# sourceMappingURL=chunk-TPTZA6NI.js.map
+//# sourceMappingURL=chunk-TPTZA6NI.js.map