@ap3x/agent-core 0.1.0 → 0.2.0

package/dist/index.js

@@ -143,6 +143,436 @@ function mapLimit(items, concurrency, fn) {
 import {
   validateToolArguments
 } from "@ap3x/ai";
+
+// src/execution-controller.ts
+import { AsyncLocalStorage } from "async_hooks";
+import {
+  withProviderExecution
+} from "@ap3x/ai";
+
+// src/run-context.ts
+function createRunContext(options = {}) {
+  if (options.parent && options.tenantId !== void 0 && options.tenantId !== options.parent.tenantId) {
+    throw new Error("A child run cannot change tenant identity");
+  }
+  if (options.parent && (options.controller && options.controller !== options.parent.controller || options.policy && options.policy !== options.parent.policy)) {
+    throw new Error("A child run cannot replace execution authority");
+  }
+  const controller = options.parent?.controller ?? options.controller;
+  const policy = options.parent?.policy ?? options.policy;
+  if (policy && !Object.isFrozen(policy)) Object.freeze(policy);
+  return Object.freeze({
+    runId: options.runId ?? uuidv7(),
+    parentRunId: options.parent?.runId,
+    tenantId: options.parent?.tenantId ?? options.tenantId,
+    signal: options.parent?.signal ?? options.signal ?? controller?.signal,
+    controller,
+    policy,
+    depth: options.parent ? options.parent.depth + 1 : 0,
+    attempt: options.parent?.attempt ?? options.attempt ?? 1,
+    fence: options.parent?.fence ?? options.fence ?? 0
+  });
+}
+
+// src/execution-controller.ts
+var ExecutionLimitError = class extends Error {
+  constructor(limit, resources) {
+    super(`Execution refused: ${limit}`);
+    this.limit = limit;
+    this.resources = resources;
+    this.name = "ExecutionLimitError";
+  }
+  limit;
+  resources;
+  reasonCode = "execution_limit";
+};
+var ExecutionController = class {
+  limits;
+  signal;
+  abortController = new AbortController();
+  startedAt = Date.now();
+  values = {
+    turns: 0,
+    toolCalls: 0,
+    childAgents: 0,
+    activeChildren: 0,
+    tokens: 0,
+    estimatedUsd: 0,
+    reservedTokens: 0,
+    reservedEstimatedUsd: 0,
+    unknownPricing: false,
+    usageIncomplete: false
+  };
+  terminalLimit;
+  waiters = /* @__PURE__ */ new Set();
+  timer;
+  detach;
+  constructor(limits = {}, signal) {
+    for (const [name, value] of Object.entries(limits)) {
+      if (value === void 0) continue;
+      if (!Number.isFinite(value) || value < 0) throw new Error(`Invalid execution limit: ${name}`);
+      if (name !== "maxEstimatedUsd" && name !== "opaqueChildEstimatedUsd" && !Number.isInteger(value))
+        throw new Error(`Execution limit must be an integer: ${name}`);
+    }
+    this.limits = Object.freeze({ ...limits });
+    this.signal = this.abortController.signal;
+    if (signal) {
+      const cancel = () => this.cancel();
+      signal.addEventListener("abort", cancel, { once: true });
+      this.detach = () => signal.removeEventListener("abort", cancel);
+      if (signal.aborted) this.cancel();
+    }
+    if (limits.maxElapsedMs !== void 0) {
+      this.timer = setTimeout(() => this.stop("maxElapsedMs"), limits.maxElapsedMs);
+      this.timer.unref?.();
+    }
+  }
+  snapshot() {
+    return { ...this.values, elapsedMs: Date.now() - this.startedAt, limit: this.terminalLimit };
+  }
+  cancel() {
+    this.stop("cancelled");
+  }
+  dispose() {
+    if (this.timer) clearTimeout(this.timer);
+    this.detach?.();
+  }
+  stop(limit) {
+    this.terminalLimit ??= limit;
+    this.abortController.abort();
+    for (const wake of this.waiters) wake();
+  }
+  refuse(limit) {
+    this.stop(limit);
+    throw new ExecutionLimitError(limit, this.snapshot());
+  }
+  assertActive(signal) {
+    if (this.limits.maxElapsedMs !== void 0 && Date.now() - this.startedAt >= this.limits.maxElapsedMs)
+      this.stop("maxElapsedMs");
+    if (this.signal.aborted)
+      throw new ExecutionLimitError(this.terminalLimit ?? "cancelled", this.snapshot());
+    if (signal?.aborted) throw new ExecutionLimitError("cancelled", this.snapshot());
+  }
+  consume(key, cap) {
+    this.assertActive();
+    const maximum = this.limits[cap];
+    if (maximum !== void 0 && this.values[key] >= maximum) this.refuse(cap);
+    this.values[key]++;
+  }
+  turn() {
+    this.consume("turns", "maxTurns");
+  }
+  tool() {
+    this.consume("toolCalls", "maxToolCalls");
+  }
+  assertDepth(depth) {
+    this.assertActive();
+    if (this.limits.maxDepth !== void 0 && depth > this.limits.maxDepth) this.refuse("maxDepth");
+  }
+  async child(depth, signal) {
+    this.assertActive(signal);
+    if (this.limits.maxDepth !== void 0 && depth > this.limits.maxDepth) this.refuse("maxDepth");
+    if (this.limits.maxActiveChildren === 0) this.refuse("maxActiveChildren");
+    this.consume("childAgents", "maxChildAgents");
+    if (this.limits.maxActiveChildren !== void 0 && this.values.activeChildren >= this.limits.maxActiveChildren)
+      this.refuse("maxActiveChildren");
+    this.assertActive(signal);
+    this.values.activeChildren++;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.values.activeChildren--;
+      for (const wake of this.waiters) wake();
+    };
+  }
+  reserve(tokens, estimatedUsd) {
+    this.assertActive();
+    if (!Number.isFinite(tokens) || tokens < 0 || estimatedUsd !== void 0 && (!Number.isFinite(estimatedUsd) || estimatedUsd < 0))
+      throw new Error("Invalid execution reservation");
+    if (estimatedUsd === void 0) {
+      this.values.unknownPricing = true;
+      if (this.limits.maxEstimatedUsd !== void 0) this.refuse("unknown_pricing");
+    }
+    const usd = estimatedUsd ?? 0;
+    if (this.limits.maxTokens !== void 0 && this.values.tokens + this.values.reservedTokens + tokens > this.limits.maxTokens)
+      this.refuse("maxTokens");
+    if (this.limits.maxEstimatedUsd !== void 0 && this.values.estimatedUsd + this.values.reservedEstimatedUsd + usd > this.limits.maxEstimatedUsd)
+      this.refuse("maxEstimatedUsd");
+    this.values.reservedTokens += tokens;
+    this.values.reservedEstimatedUsd += usd;
+    let settled = false;
+    return {
+      settle: (usage) => {
+        if (settled) return;
+        settled = true;
+        this.values.reservedTokens -= tokens;
+        this.values.reservedEstimatedUsd -= usd;
+        if (!usage) this.values.usageIncomplete = true;
+        this.values.tokens += usage?.totalTokens ?? tokens;
+        if (estimatedUsd !== void 0) this.values.estimatedUsd += usage?.cost.total ?? usd;
+        if (this.limits.maxTokens !== void 0 && this.values.tokens + this.values.reservedTokens > this.limits.maxTokens)
+          this.stop("maxTokens");
+        if (this.limits.maxEstimatedUsd !== void 0 && this.values.estimatedUsd + this.values.reservedEstimatedUsd > this.limits.maxEstimatedUsd)
+          this.stop("maxEstimatedUsd");
+      }
+    };
+  }
+};
+var storage = new AsyncLocalStorage();
+function currentRunContext() {
+  return storage.getStore();
+}
+function withRunContext(context, fn) {
+  const parent = currentRunContext();
+  if (parent && (context.controller !== parent.controller || context.tenantId !== parent.tenantId || context.policy !== parent.policy))
+    throw new Error("Nested work cannot replace root execution authority");
+  if (parent && context.depth < parent.depth)
+    throw new Error("Nested work cannot reset execution depth");
+  return storage.run(
+    context,
+    () => withProviderExecution(
+      context.controller ? { signal: context.controller.signal, admit: reserveProviderCall } : void 0,
+      fn
+    )
+  );
+}
+function resolveRunContext(context, signal) {
+  const parent = currentRunContext();
+  if (parent && context && (context.controller !== parent.controller || context.tenantId !== parent.tenantId || context.policy !== parent.policy))
+    throw new Error("Nested work cannot replace root execution authority");
+  if (parent) return parent;
+  return context ?? createRunContext({ signal });
+}
+var workflowDepth = new AsyncLocalStorage();
+function withWorkflowContext(fn) {
+  const parent = currentRunContext();
+  const nested = (workflowDepth.getStore() ?? 0) > 0;
+  const context = parent ? nested ? createRunContext({ parent }) : parent : createRunContext();
+  context.controller?.assertDepth(context.depth);
+  return withRunContext(context, () => workflowDepth.run((workflowDepth.getStore() ?? 0) + 1, fn));
+}
+var opaqueScope = new AsyncLocalStorage();
+function hasOpaqueReservation(context) {
+  return opaqueScope.getStore() === context.runId;
+}
+async function executeMember(agent, task, options) {
+  const parent = resolveRunContext(options?.context, options?.signal);
+  const context = createRunContext({ parent });
+  const controller = context.controller;
+  const release = await controller?.child(context.depth, options?.signal ?? context.signal);
+  let reservation;
+  try {
+    if (controller && !agent.supports?.("execution-controls")) {
+      const { maxTokens, maxEstimatedUsd, opaqueChildTokens, opaqueChildEstimatedUsd } = controller.limits;
+      if (maxTokens !== void 0 && opaqueChildTokens === void 0)
+        throw new Error("Opaque backend requires opaqueChildTokens allocation");
+      if (maxEstimatedUsd !== void 0 && opaqueChildEstimatedUsd === void 0)
+        throw new Error("Opaque backend requires opaqueChildEstimatedUsd allocation");
+      reservation = controller.reserve(opaqueChildTokens ?? 0, opaqueChildEstimatedUsd);
+    }
+    controller?.assertActive(options?.signal);
+    const memberOptions = controller || context.policy || options?.context ? { ...options, context } : options;
+    const run = () => withRunContext(context, () => agent.run(task, memberOptions));
+    const result = await (reservation ? opaqueScope.run(context.runId, run) : run());
+    reservation?.settle(
+      result.usageIncomplete ? void 0 : result.aggregateUsage ?? result.usage
+    );
+    if (controller?.snapshot().limit)
+      return {
+        ...result,
+        stopReason: "length",
+        outcome: "partial",
+        reasonCode: "execution_limit",
+        execution: controller.snapshot()
+      };
+    return result;
+  } finally {
+    reservation?.settle();
+    release?.();
+  }
+}
+function reserveProviderCall(model, context, options) {
+  const controller = currentRunContext()?.controller;
+  if (!controller) return void 0;
+  controller.assertActive(options?.signal);
+  const input = Buffer.byteLength(JSON.stringify(context), "utf8") + 1024;
+  const output = options?.maxTokens ?? model.maxTokens;
+  const rates = Object.values(model.cost ?? {});
+  const known = rates.length === 4 && rates.every((rate) => Number.isFinite(rate) && rate >= 0);
+  return controller.reserve(
+    input + output,
+    known ? (input * Math.max(model.cost.input, model.cost.cacheRead, model.cost.cacheWrite) + output * model.cost.output) / 1e6 : void 0
+  );
+}
+function withProviderReservation(reservation, call) {
+  if (!reservation) return call();
+  let claimed = false;
+  return withProviderExecution(
+    {
+      signal: currentRunContext()?.controller?.signal,
+      admit: (model, context, options) => {
+        if (!claimed) {
+          claimed = true;
+          return reservation;
+        }
+        return reserveProviderCall(model, context, options);
+      }
+    },
+    call
+  );
+}
+async function controlledProviderCall(model, context, options, call) {
+  const reservation = reserveProviderCall(model, context, options);
+  try {
+    const result = await withProviderReservation(reservation, call);
+    reservation?.settle(result.usage);
+    return result;
+  } finally {
+    reservation?.settle();
+  }
+}
+
+// src/policy.ts
+import { createHash } from "crypto";
+var PolicyDeniedError = class extends Error {
+  reasonCode = "policy_denied";
+  constructor(message) {
+    super(message);
+    this.name = "PolicyDeniedError";
+  }
+};
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  const object = value;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonical(object[key])}`).join(",")}}`;
+}
+function argumentsHash(args) {
+  return createHash("sha256").update(canonical(args)).digest("hex");
+}
+function deepFreeze(value) {
+  if (value && typeof value === "object") {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+function immutableArguments(args) {
+  return deepFreeze(JSON.parse(JSON.stringify(args)));
+}
+async function authorizeTool(context, toolName, toolCallId, args, signal) {
+  context?.controller?.assertActive(signal);
+  if (signal?.aborted || context?.signal?.aborted)
+    throw new PolicyDeniedError("Tool call cancelled");
+  const policy = context?.policy;
+  if (!policy || !context) return;
+  const request = Object.freeze({
+    toolName,
+    toolCallId,
+    args,
+    argumentsHash: argumentsHash(args),
+    runId: context.runId,
+    tenantId: context.tenantId,
+    attempt: context.attempt,
+    fence: context.fence,
+    policyVersion: policy.version
+  });
+  let decision;
+  try {
+    decision = await policy.evaluate(request);
+  } catch {
+    throw new PolicyDeniedError("Execution policy failed");
+  }
+  if (decision?.action === "deny") throw new PolicyDeniedError(decision.reason);
+  if (decision?.action === "allow") {
+    context.controller?.assertActive(signal);
+    if (signal?.aborted || context.signal?.aborted)
+      throw new PolicyDeniedError("Tool call cancelled");
+    return;
+  }
+  if (decision?.action !== "require-approval" || !policy.requestApproval)
+    throw new PolicyDeniedError("No valid approval authority available");
+  const expiresInMs = decision.expiresInMs ?? 3e5;
+  if (!Number.isFinite(expiresInMs) || expiresInMs <= 0)
+    throw new PolicyDeniedError("Invalid approval expiry");
+  const now = policy.now ?? Date.now;
+  const approval = Object.freeze({
+    ...request,
+    approvalId: uuidv7(),
+    expiresAt: now() + expiresInMs,
+    reason: decision.reason
+  });
+  const abort = new AbortController();
+  const signals = [
+    ...new Set(
+      [signal, context.signal, context.controller?.signal].filter((s) => !!s)
+    )
+  ];
+  const cancel = () => abort.abort();
+  for (const s of signals) s.addEventListener("abort", cancel, { once: true });
+  if (signals.some((s) => s.aborted)) abort.abort();
+  let timer;
+  let onAbort;
+  try {
+    const interrupted = new Promise((_resolve, reject) => {
+      onAbort = () => reject(new PolicyDeniedError("Approval cancelled or expired"));
+      abort.signal.addEventListener("abort", onAbort, { once: true });
+      if (abort.signal.aborted) onAbort();
+      timer = setTimeout(cancel, expiresInMs);
+    });
+    const resolution = await Promise.race([
+      policy.requestApproval(approval, abort.signal),
+      interrupted
+    ]);
+    if (!resolution.approved || now() >= approval.expiresAt || abort.signal.aborted || signals.some((s) => s.aborted))
+      throw new PolicyDeniedError("Approval denied, expired or cancelled");
+    for (const key of [
+      "approvalId",
+      "argumentsHash",
+      "runId",
+      "attempt",
+      "fence",
+      "policyVersion"
+    ])
+      if (resolution[key] !== approval[key])
+        throw new PolicyDeniedError(`Stale approval binding: ${key}`);
+    if (argumentsHash(args) !== request.argumentsHash)
+      throw new PolicyDeniedError("Approved arguments changed");
+    context.controller?.assertActive(signal);
+  } catch (error) {
+    if (error instanceof PolicyDeniedError) throw error;
+    throw new PolicyDeniedError("Approval authority failed");
+  } finally {
+    if (timer) clearTimeout(timer);
+    for (const s of signals) s.removeEventListener("abort", cancel);
+    if (onAbort) abort.signal.removeEventListener("abort", onAbort);
+  }
+}
+function developmentPolicy() {
+  return Object.freeze({
+    version: "development-v1",
+    evaluate: () => ({ action: "allow" })
+  });
+}
+function readOnlyPolicy(tools = ["read", "ls", "find", "grep"]) {
+  const names = new Set(tools);
+  return Object.freeze({
+    version: `read-only-v1:${argumentsHash([...names].sort())}`,
+    evaluate: (request) => names.has(request.toolName) ? { action: "allow" } : { action: "deny", reason: "Read-only policy" }
+  });
+}
+function productionPolicy(options) {
+  const allowed = new Set(options.allow);
+  const protectedTools = new Set(options.approval);
+  return Object.freeze({
+    version: options.version,
+    requestApproval: options.requestApproval,
+    evaluate: (request) => protectedTools.has(request.toolName) ? { action: "require-approval", reason: `Approval required for ${request.toolName}` } : allowed.has(request.toolName) ? { action: "allow" } : { action: "deny", reason: "Tool is outside the production allowlist" }
+  });
+}
+
+// src/tools.ts
 function defineTool(spec) {
   return spec;
 }
@@ -184,6 +614,7 @@ async function prepareToolCall(toolCall, tools, hooks, signal, refs) {
       assistantMessage: refs.assistantMessage,
       toolCall,
       args,
+      runContext: refs.runContext,
       agentContext: refs.agentContext,
       signal
     } : void 0;
@@ -211,11 +642,20 @@ async function prepareToolCall(toolCall, tools, hooks, signal, refs) {
   if (signal?.aborted) {
     return { kind: "immediate", result: textResult("Operation aborted", true) };
   }
+  const runContext = refs.runContext ?? currentRunContext();
+  try {
+    args = immutableArguments(args);
+    await authorizeTool(runContext, tool.name, toolCall.id, args, signal);
+  } catch (error) {
+    return { kind: "immediate", result: textResult(toError(error).message, true) };
+  }
   return { kind: "ready", tool, args };
 }
 async function executePreparedToolCall(toolCall, prepared, signal, emitUpdate) {
   let acceptingUpdates = true;
   try {
+    currentRunContext()?.controller?.assertActive(signal);
+    currentRunContext()?.controller?.tool();
     const result = await prepared.tool.execute(toolCall.id, prepared.args, signal, (update) => {
       if (acceptingUpdates) emitUpdate(update);
     });
@@ -235,6 +675,7 @@ async function finalizeExecutedToolCall(toolCall, result, hooks, refs) {
       args: refs.args ?? toolCall.arguments,
       result,
       isError: result.isError ?? false,
+      runContext: refs.runContext,
       agentContext: refs.agentContext,
       signal: refs.signal
     } : void 0;
@@ -258,7 +699,11 @@ function parallelToolCallLimit() {
 }
 async function runOneToolCall(toolCall, options) {
   const { tools, hooks, signal, emit, assistantMessage, context } = options;
-  const refs = { assistantMessage, agentContext: context };
+  const refs = {
+    assistantMessage,
+    agentContext: context,
+    runContext: options.runContext
+  };
   await emit({
     type: "tool_execution_start",
     toolCallId: toolCall.id,
@@ -283,7 +728,7 @@ async function runOneToolCall(toolCall, options) {
     signal
   });
 }
-async function executeToolCalls(options) {
+async function executeToolCallsInternal(options) {
   const { toolCalls, signal, mode, emit } = options;
   const sequential = mode === "sequential" || toolCalls.some((toolCall) => {
     const tool = options.tools.find((candidate) => candidate.name === toolCall.name);
@@ -329,11 +774,16 @@ async function executeToolCalls(options) {
   }
   return { messages, terminate: shouldTerminateBatch(results) };
 }
+function executeToolCalls(options) {
+  const runContext = resolveRunContext(options.runContext, options.signal);
+  return withRunContext(runContext, () => executeToolCallsInternal({ ...options, runContext }));
+}
 
 // src/agent-loop.ts
 import {
   streamSimple
 } from "@ap3x/ai";
+import { completeSimple as completeSimple2 } from "@ap3x/ai";
 
 // src/compaction.ts
 import { completeSimple } from "@ap3x/ai";
@@ -685,379 +1135,17 @@ var logger = {
   }
 };
 
-// src/agent-loop.ts
-var DEFAULT_MAX_LOOPS = 1e3;
-function emptyUsage() {
-  return {
-    input: 0,
-    output: 0,
-    cacheRead: 0,
-    cacheWrite: 0,
-    totalTokens: 0,
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
-  };
-}
-function failureMessage(model, message) {
-  return {
-    role: "assistant",
-    content: [],
-    api: model.api,
-    provider: model.provider,
-    model: model.id,
-    usage: emptyUsage(),
-    stopReason: "error",
-    errorMessage: message,
-    timestamp: Date.now()
-  };
-}
-function toolCallsOf(message) {
-  return message.content.filter((block) => block.type === "toolCall");
-}
-function configForTurn(config, turn, messages) {
-  if (!config.selectModel) return config;
-  const model = config.selectModel({ turn, messages });
-  return model ? { ...config, model } : config;
+// src/agent.ts
+function finalTextOf(message) {
+  if (!message) return "";
+  return message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
 }
-async function streamAssistantResponse(context, config, emit, signal, streamFn) {
-  const transformed = config.hooks?.transformContext ? await config.hooks.transformContext(context.messages, signal) : context.messages;
-  const messages = config.hooks?.convertToLlm ? await config.hooks.convertToLlm(transformed) : (
-    // Without a convertToLlm hook the (already transformed) transcript passes
-    // straight through. `AgentMessage` may be wider than `Message` once a host
-    // augments CustomAgentMessages, but a host that does so is expected to map
-    // its custom types down via convertToLlm; absent that, the transcript is
-    // standard `Message`s, so this cast is a no-op on the runtime value.
-    transformed
-  );
-  const llmContext = {
-    systemPrompt: config.systemPrompt ?? context.systemPrompt,
-    messages,
-    tools: config.tools?.map((tool) => ({
-      name: tool.name,
-      description: tool.description,
-      parameters: tool.parameters
-    }))
-  };
-  const resolvedApiKey = config.hooks?.getApiKey ? await config.hooks.getApiKey(config.model.provider) : void 0;
-  const options = {
-    ...config.streamOptions,
-    ...resolvedApiKey ? { apiKey: resolvedApiKey } : {},
-    signal,
-    ...config.reasoning ? { reasoning: config.reasoning } : {}
-  };
-  let started = false;
-  try {
-    const eventStream = streamFn(config.model, llmContext, options);
-    for await (const providerEvent of eventStream) {
-      if (providerEvent.type === "start") {
-        started = true;
-        await emit({ type: "message_start", message: providerEvent.partial });
-        continue;
-      }
-      if (providerEvent.type === "done" || providerEvent.type === "error") {
-        break;
-      }
-      if ("partial" in providerEvent) {
-        await emit({
-          type: "message_update",
-          message: providerEvent.partial,
-          assistantMessageEvent: providerEvent
-        });
-      }
-    }
-    const final = await eventStream.result();
-    if (!started) await emit({ type: "message_start", message: final });
-    await emit({ type: "message_end", message: final });
-    return final;
-  } catch (error) {
-    const message = failureMessage(
-      config.model,
-      error instanceof Error ? error.message : String(error)
-    );
-    if (!started) await emit({ type: "message_start", message });
-    await emit({ type: "message_end", message });
-    return message;
+function lastAssistant(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role === "assistant") return message;
   }
-}
-async function runAgentLoop(prompts, context, config, emit, signal) {
-  const streamFn = config.streamFn ?? streamSimple;
-  const maxLoops = config.maxLoops ?? DEFAULT_MAX_LOOPS;
-  const newMessages = [];
-  const working = {
-    systemPrompt: config.systemPrompt ?? context.systemPrompt,
-    messages: [...context.messages],
-    tools: context.tools
-  };
-  await emit({ type: "agent_start" });
-  const drainSteering = async () => {
-    if (signal?.aborted || !config.hooks?.getSteeringMessages) return [];
-    return await config.hooks.getSteeringMessages() ?? [];
-  };
-  const drainFollowUp = async () => {
-    if (signal?.aborted || !config.hooks?.getFollowUpMessages) return [];
-    return await config.hooks.getFollowUpMessages() ?? [];
-  };
-  const compactionDeferred = async () => {
-    if (!config.hooks?.beforeCompaction) return false;
-    try {
-      return (await config.hooks.beforeCompaction())?.defer === true;
-    } catch {
-      return false;
-    }
-  };
-  let turns = 0;
-  let hasMoreToolCalls = true;
-  let pending = [...prompts];
-  const contextWindow = config.model.contextWindow;
-  const settings = resolveCompactionSettings(
-    config.compaction ?? DEFAULT_COMPACTION_SETTINGS,
-    contextWindow
-  );
-  const compactionOn = settings.enabled && contextWindow > 0;
-  let shadow = null;
-  let anchorFloor = 0;
-  let lastSummary = config.previousSummary;
-  let sawToolContinuation = false;
-  const launchShadow = () => {
-    const snapshotLen = working.messages.length;
-    const snapshot = working.messages.slice(0, snapshotLen);
-    const abort = new AbortController();
-    const onAbort = () => abort.abort();
-    let detached = false;
-    const cleanup = () => {
-      if (detached) return;
-      detached = true;
-      if (signal) signal.removeEventListener("abort", onAbort);
-    };
-    if (signal) signal.addEventListener("abort", onAbort, { once: true });
-    const s = { snapshotLen, abort, cleanup, promise: void 0 };
-    s.promise = compact(snapshot, config.model, {
-      settings,
-      signal: abort.signal,
-      ...lastSummary !== void 0 ? { previousSummary: lastSummary } : {},
-      ...config.compactionComplete ? { complete: config.compactionComplete } : {}
-    }).then((r) => {
-      s.settled = r;
-      cleanup();
-      return r;
-    }).catch((e) => {
-      const r = err(
-        new CompactionError("compaction", toError(e).message, e)
-      );
-      s.settled = r;
-      cleanup();
-      return r;
-    });
-    logger.debug(`compaction: launched shadow (snapshotLen=${snapshotLen})`);
-    return s;
-  };
-  const applyShadow = async (s) => {
-    const r = s.settled;
-    if (!r) return false;
-    if (!r.ok) {
-      logger.warn(`compaction: failed, keeping context (${r.error.message})`);
-      return false;
-    }
-    const cr = r.value;
-    if (cr.summary === "" || cr.keptMessages.length >= s.snapshotLen) return false;
-    const summaryMsg = {
-      // Mirrors buildSessionContext so in-memory swap and resume read identically.
-      role: "user",
-      content: `[Earlier conversation summarized]
-${cr.summary}`,
-      timestamp: Date.now()
-    };
-    const rebased = [
-      summaryMsg,
-      ...cr.keptMessages,
-      ...working.messages.slice(s.snapshotLen)
-      // the arrival tail — messages appended during the in-flight compaction
-    ];
-    const sum = (ms) => ms.reduce((n, m) => n + estimateMessageTokens(m), 0);
-    const before = sum(working.messages);
-    const after = sum(rebased);
-    if (after >= before) {
-      logger.debug("compaction: not smaller, rolled back");
-      return false;
-    }
-    if (rebased.at(-1) !== working.messages.at(-1)) {
-      logger.debug("compaction: tail identity check failed, rolled back");
-      return false;
-    }
-    working.messages = rebased;
-    anchorFloor = rebased.length;
-    lastSummary = cr.summary;
-    await emit({
-      type: "compaction",
-      summary: cr.summary,
-      tokensBefore: cr.tokensBefore,
-      retainedAtSwap: rebased.length - 1,
-      // excludes summaryMsg
-      newMessagesAtSwap: newMessages.length
-    });
-    logger.info(`compaction: swapped ${before}->${after} tokens (kept ${cr.keptMessages.length})`);
-    return true;
-  };
-  while (hasMoreToolCalls || pending.length > 0) {
-    if (turns >= maxLoops) break;
-    await emit({ type: "turn_start" });
-    const steering = await drainSteering();
-    if (steering.length > 0) pending.push(...steering);
-    for (const prompt of pending) {
-      await emit({ type: "message_start", message: prompt });
-      working.messages.push(prompt);
-      newMessages.push(prompt);
-      await emit({ type: "message_end", message: prompt });
-    }
-    pending = [];
-    if (compactionOn) {
-      let handled = false;
-      if (shadow?.settled) {
-        await applyShadow(shadow);
-        shadow = null;
-        handled = true;
-      }
-      if (!handled) {
-        const usage = estimateContextTokens(working.messages, anchorFloor);
-        const tier = compactionTier(usage, contextWindow, settings);
-        if (tier === "hard") {
-          if (!shadow && !await compactionDeferred()) shadow = launchShadow();
-          if (shadow) {
-            await shadow.promise;
-            await applyShadow(shadow);
-            shadow = null;
-          }
-        } else if (tier === "soft" && !shadow && sawToolContinuation && !await compactionDeferred()) {
-          shadow = launchShadow();
-        }
-      }
-    }
-    const assistant = await streamAssistantResponse(
-      working,
-      configForTurn(config, turns, working.messages),
-      emit,
-      signal,
-      streamFn
-    );
-    working.messages.push(assistant);
-    newMessages.push(assistant);
-    turns++;
-    if (config.hooks?.onResponse) await config.hooks.onResponse(assistant);
-    if (assistant.stopReason === "error" || assistant.stopReason === "aborted") {
-      await emit({ type: "turn_end", message: assistant, toolResults: [] });
-      break;
-    }
-    const toolCalls = toolCallsOf(assistant);
-    hasMoreToolCalls = false;
-    if (toolCalls.length === 0) {
-      await emit({ type: "turn_end", message: assistant, toolResults: [] });
-      const followUp = await drainFollowUp();
-      if (followUp.length > 0) {
-        pending = followUp;
-        continue;
-      }
-      break;
-    }
-    const batch = await executeToolCalls({
-      toolCalls,
-      tools: config.tools ?? [],
-      hooks: config.hooks,
-      signal,
-      mode: config.toolExecution ?? "parallel",
-      assistantMessage: assistant,
-      context: working,
-      emit: (event) => emit(event)
-    });
-    for (const result of batch.messages) {
-      await emit({ type: "message_start", message: result });
-      working.messages.push(result);
-      newMessages.push(result);
-      await emit({ type: "message_end", message: result });
-    }
-    await emit({ type: "turn_end", message: assistant, toolResults: batch.messages });
-    if (batch.terminate) {
-      const followUp = await drainFollowUp();
-      if (followUp.length > 0) {
-        pending = followUp;
-        continue;
-      }
-      break;
-    }
-    if (signal?.aborted) break;
-    hasMoreToolCalls = true;
-    sawToolContinuation = true;
-  }
-  if (shadow && !shadow.settled) {
-    shadow.abort.abort();
-    shadow.cleanup();
-  }
-  await emit({ type: "agent_end", messages: newMessages });
-  return newMessages;
-}
-async function runAgentLoopContinue(context, config, emit, signal) {
-  const last = context.messages.at(-1);
-  if (!last) throw new Error("Cannot continue: no messages in context");
-  if (last.role === "assistant") {
-    throw new Error("Cannot continue from message role: assistant");
-  }
-  return runAgentLoop([], context, config, emit, signal);
-}
-function makeEventStream(run) {
-  const queue = [];
-  const waiters = [];
-  let done = false;
-  const emit = (event) => {
-    const waiter = waiters.shift();
-    if (waiter) waiter({ value: event, done: false });
-    else queue.push(event);
-  };
-  const resultPromise = run(emit).finally(() => {
-    done = true;
-    while (waiters.length > 0) {
-      waiters.shift()?.({ value: void 0, done: true });
-    }
-  });
-  return {
-    result: () => resultPromise,
-    async *[Symbol.asyncIterator]() {
-      while (true) {
-        if (queue.length > 0) {
-          yield queue.shift();
-        } else if (done) {
-          return;
-        } else {
-          const next = await new Promise((resolve2) => {
-            waiters.push(resolve2);
-          });
-          if (next.done) return;
-          yield next.value;
-        }
-      }
-    }
-  };
-}
-function agentLoop(prompts, context, config, signal) {
-  return makeEventStream((emit) => runAgentLoop(prompts, context, config, emit, signal));
-}
-function agentLoopContinue(context, config, signal) {
-  const last = context.messages.at(-1);
-  if (!last) throw new Error("Cannot continue: no messages in context");
-  if (last.role === "assistant") {
-    throw new Error("Cannot continue from message role: assistant");
-  }
-  return makeEventStream((emit) => runAgentLoopContinue(context, config, emit, signal));
-}
-
-// src/agent.ts
-function finalTextOf(message) {
-  if (!message) return "";
-  return message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
-}
-function lastAssistant(messages) {
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const message = messages[i];
-    if (message?.role === "assistant") return message;
-  }
-  return void 0;
+  return void 0;
 }
 var Agent = class {
   model;
@@ -1071,6 +1159,8 @@ var Agent = class {
   sessionId;
   autoCompact;
   previousSummary;
+  runContext;
+  compactionComplete;
   toolList;
   transcript;
   running = false;
@@ -1089,6 +1179,7 @@ var Agent = class {
   /** A never-aborted signal handed to listeners for out-of-run queue events. */
   idleSignal = new AbortController().signal;
   constructor(options) {
+    this.compactionComplete = options.compactionComplete;
     this.model = options.model;
     this.systemPrompt = options.systemPrompt;
     this.reasoning = options.reasoning;
@@ -1223,6 +1314,8 @@ var Agent = class {
   }
   currentConfig() {
     return {
+      runContext: this.runContext,
+      compactionComplete: this.compactionComplete,
       model: this.model,
       systemPrompt: this.systemPrompt,
       tools: this.toolList,
@@ -1261,93 +1354,666 @@ var Agent = class {
         const fromUser = userHooks.getFollowUpMessages ? await userHooks.getFollowUpMessages() : [];
         return [...drained, ...fromUser];
       }
-    };
+    };
+  }
+  /** Enqueue a pending message and notify observers via `queue_update`. */
+  enqueue(mode, message) {
+    this.pending.push({ mode, message });
+    void this.emitQueueUpdate();
+  }
+  /** Remove and return (in FIFO order) the messages whose mode matches. */
+  drainQueue(match) {
+    if (this.pending.length === 0) return [];
+    const drained = [];
+    const remaining = [];
+    for (const entry of this.pending) {
+      if (match(entry.mode)) drained.push(entry.message);
+      else remaining.push(entry);
+    }
+    this.pending = remaining;
+    return drained;
+  }
+  /**
+   * Emit a `queue_update` snapshot to every listener. Best-effort and
+   * out-of-band: a failing observer is isolated so it can neither break an
+   * enqueue nor the active run. Uses the active run's signal when running, else
+   * a never-aborted idle signal.
+   */
+  async emitQueueUpdate() {
+    const byMode = (mode) => this.pending.filter((entry) => entry.mode === mode).map((entry) => entry.message);
+    const event = {
+      type: "queue_update",
+      steer: byMode("steer"),
+      followUp: byMode("followUp"),
+      nextTurn: byMode("nextTurn")
+    };
+    const signal = this.controller?.signal ?? this.idleSignal;
+    for (const listener of this.listeners) {
+      try {
+        await listener(event, signal);
+      } catch {
+      }
+    }
+  }
+  async runWithLifecycle(run) {
+    this.running = true;
+    this.lastError = void 0;
+    this.controller = new AbortController();
+    const signal = this.controller.signal;
+    const emit = async (event) => {
+      if (event.type === "compaction") this.previousSummary = event.summary;
+      for (const listener of this.listeners) {
+        await listener(event, signal);
+      }
+    };
+    try {
+      const newMessages = await run(emit, signal);
+      this.transcript.push(...newMessages);
+      const assistant = lastAssistant(newMessages);
+      if (assistant?.errorMessage) this.lastError = assistant.errorMessage;
+      if (!assistant) {
+        throw new AgentHarnessError("invalid_state", "Run completed without an assistant message");
+      }
+      return assistant;
+    } finally {
+      this.running = false;
+      this.controller = void 0;
+    }
+  }
+};
+
+// src/agent-errors.ts
+var AgentError = class extends Error {
+  /** Machine-readable, stable error code. */
+  code;
+  cause;
+  constructor(message, code = "agent", cause) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.cause = cause;
+  }
+};
+var AgentInitializationError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_initialization", cause);
+  }
+};
+var AgentRunError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_run", cause);
+  }
+};
+var AgentLLMError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_llm", cause);
+  }
+};
+var AgentToolError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_tool", cause);
+  }
+};
+var AgentMemoryError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_memory", cause);
+  }
+};
+var AgentMCPConnectionError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_mcp_connection", cause);
+  }
+};
+var AgentMCPToolError = class extends AgentError {
+  constructor(message, cause) {
+    super(message, "agent_mcp_tool", cause);
+  }
+};
+
+// src/run-result.ts
+function emptyUsage() {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+  };
+}
+function addUsage(total, usage) {
+  total.input += usage.input;
+  total.output += usage.output;
+  total.cacheRead += usage.cacheRead;
+  total.cacheWrite += usage.cacheWrite;
+  total.totalTokens += usage.totalTokens;
+  total.cost.input += usage.cost.input;
+  total.cost.output += usage.cost.output;
+  total.cost.cacheRead += usage.cost.cacheRead;
+  total.cost.cacheWrite += usage.cost.cacheWrite;
+  total.cost.total += usage.cost.total;
+}
+function runCompletion(result) {
+  if (result.reasonCode === "execution_limit")
+    return { outcome: "partial", reasonCode: "execution_limit" };
+  if (result.stopReason === "error")
+    return { outcome: "failed", reasonCode: result.reasonCode ?? "provider_error" };
+  if (result.stopReason === "aborted") return { outcome: "cancelled", reasonCode: "cancelled" };
+  if (result.stopReason === "length")
+    return { outcome: "partial", reasonCode: result.reasonCode ?? "output_limit" };
+  if (result.outcome)
+    return {
+      outcome: result.outcome,
+      reasonCode: result.reasonCode ?? (result.outcome === "succeeded" ? "completed" : "execution_error")
+    };
+  return { outcome: "succeeded", reasonCode: "completed" };
+}
+function toRunResult(messages, metadata = {}) {
+  const assistant = lastAssistant(messages);
+  const aggregateUsage = metadata.aggregateUsage ?? emptyUsage();
+  if (!metadata.aggregateUsage) {
+    for (const message of messages)
+      if (message.role === "assistant") addUsage(aggregateUsage, message.usage);
+  }
+  const stopReason = assistant?.stopReason ?? "error";
+  const completion = assistant ? runCompletion({ stopReason, ...metadata }) : { outcome: "failed", reasonCode: "no_assistant" };
+  return {
+    messages,
+    finalText: finalTextOf(assistant),
+    usage: assistant?.usage ?? emptyUsage(),
+    aggregateUsage,
+    stopReason,
+    errorMessage: assistant?.errorMessage,
+    ...metadata.usageIncomplete ? { usageIncomplete: true } : {},
+    ...metadata.backendData !== void 0 ? { backendData: metadata.backendData } : {},
+    ...completion
+  };
+}
+var AgentRunFailure = class extends AgentRunError {
+  result;
+  completion;
+  constructor(result) {
+    const completion = runCompletion(result);
+    super(
+      result.errorMessage ?? `Agent run ${completion.outcome}: ${completion.reasonCode}`,
+      result
+    );
+    this.result = result;
+    this.completion = completion;
+  }
+};
+function assertRunSucceeded(result) {
+  if (runCompletion(result).outcome !== "succeeded") throw new AgentRunFailure(result);
+}
+
+// src/agent-loop.ts
+var DEFAULT_MAX_LOOPS = 1e3;
+function emptyUsage2() {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+  };
+}
+function failureMessage(model, message, stopReason = "error") {
+  return {
+    role: "assistant",
+    content: [],
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    usage: emptyUsage2(),
+    stopReason,
+    errorMessage: message,
+    timestamp: Date.now()
+  };
+}
+function toolCallsOf(message) {
+  return message.content.filter((block) => block.type === "toolCall");
+}
+function configForTurn(config, turn, messages) {
+  if (!config.selectModel) return config;
+  const model = config.selectModel({ turn, messages });
+  return model ? { ...config, model } : config;
+}
+async function streamAssistantResponse(context, config, emit, signal, streamFn) {
+  if (signal?.aborted) {
+    const message = failureMessage(config.model, "Agent run cancelled", "aborted");
+    await emit({ type: "message_start", message });
+    await emit({ type: "message_end", message });
+    return message;
+  }
+  const transformed = config.hooks?.transformContext ? await config.hooks.transformContext(context.messages, signal) : context.messages;
+  const messages = config.hooks?.convertToLlm ? await config.hooks.convertToLlm(transformed) : (
+    // Without a convertToLlm hook the (already transformed) transcript passes
+    // straight through. `AgentMessage` may be wider than `Message` once a host
+    // augments CustomAgentMessages, but a host that does so is expected to map
+    // its custom types down via convertToLlm; absent that, the transcript is
+    // standard `Message`s, so this cast is a no-op on the runtime value.
+    transformed
+  );
+  const llmContext = {
+    systemPrompt: config.systemPrompt ?? context.systemPrompt,
+    messages,
+    tools: config.tools?.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters
+    }))
+  };
+  const resolvedApiKey = config.hooks?.getApiKey ? await config.hooks.getApiKey(config.model.provider) : void 0;
+  const options = {
+    ...config.streamOptions,
+    ...resolvedApiKey ? { apiKey: resolvedApiKey } : {},
+    signal,
+    ...config.reasoning ? { reasoning: config.reasoning } : {}
+  };
+  let started = false;
+  let reservation;
+  try {
+    if (signal?.aborted) {
+      const message = failureMessage(config.model, "Agent run cancelled", "aborted");
+      await emit({ type: "message_start", message });
+      await emit({ type: "message_end", message });
+      return message;
+    }
+    reservation = reserveProviderCall(config.model, llmContext, options);
+    const eventStream = withProviderReservation(
+      reservation,
+      () => streamFn(config.model, llmContext, options)
+    );
+    for await (const providerEvent of eventStream) {
+      if (providerEvent.type === "start") {
+        started = true;
+        await emit({ type: "message_start", message: providerEvent.partial });
+        continue;
+      }
+      if (providerEvent.type === "done" || providerEvent.type === "error") {
+        break;
+      }
+      if ("partial" in providerEvent) {
+        await emit({
+          type: "message_update",
+          message: providerEvent.partial,
+          assistantMessageEvent: providerEvent
+        });
+      }
+    }
+    const final = await eventStream.result();
+    reservation?.settle(final.usage);
+    if (!started) await emit({ type: "message_start", message: final });
+    await emit({ type: "message_end", message: final });
+    return final;
+  } catch (error) {
+    const message = failureMessage(
+      config.model,
+      error instanceof Error ? error.message : String(error)
+    );
+    if (!started) await emit({ type: "message_start", message });
+    await emit({ type: "message_end", message });
+    return message;
+  } finally {
+    reservation?.settle();
+  }
+}
+async function runAgentLoopInternal(prompts, context, config, emit, signal) {
+  const streamFn = config.streamFn ?? streamSimple;
+  const maxLoops = config.maxLoops ?? DEFAULT_MAX_LOOPS;
+  const newMessages = [];
+  const aggregateUsage = emptyUsage();
+  let reasonCode;
+  const working = {
+    systemPrompt: config.systemPrompt ?? context.systemPrompt,
+    messages: [...context.messages],
+    tools: context.tools
+  };
+  await emit({ type: "agent_start" });
+  const drainSteering = async () => {
+    if (signal?.aborted || !config.hooks?.getSteeringMessages) return [];
+    return await config.hooks.getSteeringMessages() ?? [];
+  };
+  const drainFollowUp = async () => {
+    if (signal?.aborted || !config.hooks?.getFollowUpMessages) return [];
+    return await config.hooks.getFollowUpMessages() ?? [];
+  };
+  const compactionDeferred = async () => {
+    if (!config.hooks?.beforeCompaction) return false;
+    try {
+      return (await config.hooks.beforeCompaction())?.defer === true;
+    } catch {
+      return false;
+    }
+  };
+  let turns = 0;
+  let hasMoreToolCalls = true;
+  let pending = [...prompts];
+  const contextWindow = config.model.contextWindow;
+  const settings = resolveCompactionSettings(
+    config.compaction ?? DEFAULT_COMPACTION_SETTINGS,
+    contextWindow
+  );
+  const compactionOn = settings.enabled && contextWindow > 0;
+  let shadow = null;
+  let anchorFloor = 0;
+  let lastSummary = config.previousSummary;
+  let sawToolContinuation = false;
+  const launchShadow = () => {
+    const snapshotLen = working.messages.length;
+    const snapshot = working.messages.slice(0, snapshotLen);
+    const abort = new AbortController();
+    const onAbort = () => abort.abort();
+    let detached = false;
+    const cleanup = () => {
+      if (detached) return;
+      detached = true;
+      if (signal) signal.removeEventListener("abort", onAbort);
+    };
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
+    const s = { snapshotLen, abort, cleanup, promise: void 0 };
+    s.promise = compact(snapshot, config.model, {
+      settings,
+      signal: abort.signal,
+      ...lastSummary !== void 0 ? { previousSummary: lastSummary } : {},
+      complete: async (model, context2, options) => {
+        const response = await controlledProviderCall(
+          model,
+          context2,
+          options,
+          () => (config.compactionComplete ?? completeSimple2)(model, context2, options)
+        );
+        addUsage(aggregateUsage, response.usage);
+        return response;
+      }
+    }).then((r) => {
+      s.settled = r;
+      cleanup();
+      return r;
+    }).catch((e) => {
+      const r = err(
+        new CompactionError("compaction", toError(e).message, e)
+      );
+      s.settled = r;
+      cleanup();
+      return r;
+    });
+    logger.debug(`compaction: launched shadow (snapshotLen=${snapshotLen})`);
+    return s;
+  };
+  const applyShadow = async (s) => {
+    const r = s.settled;
+    if (!r) return false;
+    if (!r.ok) {
+      logger.warn(`compaction: failed, keeping context (${r.error.message})`);
+      return false;
+    }
+    const cr = r.value;
+    if (cr.summary === "" || cr.keptMessages.length >= s.snapshotLen) return false;
+    const summaryMsg = {
+      // Mirrors buildSessionContext so in-memory swap and resume read identically.
+      role: "user",
+      content: `[Earlier conversation summarized]
+${cr.summary}`,
+      timestamp: Date.now()
+    };
+    const rebased = [
+      summaryMsg,
+      ...cr.keptMessages,
+      ...working.messages.slice(s.snapshotLen)
+      // the arrival tail — messages appended during the in-flight compaction
+    ];
+    const sum = (ms) => ms.reduce((n, m) => n + estimateMessageTokens(m), 0);
+    const before = sum(working.messages);
+    const after = sum(rebased);
+    if (after >= before) {
+      logger.debug("compaction: not smaller, rolled back");
+      return false;
+    }
+    if (rebased.at(-1) !== working.messages.at(-1)) {
+      logger.debug("compaction: tail identity check failed, rolled back");
+      return false;
+    }
+    working.messages = rebased;
+    anchorFloor = rebased.length;
+    lastSummary = cr.summary;
+    await emit({
+      type: "compaction",
+      summary: cr.summary,
+      tokensBefore: cr.tokensBefore,
+      retainedAtSwap: rebased.length - 1,
+      // excludes summaryMsg
+      newMessagesAtSwap: newMessages.length
+    });
+    logger.info(`compaction: swapped ${before}->${after} tokens (kept ${cr.keptMessages.length})`);
+    return true;
+  };
+  try {
+    while (hasMoreToolCalls || pending.length > 0) {
+      if (turns >= maxLoops) {
+        reasonCode = "max_turns";
+        break;
+      }
+      await emit({ type: "turn_start" });
+      const steering = await drainSteering();
+      if (steering.length > 0) pending.push(...steering);
+      for (const prompt of pending) {
+        await emit({ type: "message_start", message: prompt });
+        working.messages.push(prompt);
+        newMessages.push(prompt);
+        await emit({ type: "message_end", message: prompt });
+      }
+      pending = [];
+      if (signal?.aborted) {
+        const assistant2 = failureMessage(config.model, "Agent run cancelled", "aborted");
+        newMessages.push(assistant2);
+        await emit({ type: "message_start", message: assistant2 });
+        await emit({ type: "message_end", message: assistant2 });
+        await emit({ type: "turn_end", message: assistant2, toolResults: [] });
+        break;
+      }
+      if (compactionOn) {
+        let handled = false;
+        if (shadow?.settled) {
+          await applyShadow(shadow);
+          shadow = null;
+          handled = true;
+        }
+        if (!handled) {
+          const usage = estimateContextTokens(working.messages, anchorFloor);
+          const tier = compactionTier(usage, contextWindow, settings);
+          if (tier === "hard") {
+            if (!shadow && !await compactionDeferred()) shadow = launchShadow();
+            if (shadow) {
+              await shadow.promise;
+              await applyShadow(shadow);
+              shadow = null;
+            }
+          } else if (tier === "soft" && !shadow && sawToolContinuation && !await compactionDeferred()) {
+            shadow = launchShadow();
+          }
+        }
+      }
+      currentRunContext()?.controller?.turn();
+      const assistant = await streamAssistantResponse(
+        working,
+        configForTurn(config, turns, working.messages),
+        emit,
+        signal,
+        streamFn
+      );
+      addUsage(aggregateUsage, assistant.usage);
+      working.messages.push(assistant);
+      newMessages.push(assistant);
+      turns++;
+      const stopDecision = await config.hooks?.onResponse?.(assistant);
+      if (assistant.stopReason === "error" || assistant.stopReason === "aborted") {
+        await emit({ type: "turn_end", message: assistant, toolResults: [] });
+        break;
+      }
+      if (stopDecision?.stop) {
+        await emit({ type: "turn_end", message: assistant, toolResults: [] });
+        break;
+      }
+      const toolCalls = toolCallsOf(assistant);
+      hasMoreToolCalls = false;
+      if (toolCalls.length === 0) {
+        await emit({ type: "turn_end", message: assistant, toolResults: [] });
+        const followUp = await drainFollowUp();
+        if (followUp.length > 0) {
+          pending = followUp;
+          continue;
+        }
+        break;
+      }
+      const batch = await executeToolCalls({
+        toolCalls,
+        tools: config.tools ?? [],
+        hooks: config.hooks,
+        signal,
+        mode: config.toolExecution ?? "parallel",
+        assistantMessage: assistant,
+        context: working,
+        runContext: config.runContext,
+        emit: (event) => emit(event)
+      });
+      for (const result of batch.messages) {
+        await emit({ type: "message_start", message: result });
+        working.messages.push(result);
+        newMessages.push(result);
+        await emit({ type: "message_end", message: result });
+      }
+      await emit({ type: "turn_end", message: assistant, toolResults: batch.messages });
+      if (batch.terminate) {
+        const followUp = await drainFollowUp();
+        if (followUp.length > 0) {
+          pending = followUp;
+          continue;
+        }
+        break;
+      }
+      if (signal?.aborted) break;
+      hasMoreToolCalls = true;
+      sawToolContinuation = true;
+    }
+  } catch (error) {
+    if (!(error instanceof ExecutionLimitError)) throw error;
+    reasonCode = "execution_limit";
+  } finally {
+    if (shadow) {
+      if (!shadow.settled) shadow.abort.abort();
+      shadow.cleanup();
+      await shadow.promise;
+    }
   }
-  /** Enqueue a pending message and notify observers via `queue_update`. */
-  enqueue(mode, message) {
-    this.pending.push({ mode, message });
-    void this.emitQueueUpdate();
+  const last = [...newMessages].reverse().find((message) => message.role === "assistant");
+  if (signal?.aborted && last?.stopReason !== "aborted") {
+    const cancelled = failureMessage(config.model, "Agent run cancelled", "aborted");
+    cancelled.content = last?.content.filter((block) => block.type !== "toolCall") ?? [];
+    newMessages.push(cancelled);
+    await emit({ type: "message_start", message: cancelled });
+    await emit({ type: "message_end", message: cancelled });
+  } else if (!last) {
+    const failed = failureMessage(config.model, "Run completed without an assistant message");
+    newMessages.push(failed);
+    await emit({ type: "message_start", message: failed });
+    await emit({ type: "message_end", message: failed });
+  }
+  const final = [...newMessages].reverse().find((message) => message.role === "assistant");
+  const limit = config.runContext?.controller?.snapshot().limit;
+  if (limit && limit !== "cancelled") reasonCode = "execution_limit";
+  const completion = runCompletion({
+    stopReason: final?.stopReason ?? "error",
+    ...reasonCode === "max_turns" || reasonCode === "execution_limit" ? { outcome: "partial", reasonCode } : {}
+  });
+  await emit({
+    type: "agent_end",
+    messages: newMessages,
+    aggregateUsage,
+    execution: config.runContext?.controller?.snapshot(),
+    ...completion
+  });
+  return newMessages;
+}
+async function runAgentLoop(prompts, context, config, emit, signal) {
+  const runContext = resolveRunContext(config.runContext, signal);
+  const controller = new AbortController();
+  const signals = [
+    ...new Set(
+      [signal, runContext.signal, runContext.controller?.signal].filter(
+        (s) => !!s
+      )
+    )
+  ];
+  const abort = () => controller.abort();
+  for (const s of signals) s.addEventListener("abort", abort, { once: true });
+  if (signals.some((s) => s.aborted)) abort();
+  try {
+    return await withRunContext(
+      runContext,
+      () => runAgentLoopInternal(prompts, context, { ...config, runContext }, emit, controller.signal)
+    );
+  } finally {
+    for (const s of signals) s.removeEventListener("abort", abort);
   }
-  /** Remove and return (in FIFO order) the messages whose mode matches. */
-  drainQueue(match) {
-    if (this.pending.length === 0) return [];
-    const drained = [];
-    const remaining = [];
-    for (const entry of this.pending) {
-      if (match(entry.mode)) drained.push(entry.message);
-      else remaining.push(entry);
-    }
-    this.pending = remaining;
-    return drained;
+}
+async function runAgentLoopContinue(context, config, emit, signal) {
+  const last = context.messages.at(-1);
+  if (!last) throw new Error("Cannot continue: no messages in context");
+  if (last.role === "assistant") {
+    throw new Error("Cannot continue from message role: assistant");
   }
-  /**
-   * Emit a `queue_update` snapshot to every listener. Best-effort and
-   * out-of-band: a failing observer is isolated so it can neither break an
-   * enqueue nor the active run. Uses the active run's signal when running, else
-   * a never-aborted idle signal.
-   */
-  async emitQueueUpdate() {
-    const byMode = (mode) => this.pending.filter((entry) => entry.mode === mode).map((entry) => entry.message);
-    const event = {
-      type: "queue_update",
-      steer: byMode("steer"),
-      followUp: byMode("followUp"),
-      nextTurn: byMode("nextTurn")
-    };
-    const signal = this.controller?.signal ?? this.idleSignal;
-    for (const listener of this.listeners) {
-      try {
-        await listener(event, signal);
-      } catch {
-      }
+  return runAgentLoop([], context, config, emit, signal);
+}
+function makeEventStream(run) {
+  const queue = [];
+  const waiters = [];
+  let done = false;
+  const emit = (event) => {
+    const waiter = waiters.shift();
+    if (waiter) waiter({ value: event, done: false });
+    else queue.push(event);
+  };
+  const resultPromise = run(emit).finally(() => {
+    done = true;
+    while (waiters.length > 0) {
+      waiters.shift()?.({ value: void 0, done: true });
     }
-  }
-  async runWithLifecycle(run) {
-    this.running = true;
-    this.lastError = void 0;
-    this.controller = new AbortController();
-    const signal = this.controller.signal;
-    const emit = async (event) => {
-      if (event.type === "compaction") this.previousSummary = event.summary;
-      for (const listener of this.listeners) {
-        await listener(event, signal);
-      }
-    };
-    try {
-      const newMessages = await run(emit, signal);
-      this.transcript.push(...newMessages);
-      const assistant = lastAssistant(newMessages);
-      if (assistant?.errorMessage) this.lastError = assistant.errorMessage;
-      if (!assistant) {
-        throw new AgentHarnessError("invalid_state", "Run completed without an assistant message");
+  });
+  void resultPromise.catch(() => void 0);
+  return {
+    result: () => resultPromise,
+    async *[Symbol.asyncIterator]() {
+      while (true) {
+        if (queue.length > 0) {
+          yield queue.shift();
+        } else if (done) {
+          return;
+        } else {
+          const next = await new Promise((resolve2) => {
+            waiters.push(resolve2);
+          });
+          if (next.done) return;
+          yield next.value;
+        }
       }
-      return assistant;
-    } finally {
-      this.running = false;
-      this.controller = void 0;
     }
+  };
+}
+function agentLoop(prompts, context, config, signal) {
+  return makeEventStream((emit) => runAgentLoop(prompts, context, config, emit, signal));
+}
+function agentLoopContinue(context, config, signal) {
+  const last = context.messages.at(-1);
+  if (!last) throw new Error("Cannot continue: no messages in context");
+  if (last.role === "assistant") {
+    throw new Error("Cannot continue from message role: assistant");
   }
-};
+  return makeEventStream((emit) => runAgentLoopContinue(context, config, emit, signal));
+}
 
 // src/backend.ts
-var EMPTY_USAGE = {
-  input: 0,
-  output: 0,
-  cacheRead: 0,
-  cacheWrite: 0,
-  totalTokens: 0,
-  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
-};
-function toRunResult(messages) {
-  const assistant = lastAssistant(messages);
-  return {
-    messages,
-    finalText: finalTextOf(assistant),
-    usage: assistant?.usage ?? EMPTY_USAGE,
-    stopReason: assistant?.stopReason ?? "error",
-    errorMessage: assistant?.errorMessage
-  };
-}
 function toPrompts(task) {
   if (typeof task === "string") {
     return [{ role: "user", content: task, timestamp: Date.now() }];
@@ -1358,7 +2024,7 @@ var Ap3xRuntimeBackend = class _Ap3xRuntimeBackend {
   options;
   ephemeral;
   stateful;
-  active;
+  active = /* @__PURE__ */ new Set();
   listeners = /* @__PURE__ */ new Set();
   constructor(options) {
     const { ephemeral, ...agentOptions } = options;
@@ -1374,61 +2040,52 @@ var Ap3xRuntimeBackend = class _Ap3xRuntimeBackend {
     return this.stateful;
   }
   async run(task, opts) {
-    const agent = this.agentFor();
-    this.active = agent;
-    const unsubscribers = [...this.listeners].map(
-      (listener) => agent.subscribe((event) => listener(event))
-    );
-    let onExternalAbort;
-    if (opts?.signal) {
-      onExternalAbort = () => agent.abort();
-      if (opts.signal.aborted) {
-        queueMicrotask(() => agent.abort());
-      } else {
-        opts.signal.addEventListener("abort", onExternalAbort, { once: true });
-      }
+    let terminal;
+    const context = resolveRunContext(opts?.context, opts?.signal);
+    const messages = await this.execute(task, { ...opts, context }, (event) => {
+      if (event.type === "agent_end") terminal = event;
+    });
+    return {
+      ...toRunResult(messages, terminal),
+      runId: context.runId,
+      parentRunId: context.parentRunId,
+      execution: context.controller?.snapshot()
+    };
+  }
+  runStream(task, opts) {
+    return makeEventStream((emit) => this.execute(task, opts, emit));
+  }
+  /** Both entry points drive the same Agent lifecycle, including state, hooks and subscribers. */
+  async execute(task, opts, emit) {
+    if (!this.ephemeral && this.active.size > 0) {
+      throw new AgentHarnessError("busy", "Stateful backend is already processing a run");
     }
-    const before = this.ephemeral ? 0 : agent.messages.length;
+    const agent = this.agentFor();
+    agent.runContext = resolveRunContext(opts?.context, opts?.signal);
+    this.active.add(agent);
+    let produced = [];
+    const unsubscribe = agent.subscribe(async (event) => {
+      if (event.type === "agent_end") produced = event.messages;
+      await emit(event);
+      for (const listener of this.listeners) await listener(event);
+    });
+    const signals = [
+      ...new Set(
+        [opts?.signal, agent.runContext.signal].filter((signal) => !!signal)
+      )
+    ];
+    const onAbort = () => agent.abort();
+    for (const signal of signals) signal.addEventListener("abort", onAbort, { once: true });
     try {
-      await agent.prompt(toPrompts(task));
+      const pending = withRunContext(agent.runContext, () => agent.prompt(toPrompts(task)));
+      if (signals.some((signal) => signal.aborted)) agent.abort();
+      await pending;
+      return produced;
     } finally {
-      for (const unsubscribe of unsubscribers) unsubscribe();
-      if (opts?.signal && onExternalAbort) {
-        opts.signal.removeEventListener("abort", onExternalAbort);
-      }
-      this.active = void 0;
+      unsubscribe();
+      for (const signal of signals) signal.removeEventListener("abort", onAbort);
+      this.active.delete(agent);
     }
-    const messages = this.ephemeral ? agent.messages : agent.messages.slice(before);
-    return toRunResult(messages);
-  }
-  runStream(task, opts) {
-    const agent = this.agentFor();
-    return agentLoop(
-      toPrompts(task),
-      {
-        systemPrompt: this.options.systemPrompt,
-        messages: this.ephemeral ? [] : [...agent.messages],
-        tools: this.options.tools?.map((tool) => ({
-          name: tool.name,
-          description: tool.description,
-          parameters: tool.parameters
-        }))
-      },
-      {
-        model: this.options.model,
-        systemPrompt: this.options.systemPrompt,
-        tools: this.options.tools,
-        reasoning: this.options.reasoning,
-        maxLoops: this.options.maxLoops,
-        toolExecution: this.options.toolExecution,
-        streamOptions: this.options.streamOptions,
-        hooks: this.options.hooks,
-        streamFn: this.options.streamFn,
-        compaction: resolveAutoCompact(this.options.autoCompact),
-        previousSummary: this.options.previousSummary
-      },
-      opts?.signal
-    );
   }
   subscribe(listener) {
     this.listeners.add(listener);
@@ -1437,7 +2094,7 @@ var Ap3xRuntimeBackend = class _Ap3xRuntimeBackend {
     };
   }
   abort() {
-    this.active?.abort();
+    for (const agent of this.active) agent.abort();
   }
   clone() {
     return new _Ap3xRuntimeBackend({ ...this.options, ephemeral: this.ephemeral });
@@ -1448,6 +2105,7 @@ var Ap3xRuntimeBackend = class _Ap3xRuntimeBackend {
       case "subscribe":
       case "abort":
       case "clone":
+      case "execution-controls":
         return true;
       case "tools":
         return (this.options.tools?.length ?? 0) > 0;
@@ -1455,6 +2113,9 @@ var Ap3xRuntimeBackend = class _Ap3xRuntimeBackend {
         return false;
     }
   }
+  checkpointIdentity() {
+    return { backend: "native", configuration: this.options };
+  }
   getCurrentModel() {
     return this.options.model;
   }
@@ -1548,8 +2209,8 @@ ${entry.summary}`,
   return context;
 }
 var Session = class {
-  constructor(storage) {
-    this.storage = storage;
+  constructor(storage2) {
+    this.storage = storage2;
   }
   storage;
   getStorage() {
@@ -1597,6 +2258,17 @@ var Session = class {
       message
     }));
   }
+  /** Append non-model-visible host metadata to the active branch. */
+  appendCustom(customType, data) {
+    return this.appendUnder(this.storage.getLeafId(), (id) => ({
+      id,
+      parentId: null,
+      timestamp: 0,
+      type: "custom",
+      customType,
+      data
+    }));
+  }
   /** Append a compaction boundary. Returns the new id. */
   appendCompaction(summary, firstKeptEntryId, tokensBefore) {
     if (!this.storage.getEntry(firstKeptEntryId)) {
@@ -1907,6 +2579,79 @@ var StringJsonlFile = class {
   }
 };
 
+// src/session-attempt.ts
+var SessionAttemptRecorder = class {
+  constructor(session) {
+    this.session = session;
+    session.appendCustom("run_attempt", { attemptId: this.attemptId, phase: "started" });
+  }
+  session;
+  attemptId = uuidv7();
+  count = 0;
+  finished = false;
+  compaction;
+  observe(event) {
+    if (this.finished) return;
+    if (event.type === "message_end") this.append(event.message);
+    if (event.type === "compaction") this.compaction = event;
+  }
+  append(message) {
+    this.session.appendMessage(message);
+    this.count++;
+  }
+  finish(result) {
+    if (this.finished) return;
+    for (const message of result.messages.slice(this.count)) this.append(message);
+    if (this.compaction) {
+      const kept = this.compaction.retainedAtSwap + (this.count - this.compaction.newMessagesAtSwap);
+      const entries = this.session.getBranch().filter(producesContextMessage);
+      const anchor = entries[entries.length - kept];
+      if (anchor)
+        this.session.appendCompaction(
+          this.compaction.summary,
+          anchor.id,
+          this.compaction.tokensBefore
+        );
+    }
+    this.session.appendCustom("run_attempt", {
+      attemptId: this.attemptId,
+      phase: "finished",
+      ...runCompletion(result),
+      errorMessage: result.errorMessage
+    });
+    this.finished = true;
+  }
+  fail(error) {
+    if (this.finished) return;
+    this.session.appendCustom("run_attempt", {
+      attemptId: this.attemptId,
+      phase: "finished",
+      outcome: "failed",
+      errorMessage: error instanceof Error ? error.message : String(error)
+    });
+    this.finished = true;
+  }
+};
+function inspectSessionAttempts(session) {
+  const attempts = /* @__PURE__ */ new Map();
+  for (const entry of session.getBranch()) {
+    if (entry.type !== "custom" || entry.customType !== "run_attempt" || !entry.data || typeof entry.data !== "object")
+      continue;
+    const data = entry.data;
+    if (typeof data.attemptId !== "string") continue;
+    if (data.phase === "started")
+      attempts.set(data.attemptId, { attemptId: data.attemptId, status: "incomplete" });
+    else if (data.phase === "finished" && ["succeeded", "failed", "cancelled", "partial"].includes(String(data.outcome))) {
+      attempts.set(data.attemptId, {
+        attemptId: data.attemptId,
+        status: data.outcome,
+        ...typeof data.errorMessage === "string" ? { errorMessage: data.errorMessage } : {}
+      });
+    }
+  }
+  return [...attempts.values()];
+}
+
 // src/harness.ts
 var AgentHarness = class {
   session;
@@ -1928,8 +2673,12 @@ var AgentHarness = class {
    */
   unpersistedSummary;
   busy = false;
+  incrementalPersistence;
+  recorder;
+  terminal;
   constructor(options) {
-    const { session, ...agentOptions } = options;
+    const { session, incrementalPersistence, ...agentOptions } = options;
+    this.incrementalPersistence = incrementalPersistence ?? false;
     this.session = session;
     this.agentOptions = agentOptions;
     const context = session.buildContext();
@@ -1945,16 +2694,21 @@ var AgentHarness = class {
     this.busy = true;
     const before = this.agent.messages.length;
     try {
+      this.terminal = void 0;
+      if (this.incrementalPersistence) this.recorder = new SessionAttemptRecorder(this.session);
       const carried = this.pendingNextTurn;
       this.pendingNextTurn = [];
       const userMessage = { role: "user", content: text, timestamp: Date.now() };
       const assistant = await this.agent.prompt([...carried, userMessage]);
       const produced = this.agent.messages.slice(before);
-      for (const message of produced) {
-        this.session.appendMessage(message);
-      }
+      if (this.recorder) this.recorder.finish(toRunResult(produced, this.terminal));
+      else for (const message of produced) this.session.appendMessage(message);
       return assistant;
+    } catch (error) {
+      this.recorder?.fail(error);
+      throw error;
     } finally {
+      this.recorder = void 0;
       this.busy = false;
     }
   }
@@ -2072,6 +2826,8 @@ ${value.summary}`,
     this.agent = new Agent({ ...this.agentOptions, messages });
     if (previous) this.agent.adoptPendingFrom(previous);
     this.agentUnsub = this.agent.subscribe(async (event) => {
+      this.recorder?.observe(event);
+      if (event.type === "agent_end") this.terminal = event;
       for (const listener of this.listeners) await listener(event);
     });
   }
@@ -2686,9 +3442,9 @@ var FileJsonlFile = class {
     appendFileSync(this.path, line);
   }
 };
-function entriesToFork(storage, options) {
-  if (!options.entryId) return storage.getEntries();
-  const target = storage.getEntry(options.entryId);
+function entriesToFork(storage2, options) {
+  if (!options.entryId) return storage2.getEntries();
+  const target = storage2.getEntry(options.entryId);
   if (!target) {
     throw new SessionError("not_found", `Fork target not found: ${options.entryId}`);
   }
@@ -2705,7 +3461,7 @@ function entriesToFork(storage, options) {
     effectiveLeafId = target.parentId;
   }
   if (effectiveLeafId === null) return [];
-  return storage.getPathToRoot(effectiveLeafId);
+  return storage2.getPathToRoot(effectiveLeafId);
 }
 var JsonlSessionRepo = class {
   root;
@@ -2713,6 +3469,9 @@ var JsonlSessionRepo = class {
     this.root = options?.root ?? join2(homedir(), ".ap3x", "sessions");
   }
   pathFor(id) {
+    if (!/^[A-Za-z0-9_-]{1,100}$/.test(id)) {
+      throw new SessionError("invalid_session", "Invalid session id");
+    }
     return join2(this.root, `${id}.jsonl`);
   }
   fileFor(id) {
@@ -2720,12 +3479,12 @@ var JsonlSessionRepo = class {
   }
   create(options = {}) {
     const id = options.id ?? createSessionId();
-    const storage = JsonlSessionStorage.create(this.fileFor(id), {
+    const storage2 = JsonlSessionStorage.create(this.fileFor(id), {
       cwd: options.cwd,
       sessionId: id,
       parentSessionId: options.parentSessionId
     });
-    return new Session(storage);
+    return new Session(storage2);
   }
   open(id) {
     if (!existsSync(this.pathFor(id))) {
@@ -2746,13 +3505,13 @@ var JsonlSessionRepo = class {
       if (!name.endsWith(".jsonl")) continue;
       const path = join2(this.root, name);
       try {
-        const storage = JsonlSessionStorage.open(new FileJsonlFile(path));
-        const metadata = storage.getMetadata();
+        const storage2 = JsonlSessionStorage.open(new FileJsonlFile(path));
+        const metadata = storage2.getMetadata();
         sessions.push({
           id: metadata.id,
           path,
           cwd: metadata.cwd,
-          name: new Session(storage).buildContext().sessionName,
+          name: new Session(storage2).buildContext().sessionName,
           parentSessionId: metadata.parentSessionId,
           createdAt: metadata.timestamp,
           updatedAt: statSync(path).mtimeMs
@@ -3996,54 +4755,6 @@ var SafeStateManager = {
   }
 };
 
-// src/agent-errors.ts
-var AgentError = class extends Error {
-  /** Machine-readable, stable error code. */
-  code;
-  cause;
-  constructor(message, code = "agent", cause) {
-    super(message);
-    this.name = new.target.name;
-    this.code = code;
-    this.cause = cause;
-  }
-};
-var AgentInitializationError = class extends AgentError {
-  constructor(message, cause) {
-    super(message, "agent_initialization", cause);
-  }
-};
-var AgentRunError = class extends AgentError {
-  constructor(message, cause) {
-    super(message, "agent_run", cause);
-  }
-};
-var AgentLLMError = class extends AgentError {
-  constructor(message, cause) {
-    super(message, "agent_llm", cause);
-  }
-};
-var AgentToolError = class extends AgentError {
-  constructor(message, cause) {
-    super(message, "agent_tool", cause);
-  }
-};
-var AgentMemoryError = class extends AgentError {
-  constructor(message, cause) {
-    super(message, "agent_memory", cause);
-  }
-};
-var AgentMCPConnectionError = class extends AgentError {
-  constructor(message, cause) {
-    super(message, "agent_mcp_connection", cause);
-  }
-};
-var AgentMCPToolError = class extends AgentError {
-  constructor(message, cause) {
-    super(message, "agent_mcp_tool", cause);
-  }
-};
-
 // src/index.ts
 var PACKAGE = "@ap3x/agent-core";
 var VERSION = "0.1.0";
@@ -4062,6 +4773,7 @@ export {
   AgentRegistry,
   AgentRegistrySchema,
   AgentRunError,
+  AgentRunFailure,
   AgentSpecSchema,
   AgentToolError,
   Ap3xError,
@@ -4070,7 +4782,9 @@ export {
   Conversation,
   DEFAULT_COMPACTION_SETTINGS,
   DEFAULT_MAX_LOOPS,
+  ExecutionController,
   ExecutionError,
+  ExecutionLimitError,
   FileError,
   FileJsonlFile,
   InMemorySessionStorage,
@@ -4078,36 +4792,48 @@ export {
   JsonlSessionStorage,
   NodeExecutionEnv,
   PACKAGE,
+  PolicyDeniedError,
   SUMMARIZATION_SYSTEM_PROMPT,
   SYSTEM_PROMPT_SECTIONS,
   SafeStateManager,
   SerializableMixin,
   Session,
+  SessionAttemptRecorder,
   SessionError,
   SkillRegistry,
   StringJsonlFile,
   SystemPromptBuilder,
   VERSION,
+  addUsage,
   agentLoop,
   agentLoopContinue,
+  argumentsHash,
   assembleSystemPrompt,
+  assertRunSucceeded,
+  authorizeTool,
   availableParallelism,
   buildSessionContext,
   compact,
   compactionTier,
+  controlledProviderCall,
   createLimiter,
+  createRunContext,
   createRuntimeBackend,
   createSessionId,
   createStateDict,
+  currentRunContext,
   defineTool,
   detectShell,
+  developmentPolicy,
   discoverSkillFiles,
   discoverSkills,
+  emptyUsage,
   environmentSection,
   err,
   estimateContextTokens,
   estimateMessageTokens,
   estimateTokens,
+  executeMember,
   executeShellWithCapture,
   executeToolCalls,
   finalTextOf,
@@ -4118,7 +4844,10 @@ export {
   getLogLevel,
   getOrThrow,
   getOrUndefined,
+  hasOpaqueReservation,
   historyOutputFormatter,
+  immutableArguments,
+  inspectSessionAttempts,
   isBlockedCommand,
   isClassInstance,
   isSafeType,
@@ -4127,6 +4856,7 @@ export {
   loadSkill,
   loadSkills,
   logger,
+  makeEventStream,
   mapLimit,
   matchBlocklist,
   ok,
@@ -4137,11 +4867,16 @@ export {
   prepareCompaction,
   preserveInstances,
   producesContextMessage,
+  productionPolicy,
+  readOnlyPolicy,
   renderPromptTemplate,
+  reserveProviderCall,
   resolveAutoCompact,
   resolveCompactionSettings,
+  resolveRunContext,
   runAgentLoop,
   runAgentLoopContinue,
+  runCompletion,
   serializeAttr,
   serializeState,
   setLogLevel,
@@ -4149,5 +4884,8 @@ export {
   shouldCompact,
   substituteArgs,
   toError,
-  uuidv7
+  toRunResult,
+  uuidv7,
+  withRunContext,
+  withWorkflowContext
 };