@theokit/sdk 2.15.2 → 2.18.1

package/dist/a2a/index.js

@@ -1,7 +1,7 @@
 import { existsSync, realpathSync, mkdirSync, lstatSync, readlinkSync, readFileSync, readdirSync } from 'fs';
 import { randomUUID, createHash, randomBytes } from 'crypto';
 import { join, dirname, resolve, sep, relative, isAbsolute } from 'path';
-import { stat, mkdir, readFile, rename, rm, readdir, appendFile, open, unlink, statfs, access } from 'fs/promises';
+import { stat, mkdir, readFile, rename, rm, readdir, open, unlink, appendFile, statfs, access } from 'fs/promises';
 import { homedir } from 'os';
 import { z, toJSONSchema } from 'zod';
 import { createRequire } from 'module';
@@ -2545,13 +2545,13 @@ var init_cloud_run = __esm({
 });
 
 // src/internal/llm/sse.ts
-async function* parseSseStream(body, signal) {
+async function* parseSseStream(body, signal, idleTimeoutMs = DEFAULT_SSE_IDLE_MS) {
   if (body === null) return;
   const reader = body.getReader();
   const decoder = new TextDecoder("utf-8");
   const state2 = { buffer: "", event: "message", data: "" };
   try {
-    for await (const chunk of readChunks(reader, signal)) {
+    for await (const chunk of readChunks(reader, signal, idleTimeoutMs)) {
       state2.buffer += decoder.decode(chunk, { stream: true });
       for (const record of drainCompleteRecords(state2)) yield record;
     }
@@ -2561,14 +2561,38 @@ async function* parseSseStream(body, signal) {
     releaseReader(reader);
   }
 }
-async function* readChunks(reader, signal) {
+async function* readChunks(reader, signal, idleTimeoutMs) {
   while (true) {
     if (signal.aborted) return;
-    const { value, done } = await reader.read();
+    const { value, done } = await readWithIdleTimeout(reader, idleTimeoutMs);
     if (done) return;
     if (value !== void 0) yield value;
   }
 }
+function readWithIdleTimeout(reader, idleTimeoutMs) {
+  if (idleTimeoutMs <= 0) return reader.read();
+  return new Promise(
+    (resolve3, reject) => {
+      const timer = setTimeout(() => {
+        reject(
+          new NetworkError(`SSE stream idle for ${idleTimeoutMs}ms \u2014 upstream stalled`, {
+            code: "stream_idle_timeout"
+          })
+        );
+      }, idleTimeoutMs);
+      reader.read().then(
+        (result) => {
+          clearTimeout(timer);
+          resolve3(result);
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      );
+    }
+  );
+}
 async function cancelReaderQuietly(reader) {
   try {
     await reader.cancel();
@@ -2619,8 +2643,11 @@ function releaseReader(reader) {
   } catch {
   }
 }
+var DEFAULT_SSE_IDLE_MS;
 var init_sse = __esm({
   "src/internal/llm/sse.ts"() {
+    init_errors();
+    DEFAULT_SSE_IDLE_MS = 6e4;
   }
 });
 
@@ -3569,9 +3596,16 @@ var init_context = __esm({
 });
 
 // src/internal/plugins/manager.ts
+function removeAll(arr, toRemove) {
+  for (const item of toRemove) {
+    const idx = arr.indexOf(item);
+    if (idx !== -1) arr.splice(idx, 1);
+  }
+}
 var PluginManager;
 var init_manager = __esm({
   "src/internal/plugins/manager.ts"() {
+    init_errors();
     init_context();
     PluginManager = class {
       #aggregated = {
@@ -3583,6 +3617,9 @@ var init_manager = __esm({
         memoryProviders: []
       };
       #initialized = false;
+      // #68 — registrations of plugins added post-init via `register()`, keyed by
+      // plugin name so a re-register REPLACES (not appends) the prior hooks.
+      #byName = /* @__PURE__ */ new Map();
       async initialize(plugins) {
         if (this.#initialized) {
           throw new Error("PluginManager.initialize called twice \u2014 register only once per process");
@@ -3600,6 +3637,36 @@ var init_manager = __esm({
           await this.#dispatchPlugin(plugin);
         }
       }
+      /**
+       * #68 — register a single `general` plugin AFTER `initialize()` has run.
+       *
+       * The bulk `initialize()` is single-shot (one call per process); late
+       * registration is a distinct, named operation used by adapters that install
+       * a plugin per-session/per-request (e.g. the ACP permission veto, which is
+       * installed once the permission mode + connection are known — after the
+       * agent's own plugins were already initialized).
+       *
+       * Idempotent by plugin NAME: re-registering a plugin with the same name
+       * REPLACES its prior hooks/tools instead of appending duplicates (the ACP
+       * permission plugin is re-installed on every prompt).
+       *
+       * Only `general` plugins may be registered late — model-provider / memory
+       * plugins are resolved during the bulk init and cannot be added afterwards.
+       */
+      async register(plugin) {
+        if (plugin.kind !== "general") {
+          throw new ConfigurationError(
+            `late register supports general plugins only (got "${plugin.kind}" for "${plugin.name}")`,
+            { code: "plugin_late_register_kind" }
+          );
+        }
+        const prior = this.#byName.get(plugin.name);
+        if (prior !== void 0) this.#unmerge(prior);
+        const { ctx, registrations } = createPluginContext();
+        await plugin.register(ctx);
+        this.#byName.set(plugin.name, registrations);
+        this.#merge(registrations);
+      }
       get aggregated() {
         return this.#aggregated;
       }
@@ -3680,6 +3747,64 @@ var init_manager = __esm({
           }
         }
       }
+      // #65 — the previously-dead hooks, now wired. Fire-and-forget hooks run
+      // in order (per-handler errors logged, never thrown); transform hooks fold
+      // over the payload (a handler returning a value replaces it).
+      /** @internal */
+      async #runFireAndForget(name, ctx) {
+        for (const h of this.#aggregated.hooks.get(name) ?? []) {
+          try {
+            await h(ctx);
+          } catch (err) {
+            process.stderr.write(
+              `[theokit-sdk] ${name} hook failed: ${err instanceof Error ? err.message : String(err)}
+`
+            );
+          }
+        }
+      }
+      /** @internal — fold: each handler may return a replacement payload; a throw keeps the prior value. */
+      async #runTransform(name, payload, ctx) {
+        let current = payload;
+        for (const h of this.#aggregated.hooks.get(name) ?? []) {
+          try {
+            const out = await h(current, ctx);
+            if (out !== void 0) current = out;
+          } catch (err) {
+            process.stderr.write(
+              `[theokit-sdk] ${name} hook failed: ${err instanceof Error ? err.message : String(err)}
+`
+            );
+          }
+        }
+        return current;
+      }
+      /** #65 — fired after a tool call completes. @internal */
+      runPostToolCallHooks(ctx) {
+        return this.#runFireAndForget("post_tool_call", ctx);
+      }
+      /** #65 — fired before / after each LLM turn. @internal */
+      runPreLlmCallHooks(ctx) {
+        return this.#runFireAndForget("pre_llm_call", ctx);
+      }
+      runPostLlmCallHooks(ctx) {
+        return this.#runFireAndForget("post_llm_call", ctx);
+      }
+      /** #65 — fired at run start / end. @internal */
+      runOnSessionStartHooks(ctx) {
+        return this.#runFireAndForget("on_session_start", ctx);
+      }
+      runOnSessionEndHooks(ctx) {
+        return this.#runFireAndForget("on_session_end", ctx);
+      }
+      /** #65/#57 — transform tool results before they reach the LLM (the #57 seam). @internal */
+      runTransformToolResultHooks(results, ctx) {
+        return this.#runTransform("transform_tool_result", results, ctx);
+      }
+      /** #65 — transform the LLM output text before it is consumed. @internal */
+      runTransformLlmOutputHooks(output, ctx) {
+        return this.#runTransform("transform_llm_output", output, ctx);
+      }
       async #dispatchPlugin(plugin) {
         if (plugin.kind === "general") {
           const { ctx, registrations } = createPluginContext();
@@ -3707,6 +3832,22 @@ var init_manager = __esm({
         }
         this.#aggregated.injected.push(...r.injected);
       }
+      /**
+       * #68 — inverse of #merge: remove a prior registration's contributions from
+       * the aggregated view by object identity. Used by `register()` to replace a
+       * same-named plugin's hooks/tools instead of accumulating duplicates.
+       */
+      #unmerge(r) {
+        removeAll(this.#aggregated.tools, r.tools);
+        removeAll(this.#aggregated.commands, r.commands);
+        removeAll(this.#aggregated.injected, r.injected);
+        for (const [hook, handlers] of r.hooks.entries()) {
+          const existing = this.#aggregated.hooks.get(hook);
+          if (existing === void 0) continue;
+          removeAll(existing, handlers);
+          if (existing.length === 0) this.#aggregated.hooks.delete(hook);
+        }
+      }
     };
   }
 });
@@ -3731,7 +3872,12 @@ var init_span_names = __esm({
       LLM_CALL: "llm.call"
     };
     HISTOGRAM_NAMES = {
-      MEMORY_RECALL_DURATION_MS: "theokit_memory_recall_duration_ms"
+      MEMORY_RECALL_DURATION_MS: "theokit_memory_recall_duration_ms",
+      TOOL_CALL_DURATION_MS: "theokit_tool_call_duration_ms",
+      LLM_CALL_DURATION_MS: "theokit_llm_call_duration_ms",
+      LLM_TOKENS: "theokit_llm_tokens",
+      /** M3 #66 — count of finishes where the provider omitted usage (silent undercount). */
+      LLM_USAGE_MISSING: "theokit_llm_usage_missing"
     };
   }
 });
@@ -4096,7 +4242,25 @@ function createTelemetry(settings) {
     enabled: true,
     includeContent: settings.includeContent === true,
     startSpan: startNewSpan,
-    startChildSpan: (_parent, name, attrs) => startNewSpan(name, attrs),
+    // M3 #64 — actually nest the child under its parent instead of discarding it.
+    // The parent's SpanContext is set on a fresh OTel context so the child links
+    // to it (traceId + parentSpanId), reconstructing the causal trace tree. Falls
+    // back to a root span when the parent has no valid span id (telemetry off /
+    // NOOP), preserving the pre-M3 behavior for parentless callers.
+    startChildSpan: (parent, name, attrs) => {
+      const redactedAttrs = attrs === void 0 ? void 0 : redactAttrs(attrs);
+      const opts = redactedAttrs ? { attributes: redactedAttrs } : void 0;
+      const pctx = safe(() => parent?.spanContext(), void 0);
+      const span = safe(() => {
+        if (pctx !== void 0 && pctx.spanId !== "0".repeat(16)) {
+          const childCtx = otel.trace.setSpanContext(otel.context.active(), pctx);
+          return tracer.startSpan(name, opts, childCtx);
+        }
+        return tracer.startSpan(name, opts);
+      }, NOOP_SPAN);
+      if (span !== NOOP_SPAN) openSpans.add(span);
+      return wrapSpan(span, openSpans);
+    },
     recordHistogram,
     endAll: () => {
       for (const span of openSpans) safe(() => span.end(), void 0);
@@ -4166,12 +4330,65 @@ var init_tracer = __esm({
     warnedOnce = false;
   }
 });
+
+// src/internal/runtime/lifecycle/env-policy.ts
+function isSecretName(name) {
+  return SECRET_PATTERNS.some((re) => re.test(name));
+}
+function inheritsUnderPolicy(name, policy) {
+  if (policy === "all") return true;
+  if (policy === "core") return CORE_VARS.includes(name);
+  return !isSecretName(name);
+}
+function resolveChildEnv(options = {}) {
+  const parent = options.parent ?? process.env;
+  const policy = options.policy ?? "inherit-scrubbed";
+  const base = {};
+  for (const [name, value] of Object.entries(parent)) {
+    if (value !== void 0 && inheritsUnderPolicy(name, policy)) base[name] = value;
+  }
+  for (const [name, value] of Object.entries(options.overrides ?? {})) {
+    base[name] = value;
+  }
+  return base;
+}
+var SECRET_PATTERNS, CORE_VARS;
+var init_env_policy = __esm({
+  "src/internal/runtime/lifecycle/env-policy.ts"() {
+    SECRET_PATTERNS = [
+      /KEY/i,
+      /SECRET/i,
+      /TOKEN/i,
+      /PASSWORD/i,
+      /PASSWD/i,
+      /PASSPHRASE/i,
+      /[_-]PWD/i,
+      /CREDENTIAL/i,
+      /PRIVATE/i,
+      /_AUTH/i
+    ];
+    CORE_VARS = [
+      "PATH",
+      "HOME",
+      "SHELL",
+      "LANG",
+      "LC_ALL",
+      "LC_CTYPE",
+      "TMPDIR",
+      "TMP",
+      "TEMP",
+      "USER",
+      "LOGNAME"
+    ];
+  }
+});
 function spawnAndCollect(options) {
   return new Promise((resolve3) => {
     const timeoutMs = options.timeoutMs ?? 3e4;
     const spawnOptions = {
       cwd: options.cwd,
-      env: { ...process.env, ...options.env ?? {} }
+      // #54 — scrub secret-like parent env by default; `options.env` still wins.
+      env: resolveChildEnv({ policy: options.envPolicy, overrides: options.env })
     };
     const child = spawn(options.command, options.args ?? [], spawnOptions);
     let stdout = "";
@@ -4212,6 +4429,7 @@ function spawnAndCollect(options) {
 }
 var init_spawn_collect = __esm({
   "src/internal/runtime/lifecycle/spawn-collect.ts"() {
+    init_env_policy();
   }
 });
 
@@ -4400,15 +4618,24 @@ function warnMalformed(agentId, line) {
 `
   );
 }
+function hydrateSessionLine(parsed) {
+  if (typeof parsed.text !== "string" || parsed.role === void 0) return void 0;
+  if (parsed.role === "user" || parsed.role === "assistant") {
+    return { role: parsed.role, text: parsed.text };
+  }
+  if (parsed.role === "tool_call" || parsed.role === "tool_result") {
+    const label = parsed.role === "tool_call" ? "tool call" : "tool result";
+    return { role: "assistant", text: `[${label}] ${parsed.text}` };
+  }
+  return void 0;
+}
 async function readSessionFile(cwd, agentId) {
   const lines = await readJsonlLines(cwd, agentId);
   const messages = [];
   for (const line of lines) {
     try {
-      const parsed = JSON.parse(line);
-      if ((parsed.role === "user" || parsed.role === "assistant") && typeof parsed.text === "string") {
-        messages.push({ role: parsed.role, text: parsed.text });
-      }
+      const msg = hydrateSessionLine(JSON.parse(line));
+      if (msg !== void 0) messages.push(msg);
     } catch {
       warnMalformed(agentId, line);
     }
@@ -4435,29 +4662,70 @@ async function readAllPersistedMessages(cwd, agentId) {
   return messages;
 }
 async function appendAnyPersistedMessage(cwd, agentId, record) {
-  const path = sessionFilePath(cwd, agentId);
-  await mkdir(dirname(path), { recursive: true });
-  await appendFile(path, `${redactSecrets(JSON.stringify(record))}
-`, "utf8");
+  await appendPersistedMessages(cwd, agentId, [record]);
 }
-async function compactSessionFile(cwd, agentId, maxTurns) {
+async function appendPersistedMessages(cwd, agentId, records) {
+  if (records.length === 0) return;
   const path = sessionFilePath(cwd, agentId);
-  let raw;
+  const payload = records.map((r) => `${redactSecrets(JSON.stringify(r))}
+`).join("");
+  const dir = dirname(path);
+  let written = false;
+  const attempt = async () => {
+    await mkdir(dir, { recursive: true });
+    await withFileLock(path, async () => {
+      await appendFile(path, payload, "utf8");
+      written = true;
+    });
+  };
   try {
-    raw = await readFile(path, "utf8");
-  } catch {
-    return;
+    await attempt();
+  } catch (cause) {
+    if (written || cause.code !== "ENOENT") throw cause;
+    await attempt();
   }
-  const lines = raw.split("\n").filter((line) => line.length > 0);
-  if (lines.length <= maxTurns * 2) return;
-  const trimmed = `${lines.slice(-maxTurns).join("\n")}
+}
+async function rewriteLockedSession(path, transform) {
+  await withFileLock(path, async () => {
+    let raw;
+    try {
+      raw = await readFile(path, "utf8");
+    } catch {
+      return;
+    }
+    const lines = raw.split("\n").filter((line) => line.length > 0);
+    const next = transform(lines);
+    if (next === void 0) return;
+    await replaceFileAtomic(path, next);
+  });
+}
+async function compactSessionFile(cwd, agentId, maxTurns) {
+  const path = sessionFilePath(cwd, agentId);
+  if (!existsSync(path)) return;
+  await rewriteLockedSession(
+    path,
+    (lines) => lines.length <= maxTurns * 2 ? void 0 : `${lines.slice(-maxTurns).join("\n")}
+`
+  );
+}
+async function truncateSessionTo(cwd, agentId, keepCount) {
+  const path = sessionFilePath(cwd, agentId);
+  if (!existsSync(path)) return 0;
+  let kept = 0;
+  await rewriteLockedSession(path, (lines) => {
+    const keep = Math.max(0, Math.min(keepCount, lines.length));
+    kept = keep;
+    if (keep === lines.length) return void 0;
+    return keep === 0 ? "" : `${lines.slice(0, keep).join("\n")}
 `;
-  await replaceFileAtomic(path, trimmed);
+  });
+  return kept;
 }
 var VALID_ROLES;
 var init_agent_session_store = __esm({
   "src/internal/runtime/session/agent-session-store.ts"() {
     init_atomic_write();
+    init_file_lock();
     init_security();
     VALID_ROLES = /* @__PURE__ */ new Set([
       "user",
@@ -4468,6 +4736,18 @@ var init_agent_session_store = __esm({
     ]);
   }
 });
+
+// src/internal/persistence/pagination.ts
+function paginate(items, opts) {
+  if (opts === void 0 || opts.offset === void 0 && opts.limit === void 0) return items;
+  const start = Math.max(0, opts.offset ?? 0);
+  const end = opts.limit === void 0 ? items.length : start + Math.max(0, opts.limit);
+  return items.slice(start, end);
+}
+var init_pagination = __esm({
+  "src/internal/persistence/pagination.ts"() {
+  }
+});
 function toStoredMessage(record) {
   return {
     role: record.role,
@@ -4475,11 +4755,15 @@ function toStoredMessage(record) {
     at: record.at
   };
 }
+function toRecord(message) {
+  return { role: message.role, text: message.content, at: message.at ?? Date.now() };
+}
 var FileSystemConversationStorage;
 var init_conversation_storage_fs = __esm({
   "src/internal/persistence/conversation-storage-fs.ts"() {
     init_agent_session_store();
     init_security();
+    init_pagination();
     FileSystemConversationStorage = class {
       #root;
       constructor(opts = {}) {
@@ -4489,23 +4773,31 @@ var init_conversation_storage_fs = __esm({
       get root() {
         return this.#root;
       }
-      async getMessages(conversationId) {
+      async getMessages(conversationId, opts) {
         const records = await readAllPersistedMessages(this.#root, conversationId);
-        return records.map(toStoredMessage);
+        const all = records.map(toStoredMessage);
+        return paginate(all, opts);
       }
       async appendMessage(conversationId, message) {
-        const record = {
-          role: message.role,
-          text: message.content,
-          at: message.at ?? Date.now()
-        };
-        await appendAnyPersistedMessage(this.#root, conversationId, record);
+        await appendAnyPersistedMessage(this.#root, conversationId, toRecord(message));
+      }
+      async appendMessages(conversationId, messages) {
+        await appendPersistedMessages(this.#root, conversationId, messages.map(toRecord));
+      }
+      async truncateConversation(conversationId, keepCount) {
+        return truncateSessionTo(this.#root, conversationId, keepCount);
       }
       async deleteConversation(conversationId) {
         const safe2 = sanitizeIdentifier(conversationId, { maxLen: 128 });
         const dirPath = safePathJoin(this.#root, ".theokit", "agents", safe2);
         await rm(dirPath, { recursive: true, force: true });
       }
+      async deleteScope(prefix) {
+        const ids = await this.listConversationIds();
+        const matching = ids.filter((id) => id.startsWith(prefix));
+        for (const id of matching) await this.deleteConversation(id);
+        return matching.length;
+      }
       async listConversationIds(opts = {}) {
         const agentsRoot = safePathJoin(this.#root, ".theokit", "agents");
         let entries;
@@ -4602,12 +4894,19 @@ async function readPersistedForCache(adapter, agentId) {
   const records = await adapter.getMessages(agentId);
   const out = [];
   for (const r of records) {
-    if (r.role === "user" || r.role === "assistant") {
-      out.push({ role: r.role, text: r.content });
-    }
+    const folded = foldStoredToSession(r);
+    if (folded !== void 0) out.push(folded);
   }
   return out;
 }
+function foldStoredToSession(r) {
+  if (r.role === "user" || r.role === "assistant") return { role: r.role, text: r.content };
+  if (r.role === "tool_call" || r.role === "tool_result") {
+    const label = r.role === "tool_call" ? "tool call" : "tool result";
+    return { role: "assistant", text: `[${label}] ${r.content}` };
+  }
+  return void 0;
+}
 async function flushSessionWrites() {
   while (pendingAppends.size > 0) {
     const all = Array.from(pendingAppends.values());
@@ -7178,11 +7477,32 @@ function reasoningEffortFromParams(params) {
   const thinking = params?.find((p) => p.id === "thinking");
   return thinking !== void 0 && thinking.value.length > 0 ? thinking.value : void 0;
 }
+function emitLlmMetrics(inputs, result, startAt) {
+  inputs.telemetry?.recordHistogram(HISTOGRAM_NAMES.LLM_CALL_DURATION_MS, Date.now() - startAt, {
+    provider: inputs.llm.name
+  });
+  if (result.inputTokens === void 0 && result.outputTokens === void 0) {
+    inputs.telemetry?.recordHistogram(HISTOGRAM_NAMES.LLM_USAGE_MISSING, 1, {
+      provider: inputs.llm.name
+    });
+    process.stderr.write(
+      `[theokit-sdk] llm usage missing from ${inputs.llm.name} finish \u2014 budget may undercount
+`
+    );
+    return;
+  }
+  inputs.telemetry?.recordHistogram(
+    HISTOGRAM_NAMES.LLM_TOKENS,
+    (result.inputTokens ?? 0) + (result.outputTokens ?? 0),
+    { provider: inputs.llm.name }
+  );
+}
 async function streamLlmTurn(inputs, ctx) {
-  const llmSpan = inputs.telemetry?.startSpan("llm.call", {
+  const llmSpan = inputs.telemetry?.startChildSpan(ctx.sendSpan, "llm.call", {
     "model.id": inputs.model.id ?? "auto",
     provider: inputs.llm.name
   });
+  const startAt = Date.now();
   const signal = inputs.signal ?? new AbortController().signal;
   const generator = inputs.llm.stream(
     {
@@ -7225,6 +7545,7 @@ async function streamLlmTurn(inputs, ctx) {
     inputTokens: result.inputTokens ?? 0,
     outputTokens: result.outputTokens ?? 0
   });
+  emitLlmMetrics(inputs, result, startAt);
   llmSpan?.end();
   const stripped = stripThinkBlocks(collected.accumulatedText);
   return {
@@ -7321,6 +7642,7 @@ async function emitReasoningDeltaCallback(inputs, text) {
 var init_loop_llm_stream = __esm({
   "src/internal/agent-loop/loop-llm-stream.ts"() {
     init_safe_call();
+    init_span_names();
     init_strip_think();
     init_message_builders();
   }
@@ -7539,21 +7861,21 @@ async function executeTool(inputs, resolved, call) {
   }
   if (resolved.origin === "shell") return runShellTool(inputs, call);
   if (resolved.origin === "memory") return runMemoryTool(resolved, call);
-  if (resolved.origin === "custom") return runCustomTool(resolved, call);
+  if (resolved.origin === "custom") return runCustomTool(resolved, call, inputs.signal);
   return runMcpTool(inputs, resolved, call);
 }
 async function runMemoryTool(resolved, call) {
   return runHandlerTool("memory", resolved.memoryHandler, call);
 }
-async function runCustomTool(resolved, call) {
-  return runHandlerTool("custom", resolved.customHandler, call);
+async function runCustomTool(resolved, call, signal) {
+  return runHandlerTool("custom", resolved.customHandler, call, signal);
 }
-async function runHandlerTool(kind, handler, call) {
+async function runHandlerTool(kind, handler, call, signal) {
   if (handler === void 0) {
     return { stdout: "", stderr: `${kind} tool ${call.name} has no handler`, exitCode: 127 };
   }
   try {
-    const stdout = await handler(call.input);
+    const stdout = await handler(call.input, { signal });
     return { stdout, stderr: "", exitCode: 0 };
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
@@ -7604,22 +7926,71 @@ var init_tool_executors = __esm({
   }
 });
 
+// src/internal/agent-loop/tool-timeout.ts
+function abortedResult(signal) {
+  const reason = signal.reason;
+  const timedOut = reason?.name === "TimeoutError";
+  return {
+    stdout: "",
+    stderr: timedOut ? "tool execution timed out" : "tool execution aborted",
+    exitCode: TOOL_ABORTED_EXIT
+  };
+}
+function raceToolExecution(exec, opts) {
+  const { signal, timeoutMs } = opts;
+  if (signal === void 0 && timeoutMs === void 0) return exec;
+  const signals = [];
+  if (signal !== void 0) signals.push(signal);
+  if (timeoutMs !== void 0) signals.push(AbortSignal.timeout(timeoutMs));
+  const merged = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+  if (merged.aborted) return Promise.resolve(abortedResult(merged));
+  return new Promise((resolve3, reject) => {
+    let settled = false;
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      resolve3(abortedResult(merged));
+    };
+    merged.addEventListener("abort", onAbort, { once: true });
+    exec.then(
+      (r) => {
+        if (settled) return;
+        settled = true;
+        merged.removeEventListener("abort", onAbort);
+        resolve3(r);
+      },
+      (e) => {
+        if (settled) return;
+        settled = true;
+        merged.removeEventListener("abort", onAbort);
+        reject(e);
+      }
+    );
+  });
+}
+var TOOL_ABORTED_EXIT;
+var init_tool_timeout = __esm({
+  "src/internal/agent-loop/tool-timeout.ts"() {
+    TOOL_ABORTED_EXIT = 124;
+  }
+});
+
 // src/internal/agent-loop/tool-dispatch.ts
-async function dispatchTools(inputs, tools, toolCalls, events) {
+async function dispatchTools(inputs, tools, toolCalls, events, parentSpan) {
   const maxConcurrent = inputs.maxConcurrentTools ?? 4;
   return mapWithConcurrency(
     toolCalls,
     maxConcurrent,
-    (call) => dispatchSingleCall(inputs, tools, call, events)
+    (call) => dispatchSingleCall(inputs, tools, call, events, parentSpan)
   );
 }
-async function dispatchSingleCall(inputs, tools, call, events) {
+async function dispatchSingleCall(inputs, tools, call, events, parentSpan) {
   const { call: workingCall, repairs } = applyRepairAndExtractCall(tools, call);
   const callId = generateCallId();
   const forkVeto = vetoFromForkWhitelist(inputs, workingCall, callId, events);
   if (forkVeto !== void 0) return forkVeto;
   const resolved = tools.find((tool) => tool.name === workingCall.name);
-  const toolSpan = startToolCallSpan(inputs, workingCall, resolved, callId, repairs);
+  const toolSpan = startToolCallSpan(inputs, workingCall, resolved, callId, repairs, parentSpan);
   events.push(buildToolUseRunning(inputs, callId, workingCall));
   const pluginVeto = await vetoFromPluginPreHook(inputs, workingCall, callId, events);
   if (pluginVeto !== void 0) {
@@ -7636,6 +8007,13 @@ async function dispatchSingleCall(inputs, tools, call, events) {
     return fileVeto;
   }
   const result = await runToolWithLifecycle(inputs, resolved, workingCall, callId);
+  await inputs.pluginManager?.runPostToolCallHooks({
+    name: workingCall.name,
+    args: workingCall.input,
+    result: { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode },
+    agentId: inputs.agentId,
+    runId: inputs.runId
+  });
   return finalizeSpanAndPostHook(inputs, workingCall, callId, result, events, toolSpan);
 }
 function applyRepairAndExtractCall(tools, call) {
@@ -7668,8 +8046,8 @@ function vetoFromForkWhitelist(inputs, call, callId, events) {
     content: `Tool blocked by fork whitelist: ${whitelistDecision.reason}`
   };
 }
-function startToolCallSpan(inputs, call, resolved, callId, repairs) {
-  const toolSpan = inputs.telemetry?.startSpan("tool.call", {
+function startToolCallSpan(inputs, call, resolved, callId, repairs, parentSpan) {
+  const toolSpan = inputs.telemetry?.startChildSpan(parentSpan, "tool.call", {
     "tool.name": call.name,
     "tool.origin": resolved?.origin ?? "unknown",
     callId
@@ -7733,8 +8111,14 @@ async function runToolWithLifecycle(inputs, resolved, call, callId) {
     conversationId: inputs.agentId,
     callId
   });
-  const result = await executeTool(inputs, resolved, call);
+  const result = await raceToolExecution(executeTool(inputs, resolved, call), {
+    signal: inputs.signal,
+    timeoutMs: inputs.perToolTimeoutMs
+  });
   const durationMs = Date.now() - startAt;
+  inputs.telemetry?.recordHistogram(HISTOGRAM_NAMES.TOOL_CALL_DURATION_MS, durationMs, {
+    "tool.name": call.name
+  });
   if (result.exitCode !== void 0 && result.exitCode !== 0 && result.exitCode !== null) {
     await safeEmitToolHook(inputs.onToolError, {
       toolName: call.name,
@@ -7837,8 +8221,44 @@ var init_tool_dispatch = __esm({
     init_ids();
     init_async_local_storage();
     init_map_with_concurrency();
+    init_span_names();
     init_repair_middleware();
     init_tool_executors();
+    init_tool_timeout();
+  }
+});
+
+// src/internal/agent-loop/tool-result-guard.ts
+function guardText(content, opts) {
+  let out = content;
+  if (opts.redactPii === true) {
+    for (const re of PII_PATTERNS) out = out.replace(re, "[REDACTED]");
+  }
+  if (opts.delimit === true) {
+    const safe2 = out.split(CLOSE).join("</ untrusted-tool-output>");
+    out = `${OPEN}
+${safe2}
+${CLOSE}`;
+  }
+  return out;
+}
+function applyToolResultGuard(parts, opts) {
+  if (opts.delimit !== true && opts.redactPii !== true) return parts;
+  return parts.map(
+    (p) => p.type === "tool_result" ? { ...p, content: guardText(p.content, opts) } : p
+  );
+}
+var OPEN, CLOSE, PII_PATTERNS;
+var init_tool_result_guard = __esm({
+  "src/internal/agent-loop/tool-result-guard.ts"() {
+    OPEN = "<untrusted-tool-output>";
+    CLOSE = "</untrusted-tool-output>";
+    PII_PATTERNS = [
+      /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+      // email
+      /\b(?:\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g
+      // phone
+    ];
   }
 });
 
@@ -8222,6 +8642,11 @@ async function runAgentLoop(inputs) {
   try {
     const ctx = await initLoopContext(inputs);
     ctxRef = ctx;
+    ctx.sendSpan = sendSpan;
+    await inputs.pluginManager?.runOnSessionStartHooks({
+      agentId: inputs.agentId,
+      runId: inputs.runId
+    });
     const budget = inputs.budget ?? new IterationBudget({ maxIterations: inputs.maxIterations ?? 8 });
     let lastTurnDecision;
     while (budget.shouldContinue()) {
@@ -8249,6 +8674,7 @@ async function runAgentLoop(inputs) {
       }
       budget.consume();
       inputs.budgetTracker?.nextIteration?.();
+      if (inputs.signal?.aborted === true) break;
     }
     if (lastTurnDecision === "continue" && budget.shouldContinue() === false) {
       ctx.stoppedAtIterationLimit = true;
@@ -8288,6 +8714,10 @@ async function runAgentLoop(inputs) {
       ...ctx.stoppedByDoomLoop === true ? { stoppedByDoomLoop: true } : {}
     };
   } finally {
+    await inputs.pluginManager?.runOnSessionEndHooks({
+      agentId: inputs.agentId,
+      runId: inputs.runId
+    });
     if (ctxRef !== void 0 && ctxRef.memoryProviderHandle !== void 0 && inputs.memoryProvider !== void 0) {
       try {
         await inputs.memoryProvider.dispose(ctxRef.memoryProviderHandle);
@@ -8391,7 +8821,10 @@ async function finishOrReflect(inputs, ctx, llmOutput) {
   return "done";
 }
 async function runIteration(inputs, ctx) {
+  const hookCtx = { agentId: inputs.agentId, runId: inputs.runId };
+  await inputs.pluginManager?.runPreLlmCallHooks(hookCtx);
   const llmOutput = await streamLlmTurn(inputs, ctx);
+  await inputs.pluginManager?.runPostLlmCallHooks(hookCtx);
   accumulateUsage(ctx.usage, llmOutput);
   if (inputs.budgetTracker !== void 0) {
     const modelId = inputs.model.id ?? "auto";
@@ -8417,6 +8850,13 @@ async function runIteration(inputs, ctx) {
   }
   return continueOrTerminate(inputs, ctx, llmOutput);
 }
+async function transformLlmOutputText(inputs, text, ctx) {
+  return inputs.pluginManager !== void 0 ? inputs.pluginManager.runTransformLlmOutputHooks(text, ctx) : text;
+}
+async function guardAndTransformToolResults(inputs, raw, ctx) {
+  const guarded = inputs.toolResultGuard !== void 0 ? applyToolResultGuard(raw, inputs.toolResultGuard) : raw;
+  return inputs.pluginManager !== void 0 ? inputs.pluginManager.runTransformToolResultHooks(guarded, ctx) : guarded;
+}
 async function continueOrTerminate(inputs, ctx, llmOutput) {
   if (llmOutput.errored) return "error";
   if (llmOutput.text.length > 0) {
@@ -8425,8 +8865,18 @@ async function continueOrTerminate(inputs, ctx, llmOutput) {
   if (llmOutput.stopReason !== "tool_use" || llmOutput.toolCalls.length === 0) {
     return finishOrReflect(inputs, ctx, llmOutput);
   }
-  ctx.messages.push(buildAssistantTurn(llmOutput.text, llmOutput.toolCalls));
-  const toolResults = await dispatchTools(inputs, ctx.tools, llmOutput.toolCalls, ctx.events);
+  const tCtx = { agentId: inputs.agentId, runId: inputs.runId };
+  const outText = await transformLlmOutputText(inputs, llmOutput.text, tCtx);
+  ctx.messages.push(buildAssistantTurn(outText, llmOutput.toolCalls));
+  const rawResults = await dispatchTools(
+    inputs,
+    ctx.tools,
+    llmOutput.toolCalls,
+    ctx.events,
+    ctx.sendSpan
+    // M3 #64 — nest tool.call spans under agent.send
+  );
+  const toolResults = await guardAndTransformToolResults(inputs, rawResults, tCtx);
   ctx.messages.push({ role: "user", content: toolResults });
   if (inputs.onStep !== void 0) {
     const cb = inputs.onStep;
@@ -8476,6 +8926,7 @@ var init_loop = __esm({
     init_loop_llm_stream();
     init_message_builders();
     init_tool_dispatch();
+    init_tool_result_guard();
     init_usage_and_cost();
     MAX_NUDGE_ATTEMPTS = 2;
     MAX_STOP_FEEDBACK_ATTEMPTS = 2;
@@ -8965,6 +9416,60 @@ var init_anthropic2 = __esm({
     init_shared();
   }
 });
+function loadJsonrepair() {
+  if (cachedJsonrepair === void 0) {
+    const req = createRequire(import.meta.url);
+    cachedJsonrepair = req("jsonrepair").jsonrepair;
+  }
+  return cachedJsonrepair;
+}
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function toFiniteNumber(raw) {
+  if (raw === "") return void 0;
+  const n = Number(raw);
+  return Number.isFinite(n) && String(n) === raw ? n : void 0;
+}
+function tryJson(raw, repair) {
+  const t = raw.trimStart();
+  if (!(t.startsWith("{") || t.startsWith("["))) return void 0;
+  try {
+    return JSON.parse(repair ? loadJsonrepair()(t) : t);
+  } catch {
+    return void 0;
+  }
+}
+function heuristicCoerce(raw, repairJson) {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (raw === "null") return null;
+  const n = toFiniteNumber(raw);
+  if (n !== void 0) return n;
+  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : void 0);
+  return json === void 0 ? raw : json;
+}
+function coerceCandidates(raw, repairJson) {
+  const out = [];
+  if (raw === "true") out.push(true);
+  else if (raw === "false") out.push(false);
+  else if (raw === "null") out.push(null);
+  const n = toFiniteNumber(raw);
+  if (n !== void 0) out.push(n);
+  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : void 0);
+  if (json !== void 0) out.push(json);
+  out.push(raw);
+  return out;
+}
+function objectShape(schema) {
+  const shape = schema?.shape;
+  return shape !== null && typeof shape === "object" ? shape : void 0;
+}
+var cachedJsonrepair;
+var init_coerce = __esm({
+  "src/sanitize/coerce.ts"() {
+  }
+});
 
 // src/internal/llm/finish.ts
 function collapseSystemText(system) {
@@ -8977,9 +9482,21 @@ function parseToolArguments(buffered) {
   try {
     return JSON.parse(buffered);
   } catch {
+    const repaired = tryJson(buffered, true);
+    if (isPlainObject(repaired)) return repaired;
     return { raw: buffered };
   }
 }
+function mapOpenAIFinish(reason) {
+  switch (reason) {
+    case "tool_calls":
+      return "tool_use";
+    case "length":
+      return "max_tokens";
+    default:
+      return "end_turn";
+  }
+}
 function makeLlmFinish(state2) {
   const finish = {
     stopReason: state2.stopReason,
@@ -8995,6 +9512,7 @@ function makeLlmFinish(state2) {
 }
 var init_finish = __esm({
   "src/internal/llm/finish.ts"() {
+    init_coerce();
   }
 });
 
@@ -9438,6 +9956,16 @@ var init_credential_pool_types = __esm({
 });
 
 // src/internal/llm/retry.ts
+function computeBackoffMs(opts) {
+  const base = opts.baseMs ?? DEFAULT_BASE_MS;
+  const cap = opts.capMs ?? DEFAULT_CAP_MS;
+  const rng = opts.rng ?? Math.random;
+  if (opts.retryAfterMs !== void 0 && opts.retryAfterMs >= 0) {
+    return Math.max(base, Math.min(cap, opts.retryAfterMs));
+  }
+  const ceiling = Math.min(cap, base * 2 ** opts.attempt);
+  return Math.floor(rng() * ceiling);
+}
 function sleepWithAbort(ms, signal) {
   if (ms <= 0 || signal.aborted) return Promise.resolve();
   return new Promise((resolve3) => {
@@ -9452,8 +9980,11 @@ function sleepWithAbort(ms, signal) {
     signal.addEventListener("abort", onAbort, { once: true });
   });
 }
+var DEFAULT_BASE_MS, DEFAULT_CAP_MS;
 var init_retry = __esm({
   "src/internal/llm/retry.ts"() {
+    DEFAULT_BASE_MS = 500;
+    DEFAULT_CAP_MS = 32e3;
   }
 });
 
@@ -10209,60 +10740,6 @@ var init_ollama_native = __esm({
     ollamaSystemText = collapseSystemText;
   }
 });
-function loadJsonrepair() {
-  if (cachedJsonrepair === void 0) {
-    const req = createRequire(import.meta.url);
-    cachedJsonrepair = req("jsonrepair").jsonrepair;
-  }
-  return cachedJsonrepair;
-}
-function isPlainObject(v) {
-  return v !== null && typeof v === "object" && !Array.isArray(v);
-}
-function toFiniteNumber(raw) {
-  if (raw === "") return void 0;
-  const n = Number(raw);
-  return Number.isFinite(n) && String(n) === raw ? n : void 0;
-}
-function tryJson(raw, repair) {
-  const t = raw.trimStart();
-  if (!(t.startsWith("{") || t.startsWith("["))) return void 0;
-  try {
-    return JSON.parse(repair ? loadJsonrepair()(t) : t);
-  } catch {
-    return void 0;
-  }
-}
-function heuristicCoerce(raw, repairJson) {
-  if (raw === "true") return true;
-  if (raw === "false") return false;
-  if (raw === "null") return null;
-  const n = toFiniteNumber(raw);
-  if (n !== void 0) return n;
-  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : void 0);
-  return json === void 0 ? raw : json;
-}
-function coerceCandidates(raw, repairJson) {
-  const out = [];
-  if (raw === "true") out.push(true);
-  else if (raw === "false") out.push(false);
-  else if (raw === "null") out.push(null);
-  const n = toFiniteNumber(raw);
-  if (n !== void 0) out.push(n);
-  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : void 0);
-  if (json !== void 0) out.push(json);
-  out.push(raw);
-  return out;
-}
-function objectShape(schema) {
-  const shape = schema?.shape;
-  return shape !== null && typeof shape === "object" ? shape : void 0;
-}
-var cachedJsonrepair;
-var init_coerce = __esm({
-  "src/sanitize/coerce.ts"() {
-  }
-});
 
 // src/sanitize/sanitize-tool-input.ts
 function applyTrim(key, value, ctx) {
@@ -10443,18 +10920,6 @@ var init_hermes_tool_extract = __esm({
 });
 
 // src/internal/llm/openai.ts
-function mapOpenAIFinish(reason) {
-  switch (reason) {
-    case "tool_calls":
-      return "tool_use";
-    case "length":
-      return "max_tokens";
-    case "stop":
-      return "end_turn";
-    default:
-      return "end_turn";
-  }
-}
 function applyReasoningRequest(body, effort, providerName) {
   if (providerName === "openai") {
     body.reasoning_effort = effort;
@@ -10551,6 +11016,7 @@ function assistantMessage(message) {
 var OpenAIClient, OpenAIStreamAccumulator, openAISystemText;
 var init_openai2 = __esm({
   "src/internal/llm/openai.ts"() {
+    init_errors();
     init_ollama2();
     init_openai_compatible();
     init_finish();
@@ -10631,8 +11097,12 @@ var init_openai2 = __esm({
           // model was actually given. Empty set (no tools) recovers nothing.
           new Set(request.tools?.map((tool) => tool.name) ?? [])
         );
+        let sawDone = false;
         for await (const record of parseSseStream(response.body, signal)) {
-          if (record.data === "[DONE]") break;
+          if (record.data === "[DONE]") {
+            sawDone = true;
+            break;
+          }
           let chunk;
           try {
             chunk = JSON.parse(record.data);
@@ -10652,6 +11122,11 @@ var init_openai2 = __esm({
           const events = accumulator.consume(chunk);
           for (const event of events) yield event;
         }
+        if (!sawDone && !accumulator.finishReasonSeen) {
+          throw new NetworkError("SSE stream truncated (no finish_reason / [DONE])", {
+            code: "stream_truncated"
+          });
+        }
         const drainEvent = accumulator.finalizeHeldText();
         if (drainEvent !== void 0) yield drainEvent;
         return accumulator.finish();
@@ -10751,8 +11226,15 @@ var init_openai2 = __esm({
           this.toolCalls.set(call.index, existing);
         }
       }
+      /** M2 #61 — true once any chunk carried a non-null `finish_reason` (else a
+       *  stream ending without `[DONE]` is a truncation, not a clean end). */
+      sawFinishReason = false;
+      get finishReasonSeen() {
+        return this.sawFinishReason;
+      }
       applyFinishReason(reason) {
         if (reason === void 0 || reason === null) return;
+        this.sawFinishReason = true;
         this.stopReason = mapOpenAIFinish(reason);
       }
       finish() {
@@ -10801,6 +11283,53 @@ var init_openai2 = __esm({
   }
 });
 
+// src/internal/resilience/circuit-breaker.ts
+var DEFAULT_MAX_TIMEOUTS, DEFAULT_COOLDOWN_MS2, CircuitBreaker;
+var init_circuit_breaker = __esm({
+  "src/internal/resilience/circuit-breaker.ts"() {
+    DEFAULT_MAX_TIMEOUTS = 3;
+    DEFAULT_COOLDOWN_MS2 = 6e4;
+    CircuitBreaker = class {
+      constructor(opts = {}) {
+        this.opts = opts;
+      }
+      opts;
+      states = /* @__PURE__ */ new Map();
+      /** @returns true when the breaker is open and the call should be skipped. */
+      shouldSkip(key) {
+        const state2 = this.states.get(key);
+        if (state2 === void 0) return false;
+        if (state2.cooldownUntilMs === 0) return false;
+        if (this.now() < state2.cooldownUntilMs) return true;
+        state2.cooldownUntilMs = 0;
+        state2.consecutiveTimeouts = 0;
+        return false;
+      }
+      recordSuccess(key) {
+        const state2 = this.states.get(key);
+        if (state2 === void 0) return;
+        state2.consecutiveTimeouts = 0;
+        state2.cooldownUntilMs = 0;
+      }
+      recordTimeout(key) {
+        const state2 = this.states.get(key) ?? { consecutiveTimeouts: 0, cooldownUntilMs: 0 };
+        state2.consecutiveTimeouts += 1;
+        if (state2.consecutiveTimeouts >= (this.opts.maxTimeouts ?? DEFAULT_MAX_TIMEOUTS)) {
+          state2.cooldownUntilMs = this.now() + (this.opts.cooldownMs ?? DEFAULT_COOLDOWN_MS2);
+        }
+        this.states.set(key, state2);
+      }
+      /** @internal — tests inspect counter state. */
+      inspect(key) {
+        return this.states.get(key) ?? { consecutiveTimeouts: 0, cooldownUntilMs: 0 };
+      }
+      now() {
+        return this.opts.now?.() ?? Date.now();
+      }
+    };
+  }
+});
+
 // src/internal/llm/pool-aware-client.ts
 function classifyAndDecide(error, hasRetried429) {
   if (error instanceof NetworkError) return "propagate";
@@ -10829,20 +11358,34 @@ var PoolAwareLlmClient;
 var init_pool_aware_client = __esm({
   "src/internal/llm/pool-aware-client.ts"() {
     init_errors();
+    init_circuit_breaker();
+    init_retry();
     init_stream_relay();
     PoolAwareLlmClient = class {
-      constructor(pool, buildClient2, waitForAvailableMs = 3e4) {
+      constructor(pool, buildClient2, waitForAvailableMs = 3e4, resilience = {}) {
         this.pool = pool;
         this.buildClient = buildClient2;
         this.waitForAvailableMs = waitForAvailableMs;
         this.name = `pool-aware:${pool.provider}`;
+        this.breaker = resilience.breaker ?? new CircuitBreaker();
+        this.backoffBaseMs = resilience.backoffBaseMs;
+        this.rng = resilience.rng;
       }
       pool;
       buildClient;
       waitForAvailableMs;
       name;
+      /** M2 #60 — provider-level circuit breaker (consecutive-failure). */
+      breaker;
+      backoffBaseMs;
+      rng;
       // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: stream() must serialize pool-select → build client → first-event probe → classify → retry/rotate/propagate. Extracting helpers fragments the linear narrative; the comments above each branch keep it readable.
       async *stream(request, signal) {
+        if (this.breaker.shouldSkip(this.pool.provider)) {
+          throw new NetworkError(`${this.pool.provider} circuit open \u2014 failing fast`, {
+            code: "circuit_open"
+          });
+        }
         let hasRetried429 = false;
         while (true) {
           if (signal.aborted) throw abortError2(signal);
@@ -10857,6 +11400,7 @@ var init_pool_aware_client = __esm({
               }
             }
             if (entry === null) {
+              this.breaker.recordTimeout(this.pool.provider);
               throw new CredentialPoolExhaustedError(
                 `All ${this.pool.provider} credentials exhausted; next retry available at ${this.nextRetryHint() ?? "unknown"}`,
                 { provider: this.pool.provider, nextRetryAt: this.nextRetryHint() }
@@ -10866,10 +11410,19 @@ var init_pool_aware_client = __esm({
           const realClient = this.buildClient(entry.accessToken);
           const attempt = await tryFirstEvent(realClient, request, signal);
           if (attempt.kind === "ok") {
+            this.breaker.recordSuccess(this.pool.provider);
             return yield* relayStream(attempt.generator, attempt.firstResult);
           }
           const decision = classifyAndDecide(attempt.error, hasRetried429);
           if (decision === "retry") {
+            await sleepWithAbort(
+              computeBackoffMs({
+                attempt: 0,
+                ...this.backoffBaseMs !== void 0 ? { baseMs: this.backoffBaseMs } : {},
+                ...this.rng !== void 0 ? { rng: this.rng } : {}
+              }),
+              signal
+            );
             hasRetried429 = true;
             continue;
           }
@@ -10889,6 +11442,7 @@ var init_pool_aware_client = __esm({
             hasRetried429 = false;
             continue;
           }
+          this.breaker.recordTimeout(this.pool.provider);
           throw attempt.error;
         }
       }
@@ -11347,9 +11901,24 @@ var init_router = __esm({
     warnedProviders = /* @__PURE__ */ new Set();
   }
 });
-function createMcpClient(name, config) {
+function createMcpClient(name, config, fetchImpl = fetch) {
   if (isStdio(config)) return new StdioMcpClient(name, config);
-  return new HttpMcpClient(name, config);
+  return new HttpMcpClient(name, config, fetchImpl);
+}
+function reconnectDelay(attempt) {
+  const ceiling = RECONNECT_BASE_MS * 2 ** attempt;
+  const ms = Math.floor(Math.random() * ceiling);
+  return ms <= 0 ? Promise.resolve() : new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+function mcpTimeoutError(name, timeoutMs) {
+  return new NetworkError(`MCP ${name} request timed out after ${timeoutMs}ms`, {
+    code: "mcp_timeout"
+  });
+}
+function isAbortLike(cause) {
+  if (typeof cause !== "object" || cause === null || !("name" in cause)) return false;
+  const name = cause.name;
+  return name === "TimeoutError" || name === "AbortError";
 }
 async function rpcInitialize(request) {
   await request("initialize", {
@@ -11379,11 +11948,16 @@ function resolveMcpCwd(configCwd) {
   if (isAbsolute(configCwd)) return configCwd;
   return safePathJoin(process.cwd(), configCwd);
 }
-var BaseMcpClient, StdioMcpClient, HttpMcpClient;
+var DEFAULT_MCP_TIMEOUT_MS, MAX_STDIO_BUFFER_BYTES, RECONNECT_BASE_MS, MAX_RECONNECT_ATTEMPTS, BaseMcpClient, StdioMcpClient, HttpMcpClient;
 var init_client = __esm({
   "src/internal/mcp/client.ts"() {
     init_errors();
+    init_env_policy();
     init_path_guard();
+    DEFAULT_MCP_TIMEOUT_MS = 3e4;
+    MAX_STDIO_BUFFER_BYTES = 8 * 1024 * 1024;
+    RECONNECT_BASE_MS = 250;
+    MAX_RECONNECT_ATTEMPTS = 2;
     BaseMcpClient = class {
       initialize() {
         return rpcInitialize((method, params) => this.request(method, params));
@@ -11405,32 +11979,107 @@ var init_client = __esm({
       name;
       child;
       nextId = 1;
+      // #59 — pending requests carry a reject + timer so a silent server times out
+      // (typed error), a late reply after timeout is a no-op, and close() settles them.
       pending = /* @__PURE__ */ new Map();
       buffer = "";
-      async initialize() {
+      // M2 #59 — reconnect-after-drop state. `dropped` is set when the child exits
+      // unexpectedly OR times out (not via close()); the next request re-spawns with
+      // backoff. `reconnectPromise` is a SINGLE in-flight reconnect shared by every
+      // concurrent request so parallel tool dispatch after a drop awaits one handshake
+      // instead of racing (or spuriously failing with mcp_not_init).
+      dropped = false;
+      reconnectAttempts = 0;
+      reconnectPromise;
+      get timeoutMs() {
+        return this.config.requestTimeoutMs ?? DEFAULT_MCP_TIMEOUT_MS;
+      }
+      /** Spawn the server child and wire stdout/stderr/error/exit handlers.
+       * Shared by `initialize()` and the M2 #59 reconnect path. */
+      spawnChild() {
         const resolvedCwd = resolveMcpCwd(this.config.cwd);
         const child = spawn(this.config.command, this.config.args ?? [], {
           cwd: resolvedCwd,
-          env: { ...process.env, ...this.config.env ?? {} }
+          // #54 (F-H1) — a third-party MCP server binary must not inherit host
+          // secrets. Scrub secret-like vars by default; `config.env` still wins.
+          env: resolveChildEnv({ policy: this.config.envPolicy, overrides: this.config.env })
         });
         this.child = child;
         child.stdout.on("data", (chunk) => this.consume(chunk));
         child.stderr.on("data", () => void 0);
+        child.stdin.on("error", () => void 0);
         child.on("error", () => {
-          for (const resolver of this.pending.values()) {
-            resolver({ error: { message: "MCP process crashed" } });
-          }
-          this.pending.clear();
+          this.rejectAllPending(
+            new NetworkError(`MCP ${this.name} process crashed`, { code: "mcp_crashed" })
+          );
+        });
+        child.on("exit", () => {
+          if (this.child !== child) return;
+          this.child = void 0;
+          this.dropped = true;
+          this.rejectAllPending(
+            new NetworkError(`MCP ${this.name} disconnected`, { code: "mcp_disconnected" })
+          );
+        });
+      }
+      async initialize() {
+        this.spawnChild();
+        await super.initialize();
+      }
+      /** M2 #59 — ensure a live child before a request. Reconnect (bounded, with
+       * full-jitter backoff) when the client was dropped; fail fast when never
+       * initialized. Concurrent callers share ONE reconnect handshake. */
+      ensureConnected() {
+        if (this.child !== void 0) return Promise.resolve();
+        if (!this.dropped) {
+          return Promise.reject(
+            new ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" })
+          );
+        }
+        this.reconnectPromise ??= this.reconnect().finally(() => {
+          this.reconnectPromise = void 0;
         });
+        return this.reconnectPromise;
+      }
+      async reconnect() {
+        if (this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+          throw new NetworkError(`MCP ${this.name} reconnect exhausted`, { code: "mcp_disconnected" });
+        }
+        await reconnectDelay(this.reconnectAttempts);
+        this.reconnectAttempts += 1;
+        this.spawnChild();
         await super.initialize();
+        this.dropped = false;
+        this.reconnectAttempts = 0;
       }
       async close() {
-        if (this.child === void 0) return;
-        this.child.kill("SIGTERM");
+        this.rejectAllPending(new NetworkError(`MCP ${this.name} closed`, { code: "mcp_closed" }));
+        const child = this.child;
         this.child = void 0;
+        this.dropped = false;
+        child?.kill("SIGTERM");
+      }
+      /** Reject + clear every pending request (crash / close). @internal */
+      rejectAllPending(error) {
+        for (const entry of this.pending.values()) {
+          clearTimeout(entry.timer);
+          entry.reject(error);
+        }
+        this.pending.clear();
       }
       consume(chunk) {
         this.buffer += chunk.toString("utf8");
+        if (this.buffer.length > MAX_STDIO_BUFFER_BYTES) {
+          this.buffer = "";
+          this.rejectAllPending(
+            new NetworkError(`MCP ${this.name} exceeded stdout buffer limit`, {
+              code: "mcp_buffer_overflow"
+            })
+          );
+          this.child?.kill("SIGKILL");
+          this.child = void 0;
+          return;
+        }
         let newlineIndex = this.buffer.indexOf("\n");
         while (newlineIndex !== -1) {
           const line = this.buffer.slice(0, newlineIndex).trim();
@@ -11447,23 +12096,47 @@ var init_client = __esm({
           return;
         }
         if (typeof message.id !== "number") return;
-        const resolver = this.pending.get(message.id);
-        if (resolver === void 0) return;
+        const entry = this.pending.get(message.id);
+        if (entry === void 0) return;
         this.pending.delete(message.id);
-        resolver(message);
+        clearTimeout(entry.timer);
+        entry.resolve(message);
       }
       request(method, params) {
-        if (this.child === void 0) {
-          return Promise.reject(
-            new ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" })
-          );
+        const child = this.child;
+        if (child !== void 0) return this.send(child, method, params);
+        if (this.dropped) return this.reconnectAndRequest(method, params);
+        return Promise.reject(
+          new ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" })
+        );
+      }
+      /** M2 #59 — reconnect a dropped client, then send. Separate async path so the
+       * happy path above never pays an extra microtask tick. */
+      async reconnectAndRequest(method, params) {
+        await this.ensureConnected();
+        const child = this.child;
+        if (child === void 0) {
+          throw new ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" });
         }
+        return this.send(child, method, params);
+      }
+      send(child, method, params) {
         const id = this.nextId++;
         const payload = { jsonrpc: "2.0", id, method, params };
-        this.child.stdin.write(`${JSON.stringify(payload)}
+        child.stdin.write(`${JSON.stringify(payload)}
 `);
-        return new Promise((resolve3) => {
-          this.pending.set(id, resolve3);
+        return new Promise((resolve3, reject) => {
+          const timer = setTimeout(() => {
+            this.pending.delete(id);
+            reject(mcpTimeoutError(this.name, this.timeoutMs));
+            this.child?.kill("SIGKILL");
+            this.child = void 0;
+            this.dropped = true;
+            this.rejectAllPending(
+              new NetworkError(`MCP ${this.name} disconnected`, { code: "mcp_disconnected" })
+            );
+          }, this.timeoutMs);
+          this.pending.set(id, { resolve: resolve3, reject, timer });
         });
       }
     };
@@ -11489,11 +12162,20 @@ var init_client = __esm({
           accept: "application/json",
           ...this.config.headers ?? {}
         };
-        const response = await this.fetchImpl(this.config.url, {
-          method: "POST",
-          headers,
-          body: JSON.stringify(payload)
-        });
+        const timeoutMs = this.config.requestTimeoutMs ?? DEFAULT_MCP_TIMEOUT_MS;
+        let response;
+        try {
+          response = await this.fetchImpl(this.config.url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+            // #59 — bound the request; a non-responding endpoint aborts here.
+            signal: AbortSignal.timeout(timeoutMs)
+          });
+        } catch (cause) {
+          if (isAbortLike(cause)) throw mcpTimeoutError(this.name, timeoutMs);
+          throw cause;
+        }
         if (!response.ok) {
           throw new NetworkError(`MCP ${this.name} returned ${response.status}`, {
             code: "mcp_http_error"
@@ -11613,11 +12295,33 @@ function resolveRunProvider(options) {
     );
   }
   const parsedModel = parseModelId(options.model?.id);
-  const inferredProvider = parsedModel.provider !== void 0 && getProviderProfile(parsedModel.provider) !== void 0 ? parsedModel.provider : void 0;
-  const primary = options.agentOptions.providers?.routes?.[0]?.provider ?? inferredProvider ?? detectPrimaryProvider();
-  const effectiveModelId = inferredProvider !== void 0 ? parsedModel.name : options.model?.id ?? "claude-sonnet-4-6";
+  const modelInferredProvider = parsedModel.provider !== void 0 && getProviderProfile(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();
+  const effectiveModelId = modelInferredProvider !== void 0 && modelInferredProvider === primary ? parsedModel.name : options.model?.id ?? "claude-sonnet-4-6";
   return { primary, effectiveModelId };
 }
+function inferProviderFromApiKey(apiKey) {
+  if (apiKey === void 0 || apiKey.length === 0) return void 0;
+  const byPrefix = [
+    { provider: "openrouter", prefix: "sk-or-" },
+    { provider: "anthropic", prefix: "sk-ant-" },
+    { provider: "openai", prefix: "sk-" }
+  ];
+  for (const { provider, prefix } of byPrefix) {
+    if (apiKey.startsWith(prefix) && getProviderProfile(provider) !== void 0) {
+      return provider;
+    }
+  }
+  return void 0;
+}
+function mergeExplicitApiKey(pools, primary, apiKey) {
+  if (apiKey === void 0 || apiKey.length === 0) return pools;
+  if (isFixtureApiKey(apiKey) || apiKey === LOCAL_RUNTIME_MOCK_KEY) return pools;
+  const existing = pools?.[primary];
+  if (existing !== void 0 && existing.length > 0) return pools;
+  return { ...pools ?? {}, [primary]: [apiKey] };
+}
 function buildLoopInputs(options, runId, userText) {
   const maxIterations = options.sendOptions.maxIterations;
   if (maxIterations !== void 0 && (!Number.isInteger(maxIterations) || maxIterations < 1)) {
@@ -11628,7 +12332,11 @@ function buildLoopInputs(options, runId, userText) {
   }
   const { primary, effectiveModelId } = resolveRunProvider(options);
   const fallback = options.agentOptions.providers?.fallback;
-  const apiKeys = options.agentOptions.providers?.apiKeys;
+  const apiKeys = mergeExplicitApiKey(
+    options.agentOptions.providers?.apiKeys,
+    primary,
+    options.agentOptions.apiKey
+  );
   const credentialPoolStrategy = options.agentOptions.providers?.credentialPoolStrategy;
   const extractToolCallsFromContent = options.agentOptions.providers?.routes?.[0]?.extractToolCallsFromContent;
   const chain = resolveProviderChain({
@@ -11672,6 +12380,10 @@ function buildLoopInputs(options, runId, userText) {
     // D318 — forward SendOptions.signal to the agent loop so streamLlmTurn
     // can attach it to the LLM `fetch({ signal })` call.
     ...options.sendOptions.signal !== void 0 ? { signal: options.sendOptions.signal } : {},
+    // #58 / #57 — forward the per-tool timeout + tool-result guard so a consumer
+    // can enable them via SendOptions (not only internal AgentLoopInputs).
+    ...options.sendOptions.perToolTimeoutMs !== void 0 ? { perToolTimeoutMs: options.sendOptions.perToolTimeoutMs } : {},
+    ...options.sendOptions.toolResultGuard !== void 0 ? { toolResultGuard: options.sendOptions.toolResultGuard } : {},
     // M1-2: per-send iteration ceiling (validated above). The loop reads
     // inputs.maxIterations (default 8 when unset).
     ...maxIterations !== void 0 ? { maxIterations } : {},
@@ -11738,6 +12450,8 @@ var init_real_local_run = __esm({
   "src/internal/runtime/local-agent/real-local-run.ts"() {
     init_errors();
     init_loop();
+    init_api_key_validator();
+    init_fixture_mode();
     init_fallback_client();
     init_model_identifier();
     init_router();
@@ -12014,7 +12728,12 @@ async function runActiveMemory(args) {
         hits: []
       });
     }
-    const cached2 = args.cache?.get(args.userText, cfg.queryMode);
+    const tenantCtx = {
+      namespace: args.namespace,
+      userId: args.userId,
+      scope: args.scope
+    };
+    const cached2 = args.cache?.get(args.userText, cfg.queryMode, tenantCtx);
     if (cached2 !== void 0) return endRecallSpan(span, args, cached2);
     const query = buildQuery(args.userText, args.priorMessages, cfg.queryMode, cfg.recentUserTurns);
     if (query.trim().length === 0) {
@@ -12099,7 +12818,12 @@ function notifyBreaker(breaker, key, status) {
   else if (status === "ok" || status === "no-recall") breaker.recordSuccess(key);
 }
 async function finalize(args, queryMode, result) {
-  args.cache?.set(args.userText, queryMode, result);
+  const tenantCtx = {
+    namespace: args.namespace,
+    userId: args.userId,
+    scope: args.scope
+  };
+  args.cache?.set(args.userText, queryMode, result, tenantCtx);
   if (args.persistTranscripts === true && args.cwd !== void 0) {
     await persistActiveMemoryTranscript(args.cwd, {
       runId: args.runId ?? `run-${Date.now()}`,
@@ -12804,53 +13528,6 @@ var init_catalog = __esm({
   }
 });
 
-// src/internal/memory/circuit-breaker.ts
-var DEFAULT_MAX_TIMEOUTS, DEFAULT_COOLDOWN_MS2, CircuitBreaker;
-var init_circuit_breaker = __esm({
-  "src/internal/memory/circuit-breaker.ts"() {
-    DEFAULT_MAX_TIMEOUTS = 3;
-    DEFAULT_COOLDOWN_MS2 = 6e4;
-    CircuitBreaker = class {
-      constructor(opts = {}) {
-        this.opts = opts;
-      }
-      opts;
-      states = /* @__PURE__ */ new Map();
-      /** @returns true when the breaker is open and the call should be skipped. */
-      shouldSkip(key) {
-        const state2 = this.states.get(key);
-        if (state2 === void 0) return false;
-        if (state2.cooldownUntilMs === 0) return false;
-        if (this.now() < state2.cooldownUntilMs) return true;
-        state2.cooldownUntilMs = 0;
-        state2.consecutiveTimeouts = 0;
-        return false;
-      }
-      recordSuccess(key) {
-        const state2 = this.states.get(key);
-        if (state2 === void 0) return;
-        state2.consecutiveTimeouts = 0;
-        state2.cooldownUntilMs = 0;
-      }
-      recordTimeout(key) {
-        const state2 = this.states.get(key) ?? { consecutiveTimeouts: 0, cooldownUntilMs: 0 };
-        state2.consecutiveTimeouts += 1;
-        if (state2.consecutiveTimeouts >= (this.opts.maxTimeouts ?? DEFAULT_MAX_TIMEOUTS)) {
-          state2.cooldownUntilMs = this.now() + (this.opts.cooldownMs ?? DEFAULT_COOLDOWN_MS2);
-        }
-        this.states.set(key, state2);
-      }
-      /** @internal — tests inspect counter state. */
-      inspect(key) {
-        return this.states.get(key) ?? { consecutiveTimeouts: 0, cooldownUntilMs: 0 };
-      }
-      now() {
-        return this.opts.now?.() ?? Date.now();
-      }
-    };
-  }
-});
-
 // src/internal/persistence/fts5-sanitize.ts
 function sanitizeFts5Query(query) {
   if (query.length === 0) return query;
@@ -14016,9 +14693,9 @@ var init_local_agent_memory = __esm({
     init_active_memory();
     init_active_memory_cache();
     init_catalog();
-    init_circuit_breaker();
     init_index_manager();
     init_tools();
+    init_circuit_breaker();
     LocalAgentMemory = class {
       constructor(options, workspaceCwd, agentId) {
         this.options = options;