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

package/src/kernel/bindings.ts

@@ -294,9 +294,7 @@ export interface RuntimeMemoryPort {
    * 按标签覆盖一块热记忆。
    *
    * @remarks
-   * Host 实现提供该能力，但当前 `packages/agent-runtime/src` 没有调用点。
-   *
-   * TODO(待确认): 确认后续写入方是否仍需通过这个公开 Port 提交热记忆。
+   * `set_context` 在校验标签和 token 预算后调用，Host 负责按当前 Agent 与会话持久化。
    */
   set(label: string, content: string): Promise<void>;
 }
@@ -524,6 +522,41 @@ export interface RuntimeSandboxPort {
 
 // #region Runtime 服务端口
 
+/** Gateway MCP 发现后可供 Pi 装配的安全 Tool 描述。 */
+export interface RuntimeGatewayMcpTool {
+  readonly name: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly inputSchema?: Record<string, unknown>;
+}
+
+/** Gateway safe Catalog 中经过认证的 Action Risk。 */
+export type RuntimeGatewayActionRisk = "none" | "high";
+
+/**
+ * 一次 Agent Runtime 独占的 Gateway MCP 逻辑 Session。
+ *
+ * Runtime Grant 由实现闭包持有；本接口只暴露发现、调用和可信风险解析，
+ * 因此 Grant 不会进入 Profile、Snapshot 描述或 transcript。
+ */
+export interface RuntimeGatewaySession {
+  readonly tools: readonly RuntimeGatewayMcpTool[];
+  callTool(
+    name: string,
+    input: Readonly<Record<string, unknown>>,
+    signal?: AbortSignal,
+  ): Promise<unknown>;
+  resolveCapabilityRisk(
+    reference: string,
+  ): Promise<RuntimeGatewayActionRisk>;
+  close(): Promise<void>;
+}
+
+/** Host 在 Runtime 启动时用它 mint Grant 并打开唯一 Gateway MCP Session。 */
+export interface RuntimeGatewayPort {
+  open(runtimeId: string): Promise<RuntimeGatewaySession>;
+}
+
 /**
  * 描述一条模型可见的定时任务。
  *
@@ -697,6 +730,22 @@ export interface RuntimeModelUsageEvent {
   };
 }
 
+/**
+ * 一次 Tool 调用刚开始，还不知道它会怎么结束。
+ *
+ * @remarks
+ * 结算事件刻意不带参数，因为它只用来记账；开始事件必须带，因为它唯一的用处
+ * 就是让 Host 立刻知道「正在写的是什么」——只有工具名的话，「write 开始了」
+ * 和「一个网页正在生成」之间的差别就丢了，而后者才是盯着屏幕的人要看的。
+ * 参数本来就随 Tool 输入里程碑落库，这里没有多暴露任何东西。
+ */
+export interface RuntimeToolStartEvent {
+  readonly submissionId: string;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+}
+
 export interface RuntimeToolSettlementEvent {
   readonly eventId: string;
   readonly submissionId: string;
@@ -728,6 +777,17 @@ export interface RuntimeTurnEventsPort {
   ): Promise<void>;
   /** 投递 Assistant 或 Compaction 的原始 provider usage。 */
   onModelUsage?(event: RuntimeModelUsageEvent): Promise<void>;
+  /**
+   * 投递一次 Tool 开始执行的事件，带上它的参数。
+   *
+   * @remarks
+   * 只在这次调用第一次落下 durable intent 时投递：恢复重放不会再报一次开始，
+   * 否则一个早就结束的 Tool 会在几分钟后再宣布自己「正在跑」。
+   *
+   * 这条是活性信号而不是账，所以不进 durable outbox：迟到的开始事件本身就是
+   * 错的，投递失败就让它丢掉，最终状态由 `onToolSettled` 兜底。
+   */
+  onToolStart?(event: RuntimeToolStartEvent): Promise<void>;
   /** 投递不含参数与结果的 Tool 最终结算事件。 */
   onToolSettled?(event: RuntimeToolSettlementEvent): Promise<void>;
   onApproval?(input: {
@@ -803,6 +863,8 @@ export interface RuntimeModelEndpoint {
   headers?: Readonly<Record<string, string>>;
   baseURL: string;
   models: readonly string[];
+  /** OpenRouter upstream provider pins keyed by model ID; pinned requests never fall back. */
+  openRouterProviderPins?: Readonly<Record<string, string>>;
 }
 
 /**
@@ -860,15 +922,15 @@ export interface RuntimePlatformPort {
 }
 
 /**
- * 汇总本次装配已授权的 Skill 来源。
+ * 汇总本次装配已配置的 Skill 来源。
  *
  * @remarks
  * Builder 在生成候选 Snapshot 时创建，Pi 组装在生成 Skill 工具时读取。
  *
- * catalog、来源与脚本策略一起保留，避免装配期访问来源或让授权在 Skill 之间漂移。
+ * catalog、来源与脚本策略一起保留，避免装配期重新访问来源。
  */
 export interface RuntimeSkillBindings {
-  /** Already-authorized external sources and their isolated script policy. */
+  /** Configured external sources and their isolated script policy. */
   sources: readonly RuntimeSkillSourceBinding[];
 }
 
@@ -878,7 +940,7 @@ export interface RuntimeSkillBindings {
  * @remarks
  * Skill Plugin 在准备来源时设置，Pi Skill 工具在决定是否注入脚本执行能力时读取。
  *
- * 这是已授权结果，执行期不应为某个 Skill 自动放宽。
+ * 这是 Config 已解析的执行策略，执行期不应自动放宽。
  */
 export interface RuntimeSkillScriptPolicy {
   network: "none" | "full";
@@ -887,12 +949,12 @@ export interface RuntimeSkillScriptPolicy {
 }
 
 /**
- * 把一个已授权 Skill 来源与其脚本策略绑定。
+ * 把一个已配置 Skill 来源与其脚本策略放在同一快照中。
  *
  * @remarks
  * Builder 为每个 Skill 贡献创建，Pi 组装和 Skill 工具按名称查找并读取。
  *
- * 名称、内容来源与权限不分开存放，防止脚本改用其他 Skill 的授权。
+ * 名称、内容来源与脚本策略不分开存放，脚本 runner 才能按 Skill 名找到对应策略。
  */
 export interface RuntimeSkillSourceBinding {
   name: string;
@@ -913,6 +975,8 @@ export interface RuntimeSkillSourceBinding {
 export interface RuntimeBindings {
   provider: RuntimeProviderPort;
   platform: RuntimePlatformPort;
+  /** Secret-capability binding; implementations must keep Runtime Grant in closure state. */
+  gateway?: RuntimeGatewayPort;
   workspace?: WorkspacePort;
   memory?: RuntimeMemoryPort;
   skills: RuntimeSkillBindings;

package/src/kernel/interaction-lifecycle.ts

@@ -0,0 +1,395 @@
+import {
+  isTerminalSubmissionStatus,
+  type RuntimeDatabase,
+  type StoredToolInteraction,
+  type SubmissionStatus,
+} from "../db";
+import type {
+  PiDurableMutation,
+  PiRecoveryCommand,
+  PiRecoveryDecision,
+  PiRuntimeAdapter,
+  PiToolInteraction,
+  PiToolInteractionCancelReason,
+} from "../pi/runtime-adapter";
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+
+// #region 类型约定
+
+/**
+ * 提供 interaction 流程定位一次持久化提交所需的最小信息。
+ *
+ * @remarks
+ * 与 `ApprovalSubmission` 同形。这里只要求 park/续跑真正需要的字段，
+ * 避免 interaction 流程依赖完整提交模型。
+ */
+export interface InteractionSubmission {
+  readonly submissionId: string;
+  readonly requestId: string;
+  readonly assemblyRevision: string;
+  readonly status: SubmissionStatus;
+}
+
+/**
+ * 表示已经绑定到持久化提交的完整 interaction 记录。
+ */
+export interface InteractionRecord extends PiToolInteraction {
+  readonly submissionId: string;
+}
+
+/**
+ * 描述一次响应或取消要写入的 ToolResult 载荷。
+ *
+ * `content` / `details` 由 Tool 自己的 `settle` 映射产出 —— 本流程不解释响应体语义。
+ * 取消不带载荷，由纯函数层用固定文案兜底。
+ */
+export interface InteractionSettlementPayload {
+  readonly content: ToolResultMessage["content"];
+  readonly details: unknown;
+}
+
+// 宿主用这些依赖把 interaction 状态机接入数据库、Pi 恢复计算和 Turn 续跑。
+interface InteractionLifecycleOptions<
+  TSubmission extends InteractionSubmission,
+> {
+  readonly db: RuntimeDatabase;
+  readonly pi: PiRuntimeAdapter;
+  readonly findSubmission: (submissionId: string) => TSubmission | null;
+  readonly applyRecoveryMutations: (
+    submission: TSubmission,
+    mutations: readonly PiDurableMutation[],
+  ) => boolean;
+  readonly materializeRecoveredToolResults: (
+    submission: TSubmission,
+  ) => Promise<PiRecoveryDecision>;
+  /** 没有内存等待器时（DO 睡过一觉）把原 Turn 重新拉起来。 */
+  readonly resumeSubmission: (submissionId: string) => Promise<void>;
+  /**
+   * pending 集合发生变化后通知宿主重算活动状态投影。
+   *
+   * park 和结算都会触发。宿主的 needs-input 是 pending 行的纯函数，
+   * 没有这个回调，park 的那一刻不会有人去重算 —— 侧栏要等下一次广播才翻牌。
+   */
+  readonly onInteractionsChanged?: () => Promise<void>;
+}
+
+// #endregion
+
+// #region interaction 流程 API
+
+/**
+ * 管理「结果由客户端提供」的 Tool 从 park、等待、响应到续跑的完整过程。
+ *
+ * @remarks
+ * 与 `ApprovalLifecycle` 结构同源但显著更小 —— 不需要 `allow_level` 的 Host 协调、
+ * 不需要批准后 `retryTool`、不需要执行档位矩阵。两者的重复是**当前有意接受的**：
+ * 审批那条路已经跑在线上，等 interaction 跑稳后再考虑抽公共核，届时改的是这两个类，
+ * 不是恢复状态机。
+ *
+ * 续跑不走 interaction 专属的调度键：响应会同时写下一条权威 `tool-result` 里程碑，
+ * 因此复用 `planPiToolRecovery` 中既有的 `tool:<id>:settled` 分支。
+ */
+export class InteractionLifecycle<
+  TSubmission extends InteractionSubmission,
+> {
+  private readonly waiters = new Map<string, () => void>();
+
+  constructor(
+    private readonly options: InteractionLifecycleOptions<TSubmission>,
+  ) {}
+
+  /**
+   * 用工具调用标识查找唯一一条仍待响应的 interaction。
+   *
+   * @remarks
+   * `Runtime.respondToolInteraction` 调用它 —— 前端只有 `toolCallId`。
+   * 调用方必须把 `null` 当作没有安全匹配，不应猜测要处理哪条记录。
+   */
+  findPending(toolCallId: string): InteractionRecord | null {
+    const stored = this.options.db.interactions
+      .findPendingByToolCallId(toolCallId);
+    return stored ? toRecord(stored) : null;
+  }
+
+  /**
+   * 按 interactionId 读取一条完整记录，不存在时返回 null。
+   */
+  read(interactionId: string): InteractionRecord | null {
+    const stored = this.options.db.interactions.find(interactionId);
+    return stored ? toRecord(stored) : null;
+  }
+
+  /**
+   * 持久化一条 interaction，并暂停当前工具执行直到客户端投递响应。
+   *
+   * @remarks
+   * 执行适配器在 Tool 声明了 `interaction` 时调用它。
+   * 记录与恢复里程碑先在事务中落盘，再建立内存等待，保证重启仍能恢复 park 状态。
+   */
+  async request(
+    submission: TSubmission,
+    interaction: PiToolInteraction,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    const pending = this.options.db.transaction(() =>
+      this.ensurePending(submission, interaction)
+    );
+    // 必须在 wait 之前通知：wait 会一直挂到客户端投递，之后再通知就晚了一个回合。
+    await this.options.onInteractionsChanged?.();
+    return this.wait(pending, signal);
+  }
+
+  /**
+   * 应用客户端的首次响应，结算对应 Tool 并唤醒原 Turn。
+   *
+   * @remarks
+   * `Runtime.respondToolInteraction` 在校验并映射出 ToolResult 后调用它。
+   * 不存在、已结束或提交已终态都返回 `{ ok: false }`，不抛 —— 口径对齐 `ApprovalLifecycle.decide`。
+   */
+  async respond(
+    interactionId: string,
+    response: unknown,
+    payload: InteractionSettlementPayload,
+  ): Promise<{ ok: boolean }> {
+    return this.settle(interactionId, {
+      kind: "respond",
+      response,
+      result: payload,
+    });
+  }
+
+  /**
+   * 在用户没有作答的情况下结束一条 interaction 并让 Turn 继续。
+   *
+   * @remarks
+   * park 期间收到用户消息时调用（`user_replied_freeform`），提交进终态时也调用。
+   * 取消同样产出稳定 ToolResult，不是 Tool 失败 —— 否则模型会收到 tool_error 并倾向重试。
+   */
+  async cancel(
+    interactionId: string,
+    reason: PiToolInteractionCancelReason,
+  ): Promise<{ ok: boolean }> {
+    return this.settle(interactionId, { kind: "cancel", reason });
+  }
+
+  /**
+   * 把某次提交下仍待响应的全部 interaction 一次性取消。
+   *
+   * @remarks
+   * `dispatchMessage` 发现 park 期间来了用户消息时、以及提交进终态时调用。
+   * 返回是否真的取消过记录，调用方据此决定要不要广播。
+   */
+  async cancelPendingForSubmission(
+    submissionId: string,
+    reason: PiToolInteractionCancelReason,
+  ): Promise<boolean> {
+    const pending = this.options.db.interactions
+      .listPendingForSubmission(submissionId);
+    if (pending.length === 0) return false;
+    let cancelled = false;
+    for (const interactionId of pending) {
+      const result = await this.cancel(interactionId, reason);
+      cancelled ||= result.ok;
+    }
+    return cancelled;
+  }
+
+  /**
+   * 在同步终态事务里把某次提交下仍待响应的 interaction 全部取消。
+   *
+   * @remarks
+   * `Runtime.commitTerminalOutcome` 在提交终态的 `transaction` 内调用，因此必须是同步的。
+   * 这里只推进状态和里程碑，**不** materialize、**不** 续跑 —— Turn 正在结束，
+   * 调用方负责在同一事务内调用 `materializeRecoveredToolResultsSync`，口径对齐审批的 `rejectPending`。
+   *
+   * 返回是否真的取消过记录；没有 pending 时返回 false，调用方可据此跳过 materialize。
+   */
+  cancelPendingForSubmissionSync(
+    submission: TSubmission,
+    reason: PiToolInteractionCancelReason = "submission_terminal",
+  ): boolean {
+    const pending = this.options.db.interactions
+      .listPendingForSubmission(submission.submissionId);
+    if (pending.length === 0) return false;
+    for (const interactionId of pending) {
+      const decision = this.decideRecovery(submission, {
+        kind: "interaction-settlement",
+        interactionId,
+        settlement: { kind: "cancel", reason },
+      });
+      this.options.applyRecoveryMutations(submission, decision.mutations);
+    }
+    return true;
+  }
+
+  /**
+   * 判断某次提交当前是否停在等待客户端响应上。
+   *
+   * @remarks
+   * `dispatchMessage` 用它决定要不要把 delivery 提升成 steer —— 否则 enqueue 的消息
+   * 要等这个 Turn 结束，而这个 Turn 正在等一个不会来的答案，死锁。
+   */
+  hasPendingForSubmission(submissionId: string): boolean {
+    return this.options.db.interactions
+      .listPendingForSubmission(submissionId).length > 0;
+  }
+
+  // #endregion
+
+  // #region 内部
+
+  // 作用：把响应或取消统一走同一条持久化 + 唤醒路径。
+  // 调用：`respond` 和 `cancel`。
+  // 原因：两种结局的差别只在 ToolResult 从哪来，状态推进和续跑必须完全一致。
+  private async settle(
+    interactionId: string,
+    settlement:
+      | {
+          kind: "respond";
+          response: unknown;
+          result: InteractionSettlementPayload;
+        }
+      | { kind: "cancel"; reason: PiToolInteractionCancelReason },
+  ): Promise<{ ok: boolean }> {
+    const stored = this.read(interactionId);
+    if (!stored) return { ok: false };
+    const submission = this.options.findSubmission(stored.submissionId);
+    if (!submission || isTerminalSubmissionStatus(submission.status)) {
+      return { ok: false };
+    }
+    if (stored.status !== "pending") return { ok: false };
+
+    const decision = this.decideRecovery(submission, {
+      kind: "interaction-settlement",
+      interactionId,
+      settlement,
+    });
+    if (!decision.applied) return { ok: false };
+    this.options.db.transaction(() => {
+      this.options.applyRecoveryMutations(submission, decision.mutations);
+    });
+    const persisted = this.read(interactionId);
+    if (!persisted || persisted.status === "pending") {
+      return { ok: false };
+    }
+
+    // 把刚写下的权威 tool-result 落成 settlement 行 —— park 住的执行链醒来后
+    // 只认 findToolSettlement，不读里程碑。这一步必须早于唤醒。
+    await this.options.materializeRecoveredToolResults(submission);
+    // 先重算活动状态再唤醒：唤醒会把 Turn 一路跑下去，晚通知就会让「等待回复」
+    // 在续跑期间多挂一段时间。
+    await this.options.onInteractionsChanged?.();
+
+    const waiter = this.waiters.get(interactionId);
+    if (waiter) {
+      waiter();
+      return { ok: true };
+    }
+    // 没有内存等待器 = DO 在 park 期间睡过一觉，原 Turn 的执行栈已经没了。
+    // 走持久恢复把它重新拉起来，里程碑里的 tool-result 会被当成已结算结果复用。
+    await this.options.resumeSubmission(submission.submissionId);
+    return { ok: true };
+  }
+
+  // 作用：读取一个 Submission 的全部恢复里程碑正文。
+  // 原因：持久化历史必须作为恢复决策的唯一输入。
+  private milestoneBodies(submissionId: string): string[] {
+    return this.options.db.milestones.listBodies(submissionId);
+  }
+
+  // 作用：请求 Pi 根据当前里程碑给出下一步。
+  // 原因：所有路径共用同一决策入口，避免各自改写恢复状态。
+  private decideRecovery(
+    submission: TSubmission,
+    command: PiRecoveryCommand = { kind: "inspect" },
+  ): PiRecoveryDecision {
+    return this.options.pi.decideRecovery({
+      milestoneBodies: this.milestoneBodies(submission.submissionId),
+      identity: {
+        turnId: submission.submissionId,
+        assemblyRevision: submission.assemblyRevision,
+      },
+      command,
+      now: Date.now(),
+    });
+  }
+
+  // 作用：复用或创建一条 pending interaction。
+  // 调用：`request` 在准入事务内调用。
+  // 原因：已存在记录的字段冲突必须报错，不能把响应投给另一次调用。
+  private ensurePending(
+    submission: TSubmission,
+    interaction: PiToolInteraction,
+  ): InteractionRecord {
+    const existing = this.read(interaction.interactionId);
+    if (existing) {
+      if (
+        existing.requestId !== submission.requestId ||
+        existing.toolCallId !== interaction.toolCallId ||
+        existing.toolName !== interaction.toolName ||
+        existing.inputJson !== interaction.inputJson
+      ) {
+        throw new Error(
+          `Conflicting durable Tool interaction: ${interaction.toolCallId}`,
+        );
+      }
+      return existing;
+    }
+    // 表行和恢复里程碑都由 record-interaction 这一条命令产出，
+    // 不在这里直接 insert —— 两份状态分叉正是恢复最难查的一类 bug。
+    const decision = this.decideRecovery(submission, {
+      kind: "record-interaction",
+      interaction,
+    });
+    this.options.applyRecoveryMutations(submission, decision.mutations);
+    return { ...interaction, submissionId: submission.submissionId };
+  }
+
+  // 作用：等待当前进程里的客户端响应。
+  // 原因：内存 Promise 只负责唤醒当前请求，数据库仍负责持久状态以支持重启。
+  private wait(
+    interaction: InteractionRecord,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    if (interaction.status !== "pending") return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const abort = () => {
+        this.waiters.delete(interaction.interactionId);
+        reject(signal?.reason ?? new Error("Tool interaction aborted"));
+      };
+      if (signal?.aborted) {
+        abort();
+        return;
+      }
+      signal?.addEventListener("abort", abort, { once: true });
+      this.waiters.set(interaction.interactionId, () => {
+        signal?.removeEventListener("abort", abort);
+        this.waiters.delete(interaction.interactionId);
+        resolve();
+      });
+    });
+  }
+
+  // #endregion
+}
+
+// 把持久行转成流程内部使用的记录。
+// find / findPending 查到记录后调用，上层因而只看 Pi 的 interaction 形状。
+function toRecord(stored: StoredToolInteraction): InteractionRecord {
+  return {
+    interactionId: stored.interactionId,
+    submissionId: stored.submissionId,
+    requestId: stored.requestId,
+    toolCallId: stored.toolCallId,
+    toolName: stored.toolName,
+    inputJson: stored.inputJson,
+    status: stored.status,
+    createdAt: stored.createdAt,
+    ...(stored.respondedAt === null
+      ? {}
+      : { respondedAt: stored.respondedAt }),
+    ...(stored.responseJson === null
+      ? {}
+      : { responseJson: stored.responseJson }),
+  };
+}

package/src/kernel/public-contracts.ts

@@ -11,6 +11,8 @@
  * @packageDocumentation
  */
 export * from "./profile";
+export * from "./runtime-assembly-view";
+export * from "./runtime-config";
 export * from "../pi/message";
 export * from "./receipts";
 export * from "./state";