@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.10

package/src/pi/turn/interaction.ts

@@ -0,0 +1,181 @@
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+
+/**
+ * 表示一个 Pi Tool 在等待客户端投递结果时的持久 park 记录。
+ *
+ * Runtime 在带 `interaction` 声明的 Tool 进入执行链时保存它，恢复路径按 `interactionId` 读取并应用一次响应。
+ *
+ * Tool 输入随记录一起保存，才能在 Durable Object 重建后把响应映射回原始调用，而不是重新推断它。
+ */
+export interface PiToolInteraction {
+  interactionId: string;
+  requestId: string;
+  toolCallId: string;
+  toolName: string;
+  inputJson: string;
+  createdAt: number;
+  status: "pending" | "responded" | "cancelled";
+  respondedAt?: number;
+  responseJson?: string;
+}
+
+/**
+ * 说明一次 interaction 为什么在没有拿到用户选择的情况下结束。
+ *
+ * 目前只有一种：用户没有点选项，而是直接在聊天里发了消息。
+ * 新增成员时必须同步更新 `cancelText` 与解码器的枚举校验。
+ */
+export type PiToolInteractionCancelReason =
+  | "user_replied_freeform"
+  | "submission_terminal";
+
+/**
+ * 描述一次 interaction 状态转换要求调用方采取的动作。
+ *
+ * `park` 表示继续等待，`settle` 表示已得到权威 ToolResult 可以续跑，`noop` 表示重复投递应被忽略。
+ *
+ * 状态转换与 I/O 分开，使同一套幂等规则同时服务在线执行和崩溃恢复 —— 与审批同构。
+ */
+export type PiToolInteractionOutcome =
+  | { kind: "park"; interactionId: string; requestId: string }
+  | {
+      kind: "settle";
+      interactionId: string;
+      requestId: string;
+      toolCallId: string;
+      toolResult: ToolResultMessage;
+    }
+  | { kind: "noop"; interactionId: string };
+
+/**
+ * 把 interaction 的新状态和对应动作绑定为一个不可拆分的结果。
+ *
+ * 在线执行与恢复调用方应同时消费 `interaction` 和 `outcome`，不要只持久化其中一半。
+ */
+export interface PiToolInteractionTransition {
+  interaction: PiToolInteraction;
+  outcome: PiToolInteractionOutcome;
+}
+
+/**
+ * 用户改为自由发言时写进 ToolResult 的提示语。
+ *
+ * 刻意**不包含用户原文** —— 紧随其后的那条用户消息里就有，复制进来模型会读到两遍。
+ * 这段文字是模型判断「那句话算不算答案」的唯一依据，改动前先想清楚它会怎么读。
+ */
+const CANCEL_TEXT: Record<PiToolInteractionCancelReason, string> = {
+  user_replied_freeform:
+    "The user did not pick an option. They replied in the chat instead — " +
+    "read their next message and treat it as the answer if it addresses " +
+    "the question; otherwise follow whatever they actually asked for.",
+  submission_terminal:
+    "The turn ended before the user answered. Do not assume any option was chosen.",
+};
+
+/**
+ * 创建一条待响应的 interaction，并告诉调用方暂停当前 Tool。
+ *
+ * 执行适配器确认 Tool 声明了 `interaction` 后调用它，再把返回的记录持久化并等待客户端投递。
+ *
+ * 此处不填写响应时间或响应体，保证新记录只有一个明确的 `pending` 起点。
+ */
+export function parkPiToolInteraction(
+  input: Omit<
+    PiToolInteraction,
+    "status" | "respondedAt" | "responseJson"
+  >,
+): PiToolInteractionTransition {
+  return {
+    interaction: { ...input, status: "pending" },
+    outcome: {
+      kind: "park",
+      interactionId: input.interactionId,
+      requestId: input.requestId,
+    },
+  };
+}
+
+/**
+ * 把客户端的首次响应应用到待响应记录。
+ *
+ * 在线 RPC 与恢复路径在读到持久记录后调用它；已经结束的记录返回 `noop`，调用方不得再次结算 Tool。
+ *
+ * `toolResult` 由调用方按 Tool 自己的 `settle` 映射产出 —— 本函数不解释响应体语义，只负责状态单调前进。
+ */
+export function respondPiToolInteraction(
+  interaction: PiToolInteraction,
+  input: {
+    response: unknown;
+    toolResult: ToolResultMessage;
+    respondedAt: number;
+  },
+): PiToolInteractionTransition {
+  if (interaction.status !== "pending") {
+    return {
+      interaction,
+      outcome: { kind: "noop", interactionId: interaction.interactionId },
+    };
+  }
+  return {
+    interaction: {
+      ...interaction,
+      status: "responded",
+      respondedAt: input.respondedAt,
+      responseJson: JSON.stringify(input.response),
+    },
+    outcome: {
+      kind: "settle",
+      interactionId: interaction.interactionId,
+      requestId: interaction.requestId,
+      toolCallId: interaction.toolCallId,
+      toolResult: input.toolResult,
+    },
+  };
+}
+
+/**
+ * 在用户没有作答的情况下结束一条 interaction。
+ *
+ * `dispatchMessage` 发现 park 期间来了用户消息时调用，Submission 进终态收尾时也调用。
+ *
+ * 取消同样产出 `isError: false` 的稳定 ToolResult —— 它不是 Tool 失败，而是一个「没选」的已处理结果；
+ * 改成异常会让模型收到 tool_error 并倾向于重试，那恰恰是我们不想要的。
+ */
+export function cancelPiToolInteraction(
+  interaction: PiToolInteraction,
+  input: {
+    reason: PiToolInteractionCancelReason;
+    cancelledAt: number;
+    toolResult?: ToolResultMessage;
+  },
+): PiToolInteractionTransition {
+  if (interaction.status !== "pending") {
+    return {
+      interaction,
+      outcome: { kind: "noop", interactionId: interaction.interactionId },
+    };
+  }
+  const toolResult: ToolResultMessage = input.toolResult ?? {
+    role: "toolResult",
+    toolCallId: interaction.toolCallId,
+    toolName: interaction.toolName,
+    content: [{ type: "text", text: CANCEL_TEXT[input.reason] }],
+    details: { cancelled: true, reason: input.reason },
+    isError: false,
+    timestamp: input.cancelledAt,
+  };
+  return {
+    interaction: {
+      ...interaction,
+      status: "cancelled",
+      respondedAt: input.cancelledAt,
+    },
+    outcome: {
+      kind: "settle",
+      interactionId: interaction.interactionId,
+      requestId: interaction.requestId,
+      toolCallId: interaction.toolCallId,
+      toolResult,
+    },
+  };
+}

package/src/pi/turn/tool-recovery.ts

@@ -5,6 +5,13 @@ import {
   type PiApprovalOutcome,
   type PiToolApproval,
 } from "./approval";
+import {
+  cancelPiToolInteraction,
+  respondPiToolInteraction,
+  type PiToolInteraction,
+  type PiToolInteractionCancelReason,
+  type PiToolInteractionOutcome,
+} from "./interaction";
 
 /**
  * 本文件实现 Pi Tool、审批、续跑和终态里程碑的纯恢复状态机。
@@ -52,12 +59,28 @@ export type PiToolRecoveryMilestone =
       type: "approval";
       approval: PiToolApproval;
     })
+  | (RecoveryIdentity & {
+      type: "interaction";
+      interaction: PiToolInteraction;
+    })
   | (RecoveryIdentity & {
       type: "continuation";
       continuationKey: string;
       phase: "pending" | "committed";
       timestamp: number;
     })
+  /**
+   * 一次被承认的装配迁移：这条 Submission 停在人机等待期间换了装配。
+   *
+   * `assemblyRevision` 是迁移前那份（所以它自己通过身份校验），
+   * `nextAssemblyRevision` 是迁移后那份。重放读到它之前按旧 revision 校验
+   * 身份，读到之后按新的。同一条 Submission 允许发生多次。
+   */
+  | (RecoveryIdentity & {
+      type: "assembly-repin";
+      nextAssemblyRevision: string;
+      timestamp: number;
+    })
   | (RecoveryIdentity & {
       type: "terminal";
       phase: "intent" | "committed";
@@ -93,6 +116,7 @@ export interface PiToolRecoveryState {
   assemblyRevision?: string;
   toolCalls: Readonly<Record<string, RecoveredToolCall>>;
   approvals: Readonly<Record<string, PiToolApproval>>;
+  interactions: Readonly<Record<string, PiToolInteraction>>;
   continuations: Readonly<
     Record<string, "pending" | "committed">
   >;
@@ -113,6 +137,11 @@ export type PiToolRecoveryPlan =
       executionId: string;
       chargeRecoveryBudget: false;
     }
+  | {
+      kind: "parked-interaction";
+      interactionId: string;
+      chargeRecoveryBudget: false;
+    }
   | {
       kind: "retry-tool";
       toolCallId: string;
@@ -168,6 +197,19 @@ export interface RecoveredPiApprovalDecision {
   outcome: PiApprovalOutcome;
 }
 
+/**
+ * 表示恢复路径应用一次 interaction 响应或取消后需要追加的里程碑和动作。
+ *
+ * Runtime 收到 respond 或 cancel 命令时同时持久化 `milestones` 并处理 `outcome`。
+ *
+ * 与审批不同的是，settle 分支的 `tool-result` 里程碑带 `needsContinuation: true`：
+ * interaction 没有自己的续跑键，续跑完全依赖既有的 `tool:<id>:settled` 路径。
+ */
+export interface RecoveredPiToolInteractionSettlement {
+  milestones: PiToolRecoveryMilestone[];
+  outcome: PiToolInteractionOutcome;
+}
+
 // #endregion
 
 // #region 里程碑编码与校验
@@ -256,6 +298,28 @@ function isApproval(value: unknown): value is PiToolApproval {
   );
 }
 
+// 校验从持久 JSON 读出的值是否是完整的 Pi Tool interaction 记录。
+// 里程碑解码器处理 interaction 事件时调用它。
+// 状态采用封闭枚举，未知协议值会让本次重放停在可信前缀 —— 与 isApproval 同一口径。
+function isInteraction(value: unknown): value is PiToolInteraction {
+  return (
+    isRecord(value) &&
+    typeof value.interactionId === "string" &&
+    typeof value.requestId === "string" &&
+    typeof value.toolCallId === "string" &&
+    typeof value.toolName === "string" &&
+    typeof value.inputJson === "string" &&
+    typeof value.createdAt === "number" &&
+    (value.respondedAt === undefined ||
+      typeof value.respondedAt === "number") &&
+    (value.responseJson === undefined ||
+      typeof value.responseJson === "string") &&
+    (value.status === "pending" ||
+      value.status === "responded" ||
+      value.status === "cancelled")
+  );
+}
+
 /**
  * 把一个 Pi Tool 恢复里程碑编码成可持久化的 JSON 正文。
  *
@@ -315,6 +379,10 @@ export function decodePiToolRecoveryMilestone(
       return isApproval(value.approval)
         ? (value as PiToolRecoveryMilestone)
         : null;
+    case "interaction":
+      return isInteraction(value.interaction)
+        ? (value as PiToolRecoveryMilestone)
+        : null;
     case "continuation":
       return typeof value.continuationKey === "string" &&
         (value.phase === "pending" ||
@@ -322,6 +390,12 @@ export function decodePiToolRecoveryMilestone(
         typeof value.timestamp === "number"
         ? (value as PiToolRecoveryMilestone)
         : null;
+    case "assembly-repin":
+      return typeof value.nextAssemblyRevision === "string" &&
+        value.nextAssemblyRevision.length > 0 &&
+        typeof value.timestamp === "number"
+        ? (value as PiToolRecoveryMilestone)
+        : null;
     case "terminal":
       return (value.phase === "intent" ||
         value.phase === "committed") &&
@@ -390,6 +464,7 @@ export function replayPiToolRecovery(
 ): PiToolRecoveryState {
   const tools: Record<string, RecoveredToolCall> = {};
   const approvals: Record<string, PiToolApproval> = {};
+  const interactions: Record<string, PiToolInteraction> = {};
   const continuations: Record<
     string,
     "pending" | "committed"
@@ -398,6 +473,7 @@ export function replayPiToolRecovery(
   let state: PiToolRecoveryState = {
     toolCalls: tools,
     approvals,
+    interactions,
     continuations,
     canonicalToolResults: results,
   };
@@ -488,6 +564,27 @@ export function replayPiToolRecovery(
         }
         break;
       }
+      case "interaction": {
+        const previous = interactions[milestone.interaction.interactionId];
+        // 与 approval 同一口径：pending 可以前进到一个结局，但已结局的记录不能被翻转。
+        // 同状态重复记录允许刷新完整持久快照，同时保持结果不变。
+        if (
+          !previous ||
+          previous.status === "pending" ||
+          previous.status === milestone.interaction.status
+        ) {
+          interactions[milestone.interaction.interactionId] =
+            milestone.interaction;
+        }
+        break;
+      }
+      case "assembly-repin":
+        // 身份校验已经按迁移前的 revision 通过；从这里往后的里程碑属于新装配。
+        state = {
+          ...state,
+          assemblyRevision: milestone.nextAssemblyRevision,
+        };
+        break;
       case "continuation":
         // committed 是单调终态，迟到的 pending 记录不能让续跑再次被调度。
         if (
@@ -529,6 +626,7 @@ export function replayPiToolRecovery(
     ...state,
     toolCalls: tools,
     approvals,
+    interactions,
     continuations,
     canonicalToolResults: results,
   };
@@ -574,7 +672,8 @@ function continuationPlan(
  *
  * Runtime 恢复适配器在每次状态变化后调用它，并只执行返回计划对应的一个动作。
  *
- * 优先级固定为终态、已决定审批、待审批、已结算 Tool、未结算 Tool，不能调换到越过终态或用户许可。
+ * 优先级固定为终态、已决定审批、待审批、待响应 interaction、已结算 Tool、未结算 Tool，
+ * 不能调换到越过终态或用户许可。
  */
 export function planPiToolRecovery(
   state: PiToolRecoveryState,
@@ -619,6 +718,18 @@ export function planPiToolRecovery(
       chargeRecoveryBudget: false,
     };
   }
+  // 仍等客户端投递结果的 interaction 同样保持 parked。
+  // 已响应或已取消的 interaction 不在这里出现：它们在写入本记录的同一批里程碑中
+  // 一并写了 tool-result，因此直接落到下面「已结算 Tool 补齐续跑」那条既有路径，
+  // 不需要 interaction 专属的续跑键。
+  for (const interaction of Object.values(state.interactions)) {
+    if (interaction.status !== "pending") continue;
+    return {
+      kind: "parked-interaction",
+      interactionId: interaction.interactionId,
+      chargeRecoveryBudget: false,
+    };
+  }
 
   // 已结算 Tool 先补齐续跑；未结算 Tool 只有声明幂等时才自动重试。
   for (const tool of Object.values(state.toolCalls)) {
@@ -724,6 +835,42 @@ export function commitPiRecoveryContinuation(
 
 // #endregion
 
+// #region 装配迁移
+
+/**
+ * 为一次停在人机等待期间发生的装配迁移创建里程碑。
+ *
+ * 宿主换完装配、准备把 Submission 重新 pin 到新装配上时调用它；返回的里程碑
+ * 必须与 `pinAssembly` 的写入落在同一个事务里，否则重启后里程碑与 Submission
+ * 会各自指向一半的迁移。
+ *
+ * 已经处在目标 revision（重复调用）或还没有任何里程碑（没有身份要迁移）时返回
+ * null：这两种情况下重放本来就得到正确的身份，多写一条只会造出假历史。
+ */
+export function stagePiAssemblyRepin(
+  state: PiToolRecoveryState,
+  nextAssemblyRevision: string,
+  timestamp: number,
+): PiToolRecoveryMilestone | null {
+  if (
+    !state.turnId ||
+    !state.assemblyRevision ||
+    state.assemblyRevision === nextAssemblyRevision
+  ) {
+    return null;
+  }
+  return {
+    version: 1,
+    turnId: state.turnId,
+    assemblyRevision: state.assemblyRevision,
+    type: "assembly-repin",
+    nextAssemblyRevision,
+    timestamp,
+  };
+}
+
+// #endregion
+
 // #region 恢复审批决定
 
 /**
@@ -790,3 +937,99 @@ export function applyRecoveredPiApprovalDecision(
 }
 
 // #endregion
+
+// #region 恢复 interaction 结算
+
+/**
+ * 在恢复状态上记录一条新 park 的 interaction。
+ *
+ * 执行链进入 park 前调用，返回的里程碑让重启后的重放知道这次 Tool 调用在等客户端，
+ * 从而规划成 `parked-interaction` 而不是去重试 Tool。
+ */
+export function recordRecoveredPiToolInteraction(
+  state: PiToolRecoveryState,
+  interaction: PiToolInteraction,
+): PiToolRecoveryMilestone[] {
+  if (!state.turnId || !state.assemblyRevision) {
+    throw new Error("Pi Tool interaction is missing its Turn revision");
+  }
+  return [{
+    version: 1,
+    turnId: state.turnId,
+    assemblyRevision: state.assemblyRevision,
+    type: "interaction",
+    interaction,
+  }];
+}
+
+/**
+ * 在恢复状态上应用一次客户端响应或取消，并生成需要持久化的里程碑。
+ *
+ * Runtime 收到 `respondToolInteraction` 或判定取消时调用它，再按返回结果更新表和恢复日志。
+ *
+ * 两种结局形状相同 —— 都写 interaction 记录 + 一条权威 `tool-result`。重复投递返回空里程碑。
+ */
+export function applyRecoveredPiToolInteractionSettlement(
+  state: PiToolRecoveryState,
+  input:
+    | {
+        interactionId: string;
+        kind: "respond";
+        response: unknown;
+        toolResult: ToolResultMessage;
+        settledAt: number;
+      }
+    | {
+        interactionId: string;
+        kind: "cancel";
+        reason: PiToolInteractionCancelReason;
+        settledAt: number;
+        toolResult?: ToolResultMessage;
+      },
+): RecoveredPiToolInteractionSettlement {
+  const interaction = state.interactions[input.interactionId];
+  if (!interaction) {
+    throw new Error(`Unknown Pi Tool interaction ${input.interactionId}`);
+  }
+  const transition = input.kind === "respond"
+    ? respondPiToolInteraction(interaction, {
+        response: input.response,
+        toolResult: input.toolResult,
+        respondedAt: input.settledAt,
+      })
+    : cancelPiToolInteraction(interaction, {
+        reason: input.reason,
+        cancelledAt: input.settledAt,
+        ...(input.toolResult ? { toolResult: input.toolResult } : {}),
+      });
+  const outcome = transition.outcome;
+  // 已结束的 interaction 只返回 noop；这里不应再追加任何持久记录。
+  if (outcome.kind !== "settle") {
+    return { milestones: [], outcome };
+  }
+  if (!state.turnId || !state.assemblyRevision) {
+    throw new Error("Pi Tool interaction is missing its Turn revision");
+  }
+
+  const identity: RecoveryIdentity = {
+    version: 1,
+    turnId: state.turnId,
+    assemblyRevision: state.assemblyRevision,
+  };
+  return {
+    milestones: [
+      { ...identity, type: "interaction", interaction: transition.interaction },
+      // needsContinuation 必须为 true：interaction 没有自己的续跑键，
+      // 唤醒原 Turn 全靠 planPiToolRecovery 里 `tool:<id>:settled` 那条既有分支。
+      {
+        ...identity,
+        type: "tool-result",
+        toolResult: outcome.toolResult,
+        needsContinuation: true,
+      },
+    ],
+    outcome,
+  };
+}
+
+// #endregion

package/src/runtime-agent-context.ts

@@ -0,0 +1,112 @@
+import type {
+  AgentToolRunStatus,
+  ChatCapableAgentClass,
+  RunAgentToolOptions,
+} from "agents";
+import type { ExecutionLevel } from "./lib/execution-level";
+import type { RuntimeConfigUpdateResult } from "./kernel/runtime-config";
+import type {
+  TemporaryAgentRequest,
+  TemporaryAgentRunContext,
+} from "./layers/orchestration/temporary-agent/core";
+
+/**
+ * 描述 Agent 寻址路径中的一级父子节点。
+ *
+ * @remarks
+ * Cloudflare Agents SDK 用 `parentPath` 暴露根节点到直接父节点的路径。
+ *
+ * 调用方通常只读取，不应自行构造后写回 SDK。
+ */
+export interface RuntimeAgentPathStep {
+  className: string;
+  name: string;
+}
+
+/**
+ * 表示一次 Agent Tool 执行返回给 Runtime 的稳定字段。
+ *
+ * @remarks
+ * Subagent 端口在调用 `RuntimeAgentConfigContext.runAgentTool` 后读取它。
+ *
+ * 这里只保留 Runtime 需要的结果，避免把 SDK 内部运行对象暴露给应用。
+ */
+export interface RuntimeAgentToolResult {
+  status: string;
+  runId: string;
+  output?: unknown;
+  summary?: string;
+  error?: string;
+}
+
+export type RuntimeAgentRole = "primary" | "temporary";
+
+/**
+ * 这是应用创建 Config 时唯一可以接触的 Agent 实例能力。
+ *
+ * 身份通过实时 getter 暴露。
+ */
+export interface RuntimeAgentConfigContext<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+> {
+  /** 读取当前 Durable Object 的状态句柄。 */
+  readonly ctx: DurableObjectState;
+  /** 读取当前 Worker 的环境绑定。 */
+  readonly env: Env;
+  /** 读取当前 Agent 实例名称。 */
+  readonly name: string;
+  /** 读取从根节点到直接父节点的 Agent 路径。 */
+  readonly parentPath: readonly RuntimeAgentPathStep[];
+  /** Runtime 根据 Agent facet 父子关系自动判定，不是外部配置项。 */
+  readonly role: RuntimeAgentRole;
+  /**
+   * 通过当前 Agent 调用一个受 SDK 管理的子 Agent Tool。
+   *
+   * @remarks
+   * subagent 端口在父 Agent 需要保留子运行状态、事件和取消边界时调用。
+   */
+  runAgentTool(
+    agentClass: ChatCapableAgentClass,
+    options: RunAgentToolOptions<unknown>,
+  ): Promise<RuntimeAgentToolResult>;
+  /**
+   * 清理符合年龄和状态条件的 SDK 子运行记录。
+   */
+  clearAgentToolRuns(options: {
+    olderThan: number;
+    status: AgentToolRunStatus[];
+  }): Promise<void>;
+  /** 读取当前已装配 User Agent 的执行档位。 */
+  executionLevel(): ExecutionLevel;
+  /**
+   * 在当前 Session Runtime 中执行一个仅对本次调用存活的临时 Agent。
+   */
+  runTemporaryAgent(
+    request: TemporaryAgentRequest,
+    context: TemporaryAgentRunContext,
+  ): Promise<string>;
+}
+
+export interface RuntimeAgentPlanningContext<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Command = never,
+  Change = never,
+> extends RuntimeAgentConfigContext<Env> {
+  /** 仅可变 Definition 提供；Host Tool 用它复用生成类的更新与重载编排。 */
+  readonly updateConfig?: (
+    command: Command,
+  ) => Promise<RuntimeConfigUpdateResult<Change>>;
+}
+
+/** 装配、Hook 与 Port 准备共用的 Agent 上下文。 */
+export type RuntimeAssemblyContext<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Command = never,
+  Change = never,
+> = RuntimeAgentPlanningContext<Env, Command, Change>;
+
+export type RuntimeAgentContext<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Command = never,
+  Change = never,
+> = RuntimeAgentPlanningContext<Env, Command, Change>;