@springbrand/agent-runtime 0.2.0-alpha.56 → 0.2.0-alpha.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.56",
+  "version": "0.2.0-alpha.58",
   "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/runtime-adapter/execution.ts

@@ -45,6 +45,7 @@ import {
 } from "./assembly";
 import {
   isRecoverableAssistantError,
+  isOpenRouterServerToolTimeout,
   isModelStreamStallMessage,
   withProviderRetry,
   type PiGenerationLifecycleObserver,
@@ -490,7 +491,7 @@ export interface PiTurnDurability {
 export interface CreatePreparedPiTurnOptions {
   readonly prepared: PreparedPiRuntime;
   readonly pinnedDescriptor: string;
-  /** 同一 Session 的所有 Submission 共用的稳定 Provider 路由身份。 */
+  /** Session 当前的稳定 Provider 路由身份；终态 Provider 故障可在下一 Submission 前旋转它。 */
   readonly modelSessionId: string;
   readonly submission: {
     readonly id: string;
@@ -609,6 +610,7 @@ export type PiCanonicalMessageCommit =
 export interface PiTurnTerminalIntent {
   readonly outcome: "succeeded" | "failed" | "aborted";
   readonly message?: string;
+  readonly resetModelSession?: boolean;
 }
 
 export interface PiPreparedTurnRunOptions {
@@ -1134,6 +1136,9 @@ export class PreparedPiTurnAdapter {
           );
           this.terminalIntent = {
             outcome: terminal.outcome,
+            ...(isOpenRouterServerToolTimeout(authoritativeMessage)
+              ? { resetModelSession: true }
+              : {}),
             ...(authoritativeMessage.errorMessage
               ? { message: authoritativeMessage.errorMessage }
               : terminal.message

package/src/pi/runtime-adapter/models.ts

@@ -182,6 +182,32 @@ export function readModelStreamStallDetails(
   }
 }
 
+export function isOpenRouterServerToolTimeout(
+  message: AssistantMessage,
+): boolean {
+  if (
+    message.stopReason !== "error" ||
+    !message.provider.startsWith("model-api-openrouter-messages-") ||
+    !message.errorMessage
+  ) return false;
+  try {
+    const payload = JSON.parse(message.errorMessage) as {
+      type?: unknown;
+      error?: {
+        type?: unknown;
+        message?: unknown;
+        error_type?: unknown;
+      };
+    };
+    return payload.type === "error" &&
+      payload.error?.type === "timeout_error" &&
+      payload.error.message === "Server tool request failed" &&
+      payload.error.error_type === "timeout";
+  } catch {
+    return false;
+  }
+}
+
 export function isRecoverableAssistantError(
   message: AssistantMessage,
 ): boolean {
@@ -189,6 +215,7 @@ export function isRecoverableAssistantError(
     message.stopReason === "error" &&
     /thought[_ ]signature/i.test(message.errorMessage ?? "")
   ) return false;
+  if (isOpenRouterServerToolTimeout(message)) return false;
   return isRetryableAssistantError(message) ||
     (message.stopReason === "error" &&
       /upstream http\/2 stream failed/i.test(message.errorMessage ?? ""));

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.ts

@@ -134,6 +134,7 @@ import {
 const SCHEDULED_STABLE_TIMEOUT_MS = 30_000;
 const TURN_EVENT_RETRY_SECONDS = 10;
 const RUNTIME_EVENT_MAX_ATTEMPTS = 5;
+const MODEL_SESSION_ID_STORAGE_KEY = "universal-agent:model-session-id";
 
 // 计划续跑丢失多久后由看门狗接手。必须显著长于一个正常执行片的时长，
 // 否则会在健康的长执行片上误判并派发出重复的一片。
@@ -404,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
 
 /**
@@ -431,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;
@@ -442,6 +457,8 @@ export abstract class AgentRuntimeKernel<
   private readonly approvals: ApprovalLifecycle<StoredSubmission>;
   private readonly interactions: InteractionLifecycle<StoredSubmission>;
   private runtimeLoadTracker?: RuntimeLoadTracker;
+  private modelSessionId?: string;
+  private readonly modelSessionIdReady?: Promise<void>;
   private runtimeEventDrainTail?: Promise<void>;
   private readonly streamBySubmission = new Map<string, string>();
   private migratedSubmissionIds?: Set<string>;
@@ -521,6 +538,11 @@ export abstract class AgentRuntimeKernel<
       snapshotKey: "__cfPiFiberSnapshot",
       snapshotKind: "pi-turn",
     });
+    this.modelSessionIdReady = ctx.storage.get<string>(
+      MODEL_SESSION_ID_STORAGE_KEY,
+    ).then((stored) => {
+      this.modelSessionId = stored;
+    });
     this.piAdapter = pi;
     this.db = new RuntimeDatabase(
       this.sql.bind(this),
@@ -734,6 +756,7 @@ export abstract class AgentRuntimeKernel<
   }
 
   protected async initCandidate(candidate: RuntimeCandidate): Promise<void> {
+    await this.modelSessionIdReady;
     const previous = this.activeRuntime;
     const candidateSnapshot = candidate.snapshot;
     this.runtimeLoad.advance("assembly");
@@ -870,6 +893,7 @@ export abstract class AgentRuntimeKernel<
         terminal: {
           outcome: "succeeded" | "failed" | "aborted";
           message?: string;
+          resetModelSession?: boolean;
         },
       ) => void | Promise<void>;
     } = {},
@@ -909,7 +933,7 @@ export abstract class AgentRuntimeKernel<
     return this.pi.createTurn({
       prepared: this.preparedPi(),
       pinnedDescriptor: submission.assemblyDescriptor,
-      modelSessionId: this.name,
+      modelSessionId: this.modelSessionId ?? this.name,
       submission: {
         id: submission.submissionId,
         requestId: submission.requestId,
@@ -3038,6 +3062,7 @@ export abstract class AgentRuntimeKernel<
       | {
           outcome: "succeeded" | "failed" | "aborted";
           message?: string;
+          resetModelSession?: boolean;
         }
       | undefined;
     const startedAt = ready.createdAt;
@@ -3050,13 +3075,20 @@ export abstract class AgentRuntimeKernel<
         this.migratedSubmissions.has(submissionId)
           ? undefined
           : this.persistAndBroadcastRecord(turn, record),
-      onTerminal: (intent) => {
+      onTerminal: async (intent) => {
         terminalIntent = intent;
         this.appendTerminalIntent(
           submission,
           intent.outcome,
           intent.message,
         );
+        if (intent.resetModelSession) {
+          this.modelSessionId = crypto.randomUUID();
+          await this.ctx.storage.put(
+            MODEL_SESSION_ID_STORAGE_KEY,
+            this.modelSessionId,
+          );
+        }
       },
     });
     for (const pending of this.db.steers.listForSubmission(submissionId)) {
@@ -4265,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);
   }
 
   /**