@springbrand/agent-runtime 0.2.0-alpha.60 → 0.2.0-alpha.62

package/package.json

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

package/src/db/submission.repo.ts

@@ -11,6 +11,7 @@ export type SubmissionStatus =
   | "error";
 export type SubmissionRecoveryReason =
   | "no_meaningful_model_progress"
+  | "server_tool_timeout"
   | "transient_model_error"
   | "context_overflow";
 

package/src/kernel/state.ts

@@ -62,7 +62,10 @@ export interface RuntimeTurnState {
   activeMessageId?: string;
   recoveryAttempt?: number;
   recoveryMax?: number;
-  recoveryReason?: "no_meaningful_model_progress" | "transient_model_error";
+  recoveryReason?:
+    | "no_meaningful_model_progress"
+    | "server_tool_timeout"
+    | "transient_model_error";
   steerable: boolean;
   hasPendingSteer: boolean;
   queued: RuntimeQueuedSubmission[];

package/src/lib/prompt.ts

@@ -111,8 +111,8 @@ 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. 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 required free text; use responseType: \"attachment\" when the user must upload one or more files. At most one question may " +
-  "request attachments. Do not add an accept field or tell the user to upload through the normal chat composer; " +
+  "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/runtime-adapter/execution.ts

@@ -83,6 +83,8 @@ const MAX_WRAP_UP_TURNS = 2;
 
 export class RetryableModelError extends Error {}
 
+export class RetryableModelSessionError extends RetryableModelError {}
+
 export class ContextOverflowError extends RetryableModelError {}
 
 function normalizePlanToolCalls(message: AgentMessage): void {
@@ -610,7 +612,6 @@ export type PiCanonicalMessageCommit =
 export interface PiTurnTerminalIntent {
   readonly outcome: "succeeded" | "failed" | "aborted";
   readonly message?: string;
-  readonly resetModelSession?: boolean;
 }
 
 export interface PiPreparedTurnRunOptions {
@@ -1058,7 +1059,8 @@ export class PreparedPiTurnAdapter {
       ) || isModelStreamStallMessage(
         event.assistantMessageEvent.error.errorMessage,
       ) ||
-        isRecoverableAssistantError(event.assistantMessageEvent.error))
+        isRecoverableAssistantError(event.assistantMessageEvent.error) ||
+        isOpenRouterServerToolTimeout(event.assistantMessageEvent.error))
     ) {
       return;
     }
@@ -1073,10 +1075,11 @@ export class PreparedPiTurnAdapter {
         }
         const stalled = message.stopReason === "error" &&
           isModelStreamStallMessage(message.errorMessage);
+        const resetModelSession = isOpenRouterServerToolTimeout(message);
         const retryable = isRecoverableAssistantError(message);
-        if (stalled || retryable) {
+        if (stalled || retryable || resetModelSession) {
           const content = visibleAssistantContent(message);
-          if (content.length > 0) {
+          if (!resetModelSession && content.length > 0) {
             this.assistantOrdinal += 1;
             await this.options.onCanonicalMessage({
               kind: "commit-turn",
@@ -1090,6 +1093,9 @@ export class PreparedPiTurnAdapter {
           if (stalled) {
             throw new ChatStreamStalledError(message.errorMessage!);
           }
+          if (resetModelSession) {
+            throw new RetryableModelSessionError(message.errorMessage);
+          }
           throw new RetryableModelError(message.errorMessage);
         }
       }
@@ -1136,9 +1142,6 @@ export class PreparedPiTurnAdapter {
           );
           this.terminalIntent = {
             outcome: terminal.outcome,
-            ...(isOpenRouterServerToolTimeout(authoritativeMessage)
-              ? { resetModelSession: true }
-              : {}),
             ...(authoritativeMessage.errorMessage
               ? { message: authoritativeMessage.errorMessage }
               : terminal.message

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

@@ -2,7 +2,11 @@ import {
   PreparedPiTurnAdapter,
   type CreatePreparedPiTurnOptions,
 } from "./execution";
-export { ContextOverflowError, RetryableModelError } from "./execution";
+export {
+  ContextOverflowError,
+  RetryableModelError,
+  RetryableModelSessionError,
+} from "./execution";
 import {
   uiUserMessageToPi,
 } from "../message";

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

@@ -215,6 +215,7 @@ export function isRecoverableAssistantError(
     message.stopReason === "error" &&
     /thought[_ ]signature/i.test(message.errorMessage ?? "")
   ) return false;
+  // Runtime resets the model Session and gives this timeout its own one-retry budget.
   if (isOpenRouterServerToolTimeout(message)) return false;
   return isRetryableAssistantError(message) ||
     (message.stopReason === "error" &&

package/src/pi/tool/base.ts

@@ -44,6 +44,11 @@ const askUserQuestion = Type.Object({
     description:
       "For single_select or multi_select, whether the user may also add free text. Defaults to false.",
   })),
+  required: Type.Optional(Type.Boolean({
+    default: false,
+    description:
+      "Whether the user must answer this question to submit. Defaults to false.",
+  })),
 }, { additionalProperties: false });
 
 const askUserParameters = Type.Object({
@@ -98,6 +103,10 @@ function questionsOf(
     if (!question || typeof question.question !== "string" || !question.question) {
       return null;
     }
+    if (
+      question.required !== undefined && typeof question.required !== "boolean"
+    ) return null;
+    const required = question.required === true;
     let responseType = question.responseType;
     if (
       typeof responseType !== "string" ||
@@ -118,6 +127,11 @@ function questionsOf(
         return null;
       }
     }
+    const normalizedQuestion = {
+      question: question.question,
+      responseType: responseType as typeof askUserResponseTypes[number],
+      required,
+    };
     if (responseType === "attachment") {
       attachmentQuestions += 1;
       if (
@@ -126,7 +140,7 @@ function questionsOf(
         question.allowCustom !== undefined ||
         (!allowLegacy && question.multiSelect !== undefined)
       ) return null;
-      normalized.push({ question: question.question, responseType });
+      normalized.push(normalizedQuestion);
       continue;
     }
     if (responseType === "text") {
@@ -137,7 +151,7 @@ function questionsOf(
       ) {
         return null;
       }
-      normalized.push({ question: question.question, responseType });
+      normalized.push(normalizedQuestion);
       continue;
     }
     if (
@@ -156,8 +170,7 @@ function questionsOf(
       (question.kind !== undefined || question.multiSelect !== undefined)
     ) return null;
     normalized.push({
-      question: question.question,
-      responseType: responseType as typeof askUserResponseTypes[number],
+      ...normalizedQuestion,
       options: question.options,
       ...(question.allowCustom === undefined
         ? {}
@@ -223,6 +236,12 @@ function isAskUserResponse(input: unknown, value: unknown): boolean {
       );
     })) 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;
@@ -367,7 +386,7 @@ export function basePiToolCandidates(
         name: "ask_user",
         label: "Ask user",
         description:
-          "Ask all 1-10 user questions needed to continue in one call. Required input for every question: question and responseType. Use responseType text for free text, single_select or multi_select with 2-6 distinct options for choices, and attachment when the user must upload 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.",
+          "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 住了。留一个失败关闭的

package/src/runtime.ts

@@ -71,6 +71,7 @@ import {
   MODEL_STREAM_STALL_TIMEOUT_MS,
   readModelStreamStallDetails,
   RetryableModelError,
+  RetryableModelSessionError,
   type PiCanonicalUserInput,
   type PiCanonicalTranscriptSnapshot,
   type PiChatRecoveryData,
@@ -145,6 +146,7 @@ const CONTINUATION_WATCHDOG_SECONDS = 300;
 // Host 侧的一次抖动会把 Session 永久卡在「队列已满」。
 const ADMISSION_ATTEMPT_WINDOW_MS = 60_000;
 export const CHAT_RECOVERY_MAX_ATTEMPTS = 5;
+const SERVER_TOOL_TIMEOUT_MAX_ATTEMPTS = 2;
 // stall 单独收窄。理由不是「stall 更不值得救」,而是它的重试**期望值和别的错不一样**:
 // 瞬时错(5xx / 断流)重跑一次往往就好了;stall 的重跑是拿同一份 transcript 让模型
 // 重新想同样久,如果它本来就超预算,再跑几次也一样超。把看门狗放宽到 240s 之后,
@@ -177,10 +179,7 @@ interface StoredSubmission extends SubmissionReceipt {
   userMessageId?: string | null;
   regenerateMessageId?: string | null;
   recoveryErrorCount: number;
-  recoveryReason?:
-    | "no_meaningful_model_progress"
-    | "transient_model_error"
-    | "context_overflow";
+  recoveryReason?: SubmissionRecoveryReason;
   runId: string | null;
   accountId: string | null;
   rateVersion: number | null;
@@ -893,7 +892,6 @@ export abstract class AgentRuntimeKernel<
         terminal: {
           outcome: "succeeded" | "failed" | "aborted";
           message?: string;
-          resetModelSession?: boolean;
         },
       ) => void | Promise<void>;
     } = {},
@@ -3062,7 +3060,6 @@ export abstract class AgentRuntimeKernel<
       | {
           outcome: "succeeded" | "failed" | "aborted";
           message?: string;
-          resetModelSession?: boolean;
         }
       | undefined;
     const startedAt = ready.createdAt;
@@ -3082,13 +3079,6 @@ export abstract class AgentRuntimeKernel<
           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)) {
@@ -3212,13 +3202,23 @@ export abstract class AgentRuntimeKernel<
       }
       const stalled = error instanceof ChatStreamStalledError;
       const contextOverflow = error instanceof ContextOverflowError;
+      const resetModelSession = error instanceof RetryableModelSessionError;
       const abortReason = this.readSubmission(submissionId)?.abortReason;
       if (!abortReason && (stalled || error instanceof RetryableModelError)) {
+        if (resetModelSession) {
+          this.modelSessionId = crypto.randomUUID();
+          await this.ctx.storage.put(
+            MODEL_SESSION_ID_STORAGE_KEY,
+            this.modelSessionId,
+          );
+        }
         const recoveryReason: SubmissionRecoveryReason = stalled
           ? "no_meaningful_model_progress"
-          : contextOverflow
-            ? "context_overflow"
-            : "transient_model_error";
+          : resetModelSession
+            ? "server_tool_timeout"
+            : contextOverflow
+              ? "context_overflow"
+              : "transient_model_error";
         let contextOverflowRecoveryClaimed = false;
         const recoveryErrorCount = this.db.transaction(() => {
           if (contextOverflow) {
@@ -3253,7 +3253,11 @@ export abstract class AgentRuntimeKernel<
           ? contextOverflowRecoveryClaimed &&
             recoveryErrorCount < CHAT_RECOVERY_MAX_ATTEMPTS
           : recoveryErrorCount <
-            (stalled ? CHAT_STALL_MAX_ATTEMPTS : CHAT_RECOVERY_MAX_ATTEMPTS);
+            (stalled
+              ? CHAT_STALL_MAX_ATTEMPTS
+              : resetModelSession
+                ? SERVER_TOOL_TIMEOUT_MAX_ATTEMPTS
+                : CHAT_RECOVERY_MAX_ATTEMPTS);
         if (
           !stoppedDuringRecovery &&
           retryAllowed
@@ -4710,7 +4714,9 @@ export abstract class AgentRuntimeKernel<
                         : current.recoveryReason ===
                             "no_meaningful_model_progress"
                           ? CHAT_STALL_MAX_ATTEMPTS
-                          : CHAT_RECOVERY_MAX_ATTEMPTS,
+                          : current.recoveryReason === "server_tool_timeout"
+                            ? SERVER_TOOL_TIMEOUT_MAX_ATTEMPTS
+                            : CHAT_RECOVERY_MAX_ATTEMPTS,
                     ...(current.recoveryReason &&
                         current.recoveryReason !== "context_overflow"
                       ? { recoveryReason: current.recoveryReason }