@springbrand/agent-runtime 0.2.0-alpha.59 → 0.2.0-alpha.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.59",
+  "version": "0.2.0-alpha.61",
   "type": "module",
   "files": [
     "src",

package/src/lib/prompt.ts

@@ -109,8 +109,10 @@ export const FILES =
 // User-interaction actions are called only when their UI semantics are useful.
 export const INTERACTION =
   "Interaction: When progress requires user decisions, put all 1-10 necessary questions in one ask_user call " +
-  "instead of asking each question separately or writing 'please choose A/B/C' as text. Use 2-6 options for " +
-  "a bounded choice; for required free text, omit the options field entirely — never pass an empty or single-item options array; " +
+  "instead of asking each question separately or writing 'please choose A/B/C' as text. Every question must set exactly one responseType. " +
+  "Use responseType: \"single_select\" or responseType: \"multi_select\" with 2-6 options for choices; use responseType: \"text\" " +
+  "for free text; use responseType: \"attachment\" for one or more files. Set required: true only when progress cannot continue " +
+  "without that answer; required defaults to false. At most one question may request attachments. Do not add an accept field or tell the user to upload through the normal chat composer; " +
   "continue the same turn when its result arrives. " +
   "Don't use it when a sensible default lets you proceed. " +
   "After completing a substantive task (report, analysis, multi-step job), finish all work and other Tool calls, " +

package/src/pi/tool/base.ts

@@ -17,53 +17,46 @@ import type { PiToolCandidate } from "./compiler";
 import { webSearchPiToolCandidate } from "./web-search";
 import type { WebSearch } from "./web-search/api";
 
-const askUserOrdinaryQuestion = Type.Object({
+const askUserResponseTypes = [
+  "text",
+  "single_select",
+  "multi_select",
+  "attachment",
+] as const;
+
+const askUserQuestion = Type.Object({
   question: Type.String({
     minLength: 1,
-    description: "The question to put to the user.",
+    description: "The question or file request to put to the user.",
+  }),
+  responseType: StringEnum(askUserResponseTypes, {
+    description:
+      "Required response UI: text, single_select, multi_select, or attachment.",
   }),
   options: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
     minItems: 2,
     maxItems: 6,
     uniqueItems: true,
     description:
-      "For a bounded choice, provide 2-6 mutually distinct options. For required free text, omit this field entirely; never pass an empty or single-item array.",
-  })),
-  multiSelect: Type.Optional(Type.Boolean({
-    description:
-      "Whether the user may select more than one option. Defaults to false.",
+      "Required only for single_select or multi_select. Provide 2-6 distinct options; omit for text and attachment.",
   })),
   allowCustom: Type.Optional(Type.Boolean({
     description:
-      "Whether the user may add free text. Defaults to false with options and true without options.",
+      "For single_select or multi_select, whether the user may also add free text. Defaults to false.",
   })),
-}, { additionalProperties: false });
-
-const askUserAttachmentQuestion = Type.Object({
-  question: Type.String({
-    minLength: 1,
-    description: "The request for one or more user files.",
-  }),
-  kind: Type.Literal("attachment", {
+  required: Type.Optional(Type.Boolean({
+    default: false,
     description:
-      "Use attachment when the user must upload one or more files to continue.",
-  }),
+      "Whether the user must answer this question to submit. Defaults to false.",
+  })),
 }, { additionalProperties: false });
 
-const askUserQuestion = Type.Union([
-  askUserOrdinaryQuestion,
-  askUserAttachmentQuestion,
-]);
-
 const askUserParameters = Type.Object({
   questions: Type.Array(askUserQuestion, {
     minItems: 1,
     maxItems: 10,
-    contains: askUserAttachmentQuestion,
-    minContains: 0,
-    maxContains: 1,
     description:
-      "All user decisions and files needed to continue. Ask them together in one call. At most one question may have kind attachment.",
+      "All user decisions and files needed to continue. Every question requires responseType. At most one question may use attachment.",
   }),
 }, { additionalProperties: false });
 
@@ -82,10 +75,11 @@ type AskUserFile = {
   readonly providerMetadata?: unknown;
 };
 type AskUserResponse = {
-  readonly answers: ReadonlyArray<
-    | { readonly selections: readonly string[]; readonly text?: string }
-    | { readonly attachments: readonly AskUserFile[] }
-  >;
+  readonly answers: ReadonlyArray<{
+    readonly selections: readonly string[];
+    readonly text: string;
+    readonly attachments: readonly AskUserFile[];
+  }>;
 };
 
 function recordOf(value: unknown): Record<string, unknown> | null {
@@ -94,55 +88,118 @@ function recordOf(value: unknown): Record<string, unknown> | null {
     : null;
 }
 
-function questionsOf(value: unknown): AskUserInput["questions"] | null {
+function questionsOf(
+  value: unknown,
+  allowLegacy = false,
+): AskUserInput["questions"] | null {
   const questions = recordOf(value)?.questions;
   if (!Array.isArray(questions) || questions.length < 1 || questions.length > 10) {
     return null;
   }
+  const normalized: AskUserInput["questions"] = [];
   let attachmentQuestions = 0;
   for (const value of questions) {
     const question = recordOf(value);
     if (!question || typeof question.question !== "string" || !question.question) {
       return null;
     }
-    if ("kind" in question && question.kind === "attachment") {
+    if (
+      question.required !== undefined && typeof question.required !== "boolean"
+    ) return null;
+    const required = question.required === true;
+    let responseType = question.responseType;
+    if (
+      typeof responseType !== "string" ||
+      !askUserResponseTypes.includes(
+        responseType as typeof askUserResponseTypes[number],
+      )
+    ) {
+      if (!allowLegacy || question.responseType !== undefined) return null;
+      if (question.kind === "attachment") {
+        responseType = "attachment";
+      } else if (question.kind === undefined) {
+        responseType = Array.isArray(question.options)
+          ? question.multiSelect === true
+            ? "multi_select"
+            : "single_select"
+          : "text";
+      } else {
+        return null;
+      }
+    }
+    const normalizedQuestion = {
+      question: question.question,
+      responseType: responseType as typeof askUserResponseTypes[number],
+      required,
+    };
+    if (responseType === "attachment") {
       attachmentQuestions += 1;
       if (
         attachmentQuestions > 1 ||
         question.options !== undefined ||
-        question.multiSelect !== undefined ||
-        question.allowCustom !== undefined
+        question.allowCustom !== undefined ||
+        (!allowLegacy && question.multiSelect !== undefined)
       ) return null;
+      normalized.push(normalizedQuestion);
+      continue;
+    }
+    if (responseType === "text") {
+      if (
+        question.options !== undefined ||
+        (!allowLegacy &&
+          (question.allowCustom !== undefined || question.multiSelect !== undefined))
+      ) {
+        return null;
+      }
+      normalized.push(normalizedQuestion);
       continue;
     }
-    if (question.kind !== undefined) return null;
     if (
-      question.multiSelect !== undefined &&
-      typeof question.multiSelect !== "boolean"
+      !Array.isArray(question.options) ||
+      question.options.length < 2 ||
+      question.options.length > 6 ||
+      !question.options.every((option) =>
+        typeof option === "string" && option.length > 0
+      ) ||
+      new Set(question.options).size !== question.options.length ||
+      (question.allowCustom !== undefined &&
+        typeof question.allowCustom !== "boolean")
     ) return null;
     if (
-      question.allowCustom !== undefined &&
-      typeof question.allowCustom !== "boolean"
+      !allowLegacy &&
+      (question.kind !== undefined || question.multiSelect !== undefined)
     ) return null;
-    if (question.options !== undefined) {
-      if (
-        !Array.isArray(question.options) ||
-        question.options.length < 2 ||
-        question.options.length > 6 ||
-        !question.options.every((option) =>
-          typeof option === "string" && option.length > 0
-        ) ||
-        new Set(question.options).size !== question.options.length
-      ) return null;
+    normalized.push({
+      ...normalizedQuestion,
+      options: question.options,
+      ...(question.allowCustom === undefined
+        ? {}
+        : { allowCustom: question.allowCustom }),
+    });
+  }
+  return normalized;
+}
+
+function prepareAskUserArguments(input: unknown): AskUserInput {
+  const value = recordOf(input);
+  if (!value) throw new Error("Invalid ask_user questions");
+  let questions = value.questions;
+  if (typeof questions === "string") {
+    try {
+      questions = JSON.parse(questions);
+    } catch {
+      throw new Error("Invalid ask_user questions");
     }
   }
-  return questions as AskUserInput["questions"];
+  const prepared = { ...value, questions };
+  if (!questionsOf(prepared)) throw new Error("Invalid ask_user questions");
+  return prepared as AskUserInput;
 }
 
 // 手写校验而不是拉 TypeBox compiler：这里只需要判真假，
 // 且校验位于 Worker 响应信任边界，不应为每次回答编译 schema。
 function isAskUserResponse(input: unknown, value: unknown): boolean {
-  const questions = questionsOf(input);
+  const questions = questionsOf(input, true);
   const answers = recordOf(value)?.answers;
   if (!questions || !Array.isArray(answers) || answers.length !== questions.length) {
     return false;
@@ -150,54 +207,61 @@ function isAskUserResponse(input: unknown, value: unknown): boolean {
 
   return questions.every((question, index) => {
     const answer = recordOf(answers[index]);
-    if ("kind" in question && question.kind === "attachment") {
-      const attachments = answer?.attachments;
-      if (
-        !answer ||
-        !Array.isArray(attachments) ||
-        attachments.length < 1 ||
-        attachments.length > 8 ||
-        Object.keys(answer).some((key) => key !== "attachments")
-      ) return false;
-      return attachments.every((value) => {
-        const file = recordOf(value);
-        return Boolean(
-          file &&
-          file.type === "file" &&
-          typeof file.url === "string" && file.url.length > 0 &&
-          typeof file.filename === "string" && file.filename.length > 0 &&
-          typeof file.mediaType === "string" && file.mediaType.length > 0 &&
-          (file.providerMetadata === undefined || recordOf(file.providerMetadata)) &&
-          Object.keys(file).every((key) =>
-            key === "type" || key === "url" || key === "filename" ||
-            key === "mediaType" || key === "providerMetadata"
-          )
-        );
-      });
-    }
-    if (!answer || !Array.isArray(answer.selections)) return false;
-    if (Object.keys(answer).some((key) => key !== "selections" && key !== "text")) {
-      return false;
-    }
+    if (
+      !answer ||
+      !Array.isArray(answer.selections) ||
+      typeof answer.text !== "string" ||
+      !Array.isArray(answer.attachments) ||
+      Object.keys(answer).some((key) =>
+        key !== "selections" && key !== "text" && key !== "attachments"
+      )
+    ) return false;
     if (!answer.selections.every((item) => typeof item === "string")) {
       return false;
     }
-    if (answer.text !== undefined && typeof answer.text !== "string") {
-      return false;
+    if (answer.text.length > 2_000) return false;
+    if (!answer.attachments.every((value) => {
+      const file = recordOf(value);
+      return Boolean(
+        file &&
+        file.type === "file" &&
+        typeof file.url === "string" && file.url.length > 0 &&
+        typeof file.filename === "string" && file.filename.length > 0 &&
+        typeof file.mediaType === "string" && file.mediaType.length > 0 &&
+        (file.providerMetadata === undefined || recordOf(file.providerMetadata)) &&
+        Object.keys(file).every((key) =>
+          key === "type" || key === "url" || key === "filename" ||
+          key === "mediaType" || key === "providerMetadata"
+        )
+      );
+    })) return false;
+
+    if (
+      answer.selections.length === 0 &&
+      !answer.text.trim() &&
+      answer.attachments.length === 0
+    ) return question.required !== true;
+
+    if (question.responseType === "attachment") {
+      return answer.selections.length === 0 && !answer.text &&
+        answer.attachments.length >= 1 && answer.attachments.length <= 8;
+    }
+    if (answer.attachments.length > 0) return false;
+    if (question.responseType === "text") {
+      return answer.selections.length === 0 && answer.text.trim().length > 0;
     }
 
-    const ordinary = question as Static<typeof askUserOrdinaryQuestion>;
-    const options = ordinary.options ?? [];
-    const text = typeof answer.text === "string" ? answer.text : "";
-    if (text.length > 2_000) return false;
+    const options = question.options ?? [];
     if (answer.selections.some((selection) => !options.includes(selection))) {
       return false;
     }
     if (new Set(answer.selections).size !== answer.selections.length) return false;
-    if (!ordinary.multiSelect && answer.selections.length > 1) return false;
-    const allowCustom = options.length === 0 || ordinary.allowCustom === true;
-    if (!allowCustom && text.trim()) return false;
-    return answer.selections.length > 0 || text.trim().length > 0;
+    if (
+      question.responseType === "single_select" &&
+      answer.selections.length > 1
+    ) return false;
+    if (!question.allowCustom && answer.text.trim()) return false;
+    return answer.selections.length > 0 || answer.text.trim().length > 0;
   });
 }
 
@@ -322,8 +386,9 @@ export function basePiToolCandidates(
         name: "ask_user",
         label: "Ask user",
         description:
-          "Ask all 1-10 user questions needed to continue in one call. For files, use one question with kind attachment; it accepts multiple files, so do not ask for each file separately or tell the user to use the normal chat composer. For a bounded choice, provide 2-6 distinct options. For required free text, omit the options field entirely; never pass an empty, single-item, or more-than-6-item options array. The answers return as this tool's result, so continue the same turn after calling it.",
+          "Ask all 1-10 user questions needed to continue in one call. Required input for every question: question and responseType; required defaults to false, so set it to true only when progress cannot continue without an answer. Use responseType text for free text, single_select or multi_select with 2-6 distinct options for choices, and attachment for files. At most one attachment question is allowed and it accepts multiple files. Do not add file-specific fields such as accept or tell the user to use the normal chat composer. The answers return as this tool's result, so continue the same turn after calling it.",
         parameters: askUserParameters,
+        prepareArguments: prepareAskUserArguments,
         // 永远不会被调用：执行链在 interaction 闸就 park 住了。留一个失败关闭的
         // 实现，是为了万一哪次改动绕过了那道闸，能立刻炸出来而不是静默返回空答案。
         async execute() {
@@ -335,59 +400,47 @@ export function basePiToolCandidates(
       interaction: {
         validateResponse: isAskUserResponse,
         settle: (input, response) => {
-          const questions = (input as AskUserInput).questions;
+          const questions = questionsOf(input, true)!;
           const responseAnswers = (response as AskUserResponse).answers;
           const answers = questions.map((question, index) => {
             const answer = responseAnswers[index]!;
-            if (
-              "kind" in question && question.kind === "attachment" &&
-              "attachments" in answer
-            ) {
-              return {
-                question: question.question,
-                attachments: answer.attachments.map((file) => {
-                  const springbrand = recordOf(
-                    recordOf(file.providerMetadata)?.springbrand,
-                  );
-                  return {
-                    name: file.filename,
-                    mediaType: file.mediaType,
-                    size: typeof springbrand?.size === "number"
-                      ? springbrand.size
-                      : 0,
-                    cdnUrl: typeof springbrand?.cdnUrl === "string"
-                      ? springbrand.cdnUrl
-                      : file.url,
-                    workspacePath: typeof springbrand?.path === "string"
-                      ? springbrand.path
-                      : "",
-                    attachmentId: typeof springbrand?.attachmentId === "string"
-                      ? springbrand.attachmentId
-                      : "",
-                    contentVersion:
-                      typeof springbrand?.contentVersion === "string"
-                        ? springbrand.contentVersion
-                        : "",
-                  };
-                }),
-              };
-            }
-            if (!("selections" in answer)) {
-              throw new Error("Invalid ask_user answer");
-            }
             return {
               question: question.question,
-              selections: answer.selections,
-              ...(answer.text !== undefined ? { text: answer.text.trim() } : {}),
+              selections: [...answer.selections],
+              text: answer.text.trim(),
+              attachments: answer.attachments.map((file) => {
+                const springbrand = recordOf(
+                  recordOf(file.providerMetadata)?.springbrand,
+                );
+                return {
+                  name: file.filename,
+                  mediaType: file.mediaType,
+                  size: typeof springbrand?.size === "number"
+                    ? springbrand.size
+                    : 0,
+                  cdnUrl: typeof springbrand?.cdnUrl === "string"
+                    ? springbrand.cdnUrl
+                    : file.url,
+                  workspacePath: typeof springbrand?.path === "string"
+                    ? springbrand.path
+                    : "",
+                  attachmentId: typeof springbrand?.attachmentId === "string"
+                    ? springbrand.attachmentId
+                    : "",
+                  contentVersion:
+                    typeof springbrand?.contentVersion === "string"
+                      ? springbrand.contentVersion
+                      : "",
+                };
+              }),
             };
           });
           return {
             content: [{
               type: "text",
               text: `The user answered:\n${answers.map((answer, index) => {
-                if ("attachments" in answer) {
+                if (answer.attachments.length > 0) {
                   const responseAnswer = responseAnswers[index]!;
-                  if (!("attachments" in responseAnswer)) return "";
                   return `${index + 1}. ${answer.question}\n${responseAnswer.attachments
                     .map((file) => `   - ${modelAttachmentText(file)}`)
                     .join("\n")}`;