@springbrand/agent-runtime 0.1.3-alpha.8 → 0.2.0-alpha.14

package/src/kernel/submission-lifecycle.ts

@@ -31,6 +31,7 @@ export interface SubmissionRecord {
   idempotencyKey?: string | null;
   status: SubmissionStatus;
   accepted: boolean;
+  admissionRejected?: boolean;
   abortReason?: string | null;
 }
 
@@ -116,7 +117,7 @@ export class SubmissionQueueFullError extends Error {
   readonly code = "queue_full";
 
   constructor() {
-    super(`Pi submission queue is full (${MAX_PENDING_SUBMISSIONS})`);
+    super(`SpringBrand submission queue is full (${MAX_PENDING_SUBMISSIONS})`);
   }
 }
 
@@ -266,9 +267,9 @@ export class SubmissionLifecycle<
     if (admitted.admitted) this.pump();
     return {
       receipt: admitted.submission,
-      completion: this.waitForTerminal(
-        admitted.submission.submissionId,
-      ),
+      completion: admitted.rejected
+        ? Promise.resolve(admitted.submission)
+        : this.waitForTerminal(admitted.submission.submissionId),
     };
   }
 
@@ -302,6 +303,16 @@ export class SubmissionLifecycle<
     return this.start(submissionId, true);
   }
 
+  /** 等当前切片退出后恢复同一条非终态 Submission，避免 planned wake 被实例内去重吞掉。 */
+  async recoverAfterCurrent(submissionId: string): Promise<TSubmission> {
+    const current = this.executions.get(submissionId);
+    if (current) {
+      const outcome = await current;
+      if (isTerminalSubmissionStatus(outcome.status)) return outcome;
+    }
+    return this.start(submissionId, true);
+  }
+
   recoverHead(): Promise<TSubmission | null> {
     const running = this.options.store.findRunning();
     if (running) return this.start(running.submissionId, true);
@@ -317,7 +328,11 @@ export class SubmissionLifecycle<
   private async admit(
     input: SubmissionInput<TSubmission>,
     create: () => TSubmission,
-  ): Promise<{ submission: TSubmission; admitted: boolean }> {
+  ): Promise<{
+    submission: TSubmission;
+    admitted: boolean;
+    rejected: boolean;
+  }> {
     const result = this.options.store.transaction(() => {
       if (input.idempotencyKey) {
         const duplicate = this.options.store.findByIdempotencyKey(
@@ -327,6 +342,7 @@ export class SubmissionLifecycle<
           return {
             submission: { ...duplicate, accepted: false } as TSubmission,
             admitted: false,
+            rejected: false,
           };
         }
       }
@@ -340,6 +356,7 @@ export class SubmissionLifecycle<
             accepted: false,
           } as TSubmission,
           admitted: false,
+          rejected: false,
         };
       }
       if (
@@ -348,7 +365,12 @@ export class SubmissionLifecycle<
       ) {
         throw new SubmissionQueueFullError();
       }
-      return { submission: create(), admitted: true };
+      const submission = create();
+      return {
+        submission,
+        admitted: submission.admissionRejected !== true,
+        rejected: submission.admissionRejected === true,
+      };
     });
     if (result.admitted) await this.options.clearTerminal();
     return result;
@@ -407,7 +429,7 @@ export class SubmissionLifecycle<
         }
         const submission = this.options.store.find(submissionId);
         if (!submission) {
-          throw new Error(`Unknown Pi submission: ${submissionId}`);
+          throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
         }
         shouldPump = isTerminalSubmissionStatus(submission.status);
         return submission;
@@ -438,10 +460,13 @@ export class SubmissionLifecycle<
     // TODO(待确认): 持久层若长期保持非终态且没有执行者，这里没有超时或外部唤醒上限。
     for (;;) {
       const execution = this.executions.get(submissionId);
-      if (execution) return execution;
+      if (execution) {
+        await execution;
+        continue;
+      }
       const submission = this.options.store.find(submissionId);
       if (!submission) {
-        throw new Error(`Unknown Pi submission: ${submissionId}`);
+        throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
       }
       if (isTerminalSubmissionStatus(submission.status)) return submission;
       await new Promise((resolve) => setTimeout(resolve, 50));
@@ -479,7 +504,7 @@ export class SubmissionLifecycle<
   ): Promise<TSubmission> {
     const latest = this.options.store.find(submission.submissionId);
     if (!latest) {
-      throw new Error(`Unknown Pi submission: ${submission.submissionId}`);
+      throw new Error(`Unknown SpringBrand submission: ${submission.submissionId}`);
     }
     if (isTerminalSubmissionStatus(latest.status)) return latest;
     return this.options.commitTerminal(latest, outcome, message);

package/src/layers/context/budget/gate.ts

@@ -1,3 +1,10 @@
+import {
+  type ArtifactRef,
+  serializeOutput,
+  sha256Hex,
+  type SpillWorkspace,
+} from "../../../lib/artifacts";
+
 /**
  * Durable history needs bounded values so one Tool response cannot make a
  * session impossible to restore.
@@ -11,7 +18,15 @@
 /** Maximum string leaf retained in durable tool output. */
 const STORAGE_LEAF_MAX_CHARS = 32 * 1024;
 
+/** Serialized outputs above this threshold get a narrower model view. */
+const MODEL_VIEW_THRESHOLD = 8 * 1024;
+
+/** Maximum string leaf exposed in a structure-preserving model view. */
+const MODEL_LEAF_MAX_CHARS = 500;
+
 const ELISION_RESERVE = 40;
+const PREVIEW_CHARS = 600;
+const DEFAULT_SPILL_DIR = "/scratch/tool-output";
 
 // 作用：把过长文本从中间截短，同时保留开头和结尾。
 // 调用：`truncateStringLeaves` 遇到字符串叶子时调用，传入该叶子的上限。
@@ -86,3 +101,87 @@ export function truncateStringLeaves(value: unknown, maxChars: number): unknown
 export function boundDurableToolOutput(value: unknown): unknown {
   return truncateStringLeaves(value, STORAGE_LEAF_MAX_CHARS);
 }
+
+/** Selects whether a Tool result is externalized or kept structurally durable. */
+export type BudgetPolicy = { kind: "spill" } | { kind: "structure" };
+
+/**
+ * Writes one large payload to Workspace and returns its narrow durable reference.
+ *
+ * Small values and failed/unavailable Workspace writes return `null`; callers
+ * must then retain the existing bounded-structure fallback.
+ */
+export async function spillDurableToolOutput(
+  value: unknown,
+  options: {
+    readonly workspace?: SpillWorkspace;
+  },
+): Promise<ArtifactRef | null> {
+  const { text, ext } = serializeOutput(value);
+  if (text.length <= MODEL_VIEW_THRESHOLD || !options.workspace) return null;
+  try {
+    const hash = await sha256Hex(text);
+    const path = `${DEFAULT_SPILL_DIR}/${hash.slice(0, 24)}.${ext}`;
+    await options.workspace.writeFile(
+      path,
+      text,
+      ext === "json" ? "application/json" : "text/plain",
+    );
+    return {
+      kind: "artifact_ref",
+      path,
+      bytes: new TextEncoder().encode(text).byteLength,
+      hash: hash.slice(0, 16),
+      preview: text.slice(0, PREVIEW_CHARS),
+      note:
+        "Output was large and has been saved to the Workspace file above. " +
+        "Use the read tool with that path to retrieve the full content when needed.",
+    };
+  } catch {
+    return null;
+  }
+}
+
+// Bounds leaves first, then removes oldest array entries until the view fits.
+function structureView(output: unknown): unknown {
+  const capped = truncateStringLeaves(output, MODEL_LEAF_MAX_CHARS);
+  if (serializeOutput(capped).text.length <= MODEL_VIEW_THRESHOLD) return capped;
+  if (typeof capped !== "object" || capped === null) return capped;
+
+  const record = { ...(capped as Record<string, unknown>) };
+  const arrayKey = Object.entries(record)
+    .filter((entry): entry is [string, unknown[]] => Array.isArray(entry[1]))
+    .sort((left, right) => right[1].length - left[1].length)[0]?.[0];
+  if (!arrayKey) return capped;
+
+  const items = [...(record[arrayKey] as unknown[])];
+  let dropped = 0;
+  while (
+    items.length > 1 &&
+    serializeOutput({ ...record, [arrayKey]: items }).text.length >
+      MODEL_VIEW_THRESHOLD
+  ) {
+    items.shift();
+    dropped += 1;
+  }
+  if (dropped === 0) return capped;
+  record[arrayKey] = items;
+  record[`${arrayKey}Omitted`] = {
+    count: dropped,
+    note:
+      `${dropped} earlier entr(ies) omitted to fit the model context budget; ` +
+      "the most recent are kept. The durable record retains the bounded value.",
+  };
+  return record;
+}
+
+/** Creates a non-destructive, smaller Tool-result projection for the model. */
+export function projectToolOutputForModel(output: unknown): unknown {
+  try {
+    return serializeOutput(output).text.length <= MODEL_VIEW_THRESHOLD
+      ? output
+      : structureView(output);
+  } catch {
+    return truncateStringLeaves(output, MODEL_LEAF_MAX_CHARS);
+  }
+}

package/src/lib/prompt.ts

@@ -63,6 +63,9 @@ export const TOOLS =
   "raw or customized network cases described above; every response and failure it sees is visible to you. " +
   "bash is a shell over the workspace filesystem only " +
   "(no network, no system utilities) and is approval-gated — don't reach for it to read files or fetch. " +
+  "For more than three related changes in one file, use one write or bash operation instead of serial edits; " +
+  "do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
+  "prioritize verification, saving durable results, and the final response. " +
   "When tool calls are independent, issue them in one turn so they run in parallel. When you reference " +
   "code, cite it as file_path:line_number.";
 
@@ -77,9 +80,10 @@ export const FILES =
 
 // User-interaction actions are called only when their UI semantics are useful.
 export const INTERACTION =
-  "Interaction: When the user must pick among a small set of options, call ask_user (2-6 options) " +
-  "instead of writing 'please choose A/B/C' as text, then end your turn and wait. Don't use it for " +
-  "open-ended questions or when a sensible default lets you proceed. " +
+  "Interaction: When progress requires user decisions, put all 1-4 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, or no options when a required free-text answer is necessary; 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): write your full answer " +
   "FIRST, then call suggest_followups (2-4 directions) as the very last action and end the turn — " +
   "write no text after it (the tool renders its own closing block). Never for small talk or while a " +

package/src/pi/message/projection.ts

@@ -282,7 +282,7 @@ export class PiChunkEncoder {
         return [];
       default:
         throw new Error(
-          `Unsupported Pi AgentEvent: ${String((event as { type?: unknown }).type)}`,
+          `Unsupported SpringBrand AgentEvent: ${String((event as { type?: unknown }).type)}`,
         );
     }
   }
@@ -449,7 +449,7 @@ export class PiChunkEncoder {
     if (message.stopReason === "error") {
       chunks.push({
         type: "error",
-        errorText: message.errorMessage ?? "Pi turn failed",
+        errorText: message.errorMessage ?? "SpringBrand turn failed",
       });
       return chunks;
     }

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

@@ -234,7 +234,8 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
 export function piToolRetryPolicy(
   candidate: PiToolCandidate,
 ): "idempotent" | "non-idempotent" {
-  return IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name)
+  return IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name) ||
+      candidate.owner.startsWith("subagent:")
     ? "idempotent"
     : "non-idempotent";
 }
@@ -320,7 +321,7 @@ class PreparedRuntime implements PreparedPiRuntime {
   read(owner: object): PreparedPiRuntimeState {
     if (owner !== this.owner) {
       throw new Error(
-        "Prepared Pi Runtime belongs to another PiRuntimeAdapter",
+        "Prepared SpringBrand Runtime belongs to another runtime adapter",
       );
     }
     return this.state;
@@ -340,7 +341,7 @@ export function readPreparedPiRuntime(
   owner: object,
 ): PreparedPiRuntimeState {
   if (!(prepared instanceof PreparedRuntime)) {
-    throw new Error("Prepared Pi Runtime handle is invalid");
+    throw new Error("Prepared SpringBrand Runtime handle is invalid");
   }
   return prepared.read(owner);
 }

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

@@ -46,10 +46,12 @@ import {
   withProviderRetry,
 } from "./models";
 import { EXECUTION_LEVELS } from "../../lib/execution-level";
+import { projectToolOutputForModel } from "../../layers/context/budget/gate";
+import type { SpillWorkspace } from "../../lib/artifacts";
 
 // #region Single-run Pi bridge
 
-const MAX_MODEL_TURNS = 30;
+const MAX_MODEL_TURNS_PER_SLICE = 30;
 
 export class RetryableModelError extends Error {}
 
@@ -91,7 +93,7 @@ function classifyPiStopReason(stopReason: string | undefined): {
       return {
         outcome: "failed",
         turnStatus: "error",
-        message: `Pi ended the turn with an unrecognized stop reason: ${
+        message: `SpringBrand ended the turn with an unrecognized stop reason: ${
           stopReason ?? "(none)"
         }`,
       };
@@ -134,6 +136,29 @@ interface PiTurnAdapterOptions {
   // PiCore 通过 AgentOptions.transformContext 调用它，Runtime 用它接入现有上下文处理。
   // 直接复用 Pi 的回调类型可避免这里维护另一套上下文转换约定。
   readonly transformContext: NonNullable<AgentOptions["transformContext"]>;
+  readonly workspace?: SpillWorkspace;
+}
+
+function projectToolResultsForModel(
+  messages: readonly AgentMessage[],
+): AgentMessage[] {
+  let changed = false;
+  const projected = messages.map((message) => {
+    if (message.role !== "toolResult") return message;
+    const payload = {
+      content: message.content,
+      details: message.details,
+    };
+    const next = projectToolOutputForModel(payload) as typeof payload;
+    if (next === payload) return message;
+    changed = true;
+    return {
+      ...message,
+      content: next.content,
+      details: next.details,
+    };
+  });
+  return changed ? projected : [...messages];
 }
 
 class PiTurnAdapter {
@@ -155,6 +180,7 @@ class PiTurnAdapter {
   private compile(candidates: readonly PiToolCandidate[]) {
     return compilePiTools(candidates, {
       governance: this.governance,
+      workspace: this.opts.workspace,
       settle: this.opts.settle,
     });
   }
@@ -201,7 +227,7 @@ class PiTurnAdapter {
       readonly signal?: AbortSignal;
     },
     listener: (event: AgentEvent) => void | Promise<void>,
-  ): Promise<boolean> {
+  ): Promise<PiTurnRunResult> {
     const { systemPrompt, signal } = opts;
     signal?.throwIfAborted();
     const canonicalMessages = await this.opts.canonicalMessages();
@@ -221,11 +247,14 @@ class PiTurnAdapter {
       // 切换 provider 或消息跨 provider 回放时若不规范化，provider 会静默拒绝。
       transformContext: async (messages, signal) => {
         const ctx = await this.opts.transformContext(messages, signal);
-        return transformMessages(ctx as Message[], this.opts.pi.model) as AgentMessage[];
+        return transformMessages(
+          projectToolResultsForModel(ctx) as Message[],
+          this.opts.pi.model,
+        ) as AgentMessage[];
       },
       afterToolCall: this.governance.afterToolCall,
       shouldStopAfterTurn: () => {
-        reachedModelTurnLimit = ++modelTurns >= MAX_MODEL_TURNS;
+        reachedModelTurnLimit = ++modelTurns >= MAX_MODEL_TURNS_PER_SLICE;
         return signal?.aborted === true || reachedModelTurnLimit;
       },
       initialState: {
@@ -256,7 +285,9 @@ class PiTurnAdapter {
         pi.abort();
       }
       await running;
-      return reachedModelTurnLimit;
+      return reachedModelTurnLimit
+        ? { kind: "yielded" }
+        : { kind: "terminal" };
     } finally {
       signal?.removeEventListener("abort", abort);
       unsubscribe();
@@ -371,6 +402,11 @@ export interface CreatePreparedPiTurnOptions {
    */
   readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
   readonly durability: PiTurnDurability;
+  /** Per-Submission executors for tools whose metadata is fixed at assembly time. */
+  readonly toolExecutors?: Readonly<Record<
+    string,
+    NonNullable<PiToolCandidate["tool"]["execute"]>
+  >>;
   /**
    * 上报受治理工具的耗时、结果大小和成败。
    *
@@ -442,6 +478,10 @@ export interface PiPreparedTurnRunOptions {
   readonly signal?: AbortSignal;
 }
 
+export type PiTurnRunResult =
+  | { readonly kind: "terminal" }
+  | { readonly kind: "yielded" };
+
 // #endregion
 
 // #region Durable prepared-Turn execution
@@ -500,7 +540,7 @@ export class PreparedPiTurnAdapter {
             : candidate.requiredExecutionLevel;
           if (!EXECUTION_LEVELS.includes(requiredExecutionLevel)) {
             throw new Error(
-              `Pi Tool "${candidate.tool.name}" resolved an invalid execution level`,
+              `SpringBrand Tool "${candidate.tool.name}" resolved an invalid execution level`,
             );
           }
           await state.snapshot.bindings.platform.gateTool?.({
@@ -617,7 +657,9 @@ export class PreparedPiTurnAdapter {
               `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
             );
           }
-          return candidate.tool.execute(
+          const execute = options.toolExecutors?.[candidate.tool.name] ??
+            candidate.tool.execute;
+          return execute(
             toolCallId,
             input,
             signal,
@@ -645,6 +687,7 @@ export class PreparedPiTurnAdapter {
         this.interrupted ? undefined : options.durability.settleTool(call),
       onToolTelemetry: options.onToolTelemetry,
       transformContext: options.transformContext,
+      workspace: state.snapshot.bindings.workspace,
     });
     this.systemPrompt = descriptor.systemPrompt;
     this.options = options;
@@ -744,9 +787,9 @@ export class PreparedPiTurnAdapter {
    */
   async run(
     options: PiPreparedTurnRunOptions,
-  ): Promise<void> {
+  ): Promise<PiTurnRunResult> {
     this.terminalIntent = undefined;
-    const reachedModelTurnLimit = await this.turn.run(
+    const result = await this.turn.run(
       {
         systemPrompt: this.systemPrompt,
         tools: this.candidates,
@@ -754,15 +797,11 @@ export class PreparedPiTurnAdapter {
       },
       (event) => this.handleEvent(event),
     );
-    if (reachedModelTurnLimit && !this.terminalIntent) {
-      this.terminalIntent = {
-        outcome: "failed",
-        message: `Pi stopped after ${MAX_MODEL_TURNS} model turns`,
-      };
-    }
     if (this.terminalIntent) {
       await this.options.onTerminal(this.terminalIntent);
+      return { kind: "terminal" };
     }
+    return result;
   }
 
   // 提交完成的 Pi 消息、推导终态意图，并把事件投影给可恢复流。

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

@@ -33,6 +33,11 @@ import {
   PiRuntimeTranscript,
   type PiTranscriptDurability,
 } from "./transcript";
+import { subagentPiToolCandidates } from "../tool/subagent";
+import type {
+  RuntimeSubagentLifecyclePort,
+  RuntimeSubagentPort,
+} from "../../kernel/bindings";
 import type { SqlTaggedTemplate } from "agents/chat";
 
 /**
@@ -201,6 +206,34 @@ export class PiRuntimeAdapter {
    * 实现理由：构造时会校验 Prepared Runtime 的 owner 和 pinned descriptor 格式，再建立本 Turn 独享的 Tool governance 与执行状态。
    * 不要跨 Turn 复用返回对象；abort、steer、assistant ordinal 和 Tool governance 都是单次执行状态。
    */
+  /**
+   * 为一个已准入的 Submission 生成绑定 durable lifecycle 的 SubAgent Tool 执行器。
+   *
+   * @remarks
+   * 调用方：Runtime 在创建 Turn 前调用一次，并把结果作为 `createTurn` 的 `toolExecutors` 传入。
+   *
+   * 实现理由：SubAgent Tool 的名称、Schema 和执行语义属于 Pi Tool 层，而 accountId、
+   * rateVersion 和 slot identity 这些计费事实属于 Submission。两者在这里汇合：Pi 提供工具，
+   * Runtime 提供本次 Submission 的 lifecycle 端口，因此 Runtime 不需要认识 Tool 模块本身。
+   * 没有可用 SubAgent 类型时返回 `undefined`，让 Turn 继续使用装配期的无 lifecycle 执行器。
+   */
+  subagentToolExecutors(
+    subagents: RuntimeSubagentPort,
+    enabledSubagents: readonly string[],
+    lifecycle: RuntimeSubagentLifecyclePort,
+  ): CreatePreparedPiTurnOptions["toolExecutors"] {
+    const entries = subagentPiToolCandidates(
+      subagents,
+      enabledSubagents,
+      lifecycle,
+    ).flatMap((candidate) =>
+      candidate.tool.execute
+        ? [[candidate.tool.name, candidate.tool.execute] as const]
+        : []
+    );
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+  }
+
   createTurn(
     options: CreatePreparedPiTurnOptions,
   ): PreparedPiTurnAdapter {
@@ -226,6 +259,7 @@ export type {
   PiStoredToolSettlement,
   PiToolSettlement,
   PiToolInputRecord,
+  PiTurnRunResult,
   PreparedPiTurnAdapter,
 } from "./execution";
 export type {

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

@@ -498,7 +498,7 @@ function configuredModel(
   );
   if (!catalogModel) {
     throw new Error(
-      `Model is not in Pi's built-in catalog for ${endpoint.protocol}: ${modelId}`,
+      `Model is not in SpringBrand's built-in catalog for ${endpoint.protocol}: ${modelId}`,
     );
   }
   const {
@@ -513,6 +513,7 @@ function configuredModel(
     ...catalogHeaders,
     ...endpoint.headers,
   };
+  const openRouterProviderPin = endpoint.openRouterProviderPins?.[modelId];
   return {
     ...metadata,
     api: apiFor(endpoint.protocol),
@@ -524,6 +525,14 @@ function configuredModel(
             ...compat,
             sendSessionAffinityHeaders: true,
             sessionAffinityFormat: "openrouter" as const,
+            ...(openRouterProviderPin
+              ? {
+                  openRouterRouting: {
+                    order: [openRouterProviderPin],
+                    allow_fallbacks: false,
+                  },
+                }
+              : {}),
           },
         }
       : {}),