@anvia/core 0.26.0 → 1.0.0-rc.10

package/dist/chunk-VX3HS6PE.js

@@ -0,0 +1,4569 @@
+import {
+  assertAgentInteractionResponse,
+  parseAgentContinuation,
+  parseAgentInteractionResponse,
+  parseAgentQuestionPrompts
+} from "./chunk-OJBFDBLG.js";
+import {
+  isMcpTool
+} from "./chunk-J6LVLV6P.js";
+import {
+  MemoryCompactionConflictError,
+  MemoryCompactionError,
+  assertPositiveInteger,
+  createMemoryCompactionSummary,
+  cumulativeCompactedMessageCount
+} from "./chunk-5C6B6ZRH.js";
+import {
+  startAgentRunObservers
+} from "./chunk-6BBOCFHV.js";
+import {
+  isSkillTool
+} from "./chunk-YK4WAAS4.js";
+import {
+  isQuestionTool,
+  isToolIndex
+} from "./chunk-SJMSS5SI.js";
+import {
+  ToolNotFoundError,
+  ToolOutput,
+  assertFiniteMinScore,
+  assertPositiveSearchLimit,
+  assertToolApprovalRequirement,
+  createTool,
+  normalizeToolResultOutput,
+  parseToolArgs,
+  prepareToolCall,
+  prepareToolCallFromInput,
+  retrieveDocuments,
+  toolMayRequireApproval,
+  toolResultContentToText
+} from "./chunk-EMZKPRE6.js";
+import {
+  AgentRunBlockedError,
+  AgentRunCancelledError,
+  AgentStreamClosedError,
+  AgentStructuredOutputError,
+  AgentToolSuspensionError,
+  MaxTurnsError
+} from "./chunk-X4LK4ODN.js";
+import {
+  mapWithConcurrency
+} from "./chunk-3RM57ZT2.js";
+import {
+  CompletionStreamAccumulator,
+  Usage,
+  assertCompletionRequestSupported,
+  assertCompletionResponseIntegrity,
+  createCompletionRequest,
+  getAssistantGenerationMetadata,
+  isProviderTool,
+  isStreamingCompletionModel,
+  textFromAssistantContent
+} from "./chunk-7PHMK7W4.js";
+import {
+  assertJsonObject
+} from "./chunk-7JLAIN6E.js";
+import {
+  parseMessage,
+  parseMessages,
+  toProviderJsonSchema
+} from "./chunk-QGX73TSQ.js";
+import {
+  isJsonValue
+} from "./chunk-3XQGVDU5.js";
+import {
+  abortError,
+  completionProviderOutputErrorUsage,
+  resolveRetryOptions,
+  retryDelayMs,
+  retryErrorAttributes,
+  retryOptionsForFailure,
+  throwIfAborted,
+  waitForRetry
+} from "./chunk-3RWESPUG.js";
+import {
+  appendGuardrailPolicies,
+  hasEnforcedOutputGuardrails,
+  runInputGuardrails,
+  runOutputGuardrails
+} from "./chunk-AZB6N7P4.js";
+
+// src/agent/tool-state.ts
+var agentToolStates = /* @__PURE__ */ new WeakMap();
+function registerAgentToolState(agent, publicState, toolsByName) {
+  agentToolStates.set(agent, { publicState, toolsByName });
+}
+function getAgentToolState(agent) {
+  return getStoredAgentToolState(agent).publicState;
+}
+function getRegisteredAgentTool(agent, toolName) {
+  return getStoredAgentToolState(agent).toolsByName.get(toolName);
+}
+function getStoredAgentToolState(agent) {
+  const state = agentToolStates.get(agent);
+  if (state === void 0) {
+    throw new TypeError("Agent tool state is unavailable.");
+  }
+  return state;
+}
+
+// src/hooks/control.ts
+function createHook(hook) {
+  return hook;
+}
+function cancelRun(reason) {
+  return { type: "terminate", reason };
+}
+function skipTool(reason) {
+  return { type: "skip", reason };
+}
+function requestToolApproval(options = {}) {
+  const action = {
+    type: "approval_request"
+  };
+  if (options.reason !== void 0) {
+    action.reason = options.reason;
+  }
+  if (options.rejectMessage !== void 0) {
+    action.rejectMessage = options.rejectMessage;
+  }
+  return action;
+}
+var runControl = {
+  continue() {
+    return { type: "continue" };
+  },
+  cancel(reason) {
+    return cancelRun(reason);
+  }
+};
+var toolCallControl = {
+  run() {
+    return { type: "continue" };
+  },
+  skip(reason) {
+    return skipTool(reason);
+  },
+  cancel(reason) {
+    return { type: "terminate", reason };
+  },
+  requestApproval(options) {
+    return requestToolApproval(options);
+  }
+};
+
+// src/agent/vector-context.ts
+function createVectorContext(options) {
+  const topK = assertPositiveSearchLimit(options.topK);
+  const minScore = assertFiniteMinScore(options.minScore);
+  let context = {
+    ...options,
+    topK,
+    kind: "vector-context"
+  };
+  if (minScore !== void 0) {
+    context = { ...context, minScore };
+  }
+  return Object.freeze(context);
+}
+function isVectorContext(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  if (candidate.kind !== "vector-context" || typeof candidate.store?.search !== "function") {
+    return false;
+  }
+  return candidate.model !== void 0 || candidate.models?.dense !== void 0 && candidate.models.sparse !== void 0;
+}
+
+// src/internal/agent-runtime/run-options.ts
+var internalAgentRunOptions = /* @__PURE__ */ Symbol("internalAgentRunOptions");
+function withInternalAgentRunOptions(options, internal) {
+  return {
+    ...options,
+    [internalAgentRunOptions]: internal
+  };
+}
+function getInternalAgentRunOptions(options) {
+  return options[internalAgentRunOptions];
+}
+
+// src/agent/lifecycle.ts
+function composeAgentLifecycle(first, second) {
+  if (first === void 0) return second;
+  if (second === void 0) return first;
+  return {
+    async onStart(event) {
+      await first.onStart?.(lifecycleSnapshot(event));
+      await second.onStart?.(lifecycleSnapshot(event));
+    },
+    async onStepFinish(event) {
+      await first.onStepFinish?.(lifecycleSnapshot(event));
+      await second.onStepFinish?.(lifecycleSnapshot(event));
+    },
+    async onToolStart(event) {
+      await first.onToolStart?.(lifecycleSnapshot(event));
+      await second.onToolStart?.(lifecycleSnapshot(event));
+    },
+    async onToolFinish(event) {
+      await first.onToolFinish?.(lifecycleSnapshot(event));
+      await second.onToolFinish?.(lifecycleSnapshot(event));
+    },
+    async onFinish(event) {
+      await first.onFinish?.(lifecycleSnapshot(event));
+      await second.onFinish?.(lifecycleSnapshot(event));
+    },
+    async onError(event) {
+      await first.onError?.(lifecycleSnapshot(event));
+      await second.onError?.(lifecycleSnapshot(event));
+    }
+  };
+}
+function lifecycleSnapshot(value) {
+  try {
+    return globalThis.structuredClone(value);
+  } catch {
+    return cloneLifecycleFallback(value, /* @__PURE__ */ new WeakMap());
+  }
+}
+function cloneLifecycleFallback(value, seen) {
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  const existing = seen.get(value);
+  if (existing !== void 0) {
+    return existing;
+  }
+  if (Array.isArray(value)) {
+    const clone2 = [];
+    seen.set(value, clone2);
+    clone2.push(...value.map((item) => cloneLifecycleFallback(item, seen)));
+    return clone2;
+  }
+  if (Object.getPrototypeOf(value) !== Object.prototype) {
+    return value;
+  }
+  const clone = {};
+  seen.set(value, clone);
+  for (const [key, item] of Object.entries(value)) {
+    clone[key] = cloneLifecycleFallback(item, seen);
+  }
+  return clone;
+}
+
+// src/agent/output-schema.ts
+var providerOutputSchemas = /* @__PURE__ */ new WeakMap();
+function registerAgentProviderOutputSchema(agent, schema) {
+  if (schema !== void 0) {
+    providerOutputSchemas.set(agent, toProviderJsonSchema(schema));
+  }
+}
+function getAgentProviderOutputSchema(agent) {
+  return providerOutputSchemas.get(agent);
+}
+
+// src/internal/async-queue.ts
+function createAsyncQueue() {
+  const values = [];
+  const waiters = [];
+  let closed = false;
+  let error;
+  function flush() {
+    while (waiters.length > 0 && values.length > 0) {
+      const waiter = waiters.shift();
+      const value = values.shift();
+      if (waiter !== void 0) {
+        waiter.resolve({ value, done: false });
+      }
+    }
+    if (values.length > 0 || waiters.length === 0 || !closed) {
+      return;
+    }
+    while (waiters.length > 0) {
+      const waiter = waiters.shift();
+      if (waiter === void 0) {
+        continue;
+      }
+      if (error !== void 0) {
+        waiter.reject(error);
+      } else {
+        waiter.resolve({ value: void 0, done: true });
+      }
+    }
+  }
+  return {
+    enqueue(value) {
+      if (closed) {
+        return;
+      }
+      values.push(value);
+      flush();
+    },
+    close() {
+      closed = true;
+      flush();
+    },
+    throw(thrown) {
+      closed = true;
+      error = thrown;
+      flush();
+    },
+    [Symbol.asyncIterator]() {
+      return {
+        next() {
+          if (values.length > 0) {
+            const value = values.shift();
+            return Promise.resolve({ value, done: false });
+          }
+          if (error !== void 0) {
+            return Promise.reject(error);
+          }
+          if (closed) {
+            return Promise.resolve({ value: void 0, done: true });
+          }
+          return new Promise((resolve, reject) => {
+            waiters.push({ resolve, reject });
+          });
+        }
+      };
+    }
+  };
+}
+
+// src/internal/rag-text.ts
+function extractRagText(message) {
+  if (message.role === "user") {
+    if (typeof message.content === "string") {
+      return message.content;
+    }
+    return message.content.flatMap((item) => item.type === "text" ? [item.text] : []).join("\n");
+  }
+  if (message.role === "tool") {
+    return message.content.flatMap((item) => {
+      if (item.type !== "tool-result") {
+        return [];
+      }
+      const output = item.output;
+      if (output.type === "text" || output.type === "error-text") {
+        return [output.value];
+      }
+      if (output.type === "content") {
+        return output.value.flatMap((part) => part.type === "text" ? [part.text] : []);
+      }
+      return [];
+    }).join("\n");
+  }
+  return void 0;
+}
+
+// src/internal/agent-runtime/continuation-state.ts
+function serializeContinuationState(state) {
+  const value = structuredClone(state);
+  if (!isJsonValue(value) || Array.isArray(value) || value === null) {
+    throw new TypeError("Agent continuation state must be strict JSON.");
+  }
+  return value;
+}
+function parseContinuationState(value, interaction) {
+  requireOnlyKeys(value, [
+    "kind",
+    "history",
+    "messages",
+    "pending",
+    "remainingToolCalls",
+    "steering",
+    "memoryScope"
+  ]);
+  if (value.kind !== "anvia.agent-continuation") {
+    throw new TypeError("Agent continuation has an unsupported internal state.");
+  }
+  const history = parseMessages(value.history);
+  const messages = parseMessages(value.messages);
+  const pending = parsePending(value.pending);
+  const remainingToolCalls = parseToolCalls(value.remainingToolCalls);
+  const steering = parseSteering(value.steering);
+  if (pending.toolCall.toolCallId !== interaction.toolCallId || pending.toolCall.toolName !== interaction.toolName || pending.toolCall.callId !== interaction.callId || pending.internalCallId !== interaction.internalCallId) {
+    throw new TypeError("Agent continuation interaction does not match its pending tool call.");
+  }
+  if (interaction.type === "tool-approval" && !jsonEqual(interaction.input, pending.input)) {
+    throw new TypeError("Agent continuation approval input does not match its pending tool input.");
+  }
+  if (interaction.type === "tool-question") {
+    const questions = object(pending.input) && "questions" in pending.input ? parseAgentQuestionPrompts(pending.input.questions) : void 0;
+    if (questions === void 0 || !jsonEqual(interaction.questions, questions)) {
+      throw new TypeError(
+        "Agent continuation questions do not match its pending question tool input."
+      );
+    }
+  }
+  const state = {
+    kind: "anvia.agent-continuation",
+    history,
+    messages,
+    pending,
+    remainingToolCalls,
+    steering
+  };
+  if (value.memoryScope !== void 0) {
+    state.memoryScope = parseOptionalJsonObject(value.memoryScope, "memoryScope");
+  }
+  return state;
+}
+function questionResult(answers) {
+  return { type: "json", value: { answers: structuredClone([...answers]) } };
+}
+function parsePending(value) {
+  if (!object(value)) throw new TypeError("Agent continuation pending state is invalid.");
+  const [toolCall] = parseToolCalls([value.toolCall]);
+  if (toolCall === void 0) throw new TypeError("Agent continuation pending tool is missing.");
+  if (typeof value.effectiveArgs !== "string" || typeof value.internalCallId !== "string") {
+    throw new TypeError("Agent continuation pending execution metadata is invalid.");
+  }
+  const pending = {
+    toolCall,
+    effectiveArgs: value.effectiveArgs,
+    input: parseJsonValue(value.input, "pending input"),
+    internalCallId: value.internalCallId
+  };
+  if (typeof value.rejectMessage === "string") {
+    pending.rejectMessage = value.rejectMessage;
+  }
+  return pending;
+}
+function parseJsonValue(value, name) {
+  if (!isJsonValue(value)) {
+    throw new TypeError(`Agent continuation ${name} is invalid.`);
+  }
+  return structuredClone(value);
+}
+function parseToolCalls(value) {
+  if (!Array.isArray(value)) throw new TypeError("Agent continuation tool calls must be an array.");
+  const message = parseMessages([{ role: "assistant", content: value }])[0];
+  if (message?.role !== "assistant" || typeof message.content === "string") {
+    throw new TypeError("Agent continuation tool calls are invalid.");
+  }
+  if (!message.content.every((part) => part.type === "tool-call")) {
+    throw new TypeError("Agent continuation contains a non-tool-call part.");
+  }
+  return message.content;
+}
+function parseSteering(value) {
+  if (!Array.isArray(value)) throw new TypeError("Agent continuation steering state is invalid.");
+  return value.map((item) => {
+    if (!object(item) || typeof item.id !== "string") {
+      throw new TypeError("Agent continuation steering entry is invalid.");
+    }
+    return { id: item.id, messages: parseMessages(item.messages) };
+  });
+}
+function parseOptionalJsonObject(value, name) {
+  if (value === void 0) return void 0;
+  if (!object(value) || !isJsonValue(value)) {
+    throw new TypeError(`Agent continuation ${name} is invalid.`);
+  }
+  return structuredClone(value);
+}
+function object(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireOnlyKeys(value, allowed) {
+  const allowedKeys = new Set(allowed);
+  const unknown = Object.keys(value).find((key) => !allowedKeys.has(key));
+  if (unknown !== void 0) {
+    throw new TypeError(`Agent continuation state contains unknown key "${unknown}".`);
+  }
+}
+function jsonEqual(left, right) {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left)) {
+    return Array.isArray(right) && left.length === right.length && left.every((value, index) => jsonEqual(value, right[index]));
+  }
+  if (object(left)) {
+    if (!object(right)) return false;
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every((key) => key in right && jsonEqual(left[key], right[key]));
+  }
+  return false;
+}
+
+// src/internal/agent-runtime/interaction-suspension.ts
+var AgentInteractionSignal = class extends Error {
+  constructor(interaction, rejectMessage) {
+    super("Agent execution requires a human interaction.");
+    this.interaction = interaction;
+    this.rejectMessage = rejectMessage;
+    this.name = "AgentInteractionSignal";
+  }
+  interaction;
+  rejectMessage;
+};
+var ToolExecutionSuspension = class extends Error {
+  constructor(interaction, pending) {
+    super("Tool execution suspended for human interaction.");
+    this.interaction = interaction;
+    this.pending = pending;
+    this.name = "ToolExecutionSuspension";
+  }
+  interaction;
+  pending;
+  completedResults = [];
+  remainingToolCalls = [];
+};
+function approvalInteraction(request) {
+  if (request.toolCallId === void 0) {
+    throw new TypeError("Tool approval requires a canonical toolCallId.");
+  }
+  if (!isJsonValue(request.args)) {
+    throw new TypeError("Tool approval input must be strict JSON.");
+  }
+  let interaction = {
+    type: "tool-approval",
+    id: request.id,
+    toolName: request.toolName,
+    toolCallId: request.toolCallId,
+    internalCallId: request.internalCallId,
+    input: request.args
+  };
+  if (request.callId !== void 0) interaction = { ...interaction, callId: request.callId };
+  if (request.reason !== void 0) interaction = { ...interaction, reason: request.reason };
+  return interaction;
+}
+
+// src/internal/agent-runtime/memory.ts
+var AgentRunMemory = class {
+  constructor(agent, memoryScope, initialHistory) {
+    this.agent = agent;
+    this.memoryScope = memoryScope;
+    this.initialHistory = initialHistory;
+  }
+  agent;
+  memoryScope;
+  initialHistory;
+  memoryPolicy() {
+    return this.memory()?.savePolicy;
+  }
+  pendingTurnMessages(newMessages) {
+    return this.memoryPolicy() === "turn" ? [...newMessages] : [];
+  }
+  async prepareHistory(runId, incomingMessageCount, abortSignal) {
+    const memory = this.memory();
+    if (memory === void 0 || this.memoryScope === void 0) {
+      return {
+        history: this.initialHistory,
+        usage: Usage.empty()
+      };
+    }
+    const preparation = await this.prepareStoredHistory(
+      memory,
+      runId,
+      incomingMessageCount,
+      abortSignal
+    );
+    const memoryHistory = preparation.history;
+    const chatHistory = [...memoryHistory, ...this.initialHistory];
+    return {
+      ...preparation,
+      history: chatHistory
+    };
+  }
+  async commitAcceptedInput(runId, messages) {
+    const memory = this.memory();
+    if (memory === void 0 || this.memoryScope === void 0 || memory.savePolicy !== "message" || messages.length === 0) {
+      return;
+    }
+    await memory.store.append({
+      scope: this.memoryScope,
+      runId,
+      turn: 1,
+      messages
+    });
+  }
+  async commitMessages(runId, turn, messages, pendingTurnMessages) {
+    const memory = this.memory();
+    if (memory === void 0 || this.memoryScope === void 0 || messages.length === 0) {
+      return;
+    }
+    if (memory.savePolicy === "message") {
+      await memory.store.append({
+        scope: this.memoryScope,
+        runId,
+        turn,
+        messages
+      });
+    } else if (memory.savePolicy === "turn") {
+      pendingTurnMessages.push(...messages);
+    }
+  }
+  async commitCompletedTurn(runId, turn, pendingTurnMessages) {
+    const memory = this.memory();
+    if (memory === void 0 || this.memoryScope === void 0 || memory.savePolicy !== "turn" || pendingTurnMessages.length === 0) {
+      return;
+    }
+    await memory.store.append({
+      scope: this.memoryScope,
+      runId,
+      turn,
+      messages: [...pendingTurnMessages]
+    });
+    pendingTurnMessages.length = 0;
+  }
+  async commitCompletedRun(runId, turn, newMessages, pendingTurnMessages) {
+    await this.commitCompletedTurn(runId, turn, pendingTurnMessages);
+    const memory = this.memory();
+    if (memory === void 0 || this.memoryScope === void 0 || memory.savePolicy !== "run") {
+      return;
+    }
+    await memory.store.append({
+      scope: this.memoryScope,
+      runId,
+      turn,
+      messages: [...newMessages]
+    });
+  }
+  async recordError(runId, error, newMessages) {
+    const memory = this.memory();
+    if (memory === void 0 || this.memoryScope === void 0) {
+      return;
+    }
+    await memory.store.recordError?.({
+      scope: this.memoryScope,
+      runId,
+      error,
+      messages: [...newMessages]
+    });
+  }
+  memory() {
+    return this.memoryScope === void 0 ? void 0 : this.agent.memory;
+  }
+  async prepareStoredHistory(memory, runId, incomingMessageCount, abortSignal) {
+    const scope = this.memoryScope;
+    if (scope === void 0) {
+      return { history: [], usage: Usage.empty() };
+    }
+    const options = memory.compaction;
+    const capability = memory.store.compaction;
+    if (options === void 0 || capability === void 0) {
+      return {
+        history: await memory.store.load({ scope }),
+        usage: Usage.empty()
+      };
+    }
+    let usage = Usage.empty();
+    const maxAttempts = options.conflictRetries === false ? 1 : options.conflictRetries.maxAttempts;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      throwIfAborted(abortSignal);
+      const snapshot = await capability.snapshot({ scope });
+      throwIfAborted(abortSignal);
+      const compactedMessageCount = compactedPrefixLength(
+        snapshot.messages,
+        incomingMessageCount,
+        options.trigger.afterMessages,
+        options.retention.recentUserTurns
+      );
+      if (compactedMessageCount === 0) {
+        return { history: snapshot.messages, usage };
+      }
+      const prefix = snapshot.messages.slice(0, compactedMessageCount);
+      let result;
+      try {
+        result = await options.compactor({
+          scope,
+          messages: prefix,
+          abortSignal
+        });
+      } catch (error) {
+        throw remappedCompactorError(error, usage);
+      }
+      if (result.usage !== void 0) {
+        usage = Usage.add(usage, result.usage);
+      }
+      const summaryText = result.summary.trim();
+      if (summaryText.length === 0) {
+        throw new MemoryCompactionError("Memory compactor returned an empty summary.", {
+          usage
+        });
+      }
+      const summary = createMemoryCompactionSummary(
+        summaryText,
+        cumulativeCompactedMessageCount(prefix)
+      );
+      throwIfAborted(abortSignal);
+      let replacement;
+      try {
+        replacement = await capability.replacePrefix({
+          scope,
+          revision: snapshot.revision,
+          messageCount: compactedMessageCount,
+          replacement: summary,
+          runId: `memory-compaction:${runId}:${attempt}`
+        });
+      } catch (error) {
+        throw new MemoryCompactionError("Memory compaction prefix replacement failed.", {
+          cause: error,
+          usage
+        });
+      }
+      if (replacement.status === "committed") {
+        const retained = snapshot.messages.slice(compactedMessageCount);
+        return {
+          history: [summary, ...retained],
+          usage,
+          compaction: {
+            originalMessageCount: snapshot.messages.length,
+            compactedMessageCount,
+            retainedMessageCount: retained.length,
+            attempts: attempt,
+            usage
+          }
+        };
+      }
+      throwIfAborted(abortSignal);
+    }
+    throw new MemoryCompactionConflictError(maxAttempts, usage);
+  }
+};
+function compactedPrefixLength(messages, incomingMessageCount, afterMessages, recentUserTurns) {
+  if (messages.length + incomingMessageCount <= afterMessages) {
+    return 0;
+  }
+  const userMessageIndexes = messages.flatMap(
+    (message, index) => message.role === "user" ? [index] : []
+  );
+  if (userMessageIndexes.length <= recentUserTurns) {
+    return 0;
+  }
+  return userMessageIndexes[userMessageIndexes.length - recentUserTurns] ?? 0;
+}
+function remappedCompactorError(error, usage) {
+  if (error instanceof MemoryCompactionError) {
+    const mergedUsage = error.usage === void 0 ? usage : isEmptyUsage(usage) ? error.usage : Usage.add(usage, error.usage);
+    if (mergedUsage === error.usage || error.usage === void 0 && isEmptyUsage(usage)) {
+      return error;
+    }
+    return new MemoryCompactionError(error.message, {
+      cause: error,
+      usage: mergedUsage
+    });
+  }
+  return new MemoryCompactionError("Memory compactor failed.", {
+    cause: error,
+    usage
+  });
+}
+function isEmptyUsage(usage) {
+  return usage.inputTokens === 0 && usage.outputTokens === 0 && usage.totalTokens === 0 && usage.cachedInputTokens === 0 && usage.cacheCreationInputTokens === 0;
+}
+
+// src/internal/agent-runtime/retrieval.ts
+async function fetchContextDocuments(agent, ragText, abortSignal) {
+  const documents = [];
+  for (const input of agent.context) {
+    if (!isVectorContext(input)) {
+      documents.push(input);
+      continue;
+    }
+    if (ragText === void 0 || ragText.length === 0) continue;
+    const request = {
+      query: ragText,
+      topK: input.topK,
+      minScore: input.minScore,
+      filter: input.filter,
+      retries: input.retries,
+      abortSignal
+    };
+    const results = "models" in input && input.models !== void 0 ? await retrieveDocuments({
+      ...request,
+      store: input.store,
+      models: input.models,
+      fusion: input.fusion
+    }) : await retrieveDocuments({ ...request, store: input.store, model: input.model });
+    for (const result of results) {
+      const formatted = input.format?.(result);
+      if (formatted !== void 0) {
+        documents.push(formatted);
+        continue;
+      }
+      const metadata = formatMetadata(result.metadata);
+      const document = {
+        id: result.id,
+        text: typeof result.document === "string" ? result.document : JSON.stringify(result.document, null, 2)
+      };
+      if (metadata !== void 0) document.additionalProps = metadata;
+      documents.push(document);
+    }
+  }
+  return documents;
+}
+async function fetchToolDefinitions(agent, ragText, abortSignal) {
+  const state = getAgentToolState(agent);
+  const staticDefinitions = await Promise.all(
+    state.staticTools.map((tool) => tool.definition(ragText ?? ""))
+  );
+  if (ragText === void 0 || ragText.length === 0 || state.toolIndexes.length === 0) {
+    return staticDefinitions;
+  }
+  const definitions = [...staticDefinitions];
+  const names = new Set(staticDefinitions.map((definition) => definition.name));
+  for (const index of state.toolIndexes) {
+    const results = await index.search({ query: ragText, abortSignal });
+    for (const result of results) {
+      const toolName = result.document.toolName;
+      if (names.has(toolName)) continue;
+      const tool = index.tools.find((candidate) => candidate.name === toolName);
+      if (tool === void 0) continue;
+      names.add(toolName);
+      definitions.push(await tool.definition(ragText));
+    }
+  }
+  return definitions;
+}
+function formatMetadata(metadata) {
+  if (metadata === void 0) return void 0;
+  return Object.fromEntries(Object.entries(metadata).map(([key, value]) => [key, String(value)]));
+}
+
+// src/internal/agent-runtime/run-validation.ts
+function assertNonnegativeSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`${name} must be a nonnegative safe integer.`);
+  }
+  return value;
+}
+function assertPositiveSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer.`);
+  }
+  return value;
+}
+
+// src/internal/agent-runtime/stream-events.ts
+function addTurn(turn, event) {
+  if (event.type === "text_delta") {
+    return { type: "text_delta", turn, delta: event.delta };
+  }
+  if (event.type === "reasoning_delta") {
+    const mapped = { type: "reasoning_delta", turn, delta: event.delta };
+    if (event.id !== void 0) mapped.id = event.id;
+    if (event.contentType !== void 0) mapped.contentType = event.contentType;
+    if (event.signature !== void 0) mapped.signature = event.signature;
+    return mapped;
+  }
+  if (event.type === "source") {
+    return { type: "source", turn, source: event.source };
+  }
+  if (event.type === "provider_tool_call") {
+    return { type: "provider_tool_call", turn, toolCall: event.toolCall };
+  }
+  return { type: "tool_call", turn, toolCall: event.toolCall };
+}
+function addTurnToToolCallDelta(turn, event) {
+  const mapped = {
+    type: "tool_call_delta",
+    turn,
+    id: event.id
+  };
+  if (event.callId !== void 0) mapped.callId = event.callId;
+  if (event.name !== void 0) mapped.name = event.name;
+  if (event.argumentsDelta !== void 0) mapped.argumentsDelta = event.argumentsDelta;
+  if (event.argumentsMode !== void 0) mapped.argumentsMode = event.argumentsMode;
+  if (event.signature !== void 0) mapped.signature = event.signature;
+  return mapped;
+}
+function isGenerationDeltaEvent(type) {
+  return type === "text_delta" || type === "reasoning_delta" || type === "tool_call_delta" || type === "tool_call" || type === "source" || type === "provider_tool_call";
+}
+
+// src/internal/agent-runtime/structured-output.ts
+var JSON_FENCE_START = "```json\n";
+var JSON_FENCE_CRLF_START = "```json\r\n";
+var UNLABELED_FENCE_START = "```\n";
+var UNLABELED_FENCE_CRLF_START = "```\r\n";
+var FENCE_END = "\n```";
+var STRUCTURED_OUTPUT_RETRY_PROMPT = "Your previous response was invalid structured output. Return only raw JSON that matches the supplied JSON schema. Do not use Markdown fences or include commentary.";
+var STRUCTURED_OUTPUT_TRUNCATED_RETRY_PROMPT = "Your previous response exceeded the provider output limit. Return substantially shorter raw JSON that matches the supplied JSON schema. Do not use Markdown fences or include commentary.";
+var STRUCTURED_OUTPUT_REPAIR_PREVIEW_MAX_LENGTH = 8192;
+var STRUCTURED_OUTPUT_REPAIR_PREVIEW_MARKER = "\n...[output omitted]...\n";
+function structuredOutputRepairPreview(text) {
+  if (text.length <= STRUCTURED_OUTPUT_REPAIR_PREVIEW_MAX_LENGTH) {
+    return { text, includedOutputLength: text.length };
+  }
+  const availableLength = STRUCTURED_OUTPUT_REPAIR_PREVIEW_MAX_LENGTH - STRUCTURED_OUTPUT_REPAIR_PREVIEW_MARKER.length;
+  const headLength = Math.ceil(availableLength / 2);
+  const tailLength = availableLength - headLength;
+  return {
+    text: `${text.slice(0, headLength)}${STRUCTURED_OUTPUT_REPAIR_PREVIEW_MARKER}${text.slice(-tailLength)}`,
+    includedOutputLength: headLength + tailLength
+  };
+}
+function normalizeStructuredOutput(text) {
+  const trimmed = text.trim();
+  const opening = fenceOpening(trimmed);
+  if (opening === void 0 || !trimmed.endsWith(FENCE_END)) {
+    return { text: trimmed, format: "raw" };
+  }
+  const closingStart = trimmed.length - 3;
+  const precedingNewline = closingStart - 1;
+  const contentEnd = trimmed[precedingNewline - 1] === "\r" ? precedingNewline - 1 : precedingNewline;
+  return {
+    text: trimmed.slice(opening.length, contentEnd).trim(),
+    format: opening.format
+  };
+}
+function fenceOpening(text) {
+  if (text.startsWith(JSON_FENCE_START)) {
+    return { length: JSON_FENCE_START.length, format: "json-fence" };
+  }
+  if (text.startsWith(JSON_FENCE_CRLF_START)) {
+    return { length: JSON_FENCE_CRLF_START.length, format: "json-fence" };
+  }
+  if (text.startsWith(UNLABELED_FENCE_START)) {
+    return { length: UNLABELED_FENCE_START.length, format: "unlabeled-fence" };
+  }
+  if (text.startsWith(UNLABELED_FENCE_CRLF_START)) {
+    return { length: UNLABELED_FENCE_CRLF_START.length, format: "unlabeled-fence" };
+  }
+  return void 0;
+}
+
+// src/internal/agent-runtime/tool-execution.ts
+var ToolCallExecutor = class {
+  constructor(agent, activeHook, approvalHandler, lifecycle, runContext, concurrency, requestMiddlewares, abortSignal, cancel) {
+    this.agent = agent;
+    this.activeHook = activeHook;
+    this.approvalHandler = approvalHandler;
+    this.lifecycle = lifecycle;
+    this.runContext = runContext;
+    this.concurrency = concurrency;
+    this.requestMiddlewares = requestMiddlewares;
+    this.abortSignal = abortSignal;
+    this.cancel = cancel;
+  }
+  agent;
+  activeHook;
+  approvalHandler;
+  lifecycle;
+  runContext;
+  concurrency;
+  requestMiddlewares;
+  abortSignal;
+  cancel;
+  async execute(toolCalls, onResult, onStreamEvent, observation) {
+    assertCompletionResponseIntegrity({
+      response: {
+        choice: [...toolCalls],
+        usage: Usage.empty(),
+        rawResponse: void 0
+      }
+    });
+    const executeOne = async (toolCall) => {
+      throwIfAborted(this.abortSignal);
+      const args = JSON.stringify(toolCall.input);
+      const internalCallId = globalThis.crypto.randomUUID();
+      const hookArgs = {
+        toolName: toolCall.toolName,
+        toolCallId: toolCall.toolCallId,
+        internalCallId,
+        args
+      };
+      if (toolCall.callId !== void 0) {
+        hookArgs.callId = toolCall.callId;
+      }
+      const tool = this.agent.getTool(toolCall.toolName);
+      const toolDefinition = observation?.toolDefinitions?.find(
+        (definition) => definition.name === toolCall.toolName
+      );
+      const toolMetadata = toolTraceMetadata(tool);
+      let toolStartArgs = {
+        turn: observation?.turn ?? 0,
+        toolCall,
+        toolName: toolCall.toolName,
+        internalCallId,
+        args
+      };
+      if (toolCall.callId !== void 0) {
+        toolStartArgs = { ...toolStartArgs, toolCallId: toolCall.callId };
+      }
+      if (toolDefinition !== void 0) toolStartArgs = { ...toolStartArgs, toolDefinition };
+      if (toolMetadata !== void 0) toolStartArgs = { ...toolStartArgs, toolMetadata };
+      const toolObservers = await observation?.runObservers.startTool(toolStartArgs);
+      const toolObservation = new ToolObserverScope(toolObservers);
+      let output;
+      let skipped = false;
+      let toolExecutionFailed = false;
+      let effectiveArgs = args;
+      try {
+        const callAction = await this.activeHook?.onToolCall?.({
+          ...hookArgs,
+          tool: toolCallControl
+        });
+        if (callAction?.type === "terminate") {
+          throw this.cancel(callAction.reason);
+        }
+        if (callAction?.type === "skip") {
+          output = { type: "text", value: callAction.reason };
+          skipped = true;
+        } else {
+          try {
+            effectiveArgs = await this.runToolInputMiddlewares({
+              ...hookArgs,
+              turn: observation?.turn ?? 0,
+              originalArgs: args
+            });
+            hookArgs.args = effectiveArgs;
+            let prepared;
+            try {
+              prepared = this.prepareToolCall(tool, toolCall.toolName, effectiveArgs);
+            } catch (error) {
+              const outcome = await this.handleToolError(
+                toolCall,
+                hookArgs,
+                effectiveArgs,
+                error,
+                toolObservation,
+                observation
+              );
+              output = outcome.output;
+              toolExecutionFailed = outcome.failed;
+            }
+            if (prepared !== void 0 && isQuestionTool(tool)) {
+              try {
+                const questions = parseAgentQuestionPrompts(
+                  prepared.input.questions
+                );
+                const interaction = {
+                  type: "tool-question",
+                  id: globalThis.crypto.randomUUID(),
+                  toolName: toolCall.toolName,
+                  toolCallId: toolCall.toolCallId,
+                  internalCallId,
+                  questions
+                };
+                if (toolCall.callId !== void 0) {
+                  Object.assign(interaction, { callId: toolCall.callId });
+                }
+                throw new AgentInteractionSignal(interaction);
+              } catch (error) {
+                if (error instanceof AgentInteractionSignal) throw error;
+                const outcome = await this.handleToolError(
+                  toolCall,
+                  hookArgs,
+                  effectiveArgs,
+                  error,
+                  toolObservation,
+                  observation
+                );
+                output = outcome.output;
+                toolExecutionFailed = outcome.failed;
+                prepared = void 0;
+              }
+            }
+            if (prepared !== void 0) {
+              const approvalContext = createApprovalContext(
+                prepared.input,
+                hookArgs,
+                this.agent,
+                this.runContext
+              );
+              const approvalDecision = callAction?.type === "approval_request" ? await this.requestApproval(approvalContext, callAction, observation) : await this.evaluateToolApproval(tool, approvalContext, observation) ?? {
+                approved: true
+              };
+              if (!approvalDecision.approved) {
+                output = { type: "execution-denied", reason: approvalDecision.result };
+                skipped = true;
+              } else {
+                const step = observation?.turn ?? 0;
+                const lifecycleEvent = {
+                  runId: this.runContext.runId,
+                  step,
+                  toolName: toolCall.toolName,
+                  input: lifecycleSnapshot(prepared.input)
+                };
+                if (toolCall.callId !== void 0) {
+                  Object.assign(lifecycleEvent, { toolCallId: toolCall.callId });
+                }
+                await this.lifecycle?.onToolStart?.(lifecycleEvent);
+                const startedAt = Date.now();
+                const outcome = await this.runApprovedToolCall(
+                  prepared,
+                  toolCall,
+                  hookArgs,
+                  effectiveArgs,
+                  toolObservation,
+                  observation,
+                  onStreamEvent
+                );
+                output = outcome.output;
+                toolExecutionFailed = outcome.failed;
+                const durationMs = Date.now() - startedAt;
+                await this.lifecycle?.onToolFinish?.(
+                  outcome.failed ? {
+                    ...lifecycleEvent,
+                    durationMs,
+                    success: false,
+                    error: lifecycleSnapshot(outcome.error)
+                  } : {
+                    ...lifecycleEvent,
+                    durationMs,
+                    success: true,
+                    output: lifecycleSnapshot(output)
+                  }
+                );
+              }
+            }
+          } catch (error) {
+            if (error instanceof AgentInteractionSignal) {
+              await toolObservation.suspend({
+                ...toolStartArgs,
+                interaction: error.interaction
+              });
+              throw error;
+            }
+            await toolObservation.error(
+              toolErrorArgs(observation?.turn ?? 0, toolCall, internalCallId, effectiveArgs, error)
+            );
+            throw error;
+          }
+        }
+        if (output === void 0) {
+          throw new Error(`Tool "${toolCall.toolName}" did not produce an execution result.`);
+        }
+        let result = toolOutputToText(output);
+        let structuredResult = toolOutputToStructuredResult(output);
+        if (!isSkillTool(tool)) {
+          const middlewareReplacement = await this.runToolResultMiddlewares({
+            ...hookArgs,
+            args: effectiveArgs,
+            result,
+            originalResult: result,
+            structuredResult,
+            originalStructuredResult: structuredResult,
+            turn: observation?.turn ?? 0
+          });
+          if (middlewareReplacement !== void 0) {
+            output = middlewareReplacement;
+            result = toolOutputToText(middlewareReplacement);
+            structuredResult = toolOutputToStructuredResult(middlewareReplacement);
+          }
+        }
+        const resultAction = await this.activeHook?.onToolResult?.({
+          ...hookArgs,
+          args: effectiveArgs,
+          result,
+          structuredResult,
+          run: runControl
+        });
+        if (!toolExecutionFailed) {
+          await toolObservation.end({
+            turn: observation?.turn ?? 0,
+            toolCall,
+            toolName: toolCall.toolName,
+            internalCallId,
+            args: effectiveArgs,
+            result,
+            structuredResult,
+            skipped,
+            toolCallId: toolCall.callId
+          });
+        }
+        if (resultAction?.type === "terminate") {
+          throw this.cancel(resultAction.reason);
+        }
+        const resultPayload = {
+          type: "tool_result",
+          toolName: toolCall.toolName,
+          toolCallId: toolCall.toolCallId,
+          internalCallId,
+          args: effectiveArgs,
+          output,
+          result,
+          structuredResult
+        };
+        if (toolCall.callId !== void 0) resultPayload.callId = toolCall.callId;
+        onResult?.(resultPayload);
+        let resultPart = {
+          type: "tool-result",
+          toolCallId: toolCall.toolCallId,
+          toolName: toolCall.toolName,
+          output
+        };
+        if (toolCall.callId !== void 0) {
+          resultPart = { ...resultPart, callId: toolCall.callId };
+        }
+        return resultPart;
+      } catch (error) {
+        if (error instanceof AgentInteractionSignal) {
+          const pending = {
+            toolCall,
+            effectiveArgs,
+            input: error.interaction.type === "tool-approval" ? error.interaction.input : parseToolArgs(effectiveArgs),
+            internalCallId
+          };
+          if (error.rejectMessage !== void 0) pending.rejectMessage = error.rejectMessage;
+          throw new ToolExecutionSuspension(error.interaction, pending);
+        }
+        await toolObservation.error(
+          toolErrorArgs(observation?.turn ?? 0, toolCall, internalCallId, effectiveArgs, error)
+        );
+        throw error;
+      }
+    };
+    if (this.concurrency === 1) {
+      const results = [];
+      for (const toolCall of toolCalls) {
+        try {
+          results.push(await executeOne(toolCall));
+        } catch (error) {
+          if (error instanceof ToolExecutionSuspension) {
+            error.completedResults = [...results];
+            error.remainingToolCalls = toolCalls.slice(results.length + 1);
+          }
+          throw error;
+        }
+      }
+      return results;
+    }
+    return mapWithConcurrency(toolCalls, this.concurrency, executeOne);
+  }
+  async executeResumed(pending, onResult, onStreamEvent, observation) {
+    throwIfAborted(this.abortSignal);
+    const { toolCall, internalCallId, effectiveArgs } = pending;
+    const tool = this.agent.getTool(toolCall.toolName);
+    if (tool === void 0) {
+      throw new Error(
+        `Cannot resume tool interaction because tool "${toolCall.toolName}" is no longer registered.`
+      );
+    }
+    if (isQuestionTool(tool)) {
+      throw new TypeError("Question interactions are resolved from their submitted answers.");
+    }
+    const hookArgs = {
+      toolName: toolCall.toolName,
+      toolCallId: toolCall.toolCallId,
+      internalCallId,
+      args: effectiveArgs
+    };
+    if (toolCall.callId !== void 0) hookArgs.callId = toolCall.callId;
+    const toolDefinition = observation?.toolDefinitions?.find(
+      (definition) => definition.name === toolCall.toolName
+    );
+    const toolMetadata = toolTraceMetadata(tool);
+    let toolStartArgs = {
+      turn: observation?.turn ?? 0,
+      toolCall,
+      toolName: toolCall.toolName,
+      internalCallId,
+      args: effectiveArgs
+    };
+    if (toolCall.callId !== void 0) {
+      toolStartArgs = { ...toolStartArgs, toolCallId: toolCall.callId };
+    }
+    if (toolDefinition !== void 0) toolStartArgs = { ...toolStartArgs, toolDefinition };
+    if (toolMetadata !== void 0) toolStartArgs = { ...toolStartArgs, toolMetadata };
+    const observers = await observation?.runObservers.startTool(toolStartArgs);
+    const toolObservation = new ToolObserverScope(observers);
+    let output;
+    let failed = false;
+    try {
+      const prepared = prepareToolCallFromInput(tool, pending.input);
+      const step = observation?.turn ?? 0;
+      const lifecycleEvent = {
+        runId: this.runContext.runId,
+        step,
+        toolName: toolCall.toolName,
+        input: lifecycleSnapshot(prepared.input)
+      };
+      if (toolCall.callId !== void 0) {
+        Object.assign(lifecycleEvent, { toolCallId: toolCall.callId });
+      }
+      await this.lifecycle?.onToolStart?.(lifecycleEvent);
+      const startedAt = Date.now();
+      const outcome = await this.runApprovedToolCall(
+        prepared,
+        toolCall,
+        hookArgs,
+        effectiveArgs,
+        toolObservation,
+        observation,
+        onStreamEvent
+      );
+      output = outcome.output;
+      failed = outcome.failed;
+      const durationMs = Date.now() - startedAt;
+      await this.lifecycle?.onToolFinish?.(
+        outcome.failed ? {
+          ...lifecycleEvent,
+          durationMs,
+          success: false,
+          error: lifecycleSnapshot(outcome.error)
+        } : {
+          ...lifecycleEvent,
+          durationMs,
+          success: true,
+          output: lifecycleSnapshot(output)
+        }
+      );
+      let result = toolOutputToText(output);
+      let structuredResult = toolOutputToStructuredResult(output);
+      if (!isSkillTool(tool)) {
+        const replacement = await this.runToolResultMiddlewares({
+          ...hookArgs,
+          args: effectiveArgs,
+          result,
+          originalResult: result,
+          structuredResult,
+          originalStructuredResult: structuredResult,
+          turn: step
+        });
+        if (replacement !== void 0) {
+          output = replacement;
+          result = toolOutputToText(replacement);
+          structuredResult = toolOutputToStructuredResult(replacement);
+        }
+      }
+      const resultAction = await this.activeHook?.onToolResult?.({
+        ...hookArgs,
+        result,
+        structuredResult,
+        run: runControl
+      });
+      if (!failed) {
+        await toolObservation.end({
+          turn: step,
+          toolCall,
+          toolName: toolCall.toolName,
+          internalCallId,
+          args: effectiveArgs,
+          result,
+          structuredResult,
+          skipped: false,
+          toolCallId: toolCall.callId
+        });
+      }
+      if (resultAction?.type === "terminate") {
+        throw this.cancel(resultAction.reason);
+      }
+      const resultPayload = {
+        type: "tool_result",
+        toolName: toolCall.toolName,
+        toolCallId: toolCall.toolCallId,
+        internalCallId,
+        args: effectiveArgs,
+        output,
+        result,
+        structuredResult
+      };
+      if (toolCall.callId !== void 0) resultPayload.callId = toolCall.callId;
+      onResult?.(resultPayload);
+      let resultPart = {
+        type: "tool-result",
+        toolName: toolCall.toolName,
+        toolCallId: toolCall.toolCallId,
+        output
+      };
+      if (toolCall.callId !== void 0) resultPart = { ...resultPart, callId: toolCall.callId };
+      return resultPart;
+    } catch (error) {
+      await toolObservation.error(
+        toolErrorArgs(observation?.turn ?? 0, toolCall, internalCallId, effectiveArgs, error)
+      );
+      throw error;
+    }
+  }
+  async resolveResumed(pending, initialOutput, onResult, observation) {
+    throwIfAborted(this.abortSignal);
+    const { toolCall, internalCallId, effectiveArgs } = pending;
+    const tool = this.agent.getTool(toolCall.toolName);
+    if (tool === void 0) {
+      throw new Error(
+        `Cannot resume tool interaction because tool "${toolCall.toolName}" is no longer registered.`
+      );
+    }
+    const hookArgs = {
+      toolName: toolCall.toolName,
+      toolCallId: toolCall.toolCallId,
+      internalCallId,
+      args: effectiveArgs
+    };
+    if (toolCall.callId !== void 0) hookArgs.callId = toolCall.callId;
+    const toolDefinition = observation?.toolDefinitions?.find(
+      (definition) => definition.name === toolCall.toolName
+    );
+    const toolMetadata = toolTraceMetadata(tool);
+    let toolStartArgs = {
+      turn: observation?.turn ?? 0,
+      toolCall,
+      toolName: toolCall.toolName,
+      internalCallId,
+      args: effectiveArgs
+    };
+    if (toolCall.callId !== void 0) {
+      toolStartArgs = { ...toolStartArgs, toolCallId: toolCall.callId };
+    }
+    if (toolDefinition !== void 0) toolStartArgs = { ...toolStartArgs, toolDefinition };
+    if (toolMetadata !== void 0) toolStartArgs = { ...toolStartArgs, toolMetadata };
+    const observers = await observation?.runObservers.startTool(toolStartArgs);
+    const toolObservation = new ToolObserverScope(observers);
+    try {
+      let output = initialOutput;
+      let result = toolOutputToText(output);
+      let structuredResult = toolOutputToStructuredResult(output);
+      if (!isSkillTool(tool)) {
+        const replacement = await this.runToolResultMiddlewares({
+          ...hookArgs,
+          args: effectiveArgs,
+          result,
+          originalResult: result,
+          structuredResult,
+          originalStructuredResult: structuredResult,
+          turn: observation?.turn ?? 0
+        });
+        if (replacement !== void 0) {
+          output = replacement;
+          result = toolOutputToText(replacement);
+          structuredResult = toolOutputToStructuredResult(replacement);
+        }
+      }
+      const resultAction = await this.activeHook?.onToolResult?.({
+        ...hookArgs,
+        result,
+        structuredResult,
+        run: runControl
+      });
+      await toolObservation.end({
+        turn: observation?.turn ?? 0,
+        toolCall,
+        toolName: toolCall.toolName,
+        internalCallId,
+        args: effectiveArgs,
+        result,
+        structuredResult,
+        skipped: true,
+        toolCallId: toolCall.callId
+      });
+      if (resultAction?.type === "terminate") {
+        throw this.cancel(resultAction.reason);
+      }
+      const resultPayload = {
+        type: "tool_result",
+        toolName: toolCall.toolName,
+        toolCallId: toolCall.toolCallId,
+        internalCallId,
+        args: effectiveArgs,
+        output,
+        result,
+        structuredResult
+      };
+      if (toolCall.callId !== void 0) resultPayload.callId = toolCall.callId;
+      onResult?.(resultPayload);
+      let resultPart = {
+        type: "tool-result",
+        toolName: toolCall.toolName,
+        toolCallId: toolCall.toolCallId,
+        output
+      };
+      if (toolCall.callId !== void 0) resultPart = { ...resultPart, callId: toolCall.callId };
+      return resultPart;
+    } catch (error) {
+      await toolObservation.error(
+        toolErrorArgs(observation?.turn ?? 0, toolCall, internalCallId, effectiveArgs, error)
+      );
+      throw error;
+    }
+  }
+  async runApprovedToolCall(prepared, toolCall, hookArgs, effectiveArgs, toolObservation, observation, onStreamEvent) {
+    try {
+      const toolContext = {
+        abortSignal: this.abortSignal,
+        emitStreamEvent: async (event) => {
+          let streamEventArgs = {
+            turn: observation?.turn ?? 0,
+            toolCall,
+            toolName: toolCall.toolName,
+            internalCallId: hookArgs.internalCallId,
+            args: effectiveArgs,
+            event
+          };
+          if (toolCall.callId !== void 0) {
+            streamEventArgs = { ...streamEventArgs, toolCallId: toolCall.callId };
+          }
+          await toolObservation.streamEvent(streamEventArgs);
+          const payload = agentToolEventPayload(toolCall, hookArgs.internalCallId, event);
+          if (payload !== void 0) {
+            onStreamEvent?.(payload);
+          }
+        }
+      };
+      return {
+        output: await prepared.call(toolContext),
+        failed: false
+      };
+    } catch (error) {
+      return this.handleToolError(
+        toolCall,
+        hookArgs,
+        effectiveArgs,
+        error,
+        toolObservation,
+        observation
+      );
+    }
+  }
+  prepareToolCall(tool, toolName, args) {
+    if (tool !== void 0) {
+      return prepareToolCall(tool, args);
+    }
+    const input = parseToolArgs(args);
+    return {
+      input,
+      call: (context) => this.agent.callTool(toolName, args, context)
+    };
+  }
+  async handleToolError(toolCall, hookArgs, args, error, toolObservation, observation) {
+    const errorAction = await this.activeHook?.onToolError?.({
+      ...hookArgs,
+      args,
+      error,
+      run: runControl
+    });
+    await toolObservation.error(
+      toolErrorArgs(observation?.turn ?? 0, toolCall, hookArgs.internalCallId, args, error)
+    );
+    if (errorAction?.type === "terminate") {
+      throw this.cancel(errorAction.reason);
+    }
+    return {
+      output: {
+        type: "error-text",
+        value: error instanceof Error ? error.toString() : String(error)
+      },
+      failed: true,
+      error
+    };
+  }
+  async runToolResultMiddlewares(args) {
+    let result = args.result;
+    let structuredResult = args.structuredResult;
+    let replaced = false;
+    for (const middleware of this.activeMiddlewares()) {
+      const outputReplacement = await middleware.onToolOutput?.({
+        ...args,
+        result,
+        structuredResult
+      });
+      if (outputReplacement !== void 0) {
+        const normalized = normalizeToolOutputMiddlewareResult(outputReplacement);
+        if (normalized.result !== void 0) {
+          result = normalized.result;
+          structuredResult = void 0;
+        }
+        if (normalized.structuredResult !== void 0) {
+          structuredResult = normalized.structuredResult;
+          result = toolResultContentToText(normalized.structuredResult);
+        }
+        replaced = true;
+      }
+    }
+    return replaced ? structuredResult === void 0 ? { type: "text", value: result } : { type: "content", value: structuredResult } : void 0;
+  }
+  async runToolInputMiddlewares(args) {
+    let current = args.args;
+    for (const middleware of this.activeMiddlewares()) {
+      const replacement = await middleware.onToolInput?.({
+        ...args,
+        args: current
+      });
+      if (replacement?.args !== void 0) {
+        if (typeof replacement.args === "string") {
+          current = replacement.args;
+        } else {
+          if (!isJsonValue(replacement.args)) {
+            throw new TypeError("Tool input middleware args must be a strict JSON value.");
+          }
+          current = JSON.stringify(replacement.args);
+        }
+      }
+    }
+    return current;
+  }
+  activeMiddlewares() {
+    return [...this.agent.middlewares, ...this.requestMiddlewares];
+  }
+  async evaluateToolApproval(tool, context, observation) {
+    const requirement = tool?.requiresApproval;
+    if (requirement === void 0) return void 0;
+    const resolved = typeof requirement === "function" ? await requirement(context.args, context) : requirement;
+    assertToolApprovalRequirement(resolved, { allowFunction: false });
+    if (resolved === false) return { approved: true };
+    const reason = resolved === true ? void 0 : resolved.reason;
+    return this.requestApproval(context, reason === void 0 ? {} : { reason }, observation);
+  }
+  async requestApproval(context, options, observation) {
+    const request = {
+      ...context,
+      id: globalThis.crypto.randomUUID()
+    };
+    if (options.reason !== void 0) {
+      request.reason = options.reason;
+    }
+    if (options.rejectMessage !== void 0) {
+      request.rejectMessage = options.rejectMessage;
+    }
+    await observation?.runObservers.event({
+      name: "tool.approval_requested",
+      attributes: approvalEventAttributes(request, observation.turn)
+    });
+    let decision;
+    try {
+      decision = await this.approvalHandler(request);
+    } catch (error) {
+      if (error instanceof AgentInteractionSignal) {
+        throw error;
+      }
+      await observation?.runObservers.event({
+        name: "tool.approval_failed",
+        level: "ERROR",
+        attributes: {
+          ...approvalEventAttributes(request, observation.turn),
+          errorName: error instanceof Error ? error.name : typeof error
+        }
+      });
+      throw error;
+    }
+    const attributes = {
+      ...approvalEventAttributes(request, observation?.turn ?? 0),
+      approved: decision.approved
+    };
+    if (decision.reason !== void 0) attributes.decisionReason = decision.reason;
+    await observation?.runObservers.event({
+      name: "tool.approval_resolved",
+      attributes
+    });
+    if (decision.approved) {
+      return { approved: true };
+    }
+    return {
+      approved: false,
+      result: decision.reason ?? request.rejectMessage ?? "Tool approval was rejected."
+    };
+  }
+};
+function createApprovalContext(input, hookArgs, agent, run) {
+  const approvalRun = {
+    agentId: agent.id,
+    runId: run.runId
+  };
+  if (run.sessionId !== void 0) {
+    approvalRun.sessionId = run.sessionId;
+  }
+  if (run.metadata !== void 0) {
+    approvalRun.metadata = run.metadata;
+  }
+  const context = {
+    toolName: hookArgs.toolName,
+    args: lifecycleSnapshot(input),
+    rawArgs: hookArgs.args,
+    toolCallId: hookArgs.toolCallId,
+    internalCallId: hookArgs.internalCallId,
+    run: approvalRun
+  };
+  if (hookArgs.callId !== void 0) {
+    context.callId = hookArgs.callId;
+  }
+  return context;
+}
+function approvalEventAttributes(request, turn) {
+  const attributes = {
+    turn,
+    approvalId: request.id,
+    toolName: request.toolName,
+    internalCallId: request.internalCallId
+  };
+  if (request.toolCallId !== void 0) attributes.toolCallId = request.toolCallId;
+  if (request.reason !== void 0) attributes.reason = request.reason;
+  return attributes;
+}
+function normalizeToolOutputMiddlewareResult(result) {
+  if (typeof result === "string") {
+    return { result };
+  }
+  if (typeof result !== "object" || result === null) {
+    throw new TypeError("Tool output middleware must return text or structured content.");
+  }
+  const prototype = Object.getPrototypeOf(result);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError("Tool output middleware must return text or structured content.");
+  }
+  const keys = Reflect.ownKeys(result);
+  const hasResult = keys.includes("result");
+  const hasStructuredResult = keys.includes("structuredResult");
+  if (hasResult === hasStructuredResult || keys.some((key) => key !== "result" && key !== "structuredResult")) {
+    throw new TypeError(
+      "Tool output middleware must return exactly one of result or structuredResult."
+    );
+  }
+  if (hasResult) {
+    const descriptor2 = Object.getOwnPropertyDescriptor(result, "result");
+    if (descriptor2 === void 0 || !("value" in descriptor2) || typeof descriptor2.value !== "string") {
+      throw new TypeError("Tool output middleware result must be a string.");
+    }
+    return { result: descriptor2.value };
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(result, "structuredResult");
+  if (descriptor === void 0 || !("value" in descriptor)) {
+    throw new TypeError("Tool output middleware structuredResult must be valid tool content.");
+  }
+  const normalized = normalizeToolResultOutput(ToolOutput.content(descriptor.value));
+  if (normalized.type !== "content") {
+    throw new TypeError("Tool output middleware structuredResult must be valid tool content.");
+  }
+  return { structuredResult: normalized.value };
+}
+function toolTraceMetadata(tool) {
+  if (tool === void 0) {
+    return void 0;
+  }
+  const result = {
+    approvalRequired: toolMayRequireApproval(tool.requiresApproval)
+  };
+  if (isMcpTool(tool)) {
+    result.mcpServerName = tool.mcp.serverName;
+    result.mcpRemoteName = tool.mcp.remoteName;
+  }
+  return result;
+}
+function toolErrorArgs(turn, toolCall, internalCallId, args, error) {
+  let observerArgs = {
+    turn,
+    toolCall,
+    toolName: toolCall.toolName,
+    internalCallId,
+    args,
+    error
+  };
+  if (toolCall.callId !== void 0) {
+    observerArgs = { ...observerArgs, toolCallId: toolCall.callId };
+  }
+  return observerArgs;
+}
+var ToolObserverScope = class {
+  constructor(observers) {
+    this.observers = observers;
+  }
+  observers;
+  terminal = false;
+  streamEvent(args) {
+    return this.observers?.streamEvent(args);
+  }
+  async end(args) {
+    if (this.terminal) return;
+    this.terminal = true;
+    await this.observers?.end(args);
+  }
+  async suspend(args) {
+    if (this.terminal) return;
+    this.terminal = true;
+    await this.observers?.suspend(args);
+  }
+  async error(args) {
+    if (this.terminal) return;
+    this.terminal = true;
+    await this.observers?.error(args);
+  }
+};
+function toolOutputToText(output) {
+  switch (output.type) {
+    case "text":
+    case "error-text":
+      return output.value;
+    case "json":
+    case "error-json":
+      return JSON.stringify(output.value);
+    case "content":
+      return toolResultContentToText(output.value);
+    case "execution-denied":
+      return output.reason ?? "Tool execution was denied.";
+  }
+}
+function toolOutputToStructuredResult(output) {
+  return output.type === "content" ? output.value : void 0;
+}
+function agentToolEventPayload(toolCall, internalCallId, event) {
+  if (typeof event.agentId !== "string" || event.agentId.length === 0) {
+    return void 0;
+  }
+  const payload = {
+    type: "agent_tool_event",
+    toolName: toolCall.toolName,
+    internalCallId,
+    agentId: event.agentId,
+    event: event.event
+  };
+  if (toolCall.callId !== void 0) {
+    payload.toolCallId = toolCall.callId;
+  }
+  if (event.agentName !== void 0) {
+    payload.agentName = event.agentName;
+  }
+  return payload;
+}
+
+// src/internal/agent-runtime/agent-run.ts
+async function settleFailureCleanup(operations) {
+  for (const operation of operations) {
+    try {
+      await operation();
+    } catch {
+    }
+  }
+}
+var AgentRun = class _AgentRun {
+  constructor(agent, promptMessage, initialHistory = [], options = {}) {
+    this.agent = agent;
+    this.promptMessage = promptMessage;
+    this.chatHistory = initialHistory;
+    this.maxTurnCount = assertNonnegativeSafeInteger(
+      options.maxTurns ?? agent.defaultMaxTurns ?? 0,
+      "maxTurns"
+    );
+    const internalOptions = getInternalAgentRunOptions(options);
+    this.activeHook = internalOptions?.hook;
+    this.onInternalFailure = internalOptions?.onFailure;
+    this.onInternalMemoryCompaction = internalOptions?.onMemoryCompaction;
+    this.requestedRunId = normalizeRequestedRunId(internalOptions?.runId);
+    this.activeLifecycle = composeAgentLifecycle(agent.lifecycle, options.lifecycle);
+    this.guardrailPolicies = options.guardrails === void 0 ? [...agent.guardrails] : appendGuardrailPolicies([...agent.guardrails], options.guardrails);
+    const configuredConcurrency = assertPositiveSafeInteger(
+      options.toolConcurrency ?? 1,
+      "toolConcurrency"
+    );
+    this.concurrency = this.activeHook !== void 0 || agent.tools.some(
+      (tool) => toolMayRequireApproval(tool.requiresApproval) || isQuestionTool(tool)
+    ) ? 1 : configuredConcurrency;
+    this.traceOptions = options.trace;
+    const retrySetting = options.retries === void 0 ? agent.retries : options.retries;
+    this.completionRetryOptions = retrySetting === void 0 || retrySetting === false ? void 0 : resolveRetryOptions(retrySetting);
+    this.requestMiddlewares = [...options.middlewares ?? []];
+    this.memoryScope = options.memoryScope;
+    this.memoryRecorder = new AgentRunMemory(agent, options.memoryScope, initialHistory);
+    this.continuationState = options.continuationState;
+    this.interactionResponse = options.interactionResponse;
+    if (options.continuationState !== void 0) {
+      this.steeringMessages.push(
+        ...options.continuationState.steering.map((entry) => ({
+          id: entry.id,
+          messages: [...entry.messages]
+        }))
+      );
+    }
+    this.resumedFrom = options.sourceRunId === void 0 || options.interactionId === void 0 ? void 0 : { runId: options.sourceRunId, interactionId: options.interactionId };
+    this.linkExternalAbortSignal(options.abortSignal);
+  }
+  agent;
+  promptMessage;
+  chatHistory;
+  maxTurnCount;
+  activeHook;
+  activeLifecycle;
+  guardrailPolicies;
+  guardrailDecisions = [];
+  concurrency;
+  traceOptions;
+  completionRetryOptions;
+  requestMiddlewares;
+  steeringMessages = [];
+  runState = "idle";
+  memoryRecorder;
+  memoryScope;
+  onInternalFailure;
+  onInternalMemoryCompaction;
+  memoryCompaction;
+  requestedRunId;
+  continuationState;
+  interactionResponse;
+  resumedFrom;
+  currentMessages = [];
+  cancellationError;
+  activeGeneration;
+  validatedStructuredOutput;
+  failedCompletionUsage = Usage.empty();
+  abortController = new AbortController();
+  removeExternalAbortListener;
+  static fromAgent(agent, options) {
+    const normalized = normalizeAgentInput(agent.id, options);
+    if (normalized.scope !== void 0 && agent.memory === void 0) {
+      throw new TypeError(`Agent "${agent.id}" cannot use a session without a memory store.`);
+    }
+    return new _AgentRun(agent, normalized.prompt, normalized.history, {
+      ...options,
+      memoryScope: normalized.scope,
+      continuationState: normalized.continuationState,
+      interactionResponse: normalized.interactionResponse,
+      sourceRunId: normalized.sourceRunId,
+      interactionId: normalized.interactionId
+    });
+  }
+  steer(input) {
+    if (this.isTerminal() || this.cancellationError !== void 0) {
+      throw new AgentStreamClosedError();
+    }
+    const receipt = Object.freeze({
+      id: globalThis.crypto.randomUUID(),
+      status: "queued"
+    });
+    this.steeringMessages.push({ id: receipt.id, messages: normalizeSteeringInput(input) });
+    return receipt;
+  }
+  cancel(reason) {
+    if (this.isTerminal() || this.cancellationError !== void 0) {
+      return;
+    }
+    const messages = this.currentMessages.length === 0 ? [this.promptMessage] : [...this.currentMessages];
+    const error = new AgentRunCancelledError([...this.chatHistory, ...messages], reason);
+    this.setCancellationError(error);
+  }
+  setCancellationError(error) {
+    this.cancellationError = error;
+    if (!this.abortController.signal.aborted) this.abortController.abort(error);
+  }
+  async generate() {
+    this.startRun();
+    const runId = this.requestedRunId ?? globalThis.crypto.randomUUID();
+    let usage = Usage.empty();
+    let currentTurns = 0;
+    let lastPrompt = this.promptMessage;
+    let newMessages = [this.promptMessage];
+    let runObservers;
+    let pendingTurnMessages = [];
+    try {
+      this.throwIfCancelled();
+      const memoryPreparation = this.continuationState === void 0 ? await this.memoryRecorder.prepareHistory(
+        runId,
+        newMessages.length,
+        this.abortController.signal
+      ) : void 0;
+      if (memoryPreparation !== void 0) {
+        this.chatHistory = memoryPreparation.history;
+        usage = Usage.add(usage, memoryPreparation.usage);
+        this.memoryCompaction = memoryPreparation.compaction;
+        await this.notifyInternalMemoryCompaction(memoryPreparation.compaction);
+      }
+      runObservers = await this.startRunObservers(runId);
+      if (memoryPreparation !== void 0) {
+        await this.recordMemoryCompaction(memoryPreparation, runObservers);
+      }
+      this.throwIfCancelled();
+      await this.activeLifecycle?.onStart?.({
+        runId,
+        input: lifecycleSnapshot(this.promptMessage),
+        history: lifecycleSnapshot(this.chatHistory),
+        maxTurns: this.maxTurnCount
+      });
+      if (this.continuationState === void 0) {
+        const inputResult = await runInputGuardrails(this.guardrailPolicies, {
+          prompt: this.promptMessage,
+          history: this.chatHistory,
+          inputText: textFromMessage(this.promptMessage),
+          run: this.guardrailRunContext(runId)
+        });
+        for (const decision of inputResult.decisions) {
+          await this.recordGuardrailDecision(decision, runObservers);
+        }
+        this.promptMessage = inputResult.prompt;
+        if (inputResult.blocked) {
+          const text = inputResult.message ?? "The request was blocked by a guardrail.";
+          const result = {
+            status: "blocked",
+            stage: "input",
+            runId,
+            text,
+            usage,
+            messages: [this.promptMessage, { role: "assistant", content: text }],
+            trace: runObservers.trace,
+            guardrails: [...this.guardrailDecisions],
+            ...this.memoryCompactionResult()
+          };
+          if (this.resumedFrom !== void 0) result.resumedFrom = this.resumedFrom;
+          this.runState = "closing";
+          await this.runLifecycleFinish(result);
+          await runObservers.end(result);
+          this.runState = "completed";
+          this.disposeAbortLink();
+          return result;
+        }
+      }
+      newMessages = [this.promptMessage];
+      await this.memoryRecorder.commitAcceptedInput(runId, newMessages);
+      pendingTurnMessages = this.memoryRecorder.pendingTurnMessages(newMessages);
+      await this.runRunStartHook(newMessages);
+      if (this.continuationState !== void 0) {
+        const interactionAttributes = {};
+        if (this.resumedFrom?.runId !== void 0) {
+          interactionAttributes.sourceRunId = this.resumedFrom.runId;
+        }
+        if (this.resumedFrom?.interactionId !== void 0) {
+          interactionAttributes.interactionId = this.resumedFrom.interactionId;
+        }
+        if (this.interactionResponse?.type !== void 0) {
+          interactionAttributes.interactionType = this.interactionResponse.type;
+        }
+        await runObservers.event({
+          name: "agent.interaction_response",
+          attributes: interactionAttributes
+        });
+        try {
+          const toolResults = await this.resolveContinuationTools(
+            runId,
+            newMessages,
+            void 0,
+            void 0,
+            {
+              turn: 1,
+              runObservers
+            }
+          );
+          const toolMessage = { role: "tool", content: toolResults };
+          newMessages.push(toolMessage);
+          await this.memoryRecorder.commitMessages(runId, 1, [toolMessage], pendingTurnMessages);
+          await this.drainSteeringMessages(runId, 1, newMessages, pendingTurnMessages);
+          await this.memoryRecorder.commitCompletedTurn(runId, 1, pendingTurnMessages);
+        } catch (error) {
+          if (error instanceof ToolExecutionSuspension) {
+            return this.finishSuspension({
+              runId,
+              turn: 1,
+              usage,
+              newMessages,
+              pendingTurnMessages,
+              runObservers,
+              suspension: error,
+              uncommittedMessages: []
+            });
+          }
+          throw error;
+        }
+      }
+      while (currentTurns <= this.maxTurnCount + 1) {
+        const prompt = newMessages.at(-1);
+        if (prompt === void 0) {
+          throw new Error("AgentRun requires at least one message");
+        }
+        lastPrompt = prompt;
+        currentTurns += 1;
+        const historyForRequest = [...this.chatHistory, ...newMessages.slice(0, -1)];
+        await this.runTurnStartHook(currentTurns, prompt, historyForRequest, newMessages);
+        await this.runCompletionCallHook(prompt, historyForRequest, newMessages);
+        const request = await this.createTurnRequest(prompt, historyForRequest, currentTurns);
+        let response;
+        try {
+          response = await this.runCompletion(request, currentTurns, runObservers);
+        } catch (error) {
+          await settleFailureCleanup([
+            () => this.runCompletionErrorHook(prompt, error, newMessages)
+          ]);
+          throw error;
+        }
+        response = await this.runCompletionResponseMiddlewares(request, response, currentTurns);
+        try {
+          assertCompletionResponseIntegrity({ response });
+        } catch (error) {
+          const providerOutputUsage = completionProviderOutputErrorUsage(error);
+          if (providerOutputUsage !== void 0) usage = Usage.add(usage, providerOutputUsage);
+          throw error;
+        }
+        usage = Usage.add(usage, response.usage);
+        this.updateRunProgress(newMessages);
+        await this.runCompletionResponseHook(prompt, response, newMessages);
+        await this.runTurnEndHook(currentTurns, response, newMessages);
+        await this.activeLifecycle?.onStepFinish?.({
+          runId,
+          step: currentTurns,
+          response: lifecycleSnapshot(response),
+          usage: lifecycleSnapshot(usage)
+        });
+        const toolCalls = response.choice.filter(
+          (item) => item.type === "tool-call"
+        );
+        const assistantMessage = this.generatedAssistantMessage(response, request);
+        newMessages.push(assistantMessage);
+        if (toolCalls.length === 0) {
+          if (this.steeringMessages.length > 0) {
+            await this.memoryRecorder.commitMessages(
+              runId,
+              currentTurns,
+              [assistantMessage],
+              pendingTurnMessages
+            );
+          }
+          const appliedSteering = await this.drainSteeringMessages(
+            runId,
+            currentTurns,
+            newMessages,
+            pendingTurnMessages,
+            { closeWhenEmpty: true }
+          );
+          if (appliedSteering.length > 0) {
+            for (const receipt of appliedSteering) {
+              await runObservers.event({
+                name: "agent.steering_applied",
+                attributes: { id: receipt.id, turn: currentTurns }
+              });
+            }
+            await this.memoryRecorder.commitCompletedTurn(runId, currentTurns, pendingTurnMessages);
+            continue;
+          }
+          const guardedOutput = await this.runOutputGuardrailsForResponse(
+            runId,
+            usage,
+            response,
+            newMessages,
+            runObservers
+          );
+          response = guardedOutput.response;
+          const finalAssistantMessage = this.generatedAssistantMessage(response, request);
+          newMessages[newMessages.length - 1] = finalAssistantMessage;
+          await this.memoryRecorder.commitMessages(
+            runId,
+            currentTurns,
+            [finalAssistantMessage],
+            pendingTurnMessages
+          );
+          const result = this.createTerminalResult(
+            runId,
+            guardedOutput.text,
+            guardedOutput.blocked,
+            usage,
+            newMessages,
+            runObservers
+          );
+          if (result.status === "completed") {
+            await this.runRunEndHook(result, newMessages);
+          }
+          await this.memoryRecorder.commitCompletedRun(
+            runId,
+            currentTurns,
+            newMessages,
+            pendingTurnMessages
+          );
+          await this.runLifecycleFinish(result);
+          await runObservers.end(result);
+          this.runState = "completed";
+          this.disposeAbortLink();
+          return result;
+        }
+        this.updateRunProgress(newMessages);
+        let toolResults;
+        try {
+          toolResults = await this.executeToolCalls(
+            runId,
+            toolCalls,
+            newMessages,
+            void 0,
+            void 0,
+            {
+              turn: currentTurns,
+              runObservers,
+              toolDefinitions: request.tools
+            }
+          );
+        } catch (error) {
+          if (error instanceof ToolExecutionSuspension) {
+            return this.finishSuspension({
+              runId,
+              turn: currentTurns,
+              usage,
+              newMessages,
+              pendingTurnMessages,
+              runObservers,
+              suspension: error,
+              uncommittedMessages: [assistantMessage]
+            });
+          }
+          throw error;
+        }
+        const toolMessage = { role: "tool", content: toolResults };
+        newMessages.push(toolMessage);
+        await this.memoryRecorder.commitMessages(
+          runId,
+          currentTurns,
+          [assistantMessage, toolMessage],
+          pendingTurnMessages
+        );
+        await this.drainSteeringMessages(runId, currentTurns, newMessages, pendingTurnMessages);
+        await this.memoryRecorder.commitCompletedTurn(runId, currentTurns, pendingTurnMessages);
+      }
+      throw new MaxTurnsError(this.maxTurnCount, [...this.chatHistory, ...newMessages], lastPrompt);
+    } catch (error) {
+      if (error instanceof MemoryCompactionError && error.usage !== void 0) {
+        usage = Usage.add(usage, error.usage);
+      }
+      const failedCompletionUsage = this.takeFailedCompletionUsage();
+      if (error instanceof AgentStructuredOutputError) {
+        usage = Usage.add(usage, error.usage);
+      } else {
+        usage = Usage.add(usage, failedCompletionUsage);
+      }
+      this.runState = "closing";
+      const runError = this.normalizeRunError(error);
+      const reportedError = await this.reportRunFailure(
+        runError,
+        runId,
+        usage,
+        newMessages,
+        runObservers
+      );
+      this.runState = reportedError instanceof AgentRunCancelledError ? "cancelled" : "errored";
+      this.disposeAbortLink();
+      throw reportedError;
+    }
+  }
+  async *events() {
+    this.startRun();
+    const runId = this.requestedRunId ?? globalThis.crypto.randomUUID();
+    let usage = Usage.empty();
+    let currentTurns = 0;
+    let lastPrompt = this.promptMessage;
+    let newMessages = [this.promptMessage];
+    const bufferOutputDeltas = hasEnforcedOutputGuardrails(this.guardrailPolicies);
+    let runObservers;
+    let pendingTurnMessages = [];
+    try {
+      this.throwIfCancelled();
+      const memoryPreparation = this.continuationState === void 0 ? await this.memoryRecorder.prepareHistory(
+        runId,
+        newMessages.length,
+        this.abortController.signal
+      ) : void 0;
+      if (memoryPreparation !== void 0) {
+        this.chatHistory = memoryPreparation.history;
+        usage = Usage.add(usage, memoryPreparation.usage);
+        this.memoryCompaction = memoryPreparation.compaction;
+        await this.notifyInternalMemoryCompaction(memoryPreparation.compaction);
+      }
+      runObservers = await this.startRunObservers(runId);
+      if (memoryPreparation !== void 0) {
+        await this.recordMemoryCompaction(memoryPreparation, runObservers);
+      }
+      if (memoryPreparation?.compaction !== void 0) {
+        yield { type: "memory_compaction", ...memoryPreparation.compaction };
+      }
+      this.throwIfCancelled();
+      await this.activeLifecycle?.onStart?.({
+        runId,
+        input: lifecycleSnapshot(this.promptMessage),
+        history: lifecycleSnapshot(this.chatHistory),
+        maxTurns: this.maxTurnCount
+      });
+      if (this.continuationState === void 0) {
+        const inputResult = await runInputGuardrails(this.guardrailPolicies, {
+          prompt: this.promptMessage,
+          history: this.chatHistory,
+          inputText: textFromMessage(this.promptMessage),
+          run: this.guardrailRunContext(runId)
+        });
+        for (const decision of inputResult.decisions) {
+          await this.recordGuardrailDecision(decision, runObservers);
+          yield { type: "guardrail_decision", decision };
+        }
+        this.promptMessage = inputResult.prompt;
+        if (inputResult.blocked) {
+          const text = inputResult.message ?? "The request was blocked by a guardrail.";
+          const result = {
+            status: "blocked",
+            stage: "input",
+            runId,
+            text,
+            usage,
+            messages: [this.promptMessage, { role: "assistant", content: text }],
+            trace: runObservers.trace,
+            guardrails: [...this.guardrailDecisions],
+            ...this.memoryCompactionResult()
+          };
+          if (this.resumedFrom !== void 0) result.resumedFrom = this.resumedFrom;
+          this.runState = "closing";
+          await this.runLifecycleFinish(result);
+          await runObservers.end(result);
+          this.runState = "completed";
+          this.disposeAbortLink();
+          yield { type: "final", result };
+          return;
+        }
+      }
+      newMessages = [this.promptMessage];
+      await this.memoryRecorder.commitAcceptedInput(runId, newMessages);
+      pendingTurnMessages = this.memoryRecorder.pendingTurnMessages(newMessages);
+      await this.runRunStartHook(newMessages);
+      if (this.continuationState !== void 0) {
+        const responsePart = this.promptMessage.role === "tool" ? this.promptMessage.content[0] : void 0;
+        if (responsePart === void 0 || responsePart.type === "tool-result") {
+          throw new TypeError("Agent continuation response message is invalid.");
+        }
+        yield {
+          type: "interaction_response",
+          response: responsePart,
+          sourceRunId: this.resumedFrom?.runId ?? this.continuationState.kind
+        };
+        try {
+          const execution = this.executeContinuationToolStream(runId, newMessages, {
+            turn: 1,
+            runObservers
+          });
+          for await (const event of execution.events) {
+            yield { turn: 1, ...event };
+          }
+          const toolResults = await execution.results;
+          const toolMessage = { role: "tool", content: toolResults };
+          newMessages.push(toolMessage);
+          await this.memoryRecorder.commitMessages(runId, 1, [toolMessage], pendingTurnMessages);
+          for (const receipt of await this.drainSteeringMessages(
+            runId,
+            1,
+            newMessages,
+            pendingTurnMessages
+          )) {
+            yield { type: "steering_applied", id: receipt.id, turn: 1 };
+          }
+          await this.memoryRecorder.commitCompletedTurn(runId, 1, pendingTurnMessages);
+        } catch (error) {
+          if (error instanceof ToolExecutionSuspension) {
+            const result = await this.finishSuspension({
+              runId,
+              turn: 1,
+              usage,
+              newMessages,
+              pendingTurnMessages,
+              runObservers,
+              suspension: error,
+              uncommittedMessages: []
+            });
+            yield { type: "final", result };
+            return;
+          }
+          throw error;
+        }
+      }
+      while (currentTurns <= this.maxTurnCount + 1) {
+        const prompt = newMessages.at(-1);
+        if (prompt === void 0) {
+          throw new Error("AgentRun requires at least one message");
+        }
+        lastPrompt = prompt;
+        currentTurns += 1;
+        const historyForRequest = [...this.chatHistory, ...newMessages.slice(0, -1)];
+        yield {
+          type: "turn_start",
+          turn: currentTurns,
+          prompt,
+          history: historyForRequest
+        };
+        await this.runTurnStartHook(currentTurns, prompt, historyForRequest, newMessages);
+        await this.runCompletionCallHook(prompt, historyForRequest, newMessages);
+        const request = await this.createTurnRequest(prompt, historyForRequest, currentTurns);
+        assertCompletionRequestSupported(this.agent.model, request, { streaming: true });
+        const providerRequest = this.providerTraceRequest(request, { stream: true });
+        const generationStartArgs = this.generationStartArgs(
+          currentTurns,
+          request,
+          providerRequest
+        );
+        const generationObservers = await runObservers.startGeneration(generationStartArgs);
+        this.activeGeneration = { turn: currentTurns, observers: generationObservers };
+        const generationStartedAt = Date.now();
+        yield {
+          type: "generation_start",
+          turn: currentTurns,
+          request,
+          modelInfo: generationStartArgs.modelInfo
+        };
+        const bufferResponseEvents = this.shouldBufferStreamResponseEvents() || this.agent.outputSchema !== void 0;
+        const completionState = {
+          response: void 0,
+          firstDeltaMs: void 0,
+          emittedToolCallIds: /* @__PURE__ */ new Set(),
+          providerErrorUsage: Usage.empty()
+        };
+        let response;
+        try {
+          try {
+            for await (const event of this.streamCompletion({
+              request,
+              turn: currentTurns,
+              bufferResponseEvents,
+              bufferOutputDeltas,
+              generationStartedAt,
+              generationObservers,
+              runObservers,
+              state: completionState
+            })) {
+              yield event;
+            }
+          } finally {
+            usage = Usage.add(usage, completionState.providerErrorUsage);
+          }
+          if (completionState.response === void 0) {
+            throw new Error("Streaming completion ended without a response.");
+          }
+          response = completionState.response;
+        } catch (error) {
+          await settleFailureCleanup([
+            () => this.closeActiveGeneration(error),
+            () => this.runCompletionErrorHook(prompt, error, newMessages)
+          ]);
+          throw error;
+        }
+        const { firstDeltaMs, emittedToolCallIds } = completionState;
+        let generationEndArgs = {
+          turn: currentTurns,
+          response
+        };
+        if (firstDeltaMs !== void 0) {
+          generationEndArgs = { ...generationEndArgs, firstDeltaMs };
+        }
+        this.activeGeneration = void 0;
+        await generationObservers.end(generationEndArgs);
+        response = await this.runCompletionResponseMiddlewares(request, response, currentTurns);
+        try {
+          assertCompletionResponseIntegrity({ response });
+        } catch (error) {
+          const providerOutputUsage = completionProviderOutputErrorUsage(error);
+          if (providerOutputUsage !== void 0) usage = Usage.add(usage, providerOutputUsage);
+          throw error;
+        }
+        usage = Usage.add(usage, response.usage);
+        this.updateRunProgress(newMessages);
+        await this.runCompletionResponseHook(prompt, response, newMessages);
+        await this.runTurnEndHook(currentTurns, response, newMessages);
+        await this.activeLifecycle?.onStepFinish?.({
+          runId,
+          step: currentTurns,
+          response: lifecycleSnapshot(response),
+          usage: lifecycleSnapshot(usage)
+        });
+        const toolCalls = response.choice.filter(
+          (item) => item.type === "tool-call"
+        );
+        const assistantMessage = this.generatedAssistantMessage(response, request);
+        newMessages.push(assistantMessage);
+        if (toolCalls.length === 0) {
+          let emittedTurnEnd = false;
+          if (!bufferOutputDeltas) {
+            if (bufferResponseEvents) {
+              for (const event of responseStreamEvents(currentTurns, response)) {
+                yield event;
+              }
+            }
+            yield {
+              type: "turn_end",
+              turn: currentTurns,
+              response,
+              firstDeltaMs
+            };
+            emittedTurnEnd = true;
+          }
+          if (this.steeringMessages.length > 0) {
+            await this.memoryRecorder.commitMessages(
+              runId,
+              currentTurns,
+              [assistantMessage],
+              pendingTurnMessages
+            );
+          }
+          const appliedSteering = await this.drainSteeringMessages(
+            runId,
+            currentTurns,
+            newMessages,
+            pendingTurnMessages,
+            { closeWhenEmpty: true }
+          );
+          for (const receipt of appliedSteering) {
+            yield { type: "steering_applied", id: receipt.id, turn: currentTurns };
+          }
+          if (appliedSteering.length > 0) {
+            await this.memoryRecorder.commitCompletedTurn(runId, currentTurns, pendingTurnMessages);
+            continue;
+          }
+          for await (const event of this.completeStreamingRun({
+            runId,
+            turn: currentTurns,
+            request,
+            response,
+            firstDeltaMs,
+            usage,
+            newMessages,
+            pendingTurnMessages,
+            runObservers,
+            bufferResponseEvents,
+            bufferOutputDeltas,
+            emittedTurnEnd
+          })) {
+            yield event;
+          }
+          return;
+        }
+        if (bufferResponseEvents) {
+          for (const event of responseStreamEvents(currentTurns, response)) {
+            yield event;
+          }
+        } else {
+          for (const toolCall of toolCalls) {
+            if (!emittedToolCallIds.has(toolCall.toolCallId)) {
+              yield { type: "tool_call", turn: currentTurns, toolCall };
+            }
+          }
+        }
+        this.updateRunProgress(newMessages);
+        yield {
+          type: "turn_end",
+          turn: currentTurns,
+          response,
+          firstDeltaMs
+        };
+        let toolResults;
+        try {
+          const toolExecution = this.executeStreamingToolCalls(runId, toolCalls, newMessages, {
+            turn: currentTurns,
+            runObservers,
+            toolDefinitions: request.tools
+          });
+          for await (const result of toolExecution.events) {
+            yield { turn: currentTurns, ...result };
+          }
+          toolResults = await toolExecution.results;
+        } catch (error) {
+          if (error instanceof ToolExecutionSuspension) {
+            const result = await this.finishSuspension({
+              runId,
+              turn: currentTurns,
+              usage,
+              newMessages,
+              pendingTurnMessages,
+              runObservers,
+              suspension: error,
+              uncommittedMessages: [assistantMessage]
+            });
+            yield { type: "final", result };
+            return;
+          }
+          throw error;
+        }
+        const toolMessage = { role: "tool", content: toolResults };
+        newMessages.push(toolMessage);
+        await this.memoryRecorder.commitMessages(
+          runId,
+          currentTurns,
+          [assistantMessage, toolMessage],
+          pendingTurnMessages
+        );
+        for (const receipt of await this.drainSteeringMessages(
+          runId,
+          currentTurns,
+          newMessages,
+          pendingTurnMessages
+        )) {
+          yield { type: "steering_applied", id: receipt.id, turn: currentTurns };
+        }
+        await this.memoryRecorder.commitCompletedTurn(runId, currentTurns, pendingTurnMessages);
+      }
+      throw new MaxTurnsError(this.maxTurnCount, [...this.chatHistory, ...newMessages], lastPrompt);
+    } catch (error) {
+      if (error instanceof MemoryCompactionError && error.usage !== void 0) {
+        usage = Usage.add(usage, error.usage);
+      }
+      if (error instanceof AgentStructuredOutputError) {
+        usage = Usage.add(usage, error.usage);
+      }
+      this.runState = "closing";
+      const runError = this.normalizeRunError(error);
+      const reportedError = await this.reportRunFailure(
+        runError,
+        runId,
+        usage,
+        newMessages,
+        runObservers
+      );
+      this.runState = reportedError instanceof AgentRunCancelledError ? "cancelled" : "errored";
+      const finalUsage = usage;
+      yield { type: "error", error: reportedError, usage: finalUsage };
+      this.disposeAbortLink();
+      return;
+    } finally {
+      if (this.runState === "running" || this.runState === "closing") {
+        const cancellation = this.cancellationError ?? new AgentRunCancelledError([...this.chatHistory, ...newMessages], "Agent stream closed.");
+        this.cancellationError = cancellation;
+        await settleFailureCleanup([() => this.closeActiveGeneration(cancellation)]);
+        await this.reportRunFailure(cancellation, runId, usage, newMessages, runObservers);
+        this.runState = "cancelled";
+        this.disposeAbortLink();
+      }
+    }
+  }
+  async runCompletion(request, turn, runObservers) {
+    assertCompletionRequestSupported(this.agent.model, request);
+    this.validatedStructuredOutput = void 0;
+    this.failedCompletionUsage = Usage.empty();
+    const providerRequest = this.providerTraceRequest(request);
+    const generationObservers = await runObservers.startGeneration(
+      this.generationStartArgs(turn, request, providerRequest)
+    );
+    let currentRequest = request;
+    let failedAttemptUsage = Usage.empty();
+    try {
+      for (let attempt = 1; ; attempt += 1) {
+        let response;
+        try {
+          this.throwIfCancelled();
+          response = await this.agent.model.completion(currentRequest, this.modelCallOptions());
+          assertCompletionResponseIntegrity({ response });
+        } catch (error) {
+          const attemptUsage = completionProviderOutputErrorUsage(error);
+          if (attemptUsage !== void 0) {
+            failedAttemptUsage = Usage.add(failedAttemptUsage, attemptUsage);
+            this.failedCompletionUsage = failedAttemptUsage;
+          }
+          const retryOptions = this.retryOptionsForFailure(error, attempt, turn, false);
+          if (retryOptions === void 0) {
+            throw error;
+          }
+          await this.scheduleCompletionRetry(
+            error,
+            attempt,
+            turn,
+            false,
+            retryOptions,
+            runObservers,
+            providerOutputRetryEventAttributes(error, failedAttemptUsage)
+          );
+          continue;
+        }
+        const cumulativeUsage = Usage.add(failedAttemptUsage, response.usage);
+        try {
+          this.validateStructuredResponse(response, attempt, cumulativeUsage);
+        } catch (error) {
+          const retryOptions = this.retryOptionsForFailure(error, attempt, turn, false);
+          if (retryOptions === void 0) {
+            throw error;
+          }
+          failedAttemptUsage = cumulativeUsage;
+          this.failedCompletionUsage = failedAttemptUsage;
+          const retryRequest = structuredOutputRetryRequest(request, response, error);
+          currentRequest = retryRequest.request;
+          await this.scheduleCompletionRetry(
+            error,
+            attempt,
+            turn,
+            false,
+            retryOptions,
+            runObservers,
+            structuredOutputRetryEventAttributes(error, retryRequest)
+          );
+          continue;
+        }
+        const finalResponse = Usage.isEmpty(failedAttemptUsage) ? response : { ...response, usage: cumulativeUsage };
+        await generationObservers.end({ turn, response: finalResponse });
+        this.failedCompletionUsage = Usage.empty();
+        return finalResponse;
+      }
+    } catch (error) {
+      await settleFailureCleanup([() => generationObservers.error({ turn, error })]);
+      throw error;
+    }
+  }
+  async createTurnRequest(prompt, history, turn) {
+    const ragText = extractRagText(prompt);
+    const abortSignal = this.abortController.signal;
+    const documents = await fetchContextDocuments(this.agent, ragText, abortSignal);
+    const toolDefinitions = await fetchToolDefinitions(this.agent, ragText, abortSignal);
+    const request = createCompletionRequest(providerMessages([...history, prompt]), {
+      instructions: this.agent.instructions,
+      documents,
+      tools: [...toolDefinitions, ...getAgentToolState(this.agent).providerTools],
+      temperature: this.agent.temperature,
+      maxTokens: this.agent.maxTokens,
+      providerOptions: this.agent.providerOptions,
+      toolChoice: this.agent.toolChoice,
+      outputSchema: getAgentProviderOutputSchema(this.agent)
+    });
+    return this.runCompletionRequestMiddlewares(request, turn);
+  }
+  async *streamCompletion(args) {
+    const model = this.agent.model;
+    if (!isStreamingCompletionModel(model)) {
+      throw new TypeError("Streaming completion requires a streaming-capable model.");
+    }
+    this.validatedStructuredOutput = void 0;
+    let currentRequest = args.request;
+    for (let attempt = 1; ; attempt += 1) {
+      const accumulator = new CompletionStreamAccumulator();
+      let hasProviderProgress = false;
+      let recordedErrorUsage = false;
+      let attemptErrorUsage;
+      try {
+        this.throwIfCancelled();
+        for await (const event of model.streamCompletion(currentRequest, this.modelCallOptions())) {
+          if (event.type === "error") {
+            const eventUsage = event.usage ?? completionProviderOutputErrorUsage(event.error);
+            if (eventUsage !== void 0) {
+              args.state.providerErrorUsage = Usage.add(args.state.providerErrorUsage, eventUsage);
+              recordedErrorUsage = true;
+              attemptErrorUsage = eventUsage;
+            }
+            throw event.error;
+          }
+          const mapped = accumulator.accept(event);
+          if (event.type === "final") break;
+          if (event.type === "tool_call_delta" || mapped !== void 0) {
+            hasProviderProgress = true;
+          }
+          if (args.state.firstDeltaMs === void 0 && isGenerationDeltaEvent(event.type)) {
+            args.state.firstDeltaMs = Date.now() - args.generationStartedAt;
+          }
+          if (event.type === "tool_call_delta") {
+            yield addTurnToToolCallDelta(args.turn, event);
+          }
+          if (mapped !== void 0) {
+            await args.generationObservers.update?.({ turn: args.turn, delta: mapped });
+            if (mapped.type === "tool_call") {
+              args.state.emittedToolCallIds.add(mapped.toolCall.toolCallId);
+            }
+            const shouldBuffer = args.bufferResponseEvents || args.bufferOutputDeltas && (mapped.type === "text_delta" || mapped.type === "reasoning_delta");
+            if (!shouldBuffer) {
+              yield addTurn(args.turn, mapped);
+            }
+          }
+        }
+        const response = accumulator.response();
+        assertCompletionResponseIntegrity({ response });
+        const cumulativeStructuredUsage = Usage.add(args.state.providerErrorUsage, response.usage);
+        try {
+          this.validateStructuredResponse(response, attempt, cumulativeStructuredUsage);
+        } catch (error) {
+          const retryOptions = this.retryOptionsForFailure(error, attempt, args.turn, true);
+          if (retryOptions === void 0) {
+            if (error instanceof AgentStructuredOutputError) {
+              args.state.providerErrorUsage = Usage.empty();
+            }
+            throw error;
+          }
+          args.state.providerErrorUsage = Usage.add(args.state.providerErrorUsage, response.usage);
+          args.state.firstDeltaMs = void 0;
+          args.state.emittedToolCallIds.clear();
+          const retryRequest = structuredOutputRetryRequest(args.request, response, error);
+          currentRequest = retryRequest.request;
+          await this.scheduleCompletionRetry(
+            error,
+            attempt,
+            args.turn,
+            true,
+            retryOptions,
+            args.runObservers,
+            structuredOutputRetryEventAttributes(error, retryRequest)
+          );
+          continue;
+        }
+        args.state.response = Usage.isEmpty(args.state.providerErrorUsage) ? response : { ...response, usage: cumulativeStructuredUsage };
+        args.state.providerErrorUsage = Usage.empty();
+        return;
+      } catch (error) {
+        if (!recordedErrorUsage) {
+          const attemptUsage = completionProviderOutputErrorUsage(error);
+          if (attemptUsage !== void 0) {
+            args.state.providerErrorUsage = Usage.add(args.state.providerErrorUsage, attemptUsage);
+            attemptErrorUsage = attemptUsage;
+          }
+        }
+        const retryOptions = hasProviderProgress ? void 0 : this.retryOptionsForFailure(error, attempt, args.turn, true);
+        if (retryOptions === void 0) {
+          throw error;
+        }
+        await this.scheduleCompletionRetry(
+          error,
+          attempt,
+          args.turn,
+          true,
+          retryOptions,
+          args.runObservers,
+          providerOutputRetryEventAttributes(
+            error,
+            args.state.providerErrorUsage,
+            attemptErrorUsage
+          )
+        );
+      }
+    }
+  }
+  async *completeStreamingRun(args) {
+    const guardedOutput = await this.runOutputGuardrailsForResponse(
+      args.runId,
+      args.usage,
+      args.response,
+      args.newMessages,
+      args.runObservers
+    );
+    for (const decision of guardedOutput.decisions) {
+      yield { type: "guardrail_decision", decision };
+    }
+    const response = guardedOutput.response;
+    const assistantMessage = this.generatedAssistantMessage(response, args.request);
+    args.newMessages[args.newMessages.length - 1] = assistantMessage;
+    await this.memoryRecorder.commitMessages(
+      args.runId,
+      args.turn,
+      [assistantMessage],
+      args.pendingTurnMessages
+    );
+    if (!args.emittedTurnEnd && (args.bufferResponseEvents || args.bufferOutputDeltas)) {
+      for (const event of responseStreamEvents(args.turn, response, args.bufferResponseEvents)) {
+        yield event;
+      }
+    }
+    if (!args.emittedTurnEnd) {
+      yield {
+        type: "turn_end",
+        turn: args.turn,
+        response,
+        firstDeltaMs: args.firstDeltaMs
+      };
+    }
+    const result = this.createTerminalResult(
+      args.runId,
+      guardedOutput.text,
+      guardedOutput.blocked,
+      args.usage,
+      args.newMessages,
+      args.runObservers
+    );
+    if (result.status === "completed") {
+      await this.runRunEndHook(result, args.newMessages);
+    }
+    await this.memoryRecorder.commitCompletedRun(
+      args.runId,
+      args.turn,
+      args.newMessages,
+      args.pendingTurnMessages
+    );
+    await this.runLifecycleFinish(result);
+    await args.runObservers.end(result);
+    this.runState = "completed";
+    this.disposeAbortLink();
+    yield { type: "final", result };
+  }
+  async finishSuspension(args) {
+    const partialToolMessage = args.suspension.completedResults.length === 0 ? void 0 : { role: "tool", content: [...args.suspension.completedResults] };
+    if (partialToolMessage !== void 0) {
+      args.newMessages.push(partialToolMessage);
+      args.uncommittedMessages.push(partialToolMessage);
+    }
+    await this.memoryRecorder.commitMessages(
+      args.runId,
+      args.turn,
+      args.uncommittedMessages,
+      args.pendingTurnMessages
+    );
+    await this.memoryRecorder.commitCompletedRun(
+      args.runId,
+      args.turn,
+      args.newMessages,
+      args.pendingTurnMessages
+    );
+    this.runState = "closing";
+    const continuationState = {
+      kind: "anvia.agent-continuation",
+      history: [...this.chatHistory],
+      messages: [...args.newMessages],
+      pending: args.suspension.pending,
+      remainingToolCalls: [...args.suspension.remainingToolCalls],
+      steering: this.steeringMessages.map((entry) => ({
+        id: entry.id,
+        messages: [...entry.messages]
+      }))
+    };
+    if (this.memoryScope !== void 0) continuationState.memoryScope = this.memoryScope;
+    const continuation = parseAgentContinuation({
+      version: 1,
+      agentId: this.agent.id,
+      sourceRunId: args.runId,
+      interaction: args.suspension.interaction,
+      state: serializeContinuationState(continuationState)
+    });
+    const result = {
+      status: "suspended",
+      runId: args.runId,
+      text: latestAssistantText([...this.chatHistory, ...args.newMessages]),
+      usage: args.usage,
+      messages: [...args.newMessages],
+      trace: args.runObservers.trace,
+      guardrails: [...this.guardrailDecisions],
+      interaction: continuation.interaction,
+      continuation,
+      ...generationArtifacts([...this.chatHistory, ...args.newMessages]),
+      ...this.memoryCompactionResult()
+    };
+    if (this.resumedFrom !== void 0) result.resumedFrom = this.resumedFrom;
+    await this.runLifecycleFinish(result);
+    await args.runObservers.end(result);
+    this.runState = "completed";
+    this.currentMessages = [...args.newMessages];
+    this.disposeAbortLink();
+    return result;
+  }
+  generatedAssistantMessage(response, _request) {
+    const generation = {
+      provider: this.agent.model.provider,
+      modelId: this.agent.model.modelId,
+      usage: { ...response.usage }
+    };
+    if (response.finishReason !== void 0) generation.finishReason = response.finishReason;
+    if (response.providerFinishReason !== void 0) {
+      generation.providerFinishReason = response.providerFinishReason;
+    }
+    if (response.contextUsage !== void 0) generation.contextUsage = response.contextUsage;
+    if (response.sources !== void 0) generation.sources = response.sources;
+    if (response.providerToolCalls !== void 0) {
+      generation.providerToolCalls = response.providerToolCalls;
+    }
+    const metadata = { anvia: { generation } };
+    let message = {
+      role: "assistant",
+      content: response.choice,
+      metadata
+    };
+    if (response.messageId !== void 0) message = { ...message, id: response.messageId };
+    return message;
+  }
+  providerTraceRequest(request, options = {}) {
+    try {
+      return this.agent.model.traceRequest?.(request, options);
+    } catch (error) {
+      return {
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  generationStartArgs(turn, request, providerRequest) {
+    let args = {
+      turn,
+      request,
+      modelInfo: {
+        provider: this.agent.model.provider,
+        modelId: this.agent.model.modelId,
+        capabilities: this.agent.model.capabilities
+      }
+    };
+    if (providerRequest !== void 0) args = { ...args, providerRequest };
+    return args;
+  }
+  retryOptionsForFailure(error, attempt, turn, streaming) {
+    if (this.abortController.signal.aborted) return void 0;
+    return retryOptionsForFailure(this.completionRetryOptions, {
+      error,
+      attempt,
+      turn,
+      streaming
+    });
+  }
+  async scheduleCompletionRetry(error, attempt, turn, streaming, options, runObservers, additionalAttributes) {
+    const delayMs = retryDelayMs(options, attempt);
+    const attributes = {
+      turn,
+      attempt,
+      nextAttempt: attempt + 1,
+      maxAttempts: options.maxAttempts,
+      delayMs,
+      streaming,
+      ...retryErrorAttributes(error)
+    };
+    if (additionalAttributes !== void 0) {
+      Object.assign(attributes, additionalAttributes);
+    }
+    await runObservers.event({
+      name: "completion.retry",
+      level: "WARNING",
+      attributes
+    });
+    await waitForRetry(delayMs, this.abortController.signal);
+  }
+  async executeToolCalls(runId, toolCalls, newMessages, onResult, onStreamEvent, observation) {
+    const executor = this.createToolExecutor(runId, newMessages);
+    return executor.execute(toolCalls, onResult, onStreamEvent, observation);
+  }
+  createToolExecutor(runId, newMessages) {
+    return new ToolCallExecutor(
+      this.agent,
+      this.activeHook,
+      async (request) => {
+        throw new AgentInteractionSignal(approvalInteraction(request), request.rejectMessage);
+      },
+      this.activeLifecycle,
+      {
+        runId,
+        sessionId: this.memoryScope?.sessionId,
+        metadata: this.memoryScope?.metadata
+      },
+      this.concurrency,
+      this.requestMiddlewares,
+      this.abortController.signal,
+      (reason) => this.cancelled(newMessages, reason)
+    );
+  }
+  async resolveContinuationTools(runId, newMessages, onResult, onStreamEvent, observation) {
+    const state = this.continuationState;
+    const response = this.interactionResponse;
+    if (state === void 0 || response === void 0) {
+      return [];
+    }
+    const pending = state.pending;
+    const interaction = this.resumedFrom;
+    if (interaction === void 0) {
+      throw new TypeError("Agent continuation is missing its source run linkage.");
+    }
+    const executor = this.createToolExecutor(runId, newMessages);
+    const results = [];
+    if (response.type === "tool-approval") {
+      const attributes = {
+        approvalId: interaction.interactionId,
+        toolName: pending.toolCall.toolName,
+        toolCallId: pending.toolCall.toolCallId,
+        internalCallId: pending.internalCallId,
+        approved: response.approved
+      };
+      if (response.reason !== void 0) attributes.decisionReason = response.reason;
+      await observation.runObservers.event({
+        name: "tool.approval_resolved",
+        attributes
+      });
+      if (response.approved) {
+        results.push(await executor.executeResumed(pending, onResult, onStreamEvent, observation));
+      } else {
+        const output = {
+          type: "execution-denied",
+          reason: response.reason ?? pending.rejectMessage ?? "Tool approval was rejected."
+        };
+        results.push(await executor.resolveResumed(pending, output, onResult, observation));
+      }
+    } else {
+      const currentTool = this.agent.getTool(pending.toolCall.toolName);
+      if (currentTool === void 0 || !isQuestionTool(currentTool)) {
+        throw new TypeError(
+          `Cannot resume question interaction because tool "${pending.toolCall.toolName}" is no longer registered as a question tool.`
+        );
+      }
+      const output = questionResult(response.answers);
+      results.push(await executor.resolveResumed(pending, output, onResult, observation));
+    }
+    try {
+      results.push(
+        ...await executor.execute(state.remainingToolCalls, onResult, onStreamEvent, observation)
+      );
+    } catch (error) {
+      if (error instanceof ToolExecutionSuspension) {
+        error.completedResults = [...results, ...error.completedResults];
+      }
+      throw error;
+    }
+    return results;
+  }
+  executeStreamingToolCalls(runId, toolCalls, newMessages, observation) {
+    const events = createAsyncQueue();
+    const results = this.executeToolCalls(
+      runId,
+      toolCalls,
+      newMessages,
+      (result) => events.enqueue(result),
+      (event) => events.enqueue(event),
+      observation
+    );
+    results.then(
+      () => events.close(),
+      (error) => events.throw(error)
+    );
+    return { events, results };
+  }
+  executeContinuationToolStream(runId, newMessages, observation) {
+    const events = createAsyncQueue();
+    const results = this.resolveContinuationTools(
+      runId,
+      newMessages,
+      (result) => events.enqueue(result),
+      (event) => events.enqueue(event),
+      observation
+    );
+    results.then(
+      () => events.close(),
+      (error) => events.throw(error)
+    );
+    return { events, results };
+  }
+  async closeActiveGeneration(error) {
+    const active = this.activeGeneration;
+    if (active === void 0) {
+      return;
+    }
+    this.activeGeneration = void 0;
+    await active.observers.error({ turn: active.turn, error });
+  }
+  updateRunProgress(messages) {
+    this.currentMessages = [...messages];
+  }
+  async runLifecycleFinish(result) {
+    const common = {
+      runId: result.runId,
+      text: result.text,
+      usage: lifecycleSnapshot(result.usage),
+      messages: lifecycleSnapshot(result.messages)
+    };
+    if (result.memoryCompaction !== void 0) {
+      Object.assign(common, { memoryCompaction: lifecycleSnapshot(result.memoryCompaction) });
+    }
+    const event = result.status === "completed" ? {
+      ...common,
+      status: "completed",
+      output: lifecycleSnapshot(result.output)
+    } : result.status === "blocked" ? {
+      ...common,
+      status: "blocked",
+      stage: result.stage
+    } : {
+      ...common,
+      status: "suspended",
+      interaction: lifecycleSnapshot(result.interaction)
+    };
+    await this.activeLifecycle?.onFinish?.(event);
+  }
+  async runLifecycleError(error, runId, usage, messages) {
+    try {
+      await this.activeLifecycle?.onError?.({
+        runId,
+        error: lifecycleSnapshot(error),
+        usage: lifecycleSnapshot(usage),
+        messages: lifecycleSnapshot([...this.chatHistory, ...messages])
+      });
+      return void 0;
+    } catch (lifecycleError) {
+      return lifecycleError;
+    }
+  }
+  async reportRunFailure(error, runId, usage, messages, runObservers) {
+    const reportedError = await this.resolveReportedRunError(error, runId, usage, messages);
+    await settleFailureCleanup([
+      () => this.onInternalFailure?.({
+        error: reportedError,
+        messages: lifecycleSnapshot(messages)
+      }),
+      () => runObservers?.error({
+        error: reportedError,
+        usage,
+        messages: [...messages]
+      }),
+      () => this.memoryRecorder.recordError(runId, reportedError, messages)
+    ]);
+    return reportedError;
+  }
+  async resolveReportedRunError(error, runId, usage, messages) {
+    try {
+      await this.runRunErrorHook(error, usage, messages);
+    } catch {
+    }
+    await this.runLifecycleError(error, runId, usage, messages);
+    return error;
+  }
+  async runOutputGuardrailsForResponse(runId, usage, response, messages, runObservers) {
+    const originalOutput = textFromAssistantContent(response.choice);
+    const result = await runOutputGuardrails(this.guardrailPolicies, {
+      outputText: originalOutput,
+      messages: [...this.chatHistory, ...messages],
+      usage,
+      run: this.guardrailRunContext(runId)
+    });
+    for (const decision of result.decisions) {
+      await this.recordGuardrailDecision(decision, runObservers);
+    }
+    const text = result.blocked ? result.message ?? "The response was blocked by a guardrail." : result.outputText;
+    if (text === originalOutput) {
+      return { text, blocked: result.blocked, response, decisions: result.decisions };
+    }
+    return {
+      text,
+      blocked: result.blocked,
+      response: {
+        ...response,
+        choice: [{ type: "text", text }]
+      },
+      decisions: result.decisions
+    };
+  }
+  createTerminalResult(runId, text, blocked, usage, messages, runObservers) {
+    const common = {
+      runId,
+      text,
+      usage,
+      messages: [...messages],
+      trace: runObservers.trace,
+      guardrails: [...this.guardrailDecisions],
+      ...generationArtifacts(messages),
+      ...this.memoryCompactionResult()
+    };
+    if (this.resumedFrom !== void 0) Object.assign(common, { resumedFrom: this.resumedFrom });
+    if (blocked) {
+      return { ...common, status: "blocked", stage: "output" };
+    }
+    return {
+      ...common,
+      status: "completed",
+      output: this.parseOutput(text)
+    };
+  }
+  validateStructuredResponse(response, attempt, usage) {
+    if (this.agent.outputSchema === void 0) return;
+    if (response.choice.some((item) => item.type === "tool-call")) return;
+    const text = textFromAssistantContent(response.choice);
+    const normalized = normalizeStructuredOutput(text);
+    if (response.finishReason === "content-filter") {
+      throw new AgentStructuredOutputError({
+        phase: "content-filter",
+        attempt,
+        maxAttempts: this.completionRetryOptions?.maxAttempts ?? 1,
+        outputLength: text.length,
+        normalizedLength: normalized.text.length,
+        outputFormat: normalized.format,
+        attemptUsage: response.usage,
+        usage,
+        finishReason: response.finishReason,
+        providerFinishReason: response.providerFinishReason
+      });
+    }
+    if (response.finishReason === "length") {
+      throw new AgentStructuredOutputError({
+        phase: "truncated",
+        attempt,
+        maxAttempts: this.completionRetryOptions?.maxAttempts ?? 1,
+        outputLength: text.length,
+        normalizedLength: normalized.text.length,
+        outputFormat: normalized.format,
+        attemptUsage: response.usage,
+        usage,
+        finishReason: response.finishReason,
+        providerFinishReason: response.providerFinishReason
+      });
+    }
+    const output = this.parseOutput(text, attempt, usage, {
+      useValidatedOutput: false,
+      attemptUsage: response.usage,
+      finishReason: response.finishReason,
+      providerFinishReason: response.providerFinishReason
+    });
+    this.validatedStructuredOutput = { text, output };
+  }
+  takeFailedCompletionUsage() {
+    const usage = this.failedCompletionUsage;
+    this.failedCompletionUsage = Usage.empty();
+    return usage;
+  }
+  parseOutput(text, attempt = 1, usage = Usage.empty(), options = {}) {
+    const schema = this.agent.outputSchema;
+    if (schema === void 0) return text;
+    if (options.useValidatedOutput !== false && this.validatedStructuredOutput?.text === text) {
+      return this.validatedStructuredOutput.output;
+    }
+    const normalized = normalizeStructuredOutput(text);
+    const maxAttempts = this.completionRetryOptions?.maxAttempts ?? 1;
+    let json;
+    try {
+      json = JSON.parse(normalized.text);
+      if (!isJsonValue(json)) {
+        throw new TypeError("Agent structured output is not a JSON value.");
+      }
+    } catch (error) {
+      throw new AgentStructuredOutputError({
+        phase: "parse",
+        attempt,
+        maxAttempts,
+        outputLength: text.length,
+        normalizedLength: normalized.text.length,
+        outputFormat: normalized.format,
+        attemptUsage: options.attemptUsage ?? usage,
+        usage,
+        finishReason: options.finishReason,
+        providerFinishReason: options.providerFinishReason,
+        cause: error
+      });
+    }
+    try {
+      return schema.parse(json);
+    } catch (error) {
+      throw new AgentStructuredOutputError({
+        phase: "schema",
+        attempt,
+        maxAttempts,
+        outputLength: text.length,
+        normalizedLength: normalized.text.length,
+        outputFormat: normalized.format,
+        attemptUsage: options.attemptUsage ?? usage,
+        usage,
+        finishReason: options.finishReason,
+        providerFinishReason: options.providerFinishReason,
+        cause: error
+      });
+    }
+  }
+  memoryCompactionResult() {
+    return this.memoryCompaction === void 0 ? {} : { memoryCompaction: lifecycleSnapshot(this.memoryCompaction) };
+  }
+  async recordGuardrailDecision(decision, runObservers) {
+    this.guardrailDecisions.push(decision);
+    await runObservers.event({
+      name: "guardrail.decision",
+      level: decision.action === "block" ? "WARNING" : "DEFAULT",
+      attributes: guardrailDecisionAttributes(decision)
+    });
+  }
+  async recordMemoryCompaction(preparation, runObservers) {
+    const compaction = preparation.compaction;
+    if (compaction === void 0) {
+      return;
+    }
+    await runObservers.event({
+      name: "memory.compaction",
+      attributes: {
+        originalMessageCount: compaction.originalMessageCount,
+        compactedMessageCount: compaction.compactedMessageCount,
+        retainedMessageCount: compaction.retainedMessageCount,
+        attempts: compaction.attempts,
+        inputTokens: compaction.usage.inputTokens,
+        outputTokens: compaction.usage.outputTokens,
+        totalTokens: compaction.usage.totalTokens
+      }
+    });
+  }
+  async notifyInternalMemoryCompaction(compaction) {
+    if (compaction === void 0) {
+      return;
+    }
+    await this.onInternalMemoryCompaction?.(lifecycleSnapshot(compaction));
+  }
+  guardrailRunContext(runId) {
+    const context = {
+      agentId: this.agent.id,
+      runId
+    };
+    if (this.memoryScope !== void 0) {
+      context.sessionId = this.memoryScope.sessionId;
+      if (this.memoryScope.metadata !== void 0) {
+        context.metadata = this.memoryScope.metadata;
+      }
+    }
+    return context;
+  }
+  async startRunObservers(runId) {
+    const observability = this.agent.observability;
+    return startAgentRunObservers(
+      observability?.observers ?? {},
+      {
+        runId,
+        agentName: this.agent.name,
+        agentDescription: this.agent.description,
+        instructions: this.agent.instructions,
+        trace: this.traceOptions,
+        promptRef: this.traceOptions?.promptRef,
+        prompt: this.promptMessage,
+        history: this.chatHistory,
+        maxTurns: this.maxTurnCount
+      },
+      {
+        primaryTrace: observability?.primaryTrace,
+        errorPolicy: observability?.errorPolicy ?? "ignore"
+      }
+    );
+  }
+  async runCompletionCallHook(prompt, history, newMessages) {
+    const action = await this.activeHook?.onCompletionCall?.({
+      prompt,
+      history,
+      run: runControl
+    });
+    if (action?.type === "terminate") {
+      throw this.cancelled(newMessages, action.reason);
+    }
+  }
+  async runRunStartHook(newMessages) {
+    const action = await this.activeHook?.onRunStart?.({
+      prompt: this.promptMessage,
+      history: this.chatHistory,
+      maxTurns: this.maxTurnCount,
+      run: runControl
+    });
+    if (action?.type === "terminate") {
+      throw this.cancelled(newMessages, action.reason);
+    }
+  }
+  async runRunEndHook(result, newMessages) {
+    const action = await this.activeHook?.onRunEnd?.({
+      status: "completed",
+      output: result.output,
+      text: result.text,
+      usage: result.usage,
+      messages: result.messages,
+      run: runControl
+    });
+    if (action?.type === "terminate") {
+      throw this.cancelled(newMessages, action.reason);
+    }
+  }
+  async runRunErrorHook(error, usage, newMessages) {
+    const action = await this.activeHook?.onRunError?.({
+      error,
+      usage,
+      messages: [...this.chatHistory, ...newMessages],
+      run: runControl
+    });
+    if (action?.type === "terminate") {
+      this.cancelled(newMessages, action.reason);
+    }
+  }
+  async runTurnStartHook(turn, prompt, history, newMessages) {
+    const action = await this.activeHook?.onTurnStart?.({
+      turn,
+      prompt,
+      history,
+      run: runControl
+    });
+    if (action?.type === "terminate") {
+      throw this.cancelled(newMessages, action.reason);
+    }
+  }
+  async runTurnEndHook(turn, response, newMessages) {
+    const action = await this.activeHook?.onTurnEnd?.({
+      turn,
+      response,
+      run: runControl
+    });
+    if (action?.type === "terminate") {
+      throw this.cancelled(newMessages, action.reason);
+    }
+  }
+  async runCompletionRequestMiddlewares(request, turn) {
+    let current = request;
+    for (const middleware of this.activeMiddlewares()) {
+      const replacement = await middleware.onCompletionRequest?.({
+        turn,
+        request: current,
+        originalRequest: request
+      });
+      if (replacement?.request !== void 0) {
+        current = replacement.request;
+        if (current.providerOptions !== void 0) {
+          assertJsonObject(current.providerOptions, "providerOptions");
+        }
+      }
+    }
+    return current;
+  }
+  async runCompletionResponseMiddlewares(request, response, turn) {
+    let current = response;
+    for (const middleware of this.activeMiddlewares()) {
+      const replacement = await middleware.onCompletionResponse?.({
+        turn,
+        request,
+        response: current,
+        originalResponse: response
+      });
+      if (replacement?.response !== void 0) {
+        current = replacement.response;
+      }
+    }
+    return current;
+  }
+  async runCompletionResponseHook(prompt, response, newMessages) {
+    const action = await this.activeHook?.onCompletionResponse?.({
+      prompt,
+      response,
+      run: runControl
+    });
+    if (action?.type === "terminate") {
+      throw this.cancelled(newMessages, action.reason);
+    }
+  }
+  async runCompletionErrorHook(prompt, error, newMessages) {
+    const action = await this.activeHook?.onCompletionError?.({
+      prompt,
+      error,
+      run: runControl
+    });
+    if (action?.type === "terminate") {
+      throw this.cancelled(newMessages, action.reason);
+    }
+  }
+  activeMiddlewares() {
+    return [...this.agent.middlewares, ...this.requestMiddlewares];
+  }
+  shouldBufferStreamResponseEvents() {
+    return this.activeHook?.onCompletionResponse !== void 0 || this.activeMiddlewares().some((middleware) => middleware.onCompletionResponse !== void 0);
+  }
+  async drainSteeringMessages(runId, turn, newMessages, pendingTurnMessages, options = {}) {
+    const receipts = this.steeringMessages.splice(0);
+    if (receipts.length === 0) {
+      if (options.closeWhenEmpty === true) {
+        this.runState = "closing";
+      }
+      return [];
+    }
+    const messages = receipts.flatMap((receipt) => receipt.messages);
+    newMessages.push(...messages);
+    await this.memoryRecorder.commitMessages(runId, turn, messages, pendingTurnMessages);
+    return receipts;
+  }
+  startRun() {
+    if (this.runState === "idle") {
+      this.runState = "running";
+      return;
+    }
+    if (this.runState === "running") {
+      throw new Error("Agent stream is already running.");
+    }
+    throw new Error("Agent stream has already been consumed.");
+  }
+  isTerminal() {
+    return this.runState !== "idle" && this.runState !== "running";
+  }
+  cancelled(newMessages, reason) {
+    if (this.cancellationError !== void 0) return this.cancellationError;
+    const error = new AgentRunCancelledError([...this.chatHistory, ...newMessages], reason);
+    this.setCancellationError(error);
+    return error;
+  }
+  linkExternalAbortSignal(signal) {
+    if (signal === void 0) return;
+    const cancelFromSignal = () => {
+      if (this.cancellationError !== void 0 || this.isTerminal()) return;
+      const cause = abortError(signal.reason);
+      const reason = abortReason(signal.reason);
+      const messages = this.currentMessages.length === 0 ? [this.promptMessage] : [...this.currentMessages];
+      this.setCancellationError(
+        new AgentRunCancelledError([...this.chatHistory, ...messages], reason, { cause })
+      );
+    };
+    if (signal.aborted) {
+      cancelFromSignal();
+      return;
+    }
+    signal.addEventListener("abort", cancelFromSignal, { once: true });
+    this.removeExternalAbortListener = () => signal.removeEventListener("abort", cancelFromSignal);
+  }
+  throwIfCancelled() {
+    if (this.cancellationError !== void 0) throw this.cancellationError;
+    throwIfAborted(this.abortController.signal);
+  }
+  normalizeRunError(error) {
+    return this.abortController.signal.aborted && this.cancellationError !== void 0 ? this.cancellationError : error;
+  }
+  modelCallOptions() {
+    return { abortSignal: this.abortController.signal };
+  }
+  disposeAbortLink() {
+    this.removeExternalAbortListener?.();
+    this.removeExternalAbortListener = void 0;
+  }
+};
+function abortReason(reason) {
+  if (typeof reason === "string" && reason.trim().length > 0) return reason;
+  if (reason instanceof Error && reason.message.trim().length > 0) return reason.message;
+  return "External abort signal.";
+}
+function normalizeAgentInput(agentId, input) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new TypeError("Agent runs require one options object with prompt or messages.");
+  }
+  const hasContinuation = "continuation" in input && input.continuation !== void 0;
+  const hasPrompt = "prompt" in input && input.prompt !== void 0;
+  const hasMessages = "messages" in input && input.messages !== void 0;
+  if (Number(hasContinuation) + Number(hasPrompt) + Number(hasMessages) !== 1) {
+    throw new TypeError("Agent runs require exactly one of prompt, messages, or continuation.");
+  }
+  if (hasContinuation) {
+    if (!("response" in input) || input.response === void 0) {
+      throw new TypeError("Agent continuation runs require an interaction response.");
+    }
+    if ("session" in input && input.session !== void 0) {
+      throw new TypeError("Agent continuations carry their memory scope and cannot use session.");
+    }
+    const continuation = parseAgentContinuation(input.continuation);
+    if (continuation.agentId !== agentId) {
+      throw new TypeError(
+        `Agent continuation belongs to "${continuation.agentId}", not "${agentId}".`
+      );
+    }
+    const response = parseAgentInteractionResponse(input.response);
+    assertAgentInteractionResponse(continuation.interaction, response);
+    const state = parseContinuationState(continuation.state, continuation.interaction);
+    let responsePart;
+    if (response.type === "tool-approval") {
+      responsePart = {
+        type: "tool-approval-response",
+        interactionId: continuation.interaction.id,
+        toolCallId: continuation.interaction.toolCallId,
+        toolName: continuation.interaction.toolName,
+        approved: response.approved
+      };
+      if (response.reason !== void 0)
+        responsePart = { ...responsePart, reason: response.reason };
+    } else {
+      responsePart = {
+        type: "tool-question-response",
+        interactionId: continuation.interaction.id,
+        toolCallId: continuation.interaction.toolCallId,
+        toolName: continuation.interaction.toolName,
+        answers: response.answers
+      };
+    }
+    if (continuation.interaction.callId !== void 0) {
+      responsePart = { ...responsePart, callId: continuation.interaction.callId };
+    }
+    const normalized = {
+      prompt: parseMessage({ role: "tool", content: [responsePart] }),
+      history: [...state.history, ...state.messages],
+      continuationState: state,
+      interactionResponse: response,
+      sourceRunId: continuation.sourceRunId,
+      interactionId: continuation.interaction.id
+    };
+    if (state.memoryScope !== void 0) {
+      Object.assign(normalized, { scope: normalizeMemoryScope(state.memoryScope) });
+    }
+    return normalized;
+  }
+  if (hasPrompt) {
+    const prompt = input.prompt;
+    if (typeof prompt !== "string" && (typeof prompt !== "object" || prompt === null || prompt.role !== "user")) {
+      throw new TypeError("Agent prompt must be text or a user message.");
+    }
+    const parsedPrompt = parseMessage(
+      typeof prompt === "string" ? { role: "user", content: prompt } : prompt
+    );
+    if (parsedPrompt.role !== "user") {
+      throw new TypeError("Agent prompt must be text or a user message.");
+    }
+    const normalized = {
+      prompt: parsedPrompt,
+      history: []
+    };
+    if (input.session !== void 0) {
+      Object.assign(normalized, { scope: normalizeMemoryScope(input.session) });
+    }
+    return normalized;
+  }
+  if (input.session !== void 0) {
+    throw new TypeError("Agent messages cannot be combined with a persisted session.");
+  }
+  const messages = input.messages;
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw new TypeError("Agent input transcript must contain at least one message.");
+  }
+  const parsedMessages = parseMessages(messages);
+  const activePrompt = parsedMessages.at(-1);
+  if (activePrompt === void 0) {
+    throw new TypeError("Agent input transcript must contain at least one message.");
+  }
+  if (activePrompt.role !== "user") {
+    throw new TypeError("Agent input transcript must end with a user message.");
+  }
+  return {
+    prompt: activePrompt,
+    history: parsedMessages.slice(0, -1)
+  };
+}
+function normalizeSteeringInput(input) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new TypeError("Agent steering requires one options object with prompt or messages.");
+  }
+  const hasPrompt = "prompt" in input && input.prompt !== void 0;
+  const hasMessages = "messages" in input && input.messages !== void 0;
+  if (hasPrompt === hasMessages) {
+    throw new TypeError("Agent steering requires exactly one of prompt or messages.");
+  }
+  if (hasPrompt) {
+    const prompt = input.prompt;
+    if (typeof prompt !== "string" && (typeof prompt !== "object" || prompt === null || prompt.role !== "user")) {
+      throw new TypeError("Agent steering prompt must be text or a user message.");
+    }
+    const parsedPrompt = parseMessage(
+      typeof prompt === "string" ? { role: "user", content: prompt } : prompt
+    );
+    if (parsedPrompt.role !== "user") {
+      throw new TypeError("Agent steering prompt must be text or a user message.");
+    }
+    return [parsedPrompt];
+  }
+  const messages = input.messages;
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw new TypeError("Agent steering messages must contain at least one user message.");
+  }
+  const parsedMessages = parseMessages(messages);
+  if (parsedMessages.some((message) => message.role !== "user")) {
+    throw new TypeError("Agent steering messages must all be user messages.");
+  }
+  return parsedMessages;
+}
+function normalizeMemoryScope(scope) {
+  if (typeof scope !== "object" || scope === null) {
+    throw new TypeError("Agent session must be an object.");
+  }
+  if (typeof scope.sessionId !== "string" || scope.sessionId.trim().length === 0) {
+    throw new TypeError("Agent sessionId must be a non-empty string.");
+  }
+  const normalized = {
+    sessionId: scope.sessionId.trim()
+  };
+  if (scope.userId !== void 0) normalized.userId = scope.userId;
+  if (scope.metadata !== void 0) normalized.metadata = scope.metadata;
+  return lifecycleSnapshot(normalized);
+}
+function normalizeRequestedRunId(runId) {
+  if (runId === void 0) {
+    return void 0;
+  }
+  if (typeof runId !== "string" || runId.trim().length === 0) {
+    throw new TypeError("runId must be a non-empty string.");
+  }
+  return runId;
+}
+function responseStreamEvents(turn, response, includeProviderArtifacts = true) {
+  const events = [];
+  for (const item of response.choice) {
+    if (item.type === "text") {
+      if (item.text.length > 0) {
+        events.push({ type: "text_delta", turn, delta: item.text });
+      }
+      continue;
+    }
+    if (item.type === "reasoning") {
+      if (item.details === void 0) {
+        if (item.text.length > 0) {
+          events.push(reasoningDeltaEvent(turn, item.text, { id: item.id }));
+        }
+        continue;
+      }
+      for (const content of item.details) {
+        const delta = content.type === "encrypted" || content.type === "redacted" ? content.data : content.text;
+        events.push(
+          reasoningDeltaEvent(turn, delta, {
+            id: item.id,
+            contentType: content.type,
+            signature: content.type === "text" ? content.signature : void 0
+          })
+        );
+      }
+      continue;
+    }
+    if (item.type === "tool-call") {
+      events.push({ type: "tool_call", turn, toolCall: item });
+    }
+  }
+  if (includeProviderArtifacts) {
+    for (const source of response.sources ?? []) {
+      events.push({ type: "source", turn, source });
+    }
+    for (const toolCall of response.providerToolCalls ?? []) {
+      events.push({ type: "provider_tool_call", turn, toolCall });
+    }
+  }
+  return events;
+}
+function generationArtifacts(messages) {
+  const sources = /* @__PURE__ */ new Map();
+  const providerToolCalls = /* @__PURE__ */ new Map();
+  let finishReason;
+  let providerFinishReason;
+  let contextUsage;
+  for (const message of messages) {
+    const metadata = getAssistantGenerationMetadata(message);
+    if (metadata !== void 0) {
+      finishReason = metadata.finishReason;
+      providerFinishReason = metadata.providerFinishReason;
+      contextUsage = metadata.contextUsage;
+    }
+    for (const source of metadata?.sources ?? []) {
+      const key = `${source.url}\0${source.startIndex ?? ""}\0${source.endIndex ?? ""}`;
+      sources.set(key, source);
+    }
+    for (const toolCall of metadata?.providerToolCalls ?? []) {
+      providerToolCalls.set(toolCall.id, toolCall);
+    }
+  }
+  const artifacts = {};
+  if (sources.size > 0) artifacts.sources = [...sources.values()];
+  if (providerToolCalls.size > 0) {
+    artifacts.providerToolCalls = [...providerToolCalls.values()];
+  }
+  if (finishReason !== void 0) artifacts.finishReason = finishReason;
+  if (providerFinishReason !== void 0) {
+    artifacts.providerFinishReason = providerFinishReason;
+  }
+  if (contextUsage !== void 0) artifacts.contextUsage = contextUsage;
+  return artifacts;
+}
+function reasoningDeltaEvent(turn, delta, details = {}) {
+  const event = {
+    type: "reasoning_delta",
+    turn,
+    delta
+  };
+  if (details.id !== void 0) {
+    event.id = details.id;
+  }
+  if (details.contentType !== void 0) {
+    event.contentType = details.contentType;
+  }
+  if (details.signature !== void 0) {
+    event.signature = details.signature;
+  }
+  return event;
+}
+function textFromMessage(message) {
+  if (message.role === "system") {
+    return message.content;
+  }
+  if (typeof message.content === "string") {
+    return message.content;
+  }
+  return message.content.flatMap((content) => {
+    if (content.type === "text") {
+      return [content.text];
+    }
+    if (content.type === "file" && content.data.type === "text") {
+      return [content.data.text];
+    }
+    return [];
+  }).join("\n");
+}
+function latestAssistantText(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message?.role === "assistant") {
+      return typeof message.content === "string" ? message.content : textFromAssistantContent(message.content);
+    }
+  }
+  return "";
+}
+function structuredOutputRetryRequest(request, response, error) {
+  const truncated = error instanceof AgentStructuredOutputError && error.phase === "truncated";
+  const correction = {
+    role: "user",
+    content: truncated ? STRUCTURED_OUTPUT_TRUNCATED_RETRY_PROMPT : STRUCTURED_OUTPUT_RETRY_PROMPT
+  };
+  if (truncated) {
+    return {
+      request: {
+        ...request,
+        chatHistory: [...request.chatHistory, correction]
+      },
+      previousResponse: "omitted",
+      includedOutputLength: 0
+    };
+  }
+  const preview = structuredOutputRepairPreview(textFromAssistantContent(response.choice));
+  if (preview.includedOutputLength === 0) {
+    return {
+      request: {
+        ...request,
+        chatHistory: [...request.chatHistory, correction]
+      },
+      previousResponse: "omitted",
+      includedOutputLength: 0
+    };
+  }
+  const invalidResponse = {
+    role: "assistant",
+    content: [{ type: "text", text: preview.text }]
+  };
+  return {
+    request: {
+      ...request,
+      chatHistory: [...request.chatHistory, invalidResponse, correction]
+    },
+    previousResponse: "preview",
+    includedOutputLength: preview.includedOutputLength
+  };
+}
+function structuredOutputRetryEventAttributes(error, retryRequest) {
+  const attributes = {
+    previousResponse: retryRequest.previousResponse,
+    includedOutputLength: retryRequest.includedOutputLength
+  };
+  if (!(error instanceof AgentStructuredOutputError)) return attributes;
+  Object.assign(attributes, {
+    failurePhase: error.phase,
+    outputLength: error.outputLength,
+    normalizedLength: error.normalizedLength,
+    attemptUsage: usageEventValue(error.attemptUsage),
+    cumulativeUsage: usageEventValue(error.usage)
+  });
+  if (error.finishReason !== void 0) attributes.finishReason = error.finishReason;
+  if (error.providerFinishReason !== void 0) {
+    attributes.providerFinishReason = error.providerFinishReason;
+  }
+  return attributes;
+}
+function providerOutputRetryEventAttributes(error, cumulativeUsage, attemptUsage) {
+  const resolvedAttemptUsage = attemptUsage ?? completionProviderOutputErrorUsage(error);
+  if (resolvedAttemptUsage === void 0) return void 0;
+  return {
+    attemptUsage: usageEventValue(resolvedAttemptUsage),
+    cumulativeUsage: usageEventValue(cumulativeUsage)
+  };
+}
+function usageEventValue(usage) {
+  const value = {
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    totalTokens: usage.totalTokens,
+    cachedInputTokens: usage.cachedInputTokens,
+    cacheCreationInputTokens: usage.cacheCreationInputTokens
+  };
+  if (usage.details !== void 0) value.details = { ...usage.details };
+  return value;
+}
+function providerMessages(messages) {
+  const providerMessages2 = [];
+  for (const message of messages) {
+    if (message.role !== "tool") {
+      providerMessages2.push(message);
+      continue;
+    }
+    const results = message.content.filter((part) => part.type === "tool-result");
+    if (results.length > 0) {
+      providerMessages2.push({ ...message, content: results });
+    }
+  }
+  return providerMessages2;
+}
+function guardrailDecisionAttributes(decision) {
+  const attributes = {
+    policyId: decision.policyId,
+    guardrailId: decision.guardrailId,
+    boundary: decision.boundary,
+    mode: decision.mode,
+    action: decision.action,
+    applied: decision.applied,
+    latencyMs: decision.latencyMs
+  };
+  if (decision.reason !== void 0) {
+    attributes.reason = decision.reason;
+  }
+  if (decision.message !== void 0) {
+    attributes.message = decision.message;
+  }
+  return attributes;
+}
+
+// src/agent/agent-stream.ts
+function createAgentStream(run) {
+  return new DefaultAgentStream(run);
+}
+var DefaultAgentStream = class {
+  constructor(run) {
+    this.run = run;
+  }
+  run;
+  consuming = false;
+  completed = false;
+  steer(input) {
+    return this.run.steer(input);
+  }
+  [Symbol.asyncIterator]() {
+    return this.consume()[Symbol.asyncIterator]();
+  }
+  async *consume() {
+    if (this.completed) {
+      throw new Error("Agent stream has already been consumed.");
+    }
+    if (this.consuming) {
+      throw new Error("Agent stream is already running.");
+    }
+    this.consuming = true;
+    try {
+      for await (const event of this.run.events()) {
+        yield event;
+      }
+    } finally {
+      if (!this.completed) {
+        this.run.cancel("Agent stream consumer closed the stream.");
+      }
+      this.consuming = false;
+      this.completed = true;
+    }
+  }
+};
+
+// src/agent/agent-tool.ts
+import { z } from "zod";
+function createAgentTool(agent, options) {
+  if (options.suspension !== "reject") {
+    throw new TypeError('Agent.asTool() requires suspension: "reject".');
+  }
+  const description = options.description ?? agent.description ?? `Prompt the ${options.name} agent.`;
+  return createTool({
+    name: options.name,
+    description,
+    inputSchema: z.object({
+      prompt: z.string().describe("The prompt to send to the agent.")
+    }),
+    execute: async ({ prompt }, context) => {
+      if (options.stream === true && context.emitStreamEvent !== void 0 && agent.model.capabilities.streaming && isStreamingCompletionModel(agent.model)) {
+        let completed = false;
+        let output;
+        const childStream = agent.stream({
+          prompt,
+          maxTurns: options.maxTurns,
+          abortSignal: context.abortSignal
+        });
+        for await (const event of childStream) {
+          const streamEvent = {
+            agentId: agent.id,
+            event
+          };
+          if (agent.name !== void 0) {
+            streamEvent.agentName = agent.name;
+          }
+          await context.emitStreamEvent(streamEvent);
+          if (event.type === "error") {
+            throw event.error;
+          }
+          if (event.type === "final") {
+            if (event.result.status === "suspended") {
+              throw new AgentToolSuspensionError(event.result);
+            }
+            if (event.result.status === "blocked") {
+              throw new AgentRunBlockedError(event.result);
+            }
+            output = event.result.output;
+            completed = true;
+          }
+        }
+        if (!completed) {
+          throw new Error(`Agent tool "${options.name}" ended without a final result.`);
+        }
+        return output;
+      }
+      const response = await agent.generate({
+        prompt,
+        maxTurns: options.maxTurns,
+        abortSignal: context.abortSignal
+      });
+      if (response.status === "suspended") {
+        throw new AgentToolSuspensionError(response);
+      }
+      if (response.status === "blocked") {
+        throw new AgentRunBlockedError(response);
+      }
+      return response.output;
+    }
+  });
+}
+
+// src/agent/ids.ts
+function normalizeAgentId(id) {
+  if (typeof id !== "string") {
+    throw new TypeError("Agent id must be a string.");
+  }
+  const normalized = id.trim();
+  if (normalized.length === 0) {
+    throw new TypeError("Agent id must be a non-empty string.");
+  }
+  return normalized;
+}
+
+// src/memory/options.ts
+function resolveMemoryOptions(options = {}) {
+  const resolved = {
+    savePolicy: options.savePolicy ?? "message"
+  };
+  if (options.compaction !== void 0) {
+    assertPositiveInteger(
+      options.compaction.trigger.afterMessages,
+      "compaction.trigger.afterMessages"
+    );
+    const recentUserTurns = options.compaction.retention?.recentUserTurns ?? 4;
+    assertPositiveInteger(recentUserTurns, "compaction.retention.recentUserTurns");
+    if (typeof options.compaction.compactor !== "function") {
+      throw new TypeError("compaction.compactor must be a function.");
+    }
+    const conflictRetries = options.compaction.conflictRetries ?? false;
+    if (conflictRetries !== false) {
+      assertPositiveInteger(conflictRetries.maxAttempts, "compaction.conflictRetries.maxAttempts");
+    }
+    resolved.compaction = {
+      trigger: {
+        afterMessages: options.compaction.trigger.afterMessages
+      },
+      retention: {
+        recentUserTurns
+      },
+      compactor: options.compaction.compactor,
+      conflictRetries
+    };
+  }
+  return resolved;
+}
+
+// src/agent/resolve-options.ts
+var resolvedAgentOptions = /* @__PURE__ */ Symbol("resolvedAgentOptions");
+function resolveAgentOptions(options) {
+  if (isInternalAgentOptions(options)) {
+    return options;
+  }
+  const toolsByName = /* @__PURE__ */ new Map();
+  const providerTools = [];
+  const toolIndexes = [];
+  for (const tool of options.tools ?? []) {
+    if (isProviderTool(tool)) {
+      providerTools.push(tool);
+    } else if (isToolIndex(tool)) {
+      toolIndexes.push(tool);
+    } else if (tool.kind === "tool-index") {
+      throw new TypeError("Invalid tool index: search, tools, and a numeric topK are required.");
+    } else if (isMcpTool(tool)) {
+      throw new TypeError(
+        `MCP tool "${tool.name}" must be registered through Agent.mcpServers, not Agent.tools.`
+      );
+    } else {
+      addUniqueTool(toolsByName, tool, "local tool");
+    }
+  }
+  if (options.skills !== void 0) {
+    for (const tool of options.skills.tools) {
+      if (isMcpTool(tool)) {
+        throw new TypeError(
+          `MCP tool "${tool.name}" must be registered through Agent.mcpServers, not Agent.skills.`
+        );
+      }
+      addUniqueTool(toolsByName, tool, "skill tool");
+    }
+  }
+  const memory = resolveAgentMemory(options);
+  const instructions = [options.instructions, options.skills?.instructions].filter((part) => part !== void 0 && part.length > 0).join("\n\n");
+  return {
+    id: options.id,
+    name: options.name,
+    description: options.description,
+    model: options.model,
+    instructions: instructions.length === 0 ? void 0 : instructions,
+    context: [...options.context ?? []],
+    temperature: options.temperature,
+    maxTokens: options.maxTokens,
+    providerOptions: options.providerOptions,
+    retries: options.retries,
+    tools: [...toolsByName.values()],
+    mcpServers: [...options.mcpServers ?? []],
+    providerTools,
+    toolIndexes,
+    toolChoice: options.toolChoice,
+    defaultMaxTurns: options.maxTurns,
+    lifecycle: options.lifecycle,
+    outputSchema: options.outputSchema,
+    observability: options.observability,
+    guardrails: options.guardrails === void 0 ? [] : appendGuardrailPolicies([], options.guardrails),
+    middlewares: [...options.middlewares ?? []],
+    memory
+  };
+}
+function markResolvedAgentOptions(options) {
+  return {
+    ...options,
+    [resolvedAgentOptions]: true
+  };
+}
+function isInternalAgentOptions(options) {
+  return options[resolvedAgentOptions] === true;
+}
+function resolveAgentMemory(options) {
+  if (options.memory === void 0) {
+    return void 0;
+  }
+  const { store, ...memoryOptions } = options.memory;
+  const resolvedOptions = resolveMemoryOptions(memoryOptions);
+  if (resolvedOptions.compaction !== void 0 && store.compaction === void 0) {
+    throw new TypeError(
+      "Memory compaction requires a store with the optional compaction capability."
+    );
+  }
+  return { store, ...resolvedOptions };
+}
+function addUniqueTool(tools, tool, source) {
+  if (tools.has(tool.name)) {
+    throw new TypeError(`Duplicate ${source} name "${tool.name}".`);
+  }
+  tools.set(tool.name, tool);
+}
+
+// src/agent/snapshot.ts
+function snapshotAgentContext(inputs) {
+  const context = (inputs ?? []).map(snapshotContextInput);
+  for (const input of context) {
+    if (!isVectorContext(input)) continue;
+    assertPositiveSearchLimit(input.topK);
+    assertFiniteMinScore(input.minScore);
+  }
+  return Object.freeze(context);
+}
+function snapshotAgentObservability(observability) {
+  if (observability === void 0) return void 0;
+  const observers = {};
+  for (const [name, observer] of Object.entries(observability.observers)) {
+    if (name.trim().length === 0) {
+      throw new TypeError("Agent observer names must not be empty.");
+    }
+    if (typeof observer !== "object" || observer === null || typeof observer.startRun !== "function") {
+      throw new TypeError(`Agent observer "${name}" must implement startRun().`);
+    }
+    observers[name] = observer;
+  }
+  if (observability.primaryTrace !== void 0 && !(observability.primaryTrace in observers)) {
+    throw new TypeError(
+      `Agent primaryTrace "${observability.primaryTrace}" must name a configured observer.`
+    );
+  }
+  const errorPolicy = observability.errorPolicy ?? "ignore";
+  if (errorPolicy !== "ignore" && errorPolicy !== "throw") {
+    throw new TypeError('Agent observability.errorPolicy must be "ignore" or "throw".');
+  }
+  let snapshot = {
+    observers: Object.freeze(observers),
+    errorPolicy
+  };
+  if (observability.primaryTrace !== void 0) {
+    snapshot = { ...snapshot, primaryTrace: observability.primaryTrace };
+  }
+  return Object.freeze(snapshot);
+}
+function snapshotGuardrailPolicies(policies) {
+  return Object.freeze((policies ?? []).map(snapshotGuardrailPolicy));
+}
+function snapshotAgentMemory(memory) {
+  if (memory === void 0) {
+    return void 0;
+  }
+  const compaction = memory.compaction === void 0 ? void 0 : Object.freeze({
+    ...memory.compaction,
+    trigger: Object.freeze({ ...memory.compaction.trigger }),
+    retention: Object.freeze({ ...memory.compaction.retention }),
+    conflictRetries: memory.compaction.conflictRetries === false ? false : Object.freeze({ ...memory.compaction.conflictRetries })
+  });
+  let snapshot = {
+    store: memory.store,
+    savePolicy: memory.savePolicy
+  };
+  if (compaction !== void 0) {
+    snapshot = { ...snapshot, compaction };
+  }
+  return Object.freeze(snapshot);
+}
+function cloneFrozenPlainData(value) {
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map(cloneFrozenPlainData));
+  }
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return value;
+  }
+  const clone = Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [key, cloneFrozenPlainData(item)])
+  );
+  return Object.freeze(clone);
+}
+function snapshotContextInput(input) {
+  if (!isVectorContext(input)) {
+    let document = {
+      id: input.id,
+      text: input.text
+    };
+    if (input.additionalProps !== void 0) {
+      document = {
+        ...document,
+        additionalProps: cloneFrozenPlainData(input.additionalProps)
+      };
+    }
+    return Object.freeze(document);
+  }
+  const format = input.format;
+  let shared = {
+    kind: "vector-context",
+    store: input.store,
+    topK: input.topK
+  };
+  if (input.minScore !== void 0) {
+    shared = { ...shared, minScore: input.minScore };
+  }
+  if (input.filter !== void 0) {
+    shared = { ...shared, filter: cloneFrozenPlainData(input.filter) };
+  }
+  if (input.retries !== void 0) {
+    shared = { ...shared, retries: cloneFrozenPlainData(input.retries) };
+  }
+  if (format !== void 0) {
+    shared = {
+      ...shared,
+      format: (result) => format.call(input, result)
+    };
+  }
+  if (!("models" in input) || input.models === void 0) {
+    return Object.freeze({ ...shared, store: input.store, model: input.model });
+  }
+  let context = {
+    ...shared,
+    store: input.store,
+    models: input.models
+  };
+  if (input.fusion !== void 0) {
+    context = { ...context, fusion: input.fusion };
+  }
+  return Object.freeze(context);
+}
+function snapshotGuardrailPolicy(policy) {
+  return Object.freeze({
+    ...policy,
+    input: Object.freeze([...policy.input]),
+    output: Object.freeze([...policy.output])
+  });
+}
+
+// src/agent/tool-catalog.ts
+function prepareAgentTools(options) {
+  assertUniqueMcpServerNames(options.mcpServers ?? []);
+  const mcpServers = Object.freeze((options.mcpServers ?? []).map(snapshotMcpServer));
+  const configuredTools = [...options.tools ?? []];
+  const staticTools = [...configuredTools, ...mcpServers.flatMap((server) => server.tools)];
+  const toolIndexes = (options.toolIndexes ?? []).map(snapshotToolIndex);
+  const providerTools = (options.providerTools ?? []).map(snapshotProviderTool);
+  assertUniqueAgentToolNames({ staticTools, providerTools, toolIndexes });
+  const toolsByName = new Map(staticTools.map((tool) => [tool.name, tool]));
+  for (const index of toolIndexes) {
+    for (const tool of index.tools) {
+      toolsByName.set(tool.name, tool);
+    }
+  }
+  const tools = Object.freeze([...toolsByName.values()]);
+  const publicState = Object.freeze({
+    configuredTools: Object.freeze(configuredTools),
+    staticTools: Object.freeze(staticTools),
+    providerTools: Object.freeze(providerTools),
+    toolIndexes: Object.freeze(toolIndexes)
+  });
+  return { mcpServers, tools, publicState, toolsByName };
+}
+function assertUniqueAgentToolNames(options) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const tool of options.staticTools) {
+    registerToolOwner(owners, tool.name, isMcpTool(tool) ? "MCP tool" : "local or skill tool");
+  }
+  for (const tool of options.providerTools) {
+    registerToolOwner(owners, tool.name, "provider tool");
+  }
+  for (const [indexPosition, index] of options.toolIndexes.entries()) {
+    if (!isToolIndex(index)) {
+      throw new TypeError("Invalid tool index: search, tools, and a numeric topK are required.");
+    }
+    assertPositiveSearchLimit(index.topK);
+    assertFiniteMinScore(index.minScore);
+    for (const tool of index.tools) {
+      if (isMcpTool(tool)) {
+        throw new TypeError(
+          `MCP tool "${tool.name}" must be registered through Agent.mcpServers, not a tool index.`
+        );
+      }
+      registerToolOwner(owners, tool.name, `tool index ${indexPosition + 1}`);
+    }
+  }
+}
+function registerToolOwner(owners, name, owner) {
+  const existing = owners.get(name);
+  if (existing !== void 0) {
+    throw new TypeError(
+      `Tool name collision for "${name}" between ${existing} and ${owner}. Tool names must be unique across every Agent tool source.`
+    );
+  }
+  owners.set(name, owner);
+}
+function snapshotProviderTool(tool) {
+  let snapshot = {
+    ...tool
+  };
+  if (tool.configuration !== void 0) {
+    snapshot = { ...snapshot, configuration: cloneFrozenPlainData(tool.configuration) };
+  }
+  return Object.freeze(snapshot);
+}
+function snapshotMcpServer(server) {
+  if (server.name.trim() === "") {
+    throw new TypeError("MCP server name must not be empty.");
+  }
+  for (const tool of server.tools) {
+    if (!isMcpTool(tool)) {
+      throw new TypeError(`MCP server "${server.name}" contains an invalid MCP tool.`);
+    }
+    if (tool.mcp.serverName !== server.name) {
+      throw new TypeError(
+        `MCP tool "${tool.name}" belongs to server "${tool.mcp.serverName}", not "${server.name}".`
+      );
+    }
+  }
+  const tools = server.tools.map(snapshotMcpTool);
+  let snapshot = {
+    name: server.name,
+    tools: Object.freeze(tools)
+  };
+  if (server.serverInfo !== void 0) {
+    snapshot = { ...snapshot, serverInfo: cloneFrozenPlainData(server.serverInfo) };
+  }
+  if (server.capabilities !== void 0) {
+    snapshot = { ...snapshot, capabilities: cloneFrozenPlainData(server.capabilities) };
+  }
+  if (server.instructions !== void 0) {
+    snapshot = { ...snapshot, instructions: server.instructions };
+  }
+  return Object.freeze(snapshot);
+}
+function snapshotMcpTool(tool) {
+  if (Object.isFrozen(tool) && Object.isFrozen(tool.mcp)) {
+    return tool;
+  }
+  const parseInput = tool.parseInput;
+  let snapshot = {
+    name: tool.name,
+    mcp: Object.freeze({ ...tool.mcp }),
+    definition: (prompt) => tool.definition(prompt),
+    call: (args, context) => tool.call(args, context)
+  };
+  if (tool.requiresApproval !== void 0) {
+    snapshot = { ...snapshot, requiresApproval: tool.requiresApproval };
+  }
+  if (parseInput !== void 0) {
+    snapshot = {
+      ...snapshot,
+      parseInput: (args) => parseInput.call(tool, args)
+    };
+  }
+  return Object.freeze(snapshot);
+}
+function assertUniqueMcpServerNames(servers) {
+  const names = /* @__PURE__ */ new Set();
+  for (const server of servers) {
+    if (names.has(server.name)) {
+      throw new TypeError(`Duplicate MCP server name "${server.name}".`);
+    }
+    names.add(server.name);
+  }
+}
+function snapshotToolIndex(index) {
+  const inspect = index.inspect;
+  let snapshot = {
+    kind: "tool-index",
+    tools: Object.freeze([...index.tools]),
+    topK: index.topK,
+    search: (options) => index.search(options)
+  };
+  if (index.minScore !== void 0) {
+    snapshot = { ...snapshot, minScore: index.minScore };
+  }
+  if (index.filter !== void 0) {
+    snapshot = { ...snapshot, filter: cloneFrozenPlainData(index.filter) };
+  }
+  if (inspect !== void 0) {
+    snapshot = {
+      ...snapshot,
+      inspect: (request) => inspect.call(index, request)
+    };
+  }
+  return Object.freeze(snapshot);
+}
+
+// src/agent/agent.ts
+var DEFAULT_MAX_TURNS = 20;
+var Agent = class {
+  id;
+  name;
+  description;
+  model;
+  instructions;
+  context;
+  temperature;
+  maxTokens;
+  providerOptions;
+  retries;
+  mcpServers;
+  tools;
+  toolChoice;
+  defaultMaxTurns;
+  lifecycle;
+  outputSchema;
+  observability;
+  guardrails;
+  middlewares;
+  memory;
+  constructor(options) {
+    const resolved = resolveAgentOptions(options);
+    this.id = normalizeAgentId(resolved.id);
+    this.name = resolved.name;
+    this.description = resolved.description;
+    this.model = resolved.model;
+    this.instructions = resolved.instructions;
+    this.context = snapshotAgentContext(resolved.context);
+    this.temperature = resolved.temperature;
+    this.maxTokens = resolved.maxTokens;
+    if (resolved.providerOptions !== void 0) {
+      assertJsonObject(resolved.providerOptions, "Agent providerOptions");
+    }
+    this.providerOptions = cloneFrozenPlainData(resolved.providerOptions);
+    this.retries = cloneFrozenPlainData(resolved.retries);
+    const preparedTools = prepareAgentTools(resolved);
+    this.mcpServers = preparedTools.mcpServers;
+    this.tools = preparedTools.tools;
+    registerAgentToolState(this, preparedTools.publicState, preparedTools.toolsByName);
+    this.toolChoice = cloneFrozenPlainData(resolved.toolChoice);
+    this.defaultMaxTurns = assertNonnegativeSafeInteger(
+      resolved.defaultMaxTurns ?? DEFAULT_MAX_TURNS,
+      "maxTurns"
+    );
+    this.lifecycle = resolved.lifecycle;
+    this.outputSchema = resolved.outputSchema;
+    registerAgentProviderOutputSchema(this, resolved.outputSchema);
+    this.observability = snapshotAgentObservability(resolved.observability);
+    this.guardrails = snapshotGuardrailPolicies(resolved.guardrails);
+    this.middlewares = Object.freeze([...resolved.middlewares ?? []]);
+    this.memory = snapshotAgentMemory(resolved.memory);
+  }
+  generate(options) {
+    return AgentRun.fromAgent(this, options).generate();
+  }
+  stream(options) {
+    const run = AgentRun.fromAgent(this, options);
+    if (!this.model.capabilities.streaming || !isStreamingCompletionModel(this.model)) {
+      throw new Error("This completion model does not support streaming");
+    }
+    return createAgentStream(run);
+  }
+  asTool(options) {
+    return createAgentTool(this, options);
+  }
+  getTool(toolName) {
+    return getRegisteredAgentTool(this, toolName);
+  }
+  async callTool(toolName, args, context) {
+    const tool = this.getTool(toolName);
+    if (tool === void 0) {
+      throw new ToolNotFoundError(toolName);
+    }
+    return prepareToolCall(tool, args).call(context ?? {});
+  }
+};
+
+export {
+  getAgentToolState,
+  createHook,
+  createVectorContext,
+  isVectorContext,
+  withInternalAgentRunOptions,
+  markResolvedAgentOptions,
+  Agent
+};
+//# sourceMappingURL=chunk-VX3HS6PE.js.map