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

package/package.json

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

package/src/index.ts

@@ -50,6 +50,7 @@ export * from "./kernel/runtime-config";
 export * from "./telemetry";
 export type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
 export * from "./runtime-agent";
+export type { ToolInteractionResponsePreparation } from "./runtime";
 export * from "./kernel/state";
 export * from "./workspace-versioning";
 export * from "./lib/execution-level";

package/src/pi/message/conversion.ts

@@ -17,8 +17,13 @@ function timestampOf(message: UIMessage): number {
   return typeof createdAt === "number" ? createdAt : Date.now();
 }
 
-function attachmentText(
-  part: Extract<UIMessage["parts"][number], { type: "file" }>,
+export function modelAttachmentText(
+  part: {
+    readonly url: string;
+    readonly filename?: string;
+    readonly mediaType: string;
+    readonly providerMetadata?: unknown;
+  },
 ): string {
   const name = part.filename?.trim() || "attachment";
   const springbrand = recordOf(recordOf(part.providerMetadata).springbrand);
@@ -66,7 +71,7 @@ function userContent(
       });
     } else {
       content.push(
-        { type: "text", text: attachmentText(part) },
+        { type: "text", text: modelAttachmentText(part) },
         {
           type: "file",
           url: part.url,

package/src/pi/tool/base.ts

@@ -12,11 +12,12 @@ import { estimateStringTokens } from "agents/experimental/memory/utils";
 import type { RuntimeMemoryPort } from "../../kernel/bindings";
 import type { RuntimeMemoryProfile } from "../../kernel/profile";
 import { serializeOutput } from "../../lib/artifacts";
+import { modelAttachmentText } from "../message/conversion";
 import type { PiToolCandidate } from "./compiler";
 import { webSearchPiToolCandidate } from "./web-search";
 import type { WebSearch } from "./web-search/api";
 
-const askUserQuestion = Type.Object({
+const askUserOrdinaryQuestion = Type.Object({
   question: Type.String({
     minLength: 1,
     description: "The question to put to the user.",
@@ -38,12 +39,31 @@ const askUserQuestion = Type.Object({
   })),
 }, { additionalProperties: false });
 
+const askUserAttachmentQuestion = Type.Object({
+  question: Type.String({
+    minLength: 1,
+    description: "The request for one or more user files.",
+  }),
+  kind: Type.Literal("attachment", {
+    description:
+      "Use attachment when the user must upload one or more files to continue.",
+  }),
+}, { 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 needed to continue. Ask them together in one call.",
+      "All user decisions and files needed to continue. Ask them together in one call. At most one question may have kind attachment.",
   }),
 }, { additionalProperties: false });
 
@@ -53,15 +73,20 @@ const askUserParameters = Type.Object({
  * `answers` 与 Tool 输入的 `questions` 按下标一一对应。
  * 刻意用结构化数组而不是拼好的字符串 —— 选项本身可能含分隔符，拼了再拆是有损的。
  */
-const askUserResponse = Type.Object({
-  answers: Type.Array(Type.Object({
-    selections: Type.Array(Type.String()),
-    text: Type.Optional(Type.String()),
-  }, { additionalProperties: false })),
-}, { additionalProperties: false });
-
 type AskUserInput = Static<typeof askUserParameters>;
-type AskUserResponse = Static<typeof askUserResponse>;
+type AskUserFile = {
+  readonly type: "file";
+  readonly url: string;
+  readonly filename: string;
+  readonly mediaType: string;
+  readonly providerMetadata?: unknown;
+};
+type AskUserResponse = {
+  readonly answers: ReadonlyArray<
+    | { readonly selections: readonly string[]; readonly text?: string }
+    | { readonly attachments: readonly AskUserFile[] }
+  >;
+};
 
 function recordOf(value: unknown): Record<string, unknown> | null {
   return typeof value === "object" && value !== null && !Array.isArray(value)
@@ -74,11 +99,23 @@ function questionsOf(value: unknown): AskUserInput["questions"] | null {
   if (!Array.isArray(questions) || questions.length < 1 || questions.length > 10) {
     return null;
   }
+  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") {
+      attachmentQuestions += 1;
+      if (
+        attachmentQuestions > 1 ||
+        question.options !== undefined ||
+        question.multiSelect !== undefined ||
+        question.allowCustom !== undefined
+      ) return null;
+      continue;
+    }
+    if (question.kind !== undefined) return null;
     if (
       question.multiSelect !== undefined &&
       typeof question.multiSelect !== "boolean"
@@ -113,7 +150,35 @@ 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.selections.every((item) => typeof item === "string")) {
       return false;
     }
@@ -121,15 +186,16 @@ function isAskUserResponse(input: unknown, value: unknown): boolean {
       return false;
     }
 
-    const options = question.options ?? [];
+    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;
     if (answer.selections.some((selection) => !options.includes(selection))) {
       return false;
     }
     if (new Set(answer.selections).size !== answer.selections.length) return false;
-    if (!question.multiSelect && answer.selections.length > 1) return false;
-    const allowCustom = options.length === 0 || question.allowCustom === true;
+    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;
   });
@@ -256,7 +322,7 @@ export function basePiToolCandidates(
         name: "ask_user",
         label: "Ask user",
         description:
-          "Ask all 1-10 user questions needed to continue in one call. 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. Do not make one call per question or write plain text like 'please pick A / B / C'. 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. 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.",
         parameters: askUserParameters,
         // 永远不会被调用：执行链在 interaction 闸就 park 住了。留一个失败关闭的
         // 实现，是为了万一哪次改动绕过了那道闸，能立刻炸出来而不是静默返回空答案。
@@ -273,6 +339,42 @@ export function basePiToolCandidates(
           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,
@@ -283,6 +385,13 @@ export function basePiToolCandidates(
             content: [{
               type: "text",
               text: `The user answered:\n${answers.map((answer, index) => {
+                if ("attachments" in answer) {
+                  const responseAnswer = responseAnswers[index]!;
+                  if (!("attachments" in responseAnswer)) return "";
+                  return `${index + 1}. ${answer.question}\n${responseAnswer.attachments
+                    .map((file) => `   - ${modelAttachmentText(file)}`)
+                    .join("\n")}`;
+                }
                 const parts = [
                   ...answer.selections,
                   ...(answer.text ? [answer.text] : []),

package/src/runtime-agent.ts

@@ -310,6 +310,13 @@ export interface RuntimeAgentConfigControls<Command, Change> {
   ): Promise<RuntimeConfigUpdateResult<Change>>;
 }
 
+/** Type-only Host extension seam implemented by AgentRuntimeKernel. */
+declare class RuntimeAgentHostSeam {
+  protected prepareToolInteractionResponse(
+    input: import("./runtime").ToolInteractionResponsePreparation,
+  ): Promise<unknown | null>;
+}
+
 /**
  * 表示 `defineRuntimeAgent` 生成类的实例。
  *
@@ -320,7 +327,7 @@ export type RuntimeAgentInstance<
   Env extends Cloudflare.Env = Cloudflare.Env,
   Command = never,
   Change = never,
-> = Agent<Env, RuntimeState> & RuntimeAgentControls &
+> = Agent<Env, RuntimeState> & RuntimeAgentHostSeam & RuntimeAgentControls &
   RuntimeAgentConfigControls<Command, Change> & AgentToolChildAdapter<unknown, string>;
 
 /**

package/src/runtime.ts

@@ -405,6 +405,13 @@ interface PendingTemporaryAgentApproval {
   resolve(decision: TemporaryAgentApprovalDecision): void;
 }
 
+export interface ToolInteractionResponsePreparation {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly toolInput: unknown;
+  readonly response: unknown;
+}
+
 // #endregion
 
 /**
@@ -432,6 +439,13 @@ export abstract class AgentRuntimeKernel<
 
   protected abstract ensureRuntimeReady(): Promise<void>;
 
+  /** Let the Host prepare a validated client response before Tool settlement. */
+  protected prepareToolInteractionResponse(
+    input: ToolInteractionResponsePreparation,
+  ): Promise<unknown | null> {
+    return Promise.resolve(input.response);
+  }
+
   private activeRuntime?: ActiveRuntime;
   private telemetryCoordinator?: RuntimeTelemetryCoordinator;
   private piAdapter?: PiRuntimeAdapter;
@@ -4283,10 +4297,19 @@ export abstract class AgentRuntimeKernel<
 
     const input = safeParseJson(pending.inputJson);
     if (!spec.validateResponse(input, response)) return { ok: false };
+    const prepared = await this.prepareToolInteractionResponse({
+      toolCallId,
+      toolName: pending.toolName,
+      toolInput: input,
+      response,
+    });
+    if (prepared === null || !spec.validateResponse(input, prepared)) {
+      return { ok: false };
+    }
     const settled = spec.settle
-      ? spec.settle(input, response)
-      : defaultInteractionResult(response);
-    return this.interactions.respond(pending.interactionId, response, settled);
+      ? spec.settle(input, prepared)
+      : defaultInteractionResult(prepared);
+    return this.interactions.respond(pending.interactionId, prepared, settled);
   }
 
   /**