@springbrand/agent-runtime 0.1.3-alpha.3 → 0.1.3-alpha.5

package/src/db/interaction.repo.ts

@@ -0,0 +1,185 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+// Tool Interaction 的统一定义见 ./index.ts。
+// #region 状态与行类型
+export type ToolInteractionStatus = "pending" | "responded" | "cancelled";
+
+export interface StoredToolInteraction {
+  interactionId: string;
+  submissionId: string;
+  requestId: string;
+  toolCallId: string;
+  toolName: string;
+  inputJson: string;
+  status: ToolInteractionStatus;
+  responseJson: string | null;
+  createdAt: number;
+  respondedAt: number | null;
+}
+
+export interface NewToolInteraction {
+  interactionId: string;
+  submissionId: string;
+  requestId: string;
+  toolCallId: string;
+  toolName: string;
+  inputJson: string;
+  status: ToolInteractionStatus;
+  createdAt: number;
+}
+
+type ToolInteractionRow = {
+  interaction_id: string;
+  submission_id: string;
+  request_id: string;
+  tool_call_id: string;
+  tool_name: string;
+  input_json: string;
+  status: string;
+  response_json: string | null;
+  created_at: number;
+  responded_at: number | null;
+};
+
+// #endregion
+// #region 行映射
+// 把 SQLite 的 Interaction 行转成 Runtime 对象。
+// find 与 findPending* 查到记录后调用，上层因而不需要理解 snake_case 列名。
+// 状态由表内字符串转成联合类型；新增列或状态时必须同步核对类型、SELECT 和映射。
+function mapRow(row: ToolInteractionRow): StoredToolInteraction {
+  return {
+    interactionId: row.interaction_id,
+    submissionId: row.submission_id,
+    requestId: row.request_id,
+    toolCallId: row.tool_call_id,
+    toolName: row.tool_name,
+    inputJson: row.input_json,
+    status: row.status as ToolInteractionStatus,
+    responseJson: row.response_json,
+    createdAt: row.created_at,
+    respondedAt: row.responded_at,
+  };
+}
+
+// #endregion
+// #region Repository
+export class ToolInteractionRepository {
+  // 保存当前 Agent SQLite 的查询入口。
+  // RuntimeDatabase 构造时调用，InteractionLifecycle 随后共享这个 Repository。
+  // Interaction 必须与所属 Submission 在同一 Agent 存储中查询，不能跨 Durable Object 拼接状态。
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  // 按 interactionId 读取一条完整 Interaction，不存在时返回 null。
+  // InteractionLifecycle 在请求去重、响应、取消和收尾时调用，调用方必须处理 null。
+  // interaction_id 是主键，LIMIT 1 明确只消费一行。
+  find(interactionId: string): StoredToolInteraction | null {
+    const row = this.sql<ToolInteractionRow>`
+      SELECT interaction_id, submission_id, request_id,
+             tool_call_id, tool_name, input_json,
+             status, response_json, created_at, responded_at
+      FROM pi_tool_interactions
+      WHERE interaction_id = ${interactionId}
+      LIMIT 1
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+
+  // 持久化一条新的 pending Interaction。
+  // InteractionLifecycle.ensurePending 在准入事务内确认没有同一记录后调用。
+  // 主键和 (submission_id, tool_call_id) 唯一约束是持久化去重防线，不能用覆盖式 INSERT 掩盖冲突。
+  insert(interaction: NewToolInteraction): void {
+    this.sql`
+      INSERT INTO pi_tool_interactions (
+        interaction_id, submission_id, request_id,
+        tool_call_id, tool_name, input_json,
+        status, created_at
+      ) VALUES (
+        ${interaction.interactionId},
+        ${interaction.submissionId},
+        ${interaction.requestId},
+        ${interaction.toolCallId},
+        ${interaction.toolName},
+        ${interaction.inputJson},
+        ${interaction.status},
+        ${interaction.createdAt}
+      )
+    `;
+  }
+
+  // 只把 pending Interaction 落成 responded 或 cancelled，并记录响应体与时间。
+  // InteractionLifecycle 在收到客户端响应或判定取消时调用，迟到的重复投递不应覆盖首次结果。
+  // WHERE status='pending' 实现首次响应胜出，不能去掉这个条件；调用方在事务后重读来确认是否真的生效。
+  settle(
+    interactionId: string,
+    status: Exclude<ToolInteractionStatus, "pending">,
+    respondedAt: number,
+    responseJson?: string,
+  ): void {
+    this.sql`
+      UPDATE pi_tool_interactions
+      SET status = ${status},
+          response_json = ${responseJson ?? null},
+          responded_at = ${respondedAt}
+      WHERE interaction_id = ${interactionId}
+        AND status = 'pending'
+    `;
+  }
+
+  // 按创建顺序列出某次 Submission 仍等待客户端响应的 interactionId。
+  // InteractionLifecycle.cancelPending 在取消或终止 Turn 时调用，随后逐条追加取消恢复事实。
+  // ORDER BY created_at 保留原始顺序，不能依赖 SQLite 未声明的默认行顺序。
+  listPendingForSubmission(submissionId: string): string[] {
+    return this.sql<{ interaction_id: string }>`
+      SELECT interaction_id
+      FROM pi_tool_interactions
+      WHERE submission_id = ${submissionId}
+        AND status = 'pending'
+      ORDER BY created_at ASC
+    `.map((row) => row.interaction_id);
+  }
+
+  // 只在某个 toolCallId 唯一匹配一条活跃 pending Interaction 时返回该记录。
+  // Runtime.respondToolInteraction 的入口调用它 —— 前端只有 toolCallId，不知道 submissionId。
+  // toolCallId 只在单个 Submission 内唯一，LIMIT 2 用最小查询识别跨 Submission 重名；
+  // 不能用 LIMIT 1 静默选中任意一条，那会把答案投给错的那次调用。口径与 ApprovalRepository 同名方法一致。
+  findPendingByToolCallId(toolCallId: string): StoredToolInteraction | null {
+    const matches = this.sql<ToolInteractionRow>`
+      SELECT interaction.interaction_id, interaction.submission_id,
+             interaction.request_id, interaction.tool_call_id,
+             interaction.tool_name, interaction.input_json,
+             interaction.status, interaction.response_json,
+             interaction.created_at, interaction.responded_at
+      FROM pi_tool_interactions interaction
+      JOIN pi_submissions submission
+        ON submission.submission_id = interaction.submission_id
+      WHERE interaction.tool_call_id = ${toolCallId}
+        AND interaction.status = 'pending'
+        AND submission.status NOT IN (
+          'completed', 'aborted', 'skipped', 'error'
+        )
+      LIMIT 2
+    `;
+    const only = matches.length === 1 ? matches[0] : undefined;
+    return only ? mapRow(only) : null;
+  }
+
+  // 列出所属 Submission 仍活跃的全部 pending Interaction。
+  // Runtime 启动扫描调用它，用来判断哪些 park 还需要续跑依据。
+  // 与 findPendingByToolCallId 使用同样的 JOIN 和状态条件，修改其一时必须核对另一个。
+  listPendingActive(): StoredToolInteraction[] {
+    return this.sql<ToolInteractionRow>`
+      SELECT interaction.interaction_id, interaction.submission_id,
+             interaction.request_id, interaction.tool_call_id,
+             interaction.tool_name, interaction.input_json,
+             interaction.status, interaction.response_json,
+             interaction.created_at, interaction.responded_at
+      FROM pi_tool_interactions interaction
+      JOIN pi_submissions submission
+        ON submission.submission_id = interaction.submission_id
+      WHERE interaction.status = 'pending'
+        AND submission.status IN ('pending', 'running')
+      ORDER BY interaction.created_at ASC
+    `.map(mapRow);
+  }
+}
+// #endregion

package/src/db/schema.ts

@@ -4,6 +4,8 @@ import type { SqlTaggedTemplate } from "agents/chat";
 // 创建当前 Runtime 需要但尚不存在的 SQLite 表。
 // AgentRuntimeKernel 构造时通过 RuntimeDatabase.initializeSchema 调用，重复启动依赖 IF NOT EXISTS 保留现有表。
 // pi_approvals 有一次显式的 risk → 四档升级；步骤均可重入，中断后下次初始化会继续。
+// pi_tool_interactions 是 client-settled tool 的 pending 索引：结果的权威副本仍在 pi_tool_settlements，
+// 这张表只回答「这次工具调用还等不等得到客户端响应」。
 export function initializeSchema(sql: SqlTaggedTemplate): void {
   sql`CREATE TABLE IF NOT EXISTS pi_message_ui (
     message_id TEXT PRIMARY KEY,
@@ -119,6 +121,19 @@ export function initializeSchema(sql: SqlTaggedTemplate): void {
         END`;
     sql`ALTER TABLE pi_approvals DROP COLUMN risk`;
   }
+  sql`CREATE TABLE IF NOT EXISTS pi_tool_interactions (
+    interaction_id TEXT PRIMARY KEY,
+    submission_id TEXT NOT NULL,
+    request_id TEXT NOT NULL,
+    tool_call_id TEXT NOT NULL,
+    tool_name TEXT NOT NULL,
+    input_json TEXT NOT NULL,
+    status TEXT NOT NULL,
+    response_json TEXT,
+    created_at INTEGER NOT NULL,
+    responded_at INTEGER,
+    UNIQUE (submission_id, tool_call_id)
+  )`;
   sql`CREATE TABLE IF NOT EXISTS pi_recovery_milestones (
     submission_id TEXT NOT NULL,
     seq INTEGER NOT NULL,

package/src/db/submission.repo.ts

@@ -180,6 +180,17 @@ export class SubmissionRepository {
     );
   }
 
+  // 按创建顺序列出还在排队或运行的 Submission id。
+  // 换装配前的「是不是全都停在等人」判断调用它，逐条核对每一条的人机等待。
+  // 状态集合与 countUnfinished 必须一致，修改其一时另一个也要跟着改。
+  listUnfinishedIds(): string[] {
+    return this.sql<{ submission_id: string }>`
+      SELECT submission_id FROM pi_submissions
+      WHERE status IN ('pending', 'running')
+      ORDER BY created_at ASC, rowid ASC
+    `.map((row) => row.submission_id);
+  }
+
   findRunning(): StoredSubmission | null {
     const id = this.sql<{ submission_id: string }>`
       SELECT submission_id FROM pi_submissions
@@ -252,6 +263,24 @@ export class SubmissionRepository {
     return updated.length === 1;
   }
 
+  // 把一条已 pin 的 Submission 换到另一对 revision / descriptor 上。
+  // Runtime 在「停在人机等待期间换了装配」之后调用，必须与那次装配迁移里程碑同事务。
+  // 与 pinAssembly 的区别就是它要求已经 pin 过：首次 pin 走 pinAssembly，
+  // 这里不接受空值，避免把一次漏写的准入 pin 伪装成一次迁移。
+  repinAssembly(id: string, revision: string, descriptor: string): boolean {
+    const updated = this.sql<{ submission_id: string }>`
+      UPDATE pi_submissions
+      SET assembly_revision = ${revision},
+          assembly_descriptor = ${descriptor}
+      WHERE submission_id = ${id}
+        AND assembly_revision <> ''
+        AND assembly_descriptor <> ''
+        AND status IN ('pending', 'running')
+      RETURNING submission_id
+    `;
+    return updated.length === 1;
+  }
+
   // 只在当前状态属于 from 时把 Submission 切换到 to，否则返回 false。
   // SubmissionLifecycle 开始 Turn 时调用，调用方用返回值识别过期或重复的状态切换。
   // Cloudflare SQLite 查询是同步的，两条语句之间不会让其他事件交错；UPDATE 再次带旧状态条件，不能去掉这层幂等保护。

package/src/index.ts

@@ -22,11 +22,10 @@
  * - `SubAgent` 是由父 Agent 发起、但拥有独立执行上下文的子任务执行者。
  * - `canonical transcript` 是 Pi 持久化和恢复 Turn 时使用的权威消息历史。
  * - `admission` 是提示进入 Turn 前的接纳、去重和状态登记流程。
- * - `AgentConfig` 是应用交给 Runtime 的一次完整装配说明。
- * - `AgentPlugin` 是一种能力的声明式准备单元。
- * - `PluginKind` 同时收窄 Plugin 可以准备的字段，并作为内部稳定合并顺序。
- * - `prepare` 读取业务数据或外部绑定，但不会改动正在运行的 Runtime。
- * - `Port` 是 Runtime 调用外部能力时依赖的最小接口。
+ * - `defineRuntimeAgent.load` 返回 config 和已加载 Resource。
+ * - `defineRuntimeAgent.tools` 是 Host 第一层 Tool 注册表声明。
+ * - `assembleRuntimeSnapshot` 消费该输入与 hooks，产出候选 Snapshot。
+ * - `Port` 是 Runtime 调用外部能力时依赖的最小接口（Definition 作者不直接装配）。
  * - `RuntimeBindings` 是本次装配选中的 Port 和可执行对象集合。
  * - `RuntimeBuilder` 是包内实现，用来校验贡献并生成候选结果。
  * - `RuntimeCandidate` 是尚未生效的候选结果和提交前检查。
@@ -38,11 +37,8 @@
  *
  * Snapshot 不允许替换已选集合，但不承诺把每个 Port 的内部对象深冻结。
  *
- * 正常调用顺序是 `prepare → merge → validate → freeze → guard → commit`。
- *
- * 应用只创建 `AgentConfig` 和 Plugin。
- *
- * Runtime 独占校验、排序和原子提交。
+ * 正常调用顺序是 `assemble → validate → freeze → guard → commit`。
+ * Runtime 独占跨能力校验和原子提交。
  *
  * @packageDocumentation
  */
@@ -50,23 +46,44 @@ export * from "./kernel/bindings";
 export * from "./kernel/extensions";
 export * from "./kernel/profile";
 export * from "./kernel/receipts";
+export * from "./kernel/runtime-config";
+export type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
 export * from "./runtime-agent";
 export * from "./kernel/state";
 export * from "./lib/execution-level";
-export { definePlugin } from "./plugins";
 export type {
-  AgentConfig,
-  AgentPlugin,
-  AgentPluginSpec,
-  PluginKind,
-  PluginPreparation,
-  PreparedPlugin,
+  RuntimeAssemblyInput,
   RuntimeDegradation,
   RuntimeExtensionContribution,
   RuntimeProfileContribution,
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
-} from "./plugins";
+} from "./runtime-assembler";
+export { assembleRuntimeSnapshot, toolRegistryPiToolCandidates } from "./runtime-assembler";
+export type {
+  PlatformToolContext,
+  PlatformToolRegistry,
+  PlatformToolSpec,
+  ProfileOverrides,
+  ResolvedConnectors,
+  ResolvedResources,
+  RuntimeAgentContext,
+  RuntimeAgentHooks,
+  RuntimeSettings,
+  RuntimeToolBindings,
+  ToolAssemblyResult,
+  ToolContext,
+  ToolRegistry,
+  ToolSpec,
+} from "./runtime-definition";
+export {
+  emptyPlatformToolRegistry,
+  emptyToolRegistry,
+  mergeToolRegistries,
+  normalizeToolAssembly,
+  piCandidateToToolSpec,
+  toolRegistryFromPiCandidates,
+} from "./tool-registry";
 export type { ModelOption } from "./lib/model-catalog";
 export {
   assembleSubagentPrompt,
@@ -92,16 +109,30 @@ export type {
   SettledPiToolCall,
 } from "./pi/tool";
 export { basePiToolCandidates } from "./pi/tool";
-export { schedulePiToolCandidates } from "./pi/tool";
 export {
+  createMemoryTools,
+  memoryPiToolCandidate,
+} from "./pi/tool";
+export {
+  createScheduleTools,
+  schedulePiToolCandidates,
+} from "./pi/tool";
+export {
+  createSandboxTools,
+  createWorkspaceTools,
   sandboxPiToolCandidates,
   workspacePiToolCandidates,
 } from "./pi/tool";
-export { subagentPiToolCandidates } from "./pi/tool";
+export {
+  createSubagentTools,
+  subagentPiToolCandidates,
+} from "./pi/tool";
 export { skillPiToolCandidates } from "./pi/tool";
 export type { PiSkillBinding } from "./pi/tool";
 export {
   browserQuickActionPiToolCandidates,
+  createCodeExecutionTool,
+  codeExecutionPiToolCandidate,
 } from "./pi/tool";
 export {
   createWorkspaceCodeExecutionPort,
@@ -113,10 +144,11 @@ export {
 export type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
-  TemporaryAgentExecutor,
+  TemporaryAgentLaunch,
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
 } from "./layers/orchestration/temporary-agent/core";
+export { TEMPORARY_AGENT_LAUNCH_KEY } from "./layers/orchestration/temporary-agent/core";
 export {
   temporaryAgentExtensionIsSafe,
   temporaryAgentToolAllowed,

package/src/kernel/approval-lifecycle.ts

@@ -101,7 +101,10 @@ interface ApprovalLifecycleOptions<
 export class ApprovalLifecycle<
   TSubmission extends ApprovalSubmission,
 > {
-  private readonly waiters = new Map<string, () => void>();
+  private readonly waiters = new Map<
+    string,
+    { readonly release: () => void; readonly discard: () => void }
+  >();
 
   /**
    * 接好审批流程需要的宿主依赖。
@@ -217,6 +220,27 @@ export class ApprovalLifecycle<
     return this.wait(pending.approval, signal);
   }
 
+  /**
+   * 丢弃某条提交在内存里的全部审批等待器。
+   *
+   * @remarks
+   * 宿主在 park 期间换掉装配、中断内存执行器之后调用。持久审批一个字都不动：
+   * 被丢弃的只是「唤醒这一条执行器」的能力。
+   *
+   * 不丢弃的后果很具体：决定到来时 `decide` 会看见等待器，把 Turn 唤回那条已经
+   * 退场的旧执行器上，于是既拿不到新能力，也永远不会走持久续跑 —— Turn 就停在
+   * running 上不动了。等待器以 `PiTurnInterruptedError` 拒绝，工具编译器认得它，
+   * 不会为此写一条权威的错误结算。
+   */
+  discardWaiters(submissionId: string): void {
+    for (
+      const executionId of this.options.db.approvals
+        .listPendingForSubmission(submissionId)
+    ) {
+      this.waiters.get(executionId)?.discard();
+    }
+  }
+
   /**
    * 在已批准工具结果落盘后，确认对应恢复调度已经完成。
    *
@@ -364,7 +388,7 @@ export class ApprovalLifecycle<
     await this.options.onApprovalsChanged();
 
     if (waiter) {
-      waiter();
+      waiter.release();
       return { ok: true };
     }
 
@@ -540,10 +564,21 @@ export class ApprovalLifecycle<
         return;
       }
       signal?.addEventListener("abort", abort, { once: true });
-      this.waiters.set(approval.executionId, () => {
-        signal?.removeEventListener("abort", abort);
-        this.waiters.delete(approval.executionId);
-        resolve();
+      this.waiters.set(approval.executionId, {
+        release: () => {
+          signal?.removeEventListener("abort", abort);
+          this.waiters.delete(approval.executionId);
+          resolve();
+        },
+        // 只把等待器摘掉，不去 settle 这个 Promise。让它继续挂着，park 住的
+        // 那次 execute 就永远不会往下走 —— 无论是拒绝（Pi 会把它当成工具失败，
+        // 接着再要一次模型输出）还是放行（工具会真的跑一遍），都会让一条本该
+        // 退场的执行器继续做事。它所属的 adapter 已经被中止并丢弃，这个悬着的
+        // Promise 随它一起变成垃圾。
+        discard: () => {
+          signal?.removeEventListener("abort", abort);
+          this.waiters.delete(approval.executionId);
+        },
       });
     });
   }

package/src/kernel/bindings.ts

@@ -522,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>;
+}
+
 /**
  * 描述一条模型可见的定时任务。
  *
@@ -911,6 +946,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;