@anvia/core 1.0.0-rc.2 → 1.0.0-rc.4

package/dist/{chunk-DBSCKTUL.js → chunk-5GXSQYQT.js}

@@ -1,12 +1,23 @@
+import {
+  isMcpTool
+} from "./chunk-FXAIYTRE.js";
+import {
+  MemoryCompactionConflictError,
+  MemoryCompactionError,
+  assertPositiveInteger,
+  createMemoryCompactionSummary,
+  cumulativeCompactedMessageCount
+} from "./chunk-KFR4CDGK.js";
+import {
+  startAgentRunObservers
+} from "./chunk-VKYZZXP5.js";
 import {
   isSkillTool
 } from "./chunk-YK4WAAS4.js";
 import {
-  isMcpTool
-} from "./chunk-EINTGEGY.js";
-import {
+  isQuestionTool,
   isToolIndex
-} from "./chunk-D37WMSP6.js";
+} from "./chunk-J2W63PJI.js";
 import {
   ToolNotFoundError,
   assertFiniteMinScore,
@@ -15,23 +26,21 @@ import {
   createTool,
   parseToolArgs,
   prepareToolCall,
+  prepareToolCallFromInput,
   retrieveDocuments,
   toolMayRequireApproval,
   toolResultContentToText
-} from "./chunk-77AIYARB.js";
-import {
-  MemoryCompactionConflictError,
-  MemoryCompactionError,
-  assertPositiveInteger,
-  createMemoryCompactionSummary,
-  cumulativeCompactedMessageCount
-} from "./chunk-OJH6HWHX.js";
+} from "./chunk-XYTPYUGB.js";
 import {
-  startAgentRunObservers
-} from "./chunk-CWM7B2OO.js";
+  AgentRunBlockedError,
+  AgentRunCancelledError,
+  AgentStreamClosedError,
+  AgentToolSuspensionError,
+  MaxTurnsError
+} from "./chunk-TRQ3XRFD.js";
 import {
   mapWithConcurrency
-} from "./chunk-FMHLROPQ.js";
+} from "./chunk-3RM57ZT2.js";
 import {
   Usage,
   assertCompletionRequestSupported,
@@ -40,18 +49,13 @@ import {
   isProviderTool,
   isStreamingCompletionModel,
   textFromAssistantContent
-} from "./chunk-KR3RCCHJ.js";
+} from "./chunk-D2ECOWN5.js";
 import {
+  isJsonValue,
   parseMessage,
   parseMessages,
   toProviderJsonSchema
-} from "./chunk-TIZYTPJO.js";
-import {
-  appendGuardrailPolicies,
-  hasEnforcedOutputGuardrails,
-  runInputGuardrails,
-  runOutputGuardrails
-} from "./chunk-KIDGIJM7.js";
+} from "./chunk-PK5LKOFL.js";
 import {
   abortError,
   resolveRetryOptions,
@@ -61,38 +65,161 @@ import {
   throwIfAborted,
   waitForRetry
 } from "./chunk-FN7HLLAZ.js";
+import {
+  appendGuardrailPolicies,
+  hasEnforcedOutputGuardrails,
+  runInputGuardrails,
+  runOutputGuardrails
+} from "./chunk-AZB6N7P4.js";
 
-// src/agent/errors.ts
-var MaxTurnsError = class extends Error {
-  constructor(maxTurns, chatHistory, prompt) {
-    super(`Reached max turn limit: ${maxTurns}`);
-    this.maxTurns = maxTurns;
-    this.chatHistory = chatHistory;
-    this.prompt = prompt;
-    this.name = "MaxTurnsError";
-  }
-  maxTurns;
-  chatHistory;
-  prompt;
-};
-var AgentRunCancelledError = class extends Error {
-  constructor(chatHistory, reason, options) {
-    super(`Agent run cancelled: ${reason}`, options);
-    this.chatHistory = chatHistory;
-    this.reason = reason;
-    this.name = "AgentRunCancelledError";
+// src/agent/interactions.ts
+import { z } from "zod";
+var nonblank = z.string().trim().min(1);
+var jsonValueSchema = z.custom(isJsonValue, {
+  message: "Expected a strict JSON value"
+});
+var jsonObjectSchema = z.custom(
+  (value) => typeof value === "object" && value !== null && !Array.isArray(value) && isJsonValue(value),
+  { message: "Expected a strict JSON object" }
+);
+var questionChoiceSchema = z.object({
+  label: nonblank,
+  value: nonblank
+}).strict();
+var questionPromptSchema = z.object({
+  id: nonblank,
+  text: nonblank,
+  choices: z.array(questionChoiceSchema).min(1).optional(),
+  allowCustom: z.boolean().optional()
+}).strict().superRefine((question, context) => {
+  if (question.choices === void 0 && question.allowCustom === false) {
+    context.addIssue({
+      code: "custom",
+      message: "A free-text question cannot disable custom answers.",
+      path: ["allowCustom"]
+    });
   }
-  chatHistory;
-  reason;
+  const values = /* @__PURE__ */ new Set();
+  for (const [index, choice] of (question.choices ?? []).entries()) {
+    if (values.has(choice.value)) {
+      context.addIssue({
+        code: "custom",
+        message: "Question choice values must be unique.",
+        path: ["choices", index, "value"]
+      });
+    }
+    values.add(choice.value);
+  }
+});
+var questionAnswerSchema = z.object({
+  questionId: nonblank,
+  value: nonblank
+}).strict();
+var interactionBase = {
+  id: nonblank,
+  toolName: nonblank,
+  toolCallId: nonblank,
+  callId: z.string().optional(),
+  internalCallId: nonblank
 };
-var AgentRunBlockedError = class extends Error {
-  constructor(result) {
-    super(`Agent run was blocked by an ${result.stage} guardrail.`);
-    this.result = result;
-    this.name = "AgentRunBlockedError";
+var approvalRequestSchema = z.object({
+  type: z.literal("tool-approval"),
+  ...interactionBase,
+  input: jsonValueSchema,
+  reason: z.string().optional()
+}).strict();
+var questionRequestSchema = z.object({
+  type: z.literal("tool-question"),
+  ...interactionBase,
+  questions: z.array(questionPromptSchema).min(1)
+}).strict().superRefine((request, context) => {
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, question] of request.questions.entries()) {
+    if (ids.has(question.id)) {
+      context.addIssue({
+        code: "custom",
+        message: "Question IDs must be unique.",
+        path: ["questions", index, "id"]
+      });
+    }
+    ids.add(question.id);
+  }
+});
+var agentInteractionRequestSchema = z.discriminatedUnion("type", [
+  approvalRequestSchema,
+  questionRequestSchema
+]);
+var agentInteractionResponseSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("tool-approval"),
+    approved: z.boolean(),
+    reason: z.string().optional()
+  }).strict(),
+  z.object({
+    type: z.literal("tool-question"),
+    answers: z.array(questionAnswerSchema)
+  }).strict()
+]);
+var agentContinuationSchema = z.object({
+  version: z.literal(1),
+  agentId: nonblank,
+  sourceRunId: nonblank,
+  interaction: agentInteractionRequestSchema,
+  state: jsonObjectSchema
+}).strict();
+function parseAgentInteractionRequest(value) {
+  return freeze(agentInteractionRequestSchema.parse(value));
+}
+function parseAgentInteractionResponse(value) {
+  return freeze(agentInteractionResponseSchema.parse(value));
+}
+function parseAgentQuestionPrompts(value) {
+  const request = questionRequestSchema.parse({
+    type: "tool-question",
+    id: "validation",
+    toolName: "validation",
+    toolCallId: "validation",
+    internalCallId: "validation",
+    questions: value
+  });
+  return freeze(request.questions);
+}
+function parseAgentContinuation(value) {
+  return freeze(agentContinuationSchema.parse(value));
+}
+function assertAgentInteractionResponse(request, response) {
+  if (request.type !== response.type) {
+    throw new TypeError("Interaction response type does not match the pending request.");
   }
-  result;
-};
+  if (request.type === "tool-question" && response.type === "tool-question") {
+    assertQuestionAnswers(request, response.answers);
+  }
+}
+function assertQuestionAnswers(request, answers) {
+  const parsed = answers.map((answer) => questionAnswerSchema.parse(answer));
+  const byId = new Map(parsed.map((answer) => [answer.questionId, answer]));
+  if (byId.size !== parsed.length) {
+    throw new TypeError("Question answers must not contain duplicate question IDs.");
+  }
+  if (byId.size !== request.questions.length) {
+    throw new TypeError("Question responses must answer every question exactly once.");
+  }
+  for (const question of request.questions) {
+    const answer = byId.get(question.id);
+    if (answer === void 0) {
+      throw new TypeError(`Question response is missing an answer for "${question.id}".`);
+    }
+    const choices = question.choices;
+    if (choices !== void 0 && question.allowCustom !== true && !choices.some((choice) => choice.value === answer.value)) {
+      throw new TypeError(`Question "${question.id}" requires one of its configured choices.`);
+    }
+  }
+}
+function freeze(value) {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) freeze(child);
+  return Object.freeze(value);
+}
 
 // src/agent/tool-state.ts
 var agentToolStates = /* @__PURE__ */ new WeakMap();
@@ -158,25 +285,19 @@ var toolCallControl = {
   }
 };
 
-// src/internal/agent-runtime/approval-details.ts
-var approvalDetails = /* @__PURE__ */ new WeakMap();
-function registerAgentApprovalRequestDetails(approval, request) {
-  approvalDetails.set(approval, request);
-}
-function getAgentApprovalRequestDetails(approval) {
-  return approvalDetails.get(approval);
-}
-
 // src/agent/vector-context.ts
 function createVectorContext(options) {
   const topK = assertPositiveSearchLimit(options.topK);
   const minScore = assertFiniteMinScore(options.minScore);
-  return Object.freeze({
+  let context = {
     ...options,
     topK,
-    ...minScore === void 0 ? {} : { minScore },
     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;
@@ -199,9 +320,6 @@ function getInternalAgentRunOptions(options) {
   return options[internalAgentRunOptions];
 }
 
-// src/agent/agent.ts
-import { z } from "zod";
-
 // src/agent/lifecycle.ts
 function composeAgentLifecycle(first, second) {
   if (first === void 0) return second;
@@ -265,6 +383,17 @@ function cloneLifecycleFallback(value, 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 = [];
@@ -343,6 +472,9 @@ function extractRagText(message) {
   }
   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];
@@ -356,6 +488,179 @@ function extractRagText(message) {
   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) {
@@ -900,11 +1205,12 @@ var CompletionStreamAccumulator = class {
       accumulatedResponse.providerToolCalls,
       response.providerToolCalls
     );
-    return {
-      ...withMessageId,
-      ...sources.length === 0 ? {} : { sources },
-      ...providerToolCalls.length === 0 ? {} : { providerToolCalls }
-    };
+    let accumulated = { ...withMessageId };
+    if (sources.length > 0) accumulated = { ...accumulated, sources };
+    if (providerToolCalls.length > 0) {
+      accumulated = { ...accumulated, providerToolCalls };
+    }
+    return accumulated;
   }
   createTextKey() {
     this.nextTextKey += 1;
@@ -926,11 +1232,12 @@ var CompletionStreamAccumulator = class {
     const last = reasoning.details.at(-1);
     if (contentType === "text") {
       if (last?.type === "text") {
-        reasoning.details[reasoning.details.length - 1] = {
+        let detail = {
           ...last,
-          text: `${last.text}${event.delta}`,
-          ...event.signature === void 0 ? {} : { signature: event.signature }
+          text: `${last.text}${event.delta}`
         };
+        if (event.signature !== void 0) detail = { ...detail, signature: event.signature };
+        reasoning.details[reasoning.details.length - 1] = detail;
       } else {
         reasoning.details.push(
           event.signature === void 0 ? { type: "text", text: event.delta } : { type: "text", text: event.delta, signature: event.signature }
@@ -979,14 +1286,15 @@ function reasoningContent(reasoning) {
 }
 function toolCallContent(toolCall, finalToolCall) {
   const argumentsValue = finalToolCall !== void 0 && !isEmptyToolArguments(finalToolCall.input) ? finalToolCall.input : parseToolArguments(toolCall.id, toolCall.argumentsText);
-  return {
+  let content = {
     type: "tool-call",
     toolCallId: toolCall.id,
     toolName: toolCall.name,
-    input: argumentsValue,
-    ...toolCall.callId === void 0 ? {} : { callId: toolCall.callId },
-    ...toolCall.signature === void 0 ? {} : { signature: toolCall.signature }
+    input: argumentsValue
   };
+  if (toolCall.callId !== void 0) content = { ...content, callId: toolCall.callId };
+  if (toolCall.signature !== void 0) content = { ...content, signature: toolCall.signature };
+  return content;
 }
 function matchingFinalToolCall(accumulated, finalChoice) {
   const byId = finalChoice?.find(
@@ -1109,33 +1417,36 @@ var ToolCallExecutor = class {
         );
       }
     }
-    return mapWithConcurrency(toolCalls, this.concurrency, async (toolCall) => {
+    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.toolCallId = toolCall.callId;
+        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);
-      const toolStartArgs = {
+      let toolStartArgs = {
         turn: observation?.turn ?? 0,
         toolCall,
         toolName: toolCall.toolName,
         internalCallId,
-        args,
-        ...toolCall.callId === void 0 ? {} : { toolCallId: toolCall.callId },
-        ...toolDefinition === void 0 ? {} : { toolDefinition },
-        ...toolMetadata === void 0 ? {} : { toolMetadata }
+        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;
@@ -1176,6 +1487,38 @@ var ToolCallExecutor = class {
               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,
@@ -1195,9 +1538,11 @@ var ToolCallExecutor = class {
                   runId: this.runContext.runId,
                   step,
                   toolName: toolCall.toolName,
-                  input: lifecycleSnapshot(prepared.input),
-                  ...toolCall.callId === void 0 ? {} : { toolCallId: toolCall.callId }
+                  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(
@@ -1228,6 +1573,13 @@ var ToolCallExecutor = class {
               }
             }
           } 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)
             );
@@ -1286,39 +1638,316 @@ var ToolCallExecutor = class {
           args: effectiveArgs,
           output,
           result,
-          structuredResult,
-          ...toolCall.callId === void 0 ? {} : { callId: toolCall.callId }
+          structuredResult
         };
+        if (toolCall.callId !== void 0) resultPayload.callId = toolCall.callId;
         onResult?.(resultPayload);
-        return {
+        let resultPart = {
           type: "tool-result",
           toolCallId: toolCall.toolCallId,
           toolName: toolCall.toolName,
-          output,
-          ...toolCall.callId === void 0 ? {} : { callId: toolCall.callId }
+          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) => {
-          const streamEventArgs = {
+          let streamEventArgs = {
             turn: observation?.turn ?? 0,
             toolCall,
             toolName: toolCall.toolName,
             internalCallId: hookArgs.internalCallId,
             args: effectiveArgs,
-            event,
-            ...toolCall.callId === void 0 ? {} : { toolCallId: toolCall.callId }
+            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) {
@@ -1442,6 +2071,9 @@ var ToolCallExecutor = class {
     try {
       decision = await this.approvalHandler(request);
     } catch (error) {
+      if (error instanceof AgentInteractionSignal) {
+        throw error;
+      }
       await observation?.runObservers.event({
         name: "tool.approval_failed",
         level: "ERROR",
@@ -1452,13 +2084,14 @@ var ToolCallExecutor = class {
       });
       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: {
-        ...approvalEventAttributes(request, observation.turn),
-        approved: decision.approved,
-        ...decision.reason === void 0 ? {} : { decisionReason: decision.reason }
-      }
+      attributes
     });
     if (decision.approved) {
       return { approved: true };
@@ -1484,11 +2117,12 @@ function createApprovalContext(input, hookArgs, agent, run) {
     toolName: hookArgs.toolName,
     args: lifecycleSnapshot(input),
     rawArgs: hookArgs.args,
+    toolCallId: hookArgs.toolCallId,
     internalCallId: hookArgs.internalCallId,
     run: approvalRun
   };
-  if (hookArgs.toolCallId !== void 0) {
-    context.toolCallId = hookArgs.toolCallId;
+  if (hookArgs.callId !== void 0) {
+    context.callId = hookArgs.callId;
   }
   return context;
 }
@@ -1522,15 +2156,17 @@ function toolTraceMetadata(tool) {
   return result;
 }
 function toolErrorArgs(turn, toolCall, internalCallId, args, error) {
-  const observerArgs = {
+  let observerArgs = {
     turn,
     toolCall,
     toolName: toolCall.toolName,
     internalCallId,
     args,
-    error,
-    ...toolCall.callId === void 0 ? {} : { toolCallId: toolCall.callId }
+    error
   };
+  if (toolCall.callId !== void 0) {
+    observerArgs = { ...observerArgs, toolCallId: toolCall.callId };
+  }
   return observerArgs;
 }
 var ToolObserverScope = class {
@@ -1547,6 +2183,11 @@ var ToolObserverScope = class {
     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;
@@ -1591,14 +2232,6 @@ function agentToolEventPayload(toolCall, internalCallId, event) {
 }
 
 // src/internal/agent-runtime/agent-run.ts
-function deferredSignal() {
-  let resolve = () => {
-  };
-  const promise = new Promise((done) => {
-    resolve = done;
-  });
-  return { promise, resolve };
-}
 async function settleFailureCleanup(operations) {
   for (const operation of operations) {
     try {
@@ -1627,13 +2260,26 @@ var AgentRun = class _AgentRun {
       options.toolConcurrency ?? 1,
       "toolConcurrency"
     );
-    this.concurrency = this.activeHook !== void 0 || agent.tools.some((tool) => toolMayRequireApproval(tool.requiresApproval)) ? 1 : configuredConcurrency;
+    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;
@@ -1655,52 +2301,39 @@ var AgentRun = class _AgentRun {
   onInternalFailure;
   onInternalMemoryCompaction;
   memoryCompaction;
-  pendingApproval;
-  approvalSignal = deferredSignal();
-  activeRunId;
   requestedRunId;
-  currentUsage = Usage.empty();
+  continuationState;
+  interactionResponse;
+  resumedFrom;
   currentMessages = [];
   cancellationError;
   activeGeneration;
   abortController = new AbortController();
   removeExternalAbortListener;
   static fromAgent(agent, options) {
-    const normalized = normalizeAgentInput(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
+      memoryScope: normalized.scope,
+      continuationState: normalized.continuationState,
+      interactionResponse: normalized.interactionResponse,
+      sourceRunId: normalized.sourceRunId,
+      interactionId: normalized.interactionId
     });
   }
   steer(input) {
     if (this.isTerminal() || this.cancellationError !== void 0) {
-      return false;
-    }
-    this.steeringMessages.push(...normalizeSteeringInput(input));
-    return true;
-  }
-  waitForApproval() {
-    return this.pendingApproval === void 0 ? this.approvalSignal.promise : Promise.resolve();
-  }
-  approvalResult() {
-    const snapshot = this.approvalSnapshot();
-    return { status: "approval_required", ...snapshot };
-  }
-  approvalEvent() {
-    const snapshot = this.approvalSnapshot();
-    return { type: "approval_required", ...snapshot };
-  }
-  resolveApproval(decision) {
-    const pending = this.pendingApproval;
-    if (pending === void 0) {
-      throw new TypeError("Agent run has no pending tool approval.");
+      throw new AgentStreamClosedError();
     }
-    this.pendingApproval = void 0;
-    this.approvalSignal = deferredSignal();
-    pending.resolve(decision);
+    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) {
@@ -1713,35 +2346,33 @@ var AgentRun = class _AgentRun {
   setCancellationError(error) {
     this.cancellationError = error;
     if (!this.abortController.signal.aborted) this.abortController.abort(error);
-    const pending = this.pendingApproval;
-    if (pending !== void 0) {
-      this.pendingApproval = void 0;
-      this.approvalSignal = deferredSignal();
-      pending.reject(error);
-    }
   }
   async generate() {
     this.startRun();
     const runId = this.requestedRunId ?? globalThis.crypto.randomUUID();
-    this.activeRunId = runId;
     let usage = Usage.empty();
     let currentTurns = 0;
     let lastPrompt = this.promptMessage;
     let newMessages = [this.promptMessage];
     let runObservers;
+    let pendingTurnMessages = [];
     try {
       this.throwIfCancelled();
-      const memoryPreparation = await this.memoryRecorder.prepareHistory(
+      const memoryPreparation = this.continuationState === void 0 ? await this.memoryRecorder.prepareHistory(
         runId,
         newMessages.length,
         this.abortController.signal
-      );
-      this.chatHistory = memoryPreparation.history;
-      usage = Usage.add(usage, memoryPreparation.usage);
-      this.memoryCompaction = memoryPreparation.compaction;
-      await this.notifyInternalMemoryCompaction(memoryPreparation.compaction);
+      ) : 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);
-      await this.recordMemoryCompaction(memoryPreparation, runObservers);
+      if (memoryPreparation !== void 0) {
+        await this.recordMemoryCompaction(memoryPreparation, runObservers);
+      }
       this.throwIfCancelled();
       await this.activeLifecycle?.onStart?.({
         runId,
@@ -1749,39 +2380,84 @@ var AgentRun = class _AgentRun {
         history: lifecycleSnapshot(this.chatHistory),
         maxTurns: this.maxTurnCount
       });
-      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()
-        };
-        await this.runLifecycleFinish(result);
-        await runObservers.end(result);
-        this.runState = "completed";
-        this.disposeAbortLink();
-        return result;
+      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);
-      const pendingTurnMessages = this.memoryRecorder.pendingTurnMessages(newMessages);
+      pendingTurnMessages = this.memoryRecorder.pendingTurnMessages(newMessages);
       await this.runRunStartHook(newMessages);
+      if (this.continuationState !== void 0) {
+        await runObservers.event({
+          name: "agent.interaction_response",
+          attributes: {
+            sourceRunId: this.resumedFrom?.runId,
+            interactionId: this.resumedFrom?.interactionId,
+            interactionType: this.interactionResponse?.type
+          }
+        });
+        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) {
@@ -1804,7 +2480,7 @@ var AgentRun = class _AgentRun {
         }
         response = await this.runCompletionResponseMiddlewares(request, response, currentTurns);
         usage = Usage.add(usage, response.usage);
-        this.updateApprovalProgress(runId, usage, newMessages);
+        this.updateRunProgress(newMessages);
         await this.runCompletionResponseHook(prompt, response, newMessages);
         await this.runTurnEndHook(currentTurns, response, newMessages);
         await this.activeLifecycle?.onStepFinish?.({
@@ -1827,7 +2503,20 @@ var AgentRun = class _AgentRun {
               pendingTurnMessages
             );
           }
-          if (await this.drainSteeringMessages(runId, currentTurns, newMessages, 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;
           }
@@ -1870,19 +2559,36 @@ var AgentRun = class _AgentRun {
           this.disposeAbortLink();
           return result;
         }
-        this.updateApprovalProgress(runId, usage, newMessages);
-        const toolResults = await this.executeToolCalls(
-          runId,
-          toolCalls,
-          newMessages,
-          void 0,
-          void 0,
-          {
-            turn: currentTurns,
-            runObservers,
-            toolDefinitions: request.tools
+        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(
@@ -1899,6 +2605,7 @@ var AgentRun = class _AgentRun {
       if (error instanceof MemoryCompactionError && error.usage !== void 0) {
         usage = Usage.add(usage, error.usage);
       }
+      this.runState = "closing";
       const runError = this.normalizeRunError(error);
       const reportedError = await this.reportRunFailure(
         runError,
@@ -1915,27 +2622,31 @@ var AgentRun = class _AgentRun {
   async *events() {
     this.startRun();
     const runId = this.requestedRunId ?? globalThis.crypto.randomUUID();
-    this.activeRunId = runId;
     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 = await this.memoryRecorder.prepareHistory(
+      const memoryPreparation = this.continuationState === void 0 ? await this.memoryRecorder.prepareHistory(
         runId,
         newMessages.length,
         this.abortController.signal
-      );
-      this.chatHistory = memoryPreparation.history;
-      usage = Usage.add(usage, memoryPreparation.usage);
-      this.memoryCompaction = memoryPreparation.compaction;
-      await this.notifyInternalMemoryCompaction(memoryPreparation.compaction);
+      ) : 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);
-      await this.recordMemoryCompaction(memoryPreparation, runObservers);
-      if (memoryPreparation.compaction !== void 0) {
+      if (memoryPreparation !== void 0) {
+        await this.recordMemoryCompaction(memoryPreparation, runObservers);
+      }
+      if (memoryPreparation?.compaction !== void 0) {
         yield { type: "memory_compaction", ...memoryPreparation.compaction };
       }
       this.throwIfCancelled();
@@ -1945,41 +2656,94 @@ var AgentRun = class _AgentRun {
         history: lifecycleSnapshot(this.chatHistory),
         maxTurns: this.maxTurnCount
       });
-      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()
-        };
-        await this.runLifecycleFinish(result);
-        await runObservers.end(result);
-        this.runState = "completed";
-        this.disposeAbortLink();
-        yield { type: "final", result };
-        return;
+      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);
-      const pendingTurnMessages = this.memoryRecorder.pendingTurnMessages(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) {
@@ -2050,16 +2814,18 @@ var AgentRun = class _AgentRun {
           throw error;
         }
         const { firstDeltaMs, emittedToolCallIds } = completionState;
-        const generationEndArgs = {
+        let generationEndArgs = {
           turn: currentTurns,
-          response,
-          ...firstDeltaMs === void 0 ? {} : { firstDeltaMs }
+          response
         };
+        if (firstDeltaMs !== void 0) {
+          generationEndArgs = { ...generationEndArgs, firstDeltaMs };
+        }
         this.activeGeneration = void 0;
         await generationObservers.end(generationEndArgs);
         response = await this.runCompletionResponseMiddlewares(request, response, currentTurns);
         usage = Usage.add(usage, response.usage);
-        this.updateApprovalProgress(runId, usage, newMessages);
+        this.updateRunProgress(newMessages);
         await this.runCompletionResponseHook(prompt, response, newMessages);
         await this.runTurnEndHook(currentTurns, response, newMessages);
         await this.activeLifecycle?.onStepFinish?.({
@@ -2097,7 +2863,17 @@ var AgentRun = class _AgentRun {
               pendingTurnMessages
             );
           }
-          if (await this.drainSteeringMessages(runId, currentTurns, newMessages, 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;
           }
@@ -2130,22 +2906,41 @@ var AgentRun = class _AgentRun {
             }
           }
         }
-        this.updateApprovalProgress(runId, usage, newMessages);
+        this.updateRunProgress(newMessages);
         yield {
           type: "turn_end",
           turn: currentTurns,
           response,
           firstDeltaMs
         };
-        const toolExecution = this.executeStreamingToolCalls(runId, toolCalls, newMessages, {
-          turn: currentTurns,
-          runObservers,
-          toolDefinitions: request.tools
-        });
-        for await (const result of toolExecution.events) {
-          yield { turn: currentTurns, ...result };
+        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 toolResults = await toolExecution.results;
         const toolMessage = { role: "tool", content: toolResults };
         newMessages.push(toolMessage);
         await this.memoryRecorder.commitMessages(
@@ -2154,7 +2949,14 @@ var AgentRun = class _AgentRun {
           [assistantMessage, toolMessage],
           pendingTurnMessages
         );
-        await this.drainSteeringMessages(runId, currentTurns, newMessages, 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);
@@ -2162,6 +2964,7 @@ var AgentRun = class _AgentRun {
       if (error instanceof MemoryCompactionError && error.usage !== void 0) {
         usage = Usage.add(usage, error.usage);
       }
+      this.runState = "closing";
       const runError = this.normalizeRunError(error);
       const reportedError = await this.reportRunFailure(
         runError,
@@ -2176,7 +2979,7 @@ var AgentRun = class _AgentRun {
       this.disposeAbortLink();
       return;
     } finally {
-      if (this.runState === "running") {
+      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)]);
@@ -2226,7 +3029,7 @@ var AgentRun = class _AgentRun {
     const abortSignal = this.abortController.signal;
     const documents = await fetchContextDocuments(this.agent, ragText, abortSignal);
     const toolDefinitions = await fetchToolDefinitions(this.agent, ragText, abortSignal);
-    const request = createCompletionRequest([...history, prompt], {
+    const request = createCompletionRequest(providerMessages([...history, prompt]), {
       instructions: this.agent.instructions,
       documents,
       tools: [...toolDefinitions, ...getAgentToolState(this.agent).providerTools],
@@ -2348,25 +3151,84 @@ var AgentRun = class _AgentRun {
     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 metadata = {
-      anvia: {
-        generation: {
-          provider: this.agent.model.provider,
-          modelId: this.agent.model.modelId,
-          usage: { ...response.usage },
-          ...response.contextUsage === void 0 ? {} : { contextUsage: response.contextUsage },
-          ...response.sources === void 0 ? {} : { sources: response.sources },
-          ...response.providerToolCalls === void 0 ? {} : { providerToolCalls: response.providerToolCalls }
-        }
-      }
+    const generation = {
+      provider: this.agent.model.provider,
+      modelId: this.agent.model.modelId,
+      usage: { ...response.usage }
     };
-    return {
+    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,
-      ...response.messageId === void 0 ? {} : { id: response.messageId },
       metadata
     };
+    if (response.messageId !== void 0) message = { ...message, id: response.messageId };
+    return message;
   }
   providerTraceRequest(request, options = {}) {
     try {
@@ -2378,16 +3240,17 @@ var AgentRun = class _AgentRun {
     }
   }
   generationStartArgs(turn, request, providerRequest) {
-    return {
+    let args = {
       turn,
       request,
       modelInfo: {
         provider: this.agent.model.provider,
         modelId: this.agent.model.modelId,
         capabilities: this.agent.model.capabilities
-      },
-      ...providerRequest === void 0 ? {} : { providerRequest }
+      }
     };
+    if (providerRequest !== void 0) args = { ...args, providerRequest };
+    return args;
   }
   retryOptionsForFailure(error, attempt, turn, streaming) {
     if (this.abortController.signal.aborted) return void 0;
@@ -2416,10 +3279,16 @@ var AgentRun = class _AgentRun {
     await waitForRetry(delayMs, this.abortController.signal);
   }
   async executeToolCalls(runId, toolCalls, newMessages, onResult, onStreamEvent, observation) {
-    const executor = new ToolCallExecutor(
+    const executor = this.createToolExecutor(runId, newMessages);
+    return executor.execute(toolCalls, onResult, onStreamEvent, observation);
+  }
+  createToolExecutor(runId, newMessages) {
+    return new ToolCallExecutor(
       this.agent,
       this.activeHook,
-      (request) => this.suspendForApproval(request),
+      async (request) => {
+        throw new AgentInteractionSignal(approvalInteraction(request), request.rejectMessage);
+      },
       this.activeLifecycle,
       {
         runId,
@@ -2431,7 +3300,63 @@ var AgentRun = class _AgentRun {
       this.abortController.signal,
       (reason) => this.cancelled(newMessages, reason)
     );
-    return executor.execute(toolCalls, onResult, onStreamEvent, observation);
+  }
+  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();
@@ -2449,17 +3374,20 @@ var AgentRun = class _AgentRun {
     );
     return { events, results };
   }
-  suspendForApproval(request) {
-    if (this.cancellationError !== void 0) {
-      return Promise.reject(this.cancellationError);
-    }
-    if (this.pendingApproval !== void 0) {
-      throw new Error("Agent run already has a pending tool approval.");
-    }
-    return new Promise((resolve, reject) => {
-      this.pendingApproval = { request, resolve, reject };
-      this.approvalSignal.resolve();
-    });
+  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;
@@ -2469,31 +3397,7 @@ var AgentRun = class _AgentRun {
     this.activeGeneration = void 0;
     await active.observers.error({ turn: active.turn, error });
   }
-  approvalSnapshot() {
-    const pending = this.pendingApproval;
-    const runId = this.activeRunId;
-    if (pending === void 0 || runId === void 0) {
-      throw new TypeError("Agent run has no pending tool approval.");
-    }
-    const approval = {
-      id: pending.request.id,
-      toolName: pending.request.toolName,
-      input: lifecycleSnapshot(pending.request.args),
-      ...pending.request.toolCallId === void 0 ? {} : { toolCallId: pending.request.toolCallId },
-      ...pending.request.reason === void 0 ? {} : { reason: pending.request.reason }
-    };
-    registerAgentApprovalRequestDetails(approval, pending.request);
-    return {
-      runId,
-      approval,
-      usage: lifecycleSnapshot(this.currentUsage),
-      messages: lifecycleSnapshot(this.currentMessages),
-      ...this.memoryCompactionResult()
-    };
-  }
-  updateApprovalProgress(runId, usage, messages) {
-    this.activeRunId = runId;
-    this.currentUsage = usage;
+  updateRunProgress(messages) {
     this.currentMessages = [...messages];
   }
   async runLifecycleFinish(result) {
@@ -2501,17 +3405,23 @@ var AgentRun = class _AgentRun {
       runId: result.runId,
       text: result.text,
       usage: lifecycleSnapshot(result.usage),
-      messages: lifecycleSnapshot(result.messages),
-      ...result.memoryCompaction === void 0 ? {} : { memoryCompaction: lifecycleSnapshot(result.memoryCompaction) }
+      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);
   }
@@ -2588,6 +3498,7 @@ var AgentRun = class _AgentRun {
       ...generationArtifacts(messages),
       ...this.memoryCompactionResult()
     };
+    if (this.resumedFrom !== void 0) Object.assign(common, { resumedFrom: this.resumedFrom });
     if (blocked) {
       return { ...common, status: "blocked", stage: "output" };
     }
@@ -2798,14 +3709,18 @@ var AgentRun = class _AgentRun {
   shouldBufferStreamResponseEvents() {
     return this.activeHook?.onCompletionResponse !== void 0 || this.activeMiddlewares().some((middleware) => middleware.onCompletionResponse !== void 0);
   }
-  async drainSteeringMessages(runId, turn, newMessages, pendingTurnMessages) {
-    const messages = this.steeringMessages.splice(0);
-    if (messages.length === 0) {
-      return false;
+  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 true;
+    return receipts;
   }
   startRun() {
     if (this.runState === "idle") {
@@ -2818,7 +3733,7 @@ var AgentRun = class _AgentRun {
     throw new Error("Agent stream has already been consumed.");
   }
   isTerminal() {
-    return this.runState === "completed" || this.runState === "errored" || this.runState === "cancelled";
+    return this.runState !== "idle" && this.runState !== "running";
   }
   cancelled(newMessages, reason) {
     if (this.cancellationError !== void 0) return this.cancellationError;
@@ -2864,14 +3779,67 @@ function abortReason(reason) {
   if (reason instanceof Error && reason.message.trim().length > 0) return reason.message;
   return "External abort signal.";
 }
-function normalizeAgentInput(input) {
+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 (hasPrompt === hasMessages) {
-    throw new TypeError("Agent runs require exactly one of prompt or messages.");
+  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;
@@ -2884,11 +3852,14 @@ function normalizeAgentInput(input) {
     if (parsedPrompt.role !== "user") {
       throw new TypeError("Agent prompt must be text or a user message.");
     }
-    return {
+    const normalized = {
       prompt: parsedPrompt,
-      history: [],
-      ...input.session === void 0 ? {} : { scope: normalizeMemoryScope(input.session) }
+      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.");
@@ -2949,11 +3920,12 @@ function normalizeMemoryScope(scope) {
   if (typeof scope.sessionId !== "string" || scope.sessionId.trim().length === 0) {
     throw new TypeError("Agent sessionId must be a non-empty string.");
   }
-  return lifecycleSnapshot({
-    sessionId: scope.sessionId.trim(),
-    ...scope.userId === void 0 ? {} : { userId: scope.userId },
-    ...scope.metadata === void 0 ? {} : { metadata: scope.metadata }
-  });
+  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) {
@@ -3023,11 +3995,13 @@ function generationArtifacts(messages) {
       providerToolCalls.set(toolCall.id, toolCall);
     }
   }
-  return {
-    ...sources.size === 0 ? {} : { sources: [...sources.values()] },
-    ...providerToolCalls.size === 0 ? {} : { providerToolCalls: [...providerToolCalls.values()] },
-    ...contextUsage === void 0 ? {} : { contextUsage }
-  };
+  const artifacts = {};
+  if (sources.size > 0) artifacts.sources = [...sources.values()];
+  if (providerToolCalls.size > 0) {
+    artifacts.providerToolCalls = [...providerToolCalls.values()];
+  }
+  if (contextUsage !== void 0) artifacts.contextUsage = contextUsage;
+  return artifacts;
 }
 function reasoningDeltaEvent2(turn, delta, details = {}) {
   const event = {
@@ -3063,6 +4037,29 @@ function textFromMessage(message) {
     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 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,
@@ -3082,9 +4079,126 @@ function guardrailDecisionAttributes(decision) {
   return attributes;
 }
 
-// src/memory/options.ts
-function resolveMemoryOptions(options = {}) {
-  const resolved = {
+// 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 as z2 } 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: z2.object({
+      prompt: z2.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) {
@@ -3115,236 +4229,8 @@ function resolveMemoryOptions(options = {}) {
   return resolved;
 }
 
-// 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/agent/agent.ts
-var DEFAULT_MAX_TURNS = 20;
-var providerOutputSchemas = /* @__PURE__ */ new WeakMap();
-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;
-    const context = (resolved.context ?? []).map(snapshotContextInput);
-    assertValidVectorContexts(context);
-    this.context = Object.freeze(context);
-    this.temperature = resolved.temperature;
-    this.maxTokens = resolved.maxTokens;
-    this.providerOptions = cloneFrozenPlainData(resolved.providerOptions);
-    this.retries = cloneFrozenPlainData(resolved.retries);
-    assertUniqueMcpServerNames(resolved.mcpServers ?? []);
-    this.mcpServers = Object.freeze((resolved.mcpServers ?? []).map(snapshotMcpServer));
-    const configuredTools = [...resolved.tools ?? []];
-    const staticTools = [...configuredTools, ...this.mcpServers.flatMap((server) => server.tools)];
-    const toolIndexes = (resolved.toolIndexes ?? []).map(snapshotToolIndex);
-    const providerTools = (resolved.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);
-      }
-    }
-    this.tools = Object.freeze([...toolsByName.values()]);
-    const publicToolState = Object.freeze({
-      configuredTools: Object.freeze(configuredTools),
-      staticTools: Object.freeze(staticTools),
-      providerTools: Object.freeze(providerTools),
-      toolIndexes: Object.freeze(toolIndexes)
-    });
-    registerAgentToolState(this, publicToolState, toolsByName);
-    this.toolChoice = cloneFrozenPlainData(resolved.toolChoice);
-    this.defaultMaxTurns = assertNonnegativeSafeInteger(
-      resolved.defaultMaxTurns ?? DEFAULT_MAX_TURNS,
-      "maxTurns"
-    );
-    this.lifecycle = resolved.lifecycle;
-    this.outputSchema = resolved.outputSchema;
-    if (resolved.outputSchema !== void 0) {
-      providerOutputSchemas.set(this, toProviderJsonSchema(resolved.outputSchema));
-    }
-    this.observability = snapshotAgentObservability(resolved.observability);
-    this.guardrails = Object.freeze((resolved.guardrails ?? []).map(snapshotGuardrailPolicy));
-    this.middlewares = Object.freeze([...resolved.middlewares ?? []]);
-    this.memory = snapshotAgentMemory(resolved.memory);
-  }
-  generate(options) {
-    return createGenerateExecution(this, AgentRun.fromAgent(this, options)).next();
-  }
-  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 createStreamExecution(this, run);
-  }
-  resume(pending, decision) {
-    assertAgentApprovalDecision(decision);
-    const continuation = approvalContinuations.get(pending);
-    if (continuation === void 0 || continuation.agent !== this) {
-      throw new TypeError("Approval continuation does not belong to this agent.");
-    }
-    approvalContinuations.delete(pending);
-    continuation.resolve(decision);
-    return continuation.mode === "generate" ? continuation.resume() : continuation.resume();
-  }
-  asTool(options) {
-    const description = options.description ?? this.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 && this.model.capabilities.streaming && isStreamingCompletionModel(this.model)) {
-          let completed = false;
-          let output;
-          const childStream = this.stream({
-            prompt,
-            maxTurns: options.maxTurns,
-            abortSignal: context.abortSignal
-          });
-          for await (const event of childStream) {
-            if (event.type === "approval_required") {
-              await cancelAgentApproval(
-                event,
-                `Agent tool "${options.name}" cannot suspend for tool approval.`
-              );
-              throw new Error(
-                `Agent tool "${options.name}" cannot suspend for tool approval. Run the agent directly to handle approvals.`
-              );
-            }
-            const streamEvent = {
-              agentId: this.id,
-              event
-            };
-            if (this.name !== void 0) {
-              streamEvent.agentName = this.name;
-            }
-            await context.emitStreamEvent(streamEvent);
-            if (event.type === "error") {
-              throw event.error;
-            }
-            if (event.type === "final") {
-              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 this.generate({
-          prompt,
-          maxTurns: options.maxTurns,
-          abortSignal: context.abortSignal
-        });
-        if (response.status === "approval_required") {
-          await cancelAgentApproval(
-            response,
-            `Agent tool "${options.name}" cannot suspend for tool approval.`
-          );
-          throw new Error(
-            `Agent tool "${options.name}" cannot suspend for tool approval. Run the agent directly to handle approvals.`
-          );
-        }
-        if (response.status === "blocked") {
-          throw new AgentRunBlockedError(response);
-        }
-        return response.output;
-      }
-    });
-  }
-  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 ?? {});
-  }
-};
+// src/agent/resolve-options.ts
 var resolvedAgentOptions = /* @__PURE__ */ Symbol("resolvedAgentOptions");
-function createResolvedAgent(options) {
-  return new Agent({
-    ...options,
-    [resolvedAgentOptions]: true
-  });
-}
-function getResolvedAgentOptions(agent) {
-  const toolState = getAgentToolState(agent);
-  return {
-    id: agent.id,
-    name: agent.name,
-    description: agent.description,
-    model: agent.model,
-    instructions: agent.instructions,
-    context: [...agent.context],
-    temperature: agent.temperature,
-    maxTokens: agent.maxTokens,
-    providerOptions: agent.providerOptions,
-    retries: agent.retries,
-    tools: [...toolState.configuredTools],
-    mcpServers: [...agent.mcpServers],
-    providerTools: [...toolState.providerTools],
-    toolIndexes: [...toolState.toolIndexes],
-    toolChoice: agent.toolChoice,
-    defaultMaxTurns: agent.defaultMaxTurns,
-    lifecycle: agent.lifecycle,
-    outputSchema: agent.outputSchema,
-    observability: agent.observability,
-    guardrails: [...agent.guardrails],
-    middlewares: [...agent.middlewares],
-    memory: agent.memory
-  };
-}
-function getAgentProviderOutputSchema(agent) {
-  return providerOutputSchemas.get(agent);
-}
 function resolveAgentOptions(options) {
   if (isInternalAgentOptions(options)) {
     return options;
@@ -3404,38 +4290,27 @@ function resolveAgentOptions(options) {
     memory
   };
 }
-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 markResolvedAgentOptions(options) {
+  return {
+    ...options,
+    [resolvedAgentOptions]: true
+  };
 }
-function registerToolOwner(owners, name, owner) {
-  const existing = owners.get(name);
-  if (existing !== void 0) {
+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(
-      `Tool name collision for "${name}" between ${existing} and ${owner}. Tool names must be unique across every Agent tool source.`
+      "Memory compaction requires a store with the optional compaction capability."
     );
   }
-  owners.set(name, owner);
+  return { store, ...resolvedOptions };
 }
 function addUniqueTool(tools, tool, source) {
   if (tools.has(tool.name)) {
@@ -3443,12 +4318,16 @@ function addUniqueTool(tools, tool, source) {
   }
   tools.set(tool.name, tool);
 }
-function assertValidVectorContexts(inputs) {
-  for (const input of inputs) {
+
+// 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;
@@ -3471,211 +4350,174 @@ function snapshotAgentObservability(observability) {
   if (errorPolicy !== "ignore" && errorPolicy !== "throw") {
     throw new TypeError('Agent observability.errorPolicy must be "ignore" or "throw".');
   }
-  return Object.freeze({
+  let snapshot = {
     observers: Object.freeze(observers),
-    ...observability.primaryTrace === void 0 ? {} : { primaryTrace: observability.primaryTrace },
     errorPolicy
-  });
+  };
+  if (observability.primaryTrace !== void 0) {
+    snapshot = { ...snapshot, primaryTrace: observability.primaryTrace };
+  }
+  return Object.freeze(snapshot);
 }
-function isInternalAgentOptions(options) {
-  return options[resolvedAgentOptions] === true;
+function snapshotGuardrailPolicies(policies) {
+  return Object.freeze((policies ?? []).map(snapshotGuardrailPolicy));
 }
-function resolveAgentMemory(options) {
-  if (options.memory === void 0) {
+function snapshotAgentMemory(memory) {
+  if (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."
-    );
+  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 { store, ...resolvedOptions };
+  return Object.freeze(snapshot);
 }
-var approvalContinuations = /* @__PURE__ */ new WeakMap();
-function assertAgentApprovalDecision(decision) {
-  if (typeof decision !== "object" || decision === null || typeof decision.approved !== "boolean") {
-    throw new TypeError("Approval decision must include an approved boolean.");
-  }
-  if (decision.reason !== void 0 && typeof decision.reason !== "string") {
-    throw new TypeError("Approval decision reason must be a string.");
-  }
-}
-function createGenerateExecution(agent, run) {
-  const completion = run.generate();
-  const execution = {
-    async next() {
-      const outcome = await Promise.race([
-        completion.then((result) => ({ type: "completed", result })),
-        run.waitForApproval().then(() => ({ type: "approval" }))
-      ]);
-      if (outcome.type === "completed") {
-        return outcome.result;
-      }
-      const pending = run.approvalResult();
-      approvalContinuations.set(pending, {
-        agent,
-        mode: "generate",
-        resolve: (decision) => run.resolveApproval(decision),
-        resume: () => execution.next(),
-        cancel: (reason) => execution.cancel(reason)
-      });
-      return pending;
-    },
-    async cancel(reason) {
-      run.cancel(reason);
-      await completion.catch(() => void 0);
+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
   };
-  return execution;
-}
-var StreamExecution = class {
-  constructor(agent, run) {
-    this.agent = agent;
-    this.run = run;
-    this.iterator = run.events()[Symbol.asyncIterator]();
+  if (input.minScore !== void 0) {
+    shared = { ...shared, minScore: input.minScore };
   }
-  agent;
-  run;
-  iterator;
-  nextEvent;
-  phase = "active";
-  segment() {
-    if (this.phase === "approval") {
-      this.phase = "active";
-    }
-    return new DefaultAgentStream(this);
+  if (input.filter !== void 0) {
+    shared = { ...shared, filter: cloneFrozenPlainData(input.filter) };
   }
-  steer(input) {
-    return this.run.steer(input);
+  if (input.retries !== void 0) {
+    shared = { ...shared, retries: cloneFrozenPlainData(input.retries) };
   }
-  async *events() {
-    while (true) {
-      this.nextEvent ??= this.iterator.next();
-      let outcome;
-      try {
-        outcome = await Promise.race([
-          this.nextEvent.then((event) => ({ type: "event", event })),
-          this.run.waitForApproval().then(() => ({ type: "approval" }))
-        ]);
-      } catch (error) {
-        this.phase = "terminal";
-        throw error;
-      }
-      if (outcome.type === "approval") {
-        this.phase = "approval";
-        const pending = this.run.approvalEvent();
-        approvalContinuations.set(pending, {
-          agent: this.agent,
-          mode: "stream",
-          resolve: (decision) => this.run.resolveApproval(decision),
-          resume: () => this.segment(),
-          cancel: (reason) => this.cancel(reason)
-        });
-        yield pending;
-        return;
-      }
-      this.nextEvent = void 0;
-      if (outcome.event.done) {
-        this.phase = "terminal";
-        return;
-      }
-      yield outcome.event.value;
-    }
+  if (format !== void 0) {
+    shared = {
+      ...shared,
+      format: (result) => format.call(input, result)
+    };
   }
-  shouldCancelActiveSegment() {
-    return this.phase === "active";
+  if (!("models" in input) || input.models === void 0) {
+    return Object.freeze({ ...shared, store: input.store, model: input.model });
   }
-  async cancel(reason) {
-    if (this.phase === "terminal" || this.phase === "cancelled") {
-      return;
-    }
-    this.phase = "cancelled";
-    this.run.cancel(reason);
-    try {
-      await this.iterator.return?.();
-    } catch {
-    }
+  let context = {
+    ...shared,
+    store: input.store,
+    models: input.models
+  };
+  if (input.fusion !== void 0) {
+    context = { ...context, fusion: input.fusion };
   }
-};
-function createStreamExecution(agent, run) {
-  return new StreamExecution(agent, run).segment();
+  return Object.freeze(context);
 }
-var DefaultAgentStream = class {
-  constructor(execution) {
-    this.execution = execution;
+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);
+    }
   }
-  execution;
-  consuming = false;
-  completed = false;
-  steer(input) {
-    return this.execution.steer(input);
+  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");
   }
-  [Symbol.asyncIterator]() {
-    return this.consume()[Symbol.asyncIterator]();
+  for (const tool of options.providerTools) {
+    registerToolOwner(owners, tool.name, "provider tool");
   }
-  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.");
+  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.");
     }
-    this.consuming = true;
-    try {
-      for await (const event of this.execution.events()) {
-        yield event;
-      }
-    } finally {
-      if (this.execution.shouldCancelActiveSegment()) {
-        await this.execution.cancel("Agent stream consumer closed the stream.");
+    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.`
+        );
       }
-      this.consuming = false;
-      this.completed = true;
+      registerToolOwner(owners, tool.name, `tool index ${indexPosition + 1}`);
     }
   }
-};
-async function cancelAgentApproval(pending, reason) {
-  const continuation = approvalContinuations.get(pending);
-  if (continuation === void 0) {
-    return;
-  }
-  approvalContinuations.delete(pending);
-  await continuation.cancel(reason);
 }
-function snapshotContextInput(input) {
-  if (!isVectorContext(input)) {
-    return Object.freeze({
-      id: input.id,
-      text: input.text,
-      ...input.additionalProps === void 0 ? {} : { additionalProps: cloneFrozenPlainData(input.additionalProps) }
-    });
+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.`
+    );
   }
-  const format = input.format;
-  const shared = {
-    kind: "vector-context",
-    store: input.store,
-    topK: input.topK,
-    ...input.minScore === void 0 ? {} : { minScore: input.minScore },
-    ...input.filter === void 0 ? {} : { filter: cloneFrozenPlainData(input.filter) },
-    ...input.retries === void 0 ? {} : { retries: cloneFrozenPlainData(input.retries) },
-    ...format === void 0 ? {} : { format: (result) => format.call(input, result) }
-  };
-  return Object.freeze(
-    "models" in input && input.models !== void 0 ? {
-      ...shared,
-      store: input.store,
-      models: input.models,
-      ...input.fusion === void 0 ? {} : { fusion: input.fusion }
-    } : { ...shared, store: input.store, model: input.model }
-  );
+  owners.set(name, owner);
 }
 function snapshotProviderTool(tool) {
-  return Object.freeze({
-    ...tool,
-    ...tool.configuration === void 0 ? {} : { configuration: cloneFrozenPlainData(tool.configuration) }
-  });
+  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() === "") {
@@ -3692,27 +4534,42 @@ function snapshotMcpServer(server) {
     }
   }
   const tools = server.tools.map(snapshotMcpTool);
-  return Object.freeze({
+  let snapshot = {
     name: server.name,
-    tools: Object.freeze(tools),
-    ...server.serverInfo === void 0 ? {} : { serverInfo: cloneFrozenPlainData(server.serverInfo) },
-    ...server.capabilities === void 0 ? {} : { capabilities: cloneFrozenPlainData(server.capabilities) },
-    ...server.instructions === void 0 ? {} : { instructions: server.instructions }
-  });
+    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;
-  return Object.freeze({
+  let snapshot = {
     name: tool.name,
     mcp: Object.freeze({ ...tool.mcp }),
-    ...tool.requiresApproval === void 0 ? {} : { requiresApproval: tool.requiresApproval },
     definition: (prompt) => tool.definition(prompt),
-    call: (args, context) => tool.call(args, context),
-    ...parseInput === void 0 ? {} : { parseInput: (args) => parseInput.call(tool, args) }
-  });
+    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();
@@ -3725,69 +4582,118 @@ function assertUniqueMcpServerNames(servers) {
 }
 function snapshotToolIndex(index) {
   const inspect = index.inspect;
-  return Object.freeze({
+  let snapshot = {
     kind: "tool-index",
     tools: Object.freeze([...index.tools]),
     topK: index.topK,
-    ...index.minScore === void 0 ? {} : { minScore: index.minScore },
-    ...index.filter === void 0 ? {} : { filter: cloneFrozenPlainData(index.filter) },
-    search: (options) => index.search(options),
-    ...inspect === void 0 ? {} : { inspect: (request) => inspect.call(index, request) }
-  });
-}
-function snapshotGuardrailPolicy(policy) {
-  return Object.freeze({
-    ...policy,
-    input: Object.freeze([...policy.input]),
-    output: Object.freeze([...policy.output])
-  });
-}
-function snapshotAgentMemory(memory) {
-  if (memory === void 0) {
-    return void 0;
+    search: (options) => index.search(options)
+  };
+  if (index.minScore !== void 0) {
+    snapshot = { ...snapshot, minScore: index.minScore };
   }
-  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 })
-  });
-  return Object.freeze({
-    store: memory.store,
-    savePolicy: memory.savePolicy,
-    ...compaction === void 0 ? {} : { compaction }
-  });
+  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);
 }
-function cloneFrozenPlainData(value) {
-  if (Array.isArray(value)) {
-    return Object.freeze(value.map(cloneFrozenPlainData));
+
+// 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;
+    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);
   }
-  if (typeof value !== "object" || value === null) {
-    return value;
+  generate(options) {
+    return AgentRun.fromAgent(this, options).generate();
   }
-  const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) {
-    return value;
+  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);
   }
-  const clone = Object.fromEntries(
-    Object.entries(value).map(([key, item]) => [key, cloneFrozenPlainData(item)])
-  );
-  return Object.freeze(clone);
-}
+  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 {
-  MaxTurnsError,
-  AgentRunCancelledError,
-  AgentRunBlockedError,
+  agentInteractionRequestSchema,
+  agentInteractionResponseSchema,
+  agentContinuationSchema,
+  parseAgentInteractionRequest,
+  parseAgentInteractionResponse,
+  parseAgentContinuation,
+  assertAgentInteractionResponse,
   getAgentToolState,
   createHook,
-  getAgentApprovalRequestDetails,
   createVectorContext,
   isVectorContext,
   withInternalAgentRunOptions,
-  Agent,
-  createResolvedAgent,
-  getResolvedAgentOptions,
-  cancelAgentApproval
+  markResolvedAgentOptions,
+  Agent
 };
-//# sourceMappingURL=chunk-DBSCKTUL.js.map
+//# sourceMappingURL=chunk-5GXSQYQT.js.map