@anvia/core 1.11.1 → 1.13.0

package/README.md

@@ -46,6 +46,42 @@ if (result.type === "response") console.log(result.output);
 Replace the sample tool body with your application's data access. Agent outcomes distinguish a
 response, a guardrail block, and an interaction that needs application input.
 
+## Ask the user a question
+
+Add `createQuestionTool()` to an agent's `tools` to let it ask for missing information:
+
+```ts
+import {
+  createQuestionTool,
+  DEFAULT_QUESTION_TOOL_NAME,
+  DEFAULT_QUESTION_TOOL_DESCRIPTION,
+} from "@anvia/core/tool";
+
+const askUser = createQuestionTool(); // name: "ask_user", with built-in model instructions
+const clarify = createQuestionTool({ name: "clarify" }); // either option can be overridden
+```
+
+The defaults are also exported from `@anvia/core`. The description guides the model to ask only
+when it cannot proceed, batch questions, and use sensible defaults for routine choices.
+Supply nonblank custom names and descriptions. Defaults apply when an option is omitted;
+explicit strings, including blanks, are preserved for compatibility with existing callers.
+New tool calls accept 1–4 questions with unique, nonblank IDs and nonblank text. Optional choices
+must contain 2–4 entries with nonblank labels and unique, nonblank values. Values are trimmed
+before validation. Set `allowCustom: true` to allow answers outside the choices, or omit choices
+for free text. A question without choices cannot set `allowCustom: false`.
+Snake-case IDs, question marks, and mutually exclusive choices are model guidance,
+not additional schema restrictions.
+
+The run returns a `type: "interaction"` outcome with a `tool-question` request and a continuation.
+Collect a nonblank answer for every question, then resume with the continuation and
+`{ type: "tool-question", answers: [{ questionId, value }] }`. The model receives
+`{ answers: [...] }` as the tool result. Calling the question tool directly does not prompt a UI;
+your application renders the interaction and supplies the answers.
+
+Stored interaction requests and continuations keep their existing parsing rules; the new array
+limits apply only to new tool inputs. See the [interaction guide](../../docs/packages/core.md)
+for the resume protocol.
+
 ## What you can build
 
 - Agents with typed tools, approvals, questions, guardrails, and streaming responses.
@@ -66,10 +102,12 @@ streamed reasoning for replay on subsequent turns. Conflicting text, reasoning,
 fail provider output validation.
 
 For recoverable execution, register a supported agent with the experimental
-[`@anvia/durable`](../durable/README.md) runtime. Durable tools receive an optional stable
+[`@anvia/durable`](../durable/README.md) runtime. Internal execution protocol 4 adds a synchronous steering checkpoint boundary for
+persisting queued user input and replaying it consistently. Upgrade core and durable together.
+Durable tools receive an optional stable
 `ToolCallContext.operationId` for external idempotency. Direct execution does not supply it.
 Durable registrations can opt into persisted streaming with `stream: true`; core execution
-protocol version 2 checkpoints validated streamed completions alongside tool results.
+protocol version 4 checkpoints validated streamed completions alongside tool results.
 
 ## Learn more
 

package/dist/agent/agent.js

@@ -1,9 +1,9 @@
 import {
   Agent
-} from "../chunk-TXWNIEZU.js";
-import "../chunk-WU4ODZKR.js";
+} from "../chunk-HF5SX5BQ.js";
+import "../chunk-OZ2GZHWH.js";
 import "../chunk-SXE4J43E.js";
-import "../chunk-DRSKZVC6.js";
+import "../chunk-ED7RKQHE.js";
 import "../chunk-LAIATEUB.js";
 import "../chunk-3F6ZY63S.js";
 import "../chunk-ZWYMXBGB.js";
@@ -15,7 +15,7 @@ import "../chunk-5ZM5DB3O.js";
 import "../chunk-5IURMWFN.js";
 import "../chunk-2NLINXRF.js";
 import "../chunk-JMJFK3A4.js";
-import "../chunk-MNBKSRS5.js";
+import "../chunk-IRXAEVEQ.js";
 import "../chunk-CASF2TDK.js";
 import "../chunk-4AW2633B.js";
 import "../chunk-YNA3UR42.js";

package/dist/agent/index.js

@@ -1,9 +1,9 @@
 import "../chunk-53TPAXYR.js";
 import {
   AgentTeam
-} from "../chunk-GSMLYI4Z.js";
+} from "../chunk-D43A3KOF.js";
 import "../chunk-X6WS3XWL.js";
-import "../chunk-PLJQ4274.js";
+import "../chunk-CKWIXVXM.js";
 import "../chunk-PIMD4DYG.js";
 import "../chunk-FSBDE6RF.js";
 import "../chunk-3TAQXJBC.js";
@@ -12,13 +12,13 @@ import {
   AgentTeamInteractionError,
   AgentTeamLimitError
 } from "../chunk-ENZ2XX27.js";
-import "../chunk-7XDM7A3W.js";
+import "../chunk-22E25UM7.js";
 import {
   Agent
-} from "../chunk-TXWNIEZU.js";
-import "../chunk-WU4ODZKR.js";
+} from "../chunk-HF5SX5BQ.js";
+import "../chunk-OZ2GZHWH.js";
 import "../chunk-SXE4J43E.js";
-import "../chunk-DRSKZVC6.js";
+import "../chunk-ED7RKQHE.js";
 import "../chunk-LAIATEUB.js";
 import "../chunk-3F6ZY63S.js";
 import "../chunk-ZWYMXBGB.js";
@@ -30,7 +30,7 @@ import "../chunk-5ZM5DB3O.js";
 import "../chunk-5IURMWFN.js";
 import "../chunk-2NLINXRF.js";
 import "../chunk-JMJFK3A4.js";
-import "../chunk-MNBKSRS5.js";
+import "../chunk-IRXAEVEQ.js";
 import "../chunk-CASF2TDK.js";
 import "../chunk-4AW2633B.js";
 import "../chunk-YNA3UR42.js";

package/dist/agent/resolved-agent.js

@@ -1,11 +1,11 @@
 import {
   createResolvedAgent,
   getResolvedAgentOptions
-} from "../chunk-7XDM7A3W.js";
-import "../chunk-TXWNIEZU.js";
-import "../chunk-WU4ODZKR.js";
+} from "../chunk-22E25UM7.js";
+import "../chunk-HF5SX5BQ.js";
+import "../chunk-OZ2GZHWH.js";
 import "../chunk-SXE4J43E.js";
-import "../chunk-DRSKZVC6.js";
+import "../chunk-ED7RKQHE.js";
 import "../chunk-LAIATEUB.js";
 import "../chunk-3F6ZY63S.js";
 import "../chunk-ZWYMXBGB.js";
@@ -17,7 +17,7 @@ import "../chunk-5ZM5DB3O.js";
 import "../chunk-5IURMWFN.js";
 import "../chunk-2NLINXRF.js";
 import "../chunk-JMJFK3A4.js";
-import "../chunk-MNBKSRS5.js";
+import "../chunk-IRXAEVEQ.js";
 import "../chunk-CASF2TDK.js";
 import "../chunk-4AW2633B.js";
 import "../chunk-YNA3UR42.js";

package/dist/agent/team/agent-team.js

@@ -1,18 +1,18 @@
 import {
   AgentTeam
-} from "../../chunk-GSMLYI4Z.js";
+} from "../../chunk-D43A3KOF.js";
 import "../../chunk-X6WS3XWL.js";
-import "../../chunk-PLJQ4274.js";
+import "../../chunk-CKWIXVXM.js";
 import "../../chunk-PIMD4DYG.js";
 import "../../chunk-FSBDE6RF.js";
 import "../../chunk-3TAQXJBC.js";
 import "../../chunk-X35O3AQG.js";
 import "../../chunk-ENZ2XX27.js";
-import "../../chunk-7XDM7A3W.js";
-import "../../chunk-TXWNIEZU.js";
-import "../../chunk-WU4ODZKR.js";
+import "../../chunk-22E25UM7.js";
+import "../../chunk-HF5SX5BQ.js";
+import "../../chunk-OZ2GZHWH.js";
 import "../../chunk-SXE4J43E.js";
-import "../../chunk-DRSKZVC6.js";
+import "../../chunk-ED7RKQHE.js";
 import "../../chunk-LAIATEUB.js";
 import "../../chunk-3F6ZY63S.js";
 import "../../chunk-ZWYMXBGB.js";
@@ -24,7 +24,7 @@ import "../../chunk-5ZM5DB3O.js";
 import "../../chunk-5IURMWFN.js";
 import "../../chunk-2NLINXRF.js";
 import "../../chunk-JMJFK3A4.js";
-import "../../chunk-MNBKSRS5.js";
+import "../../chunk-IRXAEVEQ.js";
 import "../../chunk-CASF2TDK.js";
 import "../../chunk-4AW2633B.js";
 import "../../chunk-YNA3UR42.js";

package/dist/agent/team/index.js

@@ -1,9 +1,9 @@
 import "../../chunk-53TPAXYR.js";
 import {
   AgentTeam
-} from "../../chunk-GSMLYI4Z.js";
+} from "../../chunk-D43A3KOF.js";
 import "../../chunk-X6WS3XWL.js";
-import "../../chunk-PLJQ4274.js";
+import "../../chunk-CKWIXVXM.js";
 import "../../chunk-PIMD4DYG.js";
 import "../../chunk-FSBDE6RF.js";
 import "../../chunk-3TAQXJBC.js";
@@ -12,11 +12,11 @@ import {
   AgentTeamInteractionError,
   AgentTeamLimitError
 } from "../../chunk-ENZ2XX27.js";
-import "../../chunk-7XDM7A3W.js";
-import "../../chunk-TXWNIEZU.js";
-import "../../chunk-WU4ODZKR.js";
+import "../../chunk-22E25UM7.js";
+import "../../chunk-HF5SX5BQ.js";
+import "../../chunk-OZ2GZHWH.js";
 import "../../chunk-SXE4J43E.js";
-import "../../chunk-DRSKZVC6.js";
+import "../../chunk-ED7RKQHE.js";
 import "../../chunk-LAIATEUB.js";
 import "../../chunk-3F6ZY63S.js";
 import "../../chunk-ZWYMXBGB.js";
@@ -28,7 +28,7 @@ import "../../chunk-5ZM5DB3O.js";
 import "../../chunk-5IURMWFN.js";
 import "../../chunk-2NLINXRF.js";
 import "../../chunk-JMJFK3A4.js";
-import "../../chunk-MNBKSRS5.js";
+import "../../chunk-IRXAEVEQ.js";
 import "../../chunk-CASF2TDK.js";
 import "../../chunk-4AW2633B.js";
 import "../../chunk-YNA3UR42.js";

package/dist/{chunk-7XDM7A3W.js → chunk-22E25UM7.js}

@@ -1,6 +1,6 @@
 import {
   Agent
-} from "./chunk-TXWNIEZU.js";
+} from "./chunk-HF5SX5BQ.js";
 import {
   getAgentToolState
 } from "./chunk-A7BXVZXZ.js";
@@ -45,4 +45,4 @@ export {
   createResolvedAgent,
   getResolvedAgentOptions
 };
-//# sourceMappingURL=chunk-7XDM7A3W.js.map
+//# sourceMappingURL=chunk-22E25UM7.js.map

package/dist/{chunk-2K7NSWUC.js → chunk-AGOZCYFP.js}

@@ -1,3 +1,6 @@
+import {
+  extract
+} from "./chunk-VCOGUS3Q.js";
 import {
   resolveActual,
   resolveActualText,
@@ -5,15 +8,12 @@ import {
   resolveJudgePrompt
 } from "./chunk-ZPXOBQDS.js";
 import {
-  extract
-} from "./chunk-VCOGUS3Q.js";
+  EvalOutcome
+} from "./chunk-EJR6VVB3.js";
 import {
   evalValuesEqual,
   formatValue
 } from "./chunk-ZYXMWEL4.js";
-import {
-  EvalOutcome
-} from "./chunk-EJR6VVB3.js";
 import {
   embedText
 } from "./chunk-YCTXTOOQ.js";
@@ -328,4 +328,4 @@ export {
   llmJudge,
   llmScore
 };
-//# sourceMappingURL=chunk-2K7NSWUC.js.map
+//# sourceMappingURL=chunk-AGOZCYFP.js.map

package/dist/{chunk-PLJQ4274.js → chunk-CKWIXVXM.js}

@@ -19,10 +19,10 @@ import {
 import {
   createResolvedAgent,
   getResolvedAgentOptions
-} from "./chunk-7XDM7A3W.js";
+} from "./chunk-22E25UM7.js";
 import {
   AgentRun
-} from "./chunk-WU4ODZKR.js";
+} from "./chunk-OZ2GZHWH.js";
 import {
   withInternalAgentRunOptions
 } from "./chunk-7FBSGD6E.js";
@@ -619,4 +619,4 @@ var TeamRun = class {
 export {
   TeamRun
 };
-//# sourceMappingURL=chunk-PLJQ4274.js.map
+//# sourceMappingURL=chunk-CKWIXVXM.js.map

package/dist/{chunk-GSMLYI4Z.js → chunk-D43A3KOF.js}

@@ -3,13 +3,13 @@ import {
 } from "./chunk-X6WS3XWL.js";
 import {
   TeamRun
-} from "./chunk-PLJQ4274.js";
+} from "./chunk-CKWIXVXM.js";
 import {
   TeamStream
 } from "./chunk-3TAQXJBC.js";
 import {
   Agent
-} from "./chunk-TXWNIEZU.js";
+} from "./chunk-HF5SX5BQ.js";
 import {
   assertPositiveSafeInteger
 } from "./chunk-NPJ2T3L5.js";
@@ -104,4 +104,4 @@ var AgentTeam = class {
 export {
   AgentTeam
 };
-//# sourceMappingURL=chunk-GSMLYI4Z.js.map
+//# sourceMappingURL=chunk-D43A3KOF.js.map

package/dist/{chunk-DRSKZVC6.js → chunk-ED7RKQHE.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-2NLINXRF.js";
 import {
   isQuestionTool
-} from "./chunk-MNBKSRS5.js";
+} from "./chunk-IRXAEVEQ.js";
 import {
   runControl,
   toolCallControl
@@ -967,4 +967,4 @@ function agentToolEventPayload(toolCall, internalCallId, event) {
 export {
   ToolCallExecutor
 };
-//# sourceMappingURL=chunk-DRSKZVC6.js.map
+//# sourceMappingURL=chunk-ED7RKQHE.js.map

package/dist/{chunk-TXWNIEZU.js → chunk-HF5SX5BQ.js}

@@ -1,6 +1,6 @@
 import {
   AgentRun
-} from "./chunk-WU4ODZKR.js";
+} from "./chunk-OZ2GZHWH.js";
 import {
   normalizeMemoryScope
 } from "./chunk-LAIATEUB.js";
@@ -155,4 +155,4 @@ var Agent = class {
 export {
   Agent
 };
-//# sourceMappingURL=chunk-TXWNIEZU.js.map
+//# sourceMappingURL=chunk-HF5SX5BQ.js.map

package/dist/chunk-IRXAEVEQ.js

@@ -0,0 +1,105 @@
+import {
+  createTool
+} from "./chunk-MEFGXAKJ.js";
+
+// src/tool/question-tool.ts
+import { z } from "zod";
+var questionToolMarker = /* @__PURE__ */ Symbol("anvia.question-tool");
+var DEFAULT_QUESTION_TOOL_NAME = "ask_user";
+var DEFAULT_QUESTION_TOOL_DESCRIPTION = `Ask the user questions and wait for their answers before continuing.
+
+Use this tool only when you cannot continue without the user's input:
+- The request is ambiguous, and different readings would lead to clearly different results.
+- A decision belongs to the user: a preference, a tradeoff, or something that is hard to undo.
+- Information you need is missing and you cannot find it with your other tools or work it out from the conversation.
+
+Do not use it:
+- For facts you can look up with your other tools, or work out from the conversation.
+- To ask permission for routine steps the user has already asked for.
+- To check whether your answer or plan is good. Finish the work and let the user react.
+- For choices with a sensible default. Pick it, and mention the choice in your reply.
+
+How to ask:
+- Put every question you need into one call instead of calling the tool repeatedly. Ask no more than 4 questions per call.
+- Give each question a short, unique \`id\` in snake_case.
+- Write \`text\` as one complete, self-contained question that ends with a question mark.
+- When there is a known set of reasonable answers, give 2\u20134 \`choices\` with a short \`label\` and a stable \`value\`. Make the choices mutually exclusive. If you recommend one, list it first and add " (recommended)" to its label.
+- Set \`allowCustom: true\` when the user might want an answer outside the list. Leave out \`choices\` for open-ended questions. Do not add an "Other" choice.
+
+After you get the answers:
+- Each answer has a \`questionId\` and a \`value\` (the chosen value or the user's free text).
+- Follow the answers. Do not ask the same question again unless an answer is unclear or contradicts another one.`;
+function createQuestionTool(options = {}) {
+  const tool = createTool({
+    name: options.name ?? DEFAULT_QUESTION_TOOL_NAME,
+    description: options.description ?? DEFAULT_QUESTION_TOOL_DESCRIPTION,
+    inputSchema: z.object({
+      questions: z.array(
+        z.object({
+          id: z.string().trim().min(1, "Question IDs must not be empty."),
+          text: z.string().trim().min(1, "Question text must not be empty."),
+          choices: z.array(
+            z.object({
+              label: z.string().trim().min(1, "Question choice labels must not be empty."),
+              value: z.string().trim().min(1, "Question choice values must not be empty.")
+            }).strict()
+          ).min(2, "Questions with choices must have at least 2 choices.").max(4, "Questions must have no more than 4 choices.").superRefine((choices, context) => {
+            const values = /* @__PURE__ */ new Set();
+            for (const [index, choice] of choices.entries()) {
+              if (values.has(choice.value)) {
+                context.addIssue({
+                  code: "custom",
+                  message: "Question choice values must be unique.",
+                  path: [index, "value"]
+                });
+              }
+              values.add(choice.value);
+            }
+          }).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"]
+            });
+          }
+        })
+      ).min(1, "Provide at least 1 question.").max(4, "Ask no more than 4 questions per call.").superRefine((questions, context) => {
+        const ids = /* @__PURE__ */ new Set();
+        for (const [index, question] of questions.entries()) {
+          if (ids.has(question.id)) {
+            context.addIssue({
+              code: "custom",
+              message: "Question IDs must be unique.",
+              path: [index, "id"]
+            });
+          }
+          ids.add(question.id);
+        }
+      })
+    }).strict(),
+    execute() {
+      throw new Error("Question tools can only be resolved through an Agent interaction.");
+    }
+  });
+  Object.defineProperty(tool, questionToolMarker, {
+    configurable: false,
+    enumerable: false,
+    value: true,
+    writable: false
+  });
+  return tool;
+}
+function isQuestionTool(tool) {
+  return typeof tool === "object" && tool !== null && questionToolMarker in tool;
+}
+
+export {
+  DEFAULT_QUESTION_TOOL_NAME,
+  DEFAULT_QUESTION_TOOL_DESCRIPTION,
+  createQuestionTool,
+  isQuestionTool
+};
+//# sourceMappingURL=chunk-IRXAEVEQ.js.map

package/dist/chunk-IRXAEVEQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tool/question-tool.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type { AgentQuestionAnswer, AgentQuestionPrompt } from \"../agent/interactions\";\nimport { createTool } from \"./create-tool\";\nimport type { Tool } from \"./tool\";\n\nconst questionToolMarker = Symbol(\"anvia.question-tool\");\n\nexport const DEFAULT_QUESTION_TOOL_NAME = \"ask_user\";\n\nexport const DEFAULT_QUESTION_TOOL_DESCRIPTION = `Ask the user questions and wait for their answers before continuing.\n\nUse this tool only when you cannot continue without the user's input:\n- The request is ambiguous, and different readings would lead to clearly different results.\n- A decision belongs to the user: a preference, a tradeoff, or something that is hard to undo.\n- Information you need is missing and you cannot find it with your other tools or work it out from the conversation.\n\nDo not use it:\n- For facts you can look up with your other tools, or work out from the conversation.\n- To ask permission for routine steps the user has already asked for.\n- To check whether your answer or plan is good. Finish the work and let the user react.\n- For choices with a sensible default. Pick it, and mention the choice in your reply.\n\nHow to ask:\n- Put every question you need into one call instead of calling the tool repeatedly. Ask no more than 4 questions per call.\n- Give each question a short, unique \\`id\\` in snake_case.\n- Write \\`text\\` as one complete, self-contained question that ends with a question mark.\n- When there is a known set of reasonable answers, give 2–4 \\`choices\\` with a short \\`label\\` and a stable \\`value\\`. Make the choices mutually exclusive. If you recommend one, list it first and add \" (recommended)\" to its label.\n- Set \\`allowCustom: true\\` when the user might want an answer outside the list. Leave out \\`choices\\` for open-ended questions. Do not add an \"Other\" choice.\n\nAfter you get the answers:\n- Each answer has a \\`questionId\\` and a \\`value\\` (the chosen value or the user's free text).\n- Follow the answers. Do not ask the same question again unless an answer is unclear or contradicts another one.`;\n\nexport type QuestionToolInput = {\n  questions: readonly AgentQuestionPrompt[];\n};\n\nexport type QuestionToolOutput = {\n  answers: readonly AgentQuestionAnswer[];\n};\n\nexport type CreateQuestionToolOptions = {\n  /** Defaults when omitted. Supply a nonblank name; explicit strings are preserved. */\n  name?: string;\n  /** Defaults when omitted. Supply nonblank instructions; explicit strings are preserved. */\n  description?: string;\n};\n\ntype MarkedQuestionTool = Tool<QuestionToolInput, QuestionToolOutput> & {\n  readonly [questionToolMarker]: true;\n};\n\nexport function createQuestionTool(\n  options: CreateQuestionToolOptions = {},\n): Tool<QuestionToolInput, QuestionToolOutput> {\n  const tool = createTool({\n    name: options.name ?? DEFAULT_QUESTION_TOOL_NAME,\n    description: options.description ?? DEFAULT_QUESTION_TOOL_DESCRIPTION,\n    inputSchema: z\n      .object({\n        questions: z\n          .array(\n            z\n              .object({\n                id: z.string().trim().min(1, \"Question IDs must not be empty.\"),\n                text: z.string().trim().min(1, \"Question text must not be empty.\"),\n                choices: z\n                  .array(\n                    z\n                      .object({\n                        label: z\n                          .string()\n                          .trim()\n                          .min(1, \"Question choice labels must not be empty.\"),\n                        value: z\n                          .string()\n                          .trim()\n                          .min(1, \"Question choice values must not be empty.\"),\n                      })\n                      .strict(),\n                  )\n                  .min(2, \"Questions with choices must have at least 2 choices.\")\n                  .max(4, \"Questions must have no more than 4 choices.\")\n                  .superRefine((choices, context) => {\n                    const values = new Set<string>();\n                    for (const [index, choice] of choices.entries()) {\n                      if (values.has(choice.value)) {\n                        context.addIssue({\n                          code: \"custom\",\n                          message: \"Question choice values must be unique.\",\n                          path: [index, \"value\"],\n                        });\n                      }\n                      values.add(choice.value);\n                    }\n                  })\n                  .optional(),\n                allowCustom: z.boolean().optional(),\n              })\n              .strict()\n              .superRefine((question, context) => {\n                if (question.choices === undefined && question.allowCustom === false) {\n                  context.addIssue({\n                    code: \"custom\",\n                    message: \"A free-text question cannot disable custom answers.\",\n                    path: [\"allowCustom\"],\n                  });\n                }\n              }),\n          )\n          .min(1, \"Provide at least 1 question.\")\n          .max(4, \"Ask no more than 4 questions per call.\")\n          .superRefine((questions, context) => {\n            const ids = new Set<string>();\n            for (const [index, question] of questions.entries()) {\n              if (ids.has(question.id)) {\n                context.addIssue({\n                  code: \"custom\",\n                  message: \"Question IDs must be unique.\",\n                  path: [index, \"id\"],\n                });\n              }\n              ids.add(question.id);\n            }\n          }),\n      })\n      .strict(),\n    execute(): never {\n      throw new Error(\"Question tools can only be resolved through an Agent interaction.\");\n    },\n  }) as unknown as MarkedQuestionTool;\n  Object.defineProperty(tool, questionToolMarker, {\n    configurable: false,\n    enumerable: false,\n    value: true,\n    writable: false,\n  });\n  return tool;\n}\n\nexport function isQuestionTool(tool: unknown): tool is Tool<QuestionToolInput, QuestionToolOutput> {\n  return typeof tool === \"object\" && tool !== null && questionToolMarker in tool;\n}\n"],"mappings":";;;;;AAAA,SAAS,SAAS;AAKlB,IAAM,qBAAqB,uBAAO,qBAAqB;AAEhD,IAAM,6BAA6B;AAEnC,IAAM,oCAAoC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA2C1C,SAAS,mBACd,UAAqC,CAAC,GACO;AAC7C,QAAM,OAAO,WAAW;AAAA,IACtB,MAAM,QAAQ,QAAQ;AAAA,IACtB,aAAa,QAAQ,eAAe;AAAA,IACpC,aAAa,EACV,OAAO;AAAA,MACN,WAAW,EACR;AAAA,QACC,EACG,OAAO;AAAA,UACN,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,GAAG,iCAAiC;AAAA,UAC9D,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,GAAG,kCAAkC;AAAA,UACjE,SAAS,EACN;AAAA,YACC,EACG,OAAO;AAAA,cACN,OAAO,EACJ,OAAO,EACP,KAAK,EACL,IAAI,GAAG,2CAA2C;AAAA,cACrD,OAAO,EACJ,OAAO,EACP,KAAK,EACL,IAAI,GAAG,2CAA2C;AAAA,YACvD,CAAC,EACA,OAAO;AAAA,UACZ,EACC,IAAI,GAAG,sDAAsD,EAC7D,IAAI,GAAG,6CAA6C,EACpD,YAAY,CAAC,SAAS,YAAY;AACjC,kBAAM,SAAS,oBAAI,IAAY;AAC/B,uBAAW,CAAC,OAAO,MAAM,KAAK,QAAQ,QAAQ,GAAG;AAC/C,kBAAI,OAAO,IAAI,OAAO,KAAK,GAAG;AAC5B,wBAAQ,SAAS;AAAA,kBACf,MAAM;AAAA,kBACN,SAAS;AAAA,kBACT,MAAM,CAAC,OAAO,OAAO;AAAA,gBACvB,CAAC;AAAA,cACH;AACA,qBAAO,IAAI,OAAO,KAAK;AAAA,YACzB;AAAA,UACF,CAAC,EACA,SAAS;AAAA,UACZ,aAAa,EAAE,QAAQ,EAAE,SAAS;AAAA,QACpC,CAAC,EACA,OAAO,EACP,YAAY,CAAC,UAAU,YAAY;AAClC,cAAI,SAAS,YAAY,UAAa,SAAS,gBAAgB,OAAO;AACpE,oBAAQ,SAAS;AAAA,cACf,MAAM;AAAA,cACN,SAAS;AAAA,cACT,MAAM,CAAC,aAAa;AAAA,YACtB,CAAC;AAAA,UACH;AAAA,QACF,CAAC;AAAA,MACL,EACC,IAAI,GAAG,8BAA8B,EACrC,IAAI,GAAG,wCAAwC,EAC/C,YAAY,CAAC,WAAW,YAAY;AACnC,cAAM,MAAM,oBAAI,IAAY;AAC5B,mBAAW,CAAC,OAAO,QAAQ,KAAK,UAAU,QAAQ,GAAG;AACnD,cAAI,IAAI,IAAI,SAAS,EAAE,GAAG;AACxB,oBAAQ,SAAS;AAAA,cACf,MAAM;AAAA,cACN,SAAS;AAAA,cACT,MAAM,CAAC,OAAO,IAAI;AAAA,YACpB,CAAC;AAAA,UACH;AACA,cAAI,IAAI,SAAS,EAAE;AAAA,QACrB;AAAA,MACF,CAAC;AAAA,IACL,CAAC,EACA,OAAO;AAAA,IACV,UAAiB;AACf,YAAM,IAAI,MAAM,mEAAmE;AAAA,IACrF;AAAA,EACF,CAAC;AACD,SAAO,eAAe,MAAM,oBAAoB;AAAA,IAC9C,cAAc;AAAA,IACd,YAAY;AAAA,IACZ,OAAO;AAAA,IACP,UAAU;AAAA,EACZ,CAAC;AACD,SAAO;AACT;AAEO,SAAS,eAAe,MAAoE;AACjG,SAAO,OAAO,SAAS,YAAY,SAAS,QAAQ,sBAAsB;AAC5E;","names":[]}

package/dist/{chunk-GNBPXJC6.js → chunk-KL652GO5.js}

@@ -1,6 +1,6 @@
 import {
   runEvalSuite
-} from "./chunk-4IOC4SP6.js";
+} from "./chunk-KLDNHX4Z.js";
 
 // src/evals/cli.ts
 var EvalAssertionError = class extends Error {
@@ -352,4 +352,4 @@ export {
   assertEvalOutcomes,
   runEvalCli
 };
-//# sourceMappingURL=chunk-GNBPXJC6.js.map
+//# sourceMappingURL=chunk-KL652GO5.js.map

package/dist/{chunk-4IOC4SP6.js → chunk-KLDNHX4Z.js}

@@ -1,9 +1,6 @@
 import {
   defaultEvalTraceSelector
 } from "./chunk-PHLGGRHC.js";
-import {
-  errorMessage
-} from "./chunk-ZYXMWEL4.js";
 import {
   EvalOutcome
 } from "./chunk-EJR6VVB3.js";
@@ -14,6 +11,9 @@ import {
   createConcurrencyLimiter,
   createEvalCaseSignal
 } from "./chunk-4OSA3MMA.js";
+import {
+  errorMessage
+} from "./chunk-ZYXMWEL4.js";
 import {
   Usage
 } from "./chunk-HJ6KTQTZ.js";
@@ -660,4 +660,4 @@ export {
   EvalFailFastError,
   runEvalSuite
 };
-//# sourceMappingURL=chunk-4IOC4SP6.js.map
+//# sourceMappingURL=chunk-KLDNHX4Z.js.map

package/dist/{chunk-SHSSCEGO.js → chunk-MG7JYQN2.js}

@@ -1,7 +1,7 @@
 // src/internal/agent-runtime/execution.ts
-var AGENT_RUN_EXECUTION_VERSION = 3;
+var AGENT_RUN_EXECUTION_VERSION = 4;
 
 export {
   AGENT_RUN_EXECUTION_VERSION
 };
-//# sourceMappingURL=chunk-SHSSCEGO.js.map
+//# sourceMappingURL=chunk-MG7JYQN2.js.map

package/dist/chunk-MG7JYQN2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/agent-runtime/execution.ts"],"sourcesContent":["import type { PreparedLoopContext, LoopContextCheckpoint } from \"./loop-context\";\nimport type {\n  CompletionRequest,\n  CompletionResponse,\n  ToolCallPart,\n  Message,\n  UserMessage,\n} from \"../../completion\";\nimport type { NormalizedToolOutput, ToolCallContext } from \"../../tool\";\nimport type { AgentStreamEvent } from \"../../agent/run-types\";\n\n/** Runtime capability marker: older core versions must fail before accepting durable work. */\nexport const AGENT_RUN_EXECUTION_VERSION = 4;\n\n/** Normalized generation progress; never includes raw provider responses. */\nexport type AgentCompletionStreamEvent = Extract<\n  AgentStreamEvent<unknown, unknown>,\n  {\n    type:\n      | \"text_delta\"\n      | \"reasoning_delta\"\n      | \"tool_call_delta\"\n      | \"tool_call\"\n      | \"source\"\n      | \"provider_tool_call\";\n  }\n>;\n\nexport type AgentCompletionStream = AsyncGenerator<AgentCompletionStreamEvent, CompletionResponse>;\n\nexport type AgentToolExecutionResult =\n  | { output: NormalizedToolOutput; failed: false }\n  | { output: NormalizedToolOutput; failed: true; error: unknown };\n\n/** Internal persistence boundary used by execution runtimes. Callbacks own external effects. */\nexport interface AgentRunExecution {\n  /** Synchronously checkpoint queued input at a safe boundary, including empty/closing drains. */\n  drainSteering?(turn: number, closing: boolean): { id: string; messages: UserMessage[] }[];\n  /** Persist the context selected before each model call, including skipped compaction decisions. */\n  prepareMessages?(\n    turn: number,\n    messages: readonly Message[],\n    checkpoint?: LoopContextCheckpoint,\n  ): Promise<PreparedLoopContext>;\n  completion(\n    turn: number,\n    request: CompletionRequest,\n    execute: () => Promise<CompletionResponse>,\n  ): Promise<CompletionResponse>;\n  streamCompletion?(\n    turn: number,\n    request: CompletionRequest,\n    execute: () => AgentCompletionStream,\n  ): AgentCompletionStream;\n  tool(\n    call: { turn: number; toolCall: ToolCallPart; args: string },\n    execute: (context?: Pick<ToolCallContext, \"operationId\">) => Promise<AgentToolExecutionResult>,\n  ): Promise<AgentToolExecutionResult>;\n}\n"],"mappings":";AAYO,IAAM,8BAA8B;","names":[]}

package/dist/{chunk-WU4ODZKR.js → chunk-OZ2GZHWH.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-SXE4J43E.js";
 import {
   ToolCallExecutor
-} from "./chunk-DRSKZVC6.js";
+} from "./chunk-ED7RKQHE.js";
 import {
   normalizeMemoryScope
 } from "./chunk-LAIATEUB.js";
@@ -41,7 +41,7 @@ import {
 } from "./chunk-5IURMWFN.js";
 import {
   isQuestionTool
-} from "./chunk-MNBKSRS5.js";
+} from "./chunk-IRXAEVEQ.js";
 import {
   startAgentRunObservers
 } from "./chunk-YNA3UR42.js";
@@ -384,6 +384,9 @@ var AgentRun = class _AgentRun {
           throw error;
         }
       }
+      if (this.continuationState === void 0 && this.execution?.drainSteering !== void 0) {
+        await this.drainSteeringMessages(runId, 0, newMessages, pendingTurnMessages);
+      }
       while (currentTurns <= this.maxTurnCount) {
         const prompt = newMessages.at(-1);
         if (prompt === void 0) {
@@ -695,6 +698,9 @@ var AgentRun = class _AgentRun {
           throw error;
         }
       }
+      if (this.continuationState === void 0 && this.execution?.drainSteering !== void 0) {
+        await this.drainSteeringMessages(runId, 0, newMessages, pendingTurnMessages);
+      }
       while (currentTurns <= this.maxTurnCount) {
         const prompt = newMessages.at(-1);
         if (prompt === void 0) {
@@ -1912,7 +1918,10 @@ var AgentRun = class _AgentRun {
     return this.activeHook?.onCompletionResponse !== void 0 || this.activeMiddlewares().some((middleware) => middleware.onCompletionResponse !== void 0);
   }
   async drainSteeringMessages(runId, turn, newMessages, pendingTurnMessages, options = {}) {
-    const receipts = this.steeringMessages.splice(0);
+    const receipts = [
+      ...this.execution?.drainSteering?.(turn, options.closeWhenEmpty === true) ?? [],
+      ...this.steeringMessages.splice(0)
+    ];
     if (receipts.length === 0) {
       if (options.closeWhenEmpty === true) {
         this.runState = "closing";
@@ -2384,4 +2393,4 @@ function observerRunEnd(outcome) {
 export {
   AgentRun
 };
-//# sourceMappingURL=chunk-WU4ODZKR.js.map
+//# sourceMappingURL=chunk-OZ2GZHWH.js.map