@springbrand/agent-runtime 0.2.0-alpha.44 → 0.2.0-alpha.46

package/package.json

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

package/src/adapter/cloudflare/subagent/definition.ts

@@ -19,7 +19,6 @@ import type {
 import { PiChunkEncoder } from "../../../pi/message";
 import {
   createPiModels,
-  resolvePiApiKey,
   resolvePiModel,
   withProviderRetry,
 } from "../../../pi/runtime-adapter/models";
@@ -398,8 +397,6 @@ export abstract class CloudflareSubAgent<
         input,
         model,
         streamFn: withProviderRetry(models.streamSimple.bind(models)),
-        getApiKey: () =>
-          resolvePiApiKey(provider, provider.defaultModel),
         tools,
         signal,
         onEvent: (event) => {

package/src/adapter/cloudflare/subagent/runner.ts

@@ -12,6 +12,7 @@ import type {
 import { z } from "zod";
 import { assembleSubagentPrompt } from "../../../lib/prompt";
 import type { AgentType } from "../../../layers/orchestration/subagents/agent-types/contract";
+import { structuredOutputStream } from "../../../pi/runtime-adapter/models";
 
 const RECURSIVE_TOOLS = new Set([
   "run_agent",
@@ -28,7 +29,6 @@ export interface CloudflareSubAgentRun {
   model: Model<Api>;
   streamFn: StreamFn;
   tools: AgentTool[];
-  getApiKey?: (provider: string) => string | undefined;
   signal?: AbortSignal;
   timeoutMs?: number;
   onEvent?: (event: AgentEvent, signal: AbortSignal) => void | Promise<void>;
@@ -67,11 +67,16 @@ function toolErrorText(result: unknown): string {
   return "tool execution failed";
 }
 
-function taskPrompt(type: AgentType, input: unknown): string {
+function taskPrompt(
+  input: unknown,
+  outputSchema?: Record<string, unknown>,
+): string {
   return [
     "Complete this bounded task.",
     `Input:\n${JSON.stringify(input)}`,
-    `Return only one JSON object matching this schema:\n${JSON.stringify(z.toJSONSchema(type.outputSchema))}`,
+    outputSchema
+      ? `Return only one JSON object matching this schema:\n${JSON.stringify(outputSchema)}`
+      : "Return only one JSON object matching the configured output schema.",
   ].join("\n\n");
 }
 
@@ -90,13 +95,18 @@ export async function runCloudflareSubAgent(
     }
   }
   if (run.signal?.aborted) throw new Error("SubAgent run aborted");
+  const { $schema: _, ...outputSchema } = z.toJSONSchema(run.type.outputSchema);
+  const constrainedStream = structuredOutputStream(
+    run.streamFn,
+    run.model,
+    outputSchema,
+  );
 
   // 这里没有审批闸,也装不了:到这一步工具已经被 compilePiTools 编译成 AgentTool,
   // requiredExecutionLevel 只挂在编译前的 PiToolCandidate 上,这里读不到。「子 agent 不许挂需审批的工具」
   // 这条不变量由装配处 createCloudflareSubAgentTools 的启动期断言强制执行。
   const agent = new Agent({
-    streamFn: run.streamFn,
-    getApiKey: run.getApiKey,
+    streamFn: constrainedStream ?? run.streamFn,
     initialState: {
       model: run.model,
       systemPrompt: assembleSubagentPrompt(run.type.persona),
@@ -125,7 +135,10 @@ export async function runCloudflareSubAgent(
   }, run.timeoutMs ?? DEFAULT_TIMEOUT_MS);
 
   try {
-    await agent.prompt(taskPrompt(run.type, input.data));
+    await agent.prompt(taskPrompt(
+      input.data,
+      constrainedStream ? undefined : outputSchema,
+    ));
   } finally {
     clearTimeout(timeout);
     run.signal?.removeEventListener("abort", abort);

package/src/db/schema.ts

@@ -25,7 +25,8 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
     assistant_message_id TEXT NOT NULL,
     abort_reason TEXT,
     recovery_error_count INTEGER NOT NULL DEFAULT 0,
-    recovery_reason TEXT
+    recovery_reason TEXT,
+    context_overflow_retried INTEGER NOT NULL DEFAULT 0
   )`;
   const submissionColumns = new Set(
     sql<{ name: string }>`PRAGMA table_info(pi_submissions)`
@@ -77,6 +78,10 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
   if (!submissionColumns.has("recovery_reason")) {
     sql`ALTER TABLE pi_submissions ADD COLUMN recovery_reason TEXT`;
   }
+  if (!submissionColumns.has("context_overflow_retried")) {
+    sql`ALTER TABLE pi_submissions
+        ADD COLUMN context_overflow_retried INTEGER NOT NULL DEFAULT 0`;
+  }
   sql`CREATE UNIQUE INDEX IF NOT EXISTS pi_submissions_one_running
       ON pi_submissions(status)
       WHERE status = 'running'`;

package/src/db/submission.repo.ts

@@ -11,7 +11,8 @@ export type SubmissionStatus =
   | "error";
 export type SubmissionRecoveryReason =
   | "no_meaningful_model_progress"
-  | "transient_model_error";
+  | "transient_model_error"
+  | "context_overflow";
 
 const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
   "completed",
@@ -422,6 +423,17 @@ export class SubmissionRepository {
     `[0]?.recovery_error_count ?? 0;
   }
 
+  claimContextOverflowRecovery(id: string): boolean {
+    return Boolean(this.sql<{ claimed: number }>`
+      UPDATE pi_submissions
+      SET context_overflow_retried = 1
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+        AND context_overflow_retried = 0
+      RETURNING 1 AS claimed
+    `[0]?.claimed);
+  }
+
   /**
    * 记录一个让步执行片的累计模型回合数和续跑标识。
    *

package/src/index.ts

@@ -144,6 +144,5 @@ export {
 export {
   createPiModels,
   modelRequestUrl,
-  resolvePiApiKey,
   resolvePiModel,
 } from "./pi/runtime-adapter/models";

package/src/kernel/bindings.ts

@@ -855,10 +855,6 @@ export interface RuntimeTurnEventsPort {
     readonly submissionId: string;
     readonly approvalExecutionId: string;
   }): Promise<void>;
-  /**
-   * 至少一次投当前 Session Activity；Host 应按 revision 幂等处理重试。
-   * Runtime 恢复时会略过已过时的 revision，避免重放旧 working 状态。
-   */
   onActivityChanged?(
     projection: RuntimeActivityProjection,
   ): Promise<void>;

package/src/kernel/submission-lifecycle.ts

@@ -92,14 +92,7 @@ export interface SubmissionStore<TSubmission extends SubmissionRecord> {
   countPending(): number;
   findRunning(): TSubmission | null;
   findNextPending(): TSubmission | null;
-  /**
-   * 列出全部等待或运行中的提交标识。
-   *
-   * @remarks
-   * `stop` 没有指定请求时调用，并逐条走统一取消路径。
-   *
-   * 只返回标识可以避免停止入口复制完整记录或状态判断。
-   */
+  listPending(): TSubmission[];
   /**
    * 持久化一条取消原因。
    *
@@ -694,5 +687,29 @@ export class SubmissionLifecycle<
     return { ok: submissionIds.length > 0 };
   }
 
+  /** Stops every running or queued Submission without pumping between them. */
+  async stopAll(reason = "Stopped"): Promise<{ ok: boolean }> {
+    const running = this.options.store.findRunning();
+    const submissions = [
+      ...(running ? [running] : []),
+      ...this.options.store.listPending(),
+    ];
+    if (submissions.length === 0) return { ok: false };
+
+    this.options.store.transaction(() => {
+      for (const submission of submissions) {
+        this.options.store.updateAbortReason(submission.submissionId, reason);
+        this.options.appendAbortIntent(submission, reason);
+      }
+    });
+    for (const submission of submissions) {
+      const active = this.activeBySubmission.get(submission.submissionId);
+      if (active) this.options.abortActive(active);
+      await this.finish(submission, "aborted", reason);
+    }
+    this.pump();
+    return { ok: true };
+  }
+
   // #endregion
 }

package/src/pi/assembly/context.ts

@@ -3,6 +3,7 @@ import {
   compact as compactPiTranscript,
   DEFAULT_COMPACTION_SETTINGS,
   estimateContextTokens,
+  estimateTokens,
   prepareCompaction,
   type AgentMessage,
   type CompactionEntry,
@@ -86,9 +87,9 @@ function sumUsage(responses: readonly AssistantMessage[]): Usage | undefined {
 export async function compactPiContext(input: Readonly<{
   branch: readonly SessionTreeEntry[];
   compactAfterTokens: number;
+  force?: boolean;
   models: Models;
   model: Model<any>;
-  apiKey?: string;
   signal?: AbortSignal;
 }>): Promise<{
   messages: AgentMessage[];
@@ -116,8 +117,8 @@ export async function compactPiContext(input: Readonly<{
     const settings = DEFAULT_COMPACTION_SETTINGS;
     if (
       !settings.enabled ||
-      estimateContextTokens(currentMessages).tokens <
-        input.compactAfterTokens
+      (!input.force && estimateContextTokens(currentMessages).tokens <
+        input.compactAfterTokens)
     ) {
       return {
         messages: currentMessages,
@@ -149,10 +150,7 @@ export async function compactPiContext(input: Readonly<{
         context: Parameters<Models["completeSimple"]>[1],
         options?: Parameters<Models["completeSimple"]>[2],
       ) => {
-        const response = await input.models.completeSimple(model, context, {
-          ...options,
-          ...(input.apiKey ? { apiKey: input.apiKey } : {}),
-        });
+        const response = await input.models.completeSimple(model, context, options);
         responses.push(response);
         return response;
       },
@@ -199,10 +197,25 @@ export async function compactPiContext(input: Readonly<{
       ? firstResponse.stopReason
       : undefined;
     const usage = sumUsage(responses);
+    const messages = buildSessionContext(
+      [...branch, previewEntry],
+    ).messages;
+    if (
+      input.force &&
+      messages.reduce((total, message) => total + estimateTokens(message), 0) >=
+        currentMessages.reduce(
+          (total, message) => total + estimateTokens(message),
+          0,
+        )
+    ) {
+      return {
+        messages: currentMessages,
+        didCompact: false,
+        degraded: true,
+      };
+    }
     return {
-      messages: buildSessionContext(
-        [...branch, previewEntry],
-      ).messages,
+      messages,
       compactionEntry,
       ...(firstResponse && usage
         ? {

package/src/pi/assembly/snapshot.ts

@@ -2,8 +2,11 @@ import type {
   AgentMessage,
   ThinkingLevel,
 } from "@earendil-works/pi-agent-core";
-import type { Api, Model } from "@earendil-works/pi-ai";
-import { clampReasoning } from "@earendil-works/pi-ai/api/simple-options";
+import {
+  clampThinkingLevel,
+  type Api,
+  type Model,
+} from "@earendil-works/pi-ai";
 import type {
   RuntimeMcpServer,
   RuntimeProfile,
@@ -84,15 +87,14 @@ function freezeModel(model: Model<Api>): Model<Api> {
   });
 }
 
-// 作用：把 Runtime 的思考强度名称转成 Pi Agent Core 接受的名称。
-// 调用：创建 Runtime 装配快照时对 profile 中的 `thinking` 调用。
-// 原因：`none` 映射成 `off`；xhigh/max 用 clampReasoning 夹到 API 真正支持的最高档，
-// 避免超出范围的等级在 provider 侧静默失败。
+// 作用：把 Runtime 的思考强度夹到当前模型真正支持的 Pi 档位。
+// 调用：创建 Runtime 装配快照时对已解析模型和 profile `thinking` 调用。
 function toPiThinkingLevel(
+  model: Model<Api>,
   thinking: ThinkingEffort,
 ): ThinkingLevel {
   if (thinking === "none") return "off";
-  return clampReasoning(thinking) ?? "off";
+  return clampThinkingLevel(model, thinking);
 }
 
 // 作用：复制并冻结一个 Extension 配置的 manifest 和权限集合。
@@ -197,10 +199,14 @@ export function createPiRuntimeAssembly(
   Object.freeze(messages);
   Object.freeze(mcpServers);
   Object.freeze(extensions);
+  const model = freezeModel(
+    resolvePiModel(input.provider, input.profile.model),
+  );
 
   return Object.freeze({
-    model: freezeModel(resolvePiModel(input.provider, input.profile.model)),
+    model,
     thinkingLevel: toPiThinkingLevel(
+      model,
       input.profile.thinking,
     ),
     systemPrompt: assembleSystemPrompt(

package/src/pi/message/conversion.ts

@@ -43,7 +43,15 @@ function userContent(
         data: inlineImage[2]!,
       });
     } else {
-      content.push({ type: "text", text: attachmentText(part) });
+      content.push(
+        { type: "text", text: attachmentText(part) },
+        {
+          type: "file",
+          url: part.url,
+          mimeType: part.mediaType,
+          ...(part.filename ? { filename: part.filename } : {}),
+        },
+      );
     }
   }
   if (content.length === 0) throw new Error("User message content is required");

package/src/pi/message/projection.ts

@@ -123,17 +123,40 @@ function toolCallAt(
   return part?.type === "toolCall" ? part : undefined;
 }
 
-function finishReason(reason: string): FinishReason {
-  switch (reason) {
+/** The one interpretation of a non-Tool Pi assistant terminal. */
+export function classifyPiTerminalStopReason(
+  stopReason: string | undefined,
+): {
+  outcome: "succeeded" | "failed" | "aborted";
+  turnStatus: "completed" | "error" | "aborted";
+  finishReason?: FinishReason;
+  message?: string;
+} {
+  switch (stopReason) {
     case "stop":
     case "length":
-      return reason;
-    case "toolUse":
-      return "tool-calls";
+      return {
+        outcome: "succeeded",
+        turnStatus: "completed",
+        finishReason: stopReason,
+      };
+    case "aborted":
+      return { outcome: "aborted", turnStatus: "aborted" };
     case "error":
-      return "error";
+      return {
+        outcome: "failed",
+        turnStatus: "error",
+        finishReason: "error",
+      };
     default:
-      return "other";
+      return {
+        outcome: "failed",
+        turnStatus: "error",
+        finishReason: "error",
+        message: `SpringBrand ended the turn with an unrecognized stop reason: ${
+          stopReason ?? "(none)"
+        }`,
+      };
   }
 }
 
@@ -345,8 +368,15 @@ export class PiChunkEncoder {
             update.error.errorMessage ?? update.reason,
           ) ?? "SpringBrand turn failed",
         }];
-      default:
+      case "start":
+      case "done":
         return [];
+      default:
+        throw new Error(
+          `Unsupported SpringBrand AssistantMessageEvent: ${
+            String((update as { type?: unknown }).type)
+          }`,
+        );
     }
   }
 
@@ -448,43 +478,39 @@ export class PiChunkEncoder {
     }
     this.finished = true;
     const publicError = publicAssistantError(message.errorMessage);
+    const terminal = classifyPiTerminalStopReason(message.stopReason);
     if (this.startedAt !== undefined) {
-      const turnStatus = message.stopReason === "aborted"
-        ? "aborted"
-        : message.stopReason === "error"
-          ? "error"
-          : "completed";
       chunks.push({
         type: "message-metadata",
         messageMetadata: {
           createdAt: this.startedAt,
           completedAt: message.timestamp,
           turnDurationMs: Math.max(0, message.timestamp - this.startedAt),
-          turnStatus,
+          turnStatus: terminal.turnStatus,
           ...(this.turnId ? { turnId: this.turnId } : {}),
-          ...(publicError &&
-              (message.stopReason !== "aborted" ||
+          ...((publicError ?? terminal.message) &&
+              (terminal.outcome !== "aborted" ||
                 message.errorMessage !== USER_STOP_REASON)
-            ? { error: publicError }
+            ? { error: publicError ?? terminal.message }
             : {}),
         },
       });
     }
-    if (message.stopReason === "aborted") {
+    if (terminal.outcome === "aborted") {
       chunks.push({ type: "abort", reason: message.errorMessage });
       return chunks;
     }
-    if (message.stopReason === "error") {
+    if (terminal.outcome === "failed") {
       chunks.push({
         type: "error",
-        errorText: publicError ?? "SpringBrand turn failed",
+        errorText: publicError ?? terminal.message ?? "SpringBrand turn failed",
       });
       return chunks;
     }
     chunks.push({ type: "finish-step" });
     chunks.push({
       type: "finish",
-      finishReason: finishReason(message.stopReason),
+      finishReason: terminal.finishReason ?? "other",
     });
     return chunks;
   }

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

@@ -200,46 +200,18 @@ export interface PreparedPiRuntimeState {
 
 // #region 版本描述与准备句柄
 
-const IDEMPOTENT_TOOL_NAMES = new Set([
-  "activate_skill",
-  "browser_extract",
-  "browser_links",
-  "browser_markdown",
-  "browser_scrape",
-  "bind_resource",
-  "delete",
-  "edit",
-  "execute",
-  "find",
-  "get_time",
-  "grep",
-  "list",
-  "list_resources",
-  "list_extensions",
-  "list_schedules",
-  "read",
-  "read_skill_resource",
-  "sandbox_process_logs",
-  "web_search",
-  "write",
-  "unbind_resource",
-]);
-
 /**
  * 判断工具在执行结果不确定时能否安全重试。
  *
  * @remarks
  * Turn 执行在记录第一次尝试前调用它，恢复流程随后使用这条持久化结论。
  *
- * 白名单故意保持保守，未知工具和新工具都会默认按不可重复执行处理。
+ * 重试语义由 Tool Candidate 自己声明；未声明的工具失败关闭为不可重复执行。
  */
 export function piToolRetryPolicy(
   candidate: PiToolCandidate,
 ): "idempotent" | "non-idempotent" {
-  return candidate.retry ?? (IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name) ||
-      candidate.owner.startsWith("subagent:")
-    ? "idempotent"
-    : "non-idempotent");
+  return candidate.retry ?? "non-idempotent";
 }
 
 // 把工具候选整理成版本描述里要保存的稳定字段。