@springbrand/agent-runtime 0.1.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@springbrand/agent-runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./contracts": "./src/kernel/public-contracts.ts",
+    "./models": "./src/lib/model-catalog.ts"
+  },
+  "dependencies": {
+    "@cloudflare/codemode": "0.5.0",
+    "@cloudflare/shell": "0.4.3",
+    "@cloudflare/think": "0.15.0",
+    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-ai": "0.83.0",
+    "agents": "^0.19.0",
+    "ai": "^7.0.0",
+    "lodash-es": "^4.18.1",
+    "zod": "^4.4.3"
+  }
+}

package/src/db/approval.repo.ts

@@ -0,0 +1,291 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+import type { ExecutionLevel } from "../lib/execution-level";
+
+// Approval 的统一定义见 ./index.ts。
+// #region 状态与行类型
+export type ApprovalStatus = "pending" | "approved" | "rejected";
+
+export interface StoredApproval {
+  executionId: string;
+  submissionId: string;
+  requestId: string;
+  source: string;
+  toolCallId: string;
+  toolName: string;
+  summary: string;
+  executionLevel: ExecutionLevel;
+  requiredExecutionLevel: ExecutionLevel;
+  inputJson: string;
+  status: ApprovalStatus;
+  createdAt: number;
+  decidedAt: number | null;
+  reason: string | null;
+}
+
+export interface NewApproval {
+  executionId: string;
+  submissionId: string;
+  requestId: string;
+  source: string;
+  toolCallId: string;
+  toolName: string;
+  summary: string;
+  executionLevel: ExecutionLevel;
+  requiredExecutionLevel: ExecutionLevel;
+  inputJson: string;
+  status: ApprovalStatus;
+  createdAt: number;
+}
+
+export interface PendingApprovalSummary {
+  executionId: string;
+  source: string;
+  toolName: string;
+  summary: string;
+  executionLevel: ExecutionLevel;
+  requiredExecutionLevel: ExecutionLevel;
+  inputJson: string;
+  requestId: string;
+}
+
+export interface ApprovalView {
+  executionId: string;
+  toolCallId: string;
+  status: ApprovalStatus;
+}
+
+export interface DecidedApprovalRef {
+  executionId: string;
+  submissionId: string;
+}
+
+type ApprovalRow = {
+  execution_id: string;
+  submission_id: string;
+  request_id: string;
+  source: string;
+  tool_call_id: string;
+  tool_name: string;
+  summary: string;
+  execution_level: string;
+  required_level: string;
+  input_json: string;
+  status: string;
+  created_at: number;
+  decided_at: number | null;
+  reason: string | null;
+};
+
+// #endregion
+// #region 行映射
+// 把 SQLite 的 Approval 行转成 Runtime 对象。
+// find 查到记录后调用，上层因而不需要理解 snake_case 列名。
+// 状态由表内字符串转成联合类型；新增列或状态时必须同步核对类型、SELECT 和映射。
+function mapRow(row: ApprovalRow): StoredApproval {
+  return {
+    executionId: row.execution_id,
+    submissionId: row.submission_id,
+    requestId: row.request_id,
+    source: row.source,
+    toolCallId: row.tool_call_id,
+    toolName: row.tool_name,
+    summary: row.summary,
+    executionLevel: row.execution_level as ExecutionLevel,
+    requiredExecutionLevel: row.required_level as ExecutionLevel,
+    inputJson: row.input_json,
+    status: row.status as ApprovalStatus,
+    createdAt: row.created_at,
+    decidedAt: row.decided_at,
+    reason: row.reason,
+  };
+}
+
+// #endregion
+// #region Repository
+export class ApprovalRepository {
+  // 保存当前 Agent SQLite 的查询入口。
+  // RuntimeDatabase 构造时调用，ApprovalLifecycle 和 Transcript 随后共享这个 Repository。
+  // Approval 必须与所属 Submission 在同一 Agent 存储中查询，不能跨 Durable Object 拼接状态。
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  // 按 executionId 读取一条完整 Approval，不存在时返回 null。
+  // ApprovalLifecycle 在请求去重、决策、继续和拒绝时调用，调用方必须处理 null。
+  // execution_id 是主键，LIMIT 1 明确只消费一行；不能改成按非唯一字段随意取首行。
+  find(executionId: string): StoredApproval | null {
+    const row = this.sql<ApprovalRow>`
+      SELECT execution_id, submission_id, request_id, source,
+             tool_call_id, tool_name, summary,
+             execution_level, required_level, input_json,
+             status, created_at, decided_at, reason
+      FROM pi_approvals
+      WHERE execution_id = ${executionId}
+      LIMIT 1
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+
+  // 持久化一条新的 Approval。
+  // ApprovalLifecycle.ensurePending 在准入事务内确认没有同一记录后调用。
+  // 主键和 submission_id/tool_call_id 唯一约束是持久化去重防线，不能用覆盖式 INSERT 掩盖冲突审批。
+  insert(approval: NewApproval): void {
+    this.sql`
+      INSERT INTO pi_approvals (
+        execution_id, submission_id, request_id, source,
+        tool_call_id, tool_name, summary,
+        execution_level, required_level, input_json,
+        status, created_at
+      ) VALUES (
+        ${approval.executionId},
+        ${approval.submissionId},
+        ${approval.requestId},
+        ${approval.source},
+        ${approval.toolCallId},
+        ${approval.toolName},
+        ${approval.summary},
+        ${approval.executionLevel},
+        ${approval.requiredExecutionLevel},
+        ${approval.inputJson},
+        ${approval.status},
+        ${approval.createdAt}
+      )
+    `;
+  }
+
+  // 只把 pending Approval 写成指定决策，并记录时间和原因。
+  // applyPiRecoveryMutations 在处理用户决策或恢复命令时调用，迟到的重复决策不应覆盖首次结果。
+  // WHERE status='pending' 实现首次决策胜出，不能去掉这个条件；调用方在事务后重读来确认是否真的生效。
+  decide(
+    executionId: string,
+    status: ApprovalStatus,
+    decidedAt: number,
+    reason?: string,
+  ): void {
+    this.sql`
+      UPDATE pi_approvals
+      SET status = ${status},
+          decided_at = ${decidedAt},
+          reason = ${reason ?? null}
+      WHERE execution_id = ${executionId}
+        AND status = 'pending'
+    `;
+  }
+
+  // 按创建顺序列出某次 Submission 仍待决策的 executionId。
+  // ApprovalLifecycle.rejectPending 在终止 Turn 时调用，随后为每条待决策记录追加拒绝恢复事实。
+  // ORDER BY created_at 保留决策的原始顺序，不能依赖 SQLite 未声明的默认行顺序。
+  listPendingForSubmission(submissionId: string): string[] {
+    return this.sql<{ execution_id: string }>`
+      SELECT execution_id
+      FROM pi_approvals
+      WHERE submission_id = ${submissionId}
+        AND status = 'pending'
+      ORDER BY created_at ASC
+    `.map((row) => row.execution_id);
+  }
+
+  // 列出所属 Submission 仍活跃的全部待决策 Approval 摘要。
+  // ApprovalLifecycle.list 和广播流程在生成用户可见审批列表时调用。
+  // JOIN Submission 是为了隐藏已终止 Turn 的孤立 pending 行，不能只按 Approval 自身状态暴露给用户。
+  listPendingActive(): PendingApprovalSummary[] {
+    return this.sql<{
+      execution_id: string;
+      source: string;
+      tool_name: string;
+      summary: string;
+      execution_level: string;
+      required_level: string;
+      input_json: string;
+      request_id: string;
+    }>`
+      SELECT approval.execution_id, approval.source,
+             approval.tool_name, approval.summary,
+             approval.execution_level, approval.required_level,
+             approval.input_json, approval.request_id
+      FROM pi_approvals approval
+      JOIN pi_submissions submission
+        ON submission.submission_id = approval.submission_id
+      WHERE approval.status = 'pending'
+        AND submission.status IN ('pending', 'running')
+      ORDER BY approval.created_at ASC
+    `.map((row) => ({
+      executionId: row.execution_id,
+      source: row.source,
+      toolName: row.tool_name,
+      summary: row.summary,
+      executionLevel: row.execution_level as ExecutionLevel,
+      requiredExecutionLevel: row.required_level as ExecutionLevel,
+      inputJson: row.input_json,
+      requestId: row.request_id,
+    }));
+  }
+
+  // 按决策时间列出所有已批准或已拒绝的 Approval 引用。
+  // ApprovalLifecycle.dispatchPendingContinuations 在 Runtime 启动时调用，用恢复决策判断哪些记录仍需要继续。
+  // 这里故意不预先猜测“已分派”，幂等性由 Recovery Milestone 决定；不能用内存队列替代跨重启扫描。
+  listDecided(): DecidedApprovalRef[] {
+    return this.sql<{ execution_id: string; submission_id: string }>`
+      SELECT execution_id, submission_id
+      FROM pi_approvals
+      WHERE status IN ('approved', 'rejected')
+      ORDER BY decided_at ASC
+    `.map((row) => ({
+      executionId: row.execution_id,
+      submissionId: row.submission_id,
+    }));
+  }
+
+  // 计算所属 Submission 仍活跃的 pending Approval 数量。
+  // ApprovalLifecycle.countPending 在报告交互阻塞和 Runtime 稳定状态时调用。
+  // 与 listPendingActive 使用同样的 JOIN 和状态条件才能保证计数和用户可见列表一致，修改其一时必须核对另一个。
+  countPendingActive(): number {
+    return (
+      this.sql<{ count: number }>`
+        SELECT COUNT(*) AS count
+        FROM pi_approvals approval
+        JOIN pi_submissions submission
+          ON submission.submission_id = approval.submission_id
+        WHERE approval.status = 'pending'
+          AND submission.status IN ('pending', 'running')
+      `[0]?.count ?? 0
+    );
+  }
+
+  // 只在某个 toolCallId 唯一匹配一条活跃 pending Approval 时返回 executionId。
+  // Runtime 处理工具审批决策时通过 ApprovalLifecycle 调用，返回 null 表示没有或存在歧义。
+  // toolCallId 只在单个 Submission 内唯一，LIMIT 2 用最小查询识别跨 Submission 重名；不能用 LIMIT 1 静默选中任意 Approval。
+  findPendingByToolCallId(toolCallId: string): string | null {
+    const matches = this.sql<{ execution_id: string }>`
+      SELECT approval.execution_id
+      FROM pi_approvals approval
+      JOIN pi_submissions submission
+        ON submission.submission_id = approval.submission_id
+      WHERE approval.tool_call_id = ${toolCallId}
+        AND approval.status = 'pending'
+        AND submission.status NOT IN (
+          'completed', 'aborted', 'skipped', 'error'
+        )
+      LIMIT 2
+    `;
+    return matches.length === 1 ? (matches[0]?.execution_id ?? null) : null;
+  }
+
+  // 列出某次 Submission 的审批 ID、工具调用 ID 和状态。
+  // Transcript 投影浏览器消息时调用，用这些精简字段补齐工具调用视图。
+  // 这里不返回风险、输入等内容，避免 Transcript 和 ApprovalLifecycle 共享过宽的数据契约。
+  listApprovalViews(submissionId: string): ApprovalView[] {
+    return this.sql<{
+      execution_id: string;
+      tool_call_id: string;
+      status: string;
+    }>`
+      SELECT execution_id, tool_call_id, status
+      FROM pi_approvals
+      WHERE submission_id = ${submissionId}
+    `.map((row) => ({
+      executionId: row.execution_id,
+      toolCallId: row.tool_call_id,
+      status: row.status as ApprovalStatus,
+    }));
+  }
+}
+// #endregion

package/src/db/ext-context.repo.ts

@@ -0,0 +1,34 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+// Extension Context 的统一定义见 ./index.ts。
+export class ExtContextRepository {
+  // 保存当前 Agent SQLite 的查询入口。
+  // RuntimeDatabase 构造时调用，宿主扩展只通过已创建的 Repository 读写。
+  // Repository 不自行找 Durable Object，避免把不同 Agent 的上下文混在一起。
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  // 按 label 读取扩展上下文，没有记录时返回 null。
+  // _hostGetContext 在扩展请求已保存的文本时调用，调用方应处理 null。
+  // 只选 content 保持返回值稳定；如果要暴露 updatedAt，必须同步扩展宿主契约。
+  get(label: string): string | null {
+    return (
+      this.sql<{ content: string }>`
+        SELECT content FROM pi_extension_context
+        WHERE label = ${label}
+      `[0]?.content ?? null
+    );
+  }
+
+  // 按 label 新增或替换扩展上下文。
+  // _hostSetContext 在扩展写入文本时调用，同一 label 的后一次写入覆盖前值。
+  // SQLite ON CONFLICT 利用 label 主键一条语句完成替换并同步时间，不能拆成会丢失 updated_at 的两条路径。
+  set(label: string, content: string): void {
+    this.sql`
+      INSERT INTO pi_extension_context (label, content, updated_at)
+      VALUES (${label}, ${content}, ${Date.now()})
+      ON CONFLICT(label) DO UPDATE SET
+        content = excluded.content,
+        updated_at = excluded.updated_at
+    `;
+  }
+}

package/src/db/index.ts

@@ -0,0 +1,83 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+import { initializeSchema } from "./schema";
+import { SubmissionRepository } from "./submission.repo";
+import { ApprovalRepository } from "./approval.repo";
+import { ToolSettlementRepository } from "./settlement.repo";
+import { RecoveryMilestoneRepository } from "./milestone.repo";
+import { ExtContextRepository } from "./ext-context.repo";
+import { MessageUiRepository } from "./message-ui.repo";
+import { SteerRepository } from "./steer.repo";
+import { RuntimeEventOutboxRepository } from "./runtime-event-outbox.repo";
+
+// 数据库术语以这里为准。
+// Submission 是一次可持久化的用户提交，从排队到终态都用同一个 submissionId 跟踪。
+// Approval 是某次工具调用的持久化审批记录，executionId 是对外决策时的主键。
+// Settlement 是工具调用的最终结果，同一 Submission 内用 toolCallId 防止重复落盘。
+// Recovery Milestone 是按 seq 重放的恢复事实，milestoneKey 用来去重。
+// Extension Context 是扩展按 label 保存的文本，不随清空聊天记录删除。
+// Message UI 是会话消息的用户界面补充数据，它由 Transcript 而不是 Turn 生命周期管理。
+// Repository 只把 Runtime 语义翻译成参数化 SQL，所有表都位于当前 Agent 实例自己的 Durable Object SQLite 存储中。
+// Transaction 指 Cloudflare transactionSync 包住的同步操作，回调抛错时整体回滚。
+export * from "./schema";
+export * from "./submission.repo";
+export * from "./approval.repo";
+export * from "./settlement.repo";
+export * from "./milestone.repo";
+export * from "./ext-context.repo";
+export * from "./message-ui.repo";
+export * from "./steer.repo";
+export * from "./runtime-event-outbox.repo";
+
+export class RuntimeDatabase {
+  readonly submissions: SubmissionRepository;
+  readonly approvals: ApprovalRepository;
+  readonly settlements: ToolSettlementRepository;
+  readonly milestones: RecoveryMilestoneRepository;
+  readonly extContext: ExtContextRepository;
+  readonly messageUi: MessageUiRepository;
+  readonly steers: SteerRepository;
+  readonly runtimeEvents: RuntimeEventOutboxRepository;
+
+  // 给各个 Repository 分配同一个 Agent SQLite 入口和事务入口。
+  // AgentRuntimeKernel 构造时只创建一次，业务代码随后通过对应属性访问仓储。
+  // 共享入口保证事务内的读写落在同一对象；不能用另一个 Agent 的 sql 或 transact 混用。
+  constructor(
+    private readonly sql: SqlTaggedTemplate,
+    private readonly transact: <T>(fn: () => T) => T,
+  ) {
+    this.submissions = new SubmissionRepository(sql);
+    this.approvals = new ApprovalRepository(sql);
+    this.settlements = new ToolSettlementRepository(sql);
+    this.milestones = new RecoveryMilestoneRepository(sql);
+    this.extContext = new ExtContextRepository(sql);
+    this.messageUi = new MessageUiRepository(sql);
+    this.steers = new SteerRepository(sql);
+    this.runtimeEvents = new RuntimeEventOutboxRepository(sql);
+  }
+
+  // 在一个同步 SQLite 事务里运行一组读写。
+  // Submission、Approval、Transcript 等需要一起成功或一起回滚时调用，回调不得返回 Promise。
+  // 这里直接保留 transactionSync 的抛错回滚语义；待确认：当前泛型签名无法在类型层阻止 async 回调。
+  transaction<T>(fn: () => T): T {
+    return this.transact(fn);
+  }
+
+  // 确保当前 Runtime 需要的表已经存在。
+  // AgentRuntimeKernel 每次构造时调用，调用方不需要先检查表。
+  // 这里保留单一 schema 入口；具体的旧库升级边界见 initializeSchema 的待确认说明。
+  initializeSchema(): void {
+    initializeSchema(this.sql);
+  }
+
+  // 删除所有持久化 Turn 行，但不删除 Extension Context 或 Message UI。
+  // 客户端 clear 事件会在同一 transactionSync 内先让 Transcript 清除会话和 Message UI，再调用本方法。
+  // Message UI 曾在这里删除，后来归还 Transcript 管理；不能把本方法当成整个 Agent 数据库的通用清空。
+  clearAll(): void {
+    this.sql`DELETE FROM pi_pending_steers`;
+    this.sql`DELETE FROM pi_submissions`;
+    this.sql`DELETE FROM pi_approvals`;
+    this.sql`DELETE FROM pi_tool_settlements`;
+    this.sql`DELETE FROM pi_recovery_milestones`;
+  }
+}

package/src/db/message-ui.repo.ts

@@ -0,0 +1,39 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+// Message UI 的统一定义见 ./index.ts。
+export class MessageUiRepository {
+  // 保存当前 Agent SQLite 的查询入口。
+  // RuntimeDatabase 构造时调用，Transcript 随后通过这个 Repository 管理用户侧补充数据。
+  // 把存储绑定留在构造阶段，避免每次读写都传入可能属于其他 Agent 的 sql。
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  // 按消息 ID 读取用户界面补充数据，没有记录时返回 null。
+  // Transcript 组装浏览器消息时调用，调用方负责解析 body。
+  // Repository 故意不理解 JSON 格式，否则会与 Transcript 的 sidecar 契约形成两个真相源。
+  get(messageId: string): string | null {
+    return (
+      this.sql<{ body: string }>`
+        SELECT body FROM pi_message_ui
+        WHERE message_id = ${messageId}
+      `[0]?.body ?? null
+    );
+  }
+
+  // 按消息 ID 新增或替换用户界面补充数据。
+  // Transcript 写入用户消息 sidecar 时调用，重新投影同一消息可以安全覆盖。
+  // SQLite ON CONFLICT 利用 message_id 主键收口成一条路径，不能改成会因重复主键失败的纯 INSERT。
+  upsert(messageId: string, body: string): void {
+    this.sql`
+      INSERT INTO pi_message_ui (message_id, body)
+      VALUES (${messageId}, ${body})
+      ON CONFLICT(message_id) DO UPDATE SET body = excluded.body
+    `;
+  }
+
+  // 删除全部 Message UI 补充数据。
+  // Transcript.clear 在清空标准会话时调用，并由上层事务把两类数据一起提交。
+  // 该责任曾属于 RuntimeDatabase.clearAll，现在归 Transcript 所有；不能两处分别维护清理规则。
+  clear(): void {
+    this.sql`DELETE FROM pi_message_ui`;
+  }
+}

package/src/db/milestone.repo.ts

@@ -0,0 +1,96 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+// Recovery Milestone 的统一定义见 ./index.ts。
+export interface StoredMilestone {
+  submissionId: string;
+  seq: number;
+  milestoneKey: string;
+  body: string;
+}
+
+type MilestoneRow = {
+  submission_id: string;
+  seq: number;
+  milestone_key: string;
+  body: string;
+};
+
+// 把 SQLite 的 snake_case 行转成 Runtime 使用的 Milestone 对象。
+// 待确认：当前 Repository 只返回 body，没有任何调用方使用这个映射函数。
+// 这个边界可为完整 Milestone 查询隔离表列名，但在确认未来用途前不应继续围绕它增加代码。
+function mapRow(row: MilestoneRow): StoredMilestone {
+  return {
+    submissionId: row.submission_id,
+    seq: row.seq,
+    milestoneKey: row.milestone_key,
+    body: row.body,
+  };
+}
+
+export class RecoveryMilestoneRepository {
+  // 保存当前 Agent SQLite 的查询入口。
+  // RuntimeDatabase 构造时调用，Runtime 和 ApprovalLifecycle 随后共享这个 Repository。
+  // 恢复事实必须与 Submission 位于同一 Agent 存储中，不能用另一个 sql 入口拼接。
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  // 按写入顺序返回某次 Submission 的全部恢复内容。
+  // Runtime 和 ApprovalLifecycle 在计算下一个恢复决策前调用，调用方直接把结果交给 Pi 恢复器。
+  // ORDER BY seq 是重放契约，不能改成 milestoneKey 或无排序查询，否则决策顺序会变。
+  listBodies(submissionId: string): string[] {
+    return this.sql<{ body: string }>`
+      SELECT body
+      FROM pi_recovery_milestones
+      WHERE submission_id = ${submissionId}
+      ORDER BY seq ASC
+    `.map((row) => row.body);
+  }
+
+  // 按 milestoneKey 只插入一次恢复事实，并告诉调用方是否真的新增。
+  // applyPiRecoveryMutations 在事务中调用，false 会让它对 terminal:intent 走定向更新。
+  // seq 用 MAX + 1 保留插入顺序，UNIQUE 约束是最后的去重防线；不能改成会覆盖任意旧事实的普通 UPSERT。
+  upsert(
+    submissionId: string,
+    milestoneKey: string,
+    body: string,
+  ): boolean {
+    const existing =
+      this.sql<{ count: number }>`
+        SELECT COUNT(*) AS count
+        FROM pi_recovery_milestones
+        WHERE submission_id = ${submissionId}
+          AND milestone_key = ${milestoneKey}
+      `[0]?.count ?? 0;
+    if (existing > 0) return false;
+
+    const seq =
+      this.sql<{ next_seq: number }>`
+        SELECT COALESCE(MAX(seq), 0) + 1 AS next_seq
+        FROM pi_recovery_milestones
+        WHERE submission_id = ${submissionId}
+      `[0]?.next_seq ?? 1;
+
+    this.sql`
+      INSERT INTO pi_recovery_milestones (
+        submission_id, seq, milestone_key, body
+      ) VALUES (
+        ${submissionId},
+        ${seq},
+        ${milestoneKey},
+        ${body}
+      )
+    `;
+    return true;
+  }
+
+  // 只替换已有 terminal:intent 的内容，不新建事实。
+  // applyPiRecoveryMutations 在 upsert 返回 false 且 key 是 terminal:intent 时调用。
+  // 该例外允许最终失败理由收敛，但不能放宽 WHERE 去改写其他已记录的恢复事实。
+  updateTerminalIntent(submissionId: string, body: string): void {
+    this.sql`
+      UPDATE pi_recovery_milestones
+      SET body = ${body}
+      WHERE submission_id = ${submissionId}
+        AND milestone_key = 'terminal:intent'
+    `;
+  }
+}

package/src/db/runtime-event-outbox.repo.ts

@@ -0,0 +1,89 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+export interface StoredRuntimeEvent {
+  eventId: string;
+  body: string;
+  createdAt: number;
+  deliveredAt: number | null;
+}
+
+export interface NewRuntimeEvent {
+  eventId: string;
+  body: string;
+  createdAt: number;
+}
+
+type RuntimeEventRow = {
+  event_id: string;
+  body: string;
+  created_at: number;
+  delivered_at: number | null;
+};
+
+function mapRow(row: RuntimeEventRow): StoredRuntimeEvent {
+  return {
+    eventId: row.event_id,
+    body: row.body,
+    createdAt: row.created_at,
+    deliveredAt: row.delivered_at,
+  };
+}
+
+export class RuntimeEventOutboxRepository {
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  insert(event: NewRuntimeEvent): boolean {
+    const existing = this.find(event.eventId);
+    if (existing) {
+      if (existing.body !== event.body) {
+        throw new Error(`Conflicting runtime event: ${event.eventId}`);
+      }
+      return false;
+    }
+    this.sql`
+      INSERT INTO pi_turn_event_outbox (
+        event_id, body, created_at, delivered_at
+      ) VALUES (
+        ${event.eventId}, ${event.body}, ${event.createdAt}, NULL
+      )
+    `;
+    return true;
+  }
+
+  listPending(): StoredRuntimeEvent[] {
+    return this.sql<RuntimeEventRow>`
+      SELECT event_id, body, created_at, delivered_at
+      FROM pi_turn_event_outbox
+      WHERE delivered_at IS NULL
+      ORDER BY created_at, event_id
+    `.map(mapRow);
+  }
+
+  hasPending(): boolean {
+    return Boolean(
+      this.sql<{ pending: number }>`
+        SELECT 1 AS pending
+        FROM pi_turn_event_outbox
+        WHERE delivered_at IS NULL
+        LIMIT 1
+      `[0],
+    );
+  }
+
+  markDelivered(eventId: string, deliveredAt: number): void {
+    this.sql`
+      UPDATE pi_turn_event_outbox
+      SET delivered_at = ${deliveredAt}
+      WHERE event_id = ${eventId} AND delivered_at IS NULL
+    `;
+  }
+
+  private find(eventId: string): StoredRuntimeEvent | null {
+    const row = this.sql<RuntimeEventRow>`
+      SELECT event_id, body, created_at, delivered_at
+      FROM pi_turn_event_outbox
+      WHERE event_id = ${eventId}
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+}