@theokit/sdk 2.15.1 → 2.18.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID, randomBytes } from 'crypto';
 import { existsSync, rmSync, mkdirSync, renameSync, readFileSync, realpathSync, lstatSync, readlinkSync, readdirSync } from 'fs';
 import { join, dirname, relative, resolve, sep, isAbsolute } from 'path';
-import { readFile, stat, rm, readdir, mkdir, appendFile, open, rename, unlink, statfs, access } from 'fs/promises';
+import { readFile, stat, rm, readdir, mkdir, rename, open, unlink, statfs, access, appendFile } from 'fs/promises';
 import { z, toJSONSchema } from 'zod';
 import { AsyncLocalStorage } from 'async_hooks';
 import { createRequire } from 'module';
@@ -1198,6 +1198,16 @@ var init_credential_pool_types = __esm({
 });
 
 // src/internal/llm/retry.ts
+function computeBackoffMs(opts) {
+  const base = opts.baseMs ?? DEFAULT_BASE_MS;
+  const cap2 = 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(cap2, opts.retryAfterMs));
+  }
+  const ceiling = Math.min(cap2, 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) => {
@@ -1212,8 +1222,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;
   }
 });
 
@@ -5280,7 +5293,7 @@ function abortRun(name, runId, startedAt, stepResults, signal) {
 }
 async function runStepsLoop(params) {
   const { options, steps, ctx, runId, startedAt, signal } = params;
-  const stepResults = [];
+  const stepResults = [...params.initialStepResults ?? []];
   let acc = params.input;
   for (const step of steps) {
     if (signal.aborted) return abortRun(options.name, runId, startedAt, stepResults, signal);
@@ -5339,7 +5352,8 @@ async function executeWorkflow(options, steps, input, runOpts) {
       ctx,
       runId,
       startedAt,
-      signal
+      signal,
+      ...runOpts?.initialStepResults !== void 0 ? { initialStepResults: runOpts.initialStepResults } : {}
     });
   } finally {
     runSpan.end();
@@ -5422,7 +5436,9 @@ async function resumeWorkflow(opts) {
   await store.delete(opts.runId);
   return executeWorkflow(options, remainingSteps, resumeInput, {
     signal: opts.signal,
-    runId: opts.runId
+    runId: opts.runId,
+    // M3 #62 — restore prior step outputs so the resumed run is not lossy (internal seam).
+    initialStepResults: snapshot.stepResults
   });
 }
 var init_executor = __esm({
@@ -7053,13 +7069,15 @@ function buildGitInfo() {
 init_errors();
 
 // src/internal/llm/sse.ts
-async function* parseSseStream(body, signal) {
+init_errors();
+var DEFAULT_SSE_IDLE_MS = 6e4;
+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 state4 = { buffer: "", event: "message", data: "" };
   try {
-    for await (const chunk of readChunks(reader, signal)) {
+    for await (const chunk of readChunks(reader, signal, idleTimeoutMs)) {
       state4.buffer += decoder.decode(chunk, { stream: true });
       for (const record of drainCompleteRecords(state4)) yield record;
     }
@@ -7069,14 +7087,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();
@@ -7770,6 +7812,9 @@ var PersonalityStore = class {
   }
 };
 
+// src/internal/plugins/manager.ts
+init_errors();
+
 // src/internal/plugins/context.ts
 function createPluginContext() {
   const registrations = {
@@ -7831,6 +7876,9 @@ var PluginManager = class {
     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");
@@ -7848,6 +7896,36 @@ var PluginManager = class {
       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;
   }
@@ -7928,6 +8006,64 @@ var PluginManager = class {
       }
     }
   }
+  // #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();
@@ -7955,7 +8091,29 @@ var PluginManager = class {
     }
     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);
+    }
+  }
 };
+function removeAll(arr, toRemove) {
+  for (const item of toRemove) {
+    const idx = arr.indexOf(item);
+    if (idx !== -1) arr.splice(idx, 1);
+  }
+}
 
 // src/internal/telemetry/span-names.ts
 var SPAN_NAMES = {
@@ -7963,7 +8121,12 @@ var SPAN_NAMES = {
   AGENT_SEND: "agent.send",
   MEMORY_RECALL: "memory.recall"};
 var 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"
 };
 
 // src/internal/telemetry/tracer.ts
@@ -8301,7 +8464,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);
@@ -8337,12 +8518,62 @@ function redactAttrs(attrs) {
   }
   return out;
 }
+
+// src/internal/runtime/lifecycle/env-policy.ts
+var SECRET_PATTERNS = [
+  /KEY/i,
+  /SECRET/i,
+  /TOKEN/i,
+  /PASSWORD/i,
+  /PASSWD/i,
+  /PASSPHRASE/i,
+  /[_-]PWD/i,
+  /CREDENTIAL/i,
+  /PRIVATE/i,
+  /_AUTH/i
+];
+var CORE_VARS = [
+  "PATH",
+  "HOME",
+  "SHELL",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "USER",
+  "LOGNAME"
+];
+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;
+}
+
+// src/internal/runtime/lifecycle/spawn-collect.ts
 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 = "";
@@ -8524,15 +8755,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);
     }
@@ -8559,28 +8799,78 @@ 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;
 }
 
 // src/internal/persistence/conversation-storage-fs.ts
 init_security();
+
+// 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);
+}
+
+// src/internal/persistence/conversation-storage-fs.ts
 var FileSystemConversationStorage = class {
   #root;
   constructor(opts = {}) {
@@ -8590,23 +8880,31 @@ var FileSystemConversationStorage = class {
   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;
@@ -8632,6 +8930,9 @@ function toStoredMessage(record) {
     at: record.at
   };
 }
+function toRecord(message) {
+  return { role: message.role, text: message.content, at: message.at ?? Date.now() };
+}
 
 // src/internal/runtime/session/agent-session.ts
 var DEFAULT_MAX_TURNS = 200;
@@ -8717,12 +9018,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());
@@ -11074,11 +11382,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(
     {
@@ -11121,6 +11450,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 {
@@ -11350,21 +11680,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);
@@ -11410,22 +11740,66 @@ ${result.stderr}`.trim();
   return result.stdout.trim();
 }
 
+// src/internal/agent-loop/tool-timeout.ts
+var TOOL_ABORTED_EXIT = 124;
+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);
+      }
+    );
+  });
+}
+
 // 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) {
@@ -11442,6 +11816,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) {
@@ -11474,8 +11855,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
@@ -11539,8 +11920,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,
@@ -11639,6 +12026,35 @@ function buildToolUseCompleted(inputs, callId, call, result) {
   };
 }
 
+// src/internal/agent-loop/tool-result-guard.ts
+var OPEN = "<untrusted-tool-output>";
+var CLOSE = "</untrusted-tool-output>";
+var 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
+];
+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
+  );
+}
+
 // src/internal/budget/pricing-data.json
 var pricing_data_default = {
   _meta: {
@@ -11989,6 +12405,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()) {
@@ -12016,6 +12437,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;
@@ -12055,6 +12477,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);
@@ -12158,7 +12584,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";
@@ -12184,6 +12613,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) {
@@ -12192,8 +12628,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;
@@ -12638,6 +13084,56 @@ function mapAnthropicStatusToCode(status, body) {
 function formatMessage(status, code) {
   return `Anthropic API error: ${code} (HTTP ${status})`;
 }
+var cachedJsonrepair;
+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;
+}
 
 // src/internal/llm/finish.ts
 function collapseSystemText(system) {
@@ -12650,9 +13146,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(state4) {
   const finish = {
     stopReason: state4.stopReason,
@@ -13534,56 +14042,9 @@ function toOllamaTools(tools) {
     }
   }));
 }
-var cachedJsonrepair;
-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;
-}
+
+// src/internal/llm/openai.ts
+init_errors();
 
 // src/sanitize/sanitize-tool-input.ts
 function applyTrim(key2, value, ctx) {
@@ -13680,6 +14141,77 @@ function parseHermesParams(inner) {
   }
   return sanitizeToolInput(input, { trim: true }).value;
 }
+var STREAM_MARKER = "<function=";
+var DEFAULT_STREAM_BUFFER_CAP = 8192;
+var isStreamWs = (c) => c === " " || c === "	" || c === "\n" || c === "\r";
+function streamToolCallBufferState(held, allowedToolNames, cap2 = DEFAULT_STREAM_BUFFER_CAP) {
+  if (allowedToolNames.size === 0) return "impossible";
+  const t = held.trimStart();
+  if (t.length < STREAM_MARKER.length) {
+    return STREAM_MARKER.startsWith(t) ? "possible" : "impossible";
+  }
+  if (!t.startsWith(STREAM_MARKER)) return "impossible";
+  const parsed = parseStreamMarkerName(t);
+  if (parsed === "building") return "possible";
+  if (parsed === "invalid") return "impossible";
+  const nameOk = parsed.complete ? allowedToolNames.has(parsed.name) : someToolNameStartsWith(allowedToolNames, parsed.name);
+  if (!nameOk) return "impossible";
+  return held.length > cap2 ? "impossible" : "possible";
+}
+function parseStreamMarkerName(t) {
+  let cursor = STREAM_MARKER.length;
+  while (cursor < t.length && isStreamWs(t[cursor])) cursor += 1;
+  const nameStart = cursor;
+  while (cursor < t.length && t[cursor] !== ">" && !isStreamWs(t[cursor])) cursor += 1;
+  const name = t.slice(nameStart, cursor);
+  if (name.length === 0) return cursor >= t.length ? "building" : "invalid";
+  return { name, complete: cursor < t.length && t[cursor] === ">" };
+}
+function someToolNameStartsWith(allowedToolNames, prefix) {
+  for (const name of allowedToolNames) {
+    if (name.startsWith(prefix)) return true;
+  }
+  return false;
+}
+function firstPossibleMarkerStart(held, allowedToolNames) {
+  for (let i = held.indexOf("<"); i !== -1; i = held.indexOf("<", i + 1)) {
+    if (streamToolCallBufferState(held.slice(i), allowedToolNames) === "possible") return i;
+  }
+  return -1;
+}
+var StreamSuppressionBuffer = class {
+  constructor(allowedToolNames) {
+    this.allowedToolNames = allowedToolNames;
+  }
+  allowedToolNames;
+  #held = "";
+  /** Feed a content delta; returns the text to emit as a `text_delta` now, or `undefined` to hold. */
+  push(content) {
+    this.#held += content;
+    if (streamToolCallBufferState(this.#held, this.allowedToolNames) === "possible")
+      return void 0;
+    const holdStart = firstPossibleMarkerStart(this.#held, this.allowedToolNames);
+    if (holdStart > 0) {
+      const flush2 = this.#held.slice(0, holdStart);
+      this.#held = this.#held.slice(holdStart);
+      return flush2;
+    }
+    const flush = this.#held;
+    this.#held = "";
+    return flush;
+  }
+  /** Drain the held buffer at stream end. `hasNativeCalls` mirrors `finish()`'s size-guard: when
+   *  native `tool_calls` exist, `finish()` won't strip the leaked block, so stream the held text WHOLE
+   *  (keeping `accumulatedText == finish.text`); otherwise strip the recoverable blocks. Idempotent. */
+  drain(hasNativeCalls) {
+    if (this.#held.length === 0) return void 0;
+    const held = this.#held;
+    this.#held = "";
+    if (hasNativeCalls) return held;
+    const residual = extractHermesToolCalls(held, () => "held", this.allowedToolNames).residualText;
+    return residual.length > 0 ? residual : void 0;
+  }
+};
 
 // src/internal/llm/openai.ts
 var OpenAIClient = class {
@@ -13757,8 +14289,12 @@ var OpenAIClient = class {
       // 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);
@@ -13778,6 +14314,13 @@ var OpenAIClient = class {
       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();
   }
 };
@@ -13793,6 +14336,7 @@ var OpenAIStreamAccumulator = class {
     this.extractFromContent = extractFromContent;
     this.providerName = providerName;
     this.allowedToolNames = allowedToolNames;
+    this.suppress = extractFromContent && allowedToolNames !== void 0 && allowedToolNames.size > 0 ? new StreamSuppressionBuffer(allowedToolNames) : void 0;
   }
   extractFromContent;
   providerName;
@@ -13805,18 +14349,30 @@ var OpenAIStreamAccumulator = class {
   cacheWriteTokens;
   reasoningTokens;
   toolCalls = /* @__PURE__ */ new Map();
+  /** R7: present only when recovery is enabled AND the request declares tools — holds suspected
+   *  leaked-dialect content back from the `text_delta` stream. `undefined` ⇒ stream immediately. */
+  suppress;
   consume(chunk) {
     const events = [];
     this.applyUsage(chunk.usage);
     for (const choice of chunk.choices ?? []) {
-      const reasoningEvent = this.applyReasoningDelta(
-        choice.delta?.reasoning ?? choice.delta?.reasoning_content
-      );
-      if (reasoningEvent !== void 0) events.push(reasoningEvent);
-      const textEvent = this.applyContentDelta(choice.delta?.content);
-      if (textEvent !== void 0) events.push(textEvent);
-      this.mergeToolCallDeltas(choice.delta?.tool_calls);
-      this.applyFinishReason(choice.finish_reason);
+      events.push(...this.applyChoice(choice));
+    }
+    return events;
+  }
+  applyChoice(choice) {
+    const events = [];
+    const reasoningEvent = this.applyReasoningDelta(
+      choice.delta?.reasoning ?? choice.delta?.reasoning_content
+    );
+    if (reasoningEvent !== void 0) events.push(reasoningEvent);
+    const textEvent = this.applyContentDelta(choice.delta?.content);
+    if (textEvent !== void 0) events.push(textEvent);
+    this.mergeToolCallDeltas(choice.delta?.tool_calls);
+    this.applyFinishReason(choice.finish_reason);
+    if (choice.finish_reason !== void 0 && choice.finish_reason !== null) {
+      const flushEvent = this.finalizeHeldText();
+      if (flushEvent !== void 0) events.push(flushEvent);
     }
     return events;
   }
@@ -13841,7 +14397,17 @@ var OpenAIStreamAccumulator = class {
   applyContentDelta(content) {
     if (typeof content !== "string" || content.length === 0) return void 0;
     this.text += content;
-    return { type: "text_delta", text: content };
+    if (this.suppress === void 0) return { type: "text_delta", text: content };
+    const emit2 = this.suppress.push(content);
+    return emit2 !== void 0 ? { type: "text_delta", text: emit2 } : void 0;
+  }
+  /** R7 held-buffer finalizer, called at the `finish_reason` chunk (in `applyChoice`) AND after the
+   *  SSE loop in `stream()` — so a stream that omits a `finish_reason` terminal never silently drops
+   *  held text. `toolCalls.size > 0` (native calls present) makes `finish()` skip recovery, so the
+   *  buffer streams the held text whole. Idempotent once drained. */
+  finalizeHeldText() {
+    const emit2 = this.suppress?.drain(this.toolCalls.size > 0);
+    return emit2 !== void 0 ? { type: "text_delta", text: emit2 } : void 0;
   }
   mergeToolCallDeltas(deltas) {
     for (const call of deltas ?? []) {
@@ -13852,8 +14418,15 @@ var OpenAIStreamAccumulator = class {
       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() {
@@ -13898,18 +14471,6 @@ var OpenAIStreamAccumulator = class {
     });
   }
 };
-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;
@@ -14007,19 +14568,76 @@ function assistantMessage(message) {
 
 // src/internal/llm/pool-aware-client.ts
 init_errors();
+
+// src/internal/resilience/circuit-breaker.ts
+var DEFAULT_MAX_TIMEOUTS = 3;
+var DEFAULT_COOLDOWN_MS2 = 6e4;
+var 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(key2) {
+    const state4 = this.states.get(key2);
+    if (state4 === void 0) return false;
+    if (state4.cooldownUntilMs === 0) return false;
+    if (this.now() < state4.cooldownUntilMs) return true;
+    state4.cooldownUntilMs = 0;
+    state4.consecutiveTimeouts = 0;
+    return false;
+  }
+  recordSuccess(key2) {
+    const state4 = this.states.get(key2);
+    if (state4 === void 0) return;
+    state4.consecutiveTimeouts = 0;
+    state4.cooldownUntilMs = 0;
+  }
+  recordTimeout(key2) {
+    const state4 = this.states.get(key2) ?? { consecutiveTimeouts: 0, cooldownUntilMs: 0 };
+    state4.consecutiveTimeouts += 1;
+    if (state4.consecutiveTimeouts >= (this.opts.maxTimeouts ?? DEFAULT_MAX_TIMEOUTS)) {
+      state4.cooldownUntilMs = this.now() + (this.opts.cooldownMs ?? DEFAULT_COOLDOWN_MS2);
+    }
+    this.states.set(key2, state4);
+  }
+  /** @internal — tests inspect counter state. */
+  inspect(key2) {
+    return this.states.get(key2) ?? { consecutiveTimeouts: 0, cooldownUntilMs: 0 };
+  }
+  now() {
+    return this.opts.now?.() ?? Date.now();
+  }
+};
+
+// src/internal/llm/pool-aware-client.ts
+init_retry();
 var 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);
@@ -14034,6 +14652,7 @@ var PoolAwareLlmClient = class {
           }
         }
         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() }
@@ -14043,10 +14662,19 @@ var PoolAwareLlmClient = class {
       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;
       }
@@ -14066,6 +14694,7 @@ var PoolAwareLlmClient = class {
         hasRetried429 = false;
         continue;
       }
+      this.breaker.recordTimeout(this.pool.provider);
       throw attempt.error;
     }
   }
@@ -14501,9 +15130,28 @@ function selectTransport(profile, apiKey) {
 // src/internal/mcp/client.ts
 init_errors();
 init_path_guard();
-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);
+}
+var DEFAULT_MCP_TIMEOUT_MS = 3e4;
+var MAX_STDIO_BUFFER_BYTES = 8 * 1024 * 1024;
+var RECONNECT_BASE_MS = 250;
+var MAX_RECONNECT_ATTEMPTS = 2;
+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", {
@@ -14549,32 +15197,107 @@ var StdioMcpClient = class extends BaseMcpClient {
   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();
@@ -14591,23 +15314,47 @@ var StdioMcpClient = class extends BaseMcpClient {
       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 });
     });
   }
 };
@@ -14633,11 +15380,20 @@ var HttpMcpClient = class extends BaseMcpClient {
       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"
@@ -14752,11 +15508,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)) {
@@ -14767,7 +15545,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({
@@ -14811,6 +15593,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 } : {},
@@ -15128,7 +15914,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) {
@@ -15213,7 +16004,12 @@ function notifyBreaker(breaker, key2, status) {
   else if (status === "ok" || status === "no-recall") breaker.recordSuccess(key2);
 }
 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()}`,
@@ -15786,48 +16582,6 @@ var MEMORY_EMBEDDING_ADAPTERS = {
   gemini: geminiMemoryEmbeddingProviderAdapter
 };
 
-// src/internal/memory/circuit-breaker.ts
-var DEFAULT_MAX_TIMEOUTS = 3;
-var DEFAULT_COOLDOWN_MS2 = 6e4;
-var 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(key2) {
-    const state4 = this.states.get(key2);
-    if (state4 === void 0) return false;
-    if (state4.cooldownUntilMs === 0) return false;
-    if (this.now() < state4.cooldownUntilMs) return true;
-    state4.cooldownUntilMs = 0;
-    state4.consecutiveTimeouts = 0;
-    return false;
-  }
-  recordSuccess(key2) {
-    const state4 = this.states.get(key2);
-    if (state4 === void 0) return;
-    state4.consecutiveTimeouts = 0;
-    state4.cooldownUntilMs = 0;
-  }
-  recordTimeout(key2) {
-    const state4 = this.states.get(key2) ?? { consecutiveTimeouts: 0, cooldownUntilMs: 0 };
-    state4.consecutiveTimeouts += 1;
-    if (state4.consecutiveTimeouts >= (this.opts.maxTimeouts ?? DEFAULT_MAX_TIMEOUTS)) {
-      state4.cooldownUntilMs = this.now() + (this.opts.cooldownMs ?? DEFAULT_COOLDOWN_MS2);
-    }
-    this.states.set(key2, state4);
-  }
-  /** @internal — tests inspect counter state. */
-  inspect(key2) {
-    return this.states.get(key2) ?? { consecutiveTimeouts: 0, cooldownUntilMs: 0 };
-  }
-  now() {
-    return this.opts.now?.() ?? Date.now();
-  }
-};
-
 // src/internal/runtime/local-agent/local-agent-memory.ts
 init_index_manager();
 
@@ -18416,13 +19170,13 @@ function defineTool(spec) {
     name: spec.name,
     description: spec.description,
     inputSchema,
-    handler: async (input) => {
+    handler: async (input, ctx) => {
       const raw = spec.sanitize ? sanitizeToolInput(input, {
         ...spec.sanitize === true ? {} : spec.sanitize,
         schema: spec.inputSchema
       }).value : input;
       const parsed = spec.inputSchema.parse(raw);
-      return await spec.handler(parsed);
+      return await spec.handler(parsed, ctx);
     }
   };
 }
@@ -18433,6 +19187,14 @@ init_errors();
 // src/event-bus.ts
 var EventBus = class {
   handlers = /* @__PURE__ */ new Map();
+  // M3 #64 — a swallowed handler error used to vanish without a trace (fail-loud
+  // violation). We now log it AND expose an observable count so ops/tests can see
+  // that a subscriber is silently failing, without breaking the EC-2 contract.
+  #handlerErrorCount = 0;
+  /** M3 #64 — number of handler invocations that threw (and were logged). */
+  get handlerErrorCount() {
+    return this.#handlerErrorCount;
+  }
   /**
    * Subscribe to an event. Returns an unsubscribe function.
    */
@@ -18455,7 +19217,13 @@ var EventBus = class {
     for (const handler of set) {
       try {
         handler(payload);
-      } catch {
+      } catch (cause) {
+        this.#handlerErrorCount += 1;
+        const message = cause instanceof Error ? cause.message : String(cause);
+        process.stderr.write(
+          `[theokit-sdk] event-bus: handler for "${String(event)}" threw: ${message}
+`
+        );
       }
     }
   }
@@ -18478,11 +19246,17 @@ init_generate_object();
 // src/internal/persistence/conversation-storage-memory.ts
 var InMemoryConversationStorage = class {
   #store = /* @__PURE__ */ new Map();
-  async getMessages(conversationId) {
+  async getMessages(conversationId, opts) {
     const existing = this.#store.get(conversationId);
-    return existing === void 0 ? [] : existing.slice();
+    return existing === void 0 ? [] : paginate(existing.slice(), opts);
   }
   async appendMessage(conversationId, message) {
+    this.#appendOne(conversationId, message);
+  }
+  async appendMessages(conversationId, messages) {
+    for (const message of messages) this.#appendOne(conversationId, message);
+  }
+  #appendOne(conversationId, message) {
     const existing = this.#store.get(conversationId);
     const stamped = message.at === void 0 ? { ...message, at: Date.now() } : message;
     if (existing === void 0) {
@@ -18491,9 +19265,26 @@ var InMemoryConversationStorage = class {
     }
     existing.push(stamped);
   }
+  async truncateConversation(conversationId, keepCount) {
+    const existing = this.#store.get(conversationId);
+    if (existing === void 0) return 0;
+    const keep = Math.max(0, Math.min(keepCount, existing.length));
+    this.#store.set(conversationId, existing.slice(0, keep));
+    return keep;
+  }
   async deleteConversation(conversationId) {
     this.#store.delete(conversationId);
   }
+  async deleteScope(prefix) {
+    let n = 0;
+    for (const id of [...this.#store.keys()]) {
+      if (id.startsWith(prefix)) {
+        this.#store.delete(id);
+        n += 1;
+      }
+    }
+    return n;
+  }
   async listConversationIds(opts) {
     const all = Array.from(this.#store.keys());
     if (opts?.limit !== void 0) return all.slice(0, opts.limit);
@@ -18671,23 +19462,40 @@ function createNoopMemoryProvider() {
 }
 var JobQueue = class {
   jobs = /* @__PURE__ */ new Map();
+  controllers = /* @__PURE__ */ new Map();
+  maxConcurrency;
+  running = 0;
+  waiting = [];
+  constructor(options = {}) {
+    this.maxConcurrency = options.maxConcurrency === void 0 ? Number.POSITIVE_INFINITY : Math.max(1, options.maxConcurrency);
+  }
   /**
-   * Enqueue a background function. Returns the job ID immediately.
-   * EC-1: wraps fn in Promise.resolve().then() so sync throws are caught.
+   * Enqueue a background function. Returns the job ID immediately. The function
+   * receives an `AbortSignal` that fires when the job is cancelled (#58) — a
+   * cooperative job should observe it to stop early. Existing `() => Promise<T>`
+   * callers are unaffected (the signal argument is simply ignored).
    */
   enqueue(fn) {
     const id = randomUUID();
     const job = { id, status: "pending" };
     this.jobs.set(id, job);
-    job.status = "running";
-    Promise.resolve().then(() => fn()).then((result) => {
-      if (job.status === "cancelled") return;
-      job.result = result;
-      job.status = "completed";
-    }).catch((err) => {
-      if (job.status === "cancelled") return;
-      job.error = err instanceof Error ? err.message : String(err);
-      job.status = "failed";
+    const controller = new AbortController();
+    this.controllers.set(id, controller);
+    void this.#acquire().then(() => {
+      if (job.status === "cancelled") {
+        this.#release(id);
+        return;
+      }
+      job.status = "running";
+      Promise.resolve().then(() => fn(controller.signal)).then((result) => {
+        if (job.status === "cancelled") return;
+        job.result = result;
+        job.status = "completed";
+      }).catch((err) => {
+        if (job.status === "cancelled") return;
+        job.error = err instanceof Error ? err.message : String(err);
+        job.status = "failed";
+      }).finally(() => this.#release(id));
     });
     return id;
   }
@@ -18698,17 +19506,39 @@ var JobQueue = class {
     return [...this.jobs.values()];
   }
   /**
-   * Cancel a pending or running job. Returns true if cancelled.
+   * Cancel a pending or running job. Returns true if cancelled. #58 — aborts the
+   * job's `AbortSignal` so a cooperative running job is actually interrupted.
    */
   cancel(id) {
     const job = this.jobs.get(id);
     if (!job) return false;
     if (job.status === "pending" || job.status === "running") {
       job.status = "cancelled";
+      this.controllers.get(id)?.abort();
       return true;
     }
     return false;
   }
+  /** Acquire a concurrency slot (resolves immediately when unbounded/free). */
+  #acquire() {
+    if (this.running < this.maxConcurrency) {
+      this.running += 1;
+      return Promise.resolve();
+    }
+    return new Promise((resolve3) => {
+      this.waiting.push(() => {
+        this.running += 1;
+        resolve3();
+      });
+    });
+  }
+  /** Release a slot + clean up the controller; start the next waiting job. */
+  #release(id) {
+    this.controllers.delete(id);
+    this.running -= 1;
+    const next = this.waiting.shift();
+    if (next !== void 0) next();
+  }
 };
 
 // src/internal/memory/dreaming/run.ts
@@ -19201,24 +20031,42 @@ async function migrateSqliteToLance2(options) {
 }
 
 // src/permission-engine.ts
+function argMatches(matcher, value) {
+  if (typeof matcher === "function") return matcher(value);
+  if (value === void 0) return false;
+  if (matcher instanceof RegExp) return matcher.test(String(value));
+  return matcher === value;
+}
 var PermissionEngine = class {
   constructor(rules, options = {}) {
     this.rules = rules;
-    this.defaultAction = options.defaultAction ?? "allow";
+    this.defaultAction = options.defaultAction ?? "ask";
   }
   rules;
   defaultAction;
   /**
-   * Evaluate a tool name against the rules. First match wins; falls back to the
-   * configured `defaultAction` (default `"allow"`) when no rule matches.
+   * Evaluate a tool name (and optional arguments) against the rules. First
+   * match wins; falls back to the configured `defaultAction` (default `"ask"`,
+   * fail-closed) when no rule matches. #55 — a rule with `args` gates on the
+   * argument values, so the same tool name can resolve to different actions
+   * depending on what it is asked to do.
    */
-  evaluate(toolName) {
+  evaluate(toolName, args) {
     for (const rule of this.rules) {
-      const matches = typeof rule.tool === "string" ? rule.tool === toolName : rule.tool.test(toolName);
-      if (matches) return rule.action;
+      const nameMatches = typeof rule.tool === "string" ? rule.tool === toolName : rule.tool.test(toolName);
+      if (!nameMatches) continue;
+      if (rule.args !== void 0 && !this.#argsMatch(rule.args, args)) continue;
+      return rule.action;
     }
     return this.defaultAction;
   }
+  #argsMatch(matchers, args) {
+    const call = args ?? {};
+    for (const [key2, matcher] of Object.entries(matchers)) {
+      if (!argMatches(matcher, call[key2])) return false;
+    }
+    return true;
+  }
 };
 
 // src/permission-plugin.ts
@@ -19229,8 +20077,8 @@ function createPermissionPlugin(engine, opts = {}) {
     kind: "general",
     register(ctx) {
       ctx.on("pre_tool_call", (rawCtx) => {
-        const { name } = rawCtx;
-        const action = engine.evaluate(name);
+        const { name, args } = rawCtx;
+        const action = engine.evaluate(name, args);
         if (action === "deny") {
           return { block: true, message: `denied by permission engine: ${name}` };
         }
@@ -19295,6 +20143,14 @@ var Security = class {
   }
 };
 
+// src/session-scope.ts
+function scopedConversationId(scope, id) {
+  return `${scope}__${id}`;
+}
+function sessionScopePrefix(scope) {
+  return `${scope}__`;
+}
+
 // src/squad.ts
 init_errors();
 var PersistenceSchema = z.object({
@@ -20012,6 +20868,6 @@ function safeStringify2(v) {
   }
 }
 
-export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map