@springbrand/agent-runtime 0.1.0

package/src/kernel/state.ts

@@ -0,0 +1,76 @@
+import type { ApprovalReceipt } from "./receipts";
+
+export type RuntimeLoadPhase = "config" | "plugins" | "mcp" | "pi";
+
+export type RuntimeActivity = "idle" | "working" | "needs-input";
+
+export interface RuntimeActivityProjection {
+  activity: RuntimeActivity;
+  revision: number;
+}
+
+/**
+ * Runtime 最近一次装载尝试的公开状态。
+ *
+ * `available` 与本次尝试分开表达：强制重载失败时，旧 Runtime 仍可能继续服务。
+ * 该状态由 Agents SDK 的 Agent state 同步给浏览器，不包含底层异常文本。
+ */
+export type RuntimeLoadState =
+  | {
+      status: "idle";
+      available: false;
+    }
+  | {
+      status: "loading";
+      phase: RuntimeLoadPhase;
+      available: boolean;
+      startedAt: number;
+      updatedAt: number;
+    }
+  | {
+      status: "ready";
+      available: true;
+      startedAt: number;
+      completedAt: number;
+    }
+  | {
+      status: "error";
+      phase: RuntimeLoadPhase;
+      available: boolean;
+      startedAt: number;
+      failedAt: number;
+    };
+
+export interface RuntimeQueuedSubmission {
+  submissionId: string;
+  messageId: string;
+  preview: string;
+  position: number;
+  createdAt: number;
+}
+
+export interface RuntimeTurnState {
+  activeSubmissionId?: string;
+  steerable: boolean;
+  hasPendingSteer: boolean;
+  queued: RuntimeQueuedSubmission[];
+}
+
+/**
+ * 保存 Kernel 在当前会话里自己维护的审批状态。
+ *
+ * @remarks
+ * `RuntimeAgent` 把它作为 Agent state 的形状，并在审批记录变化时读写。
+ *
+ * 它故意不保存用户、Agent 或 Session 等业务身份，避免 Runtime 越过 Host 的归属边界。
+ *
+ * `Runtime`、`Kernel` 与 `Host` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeState {
+  /** 当前实例的 Runtime 装载状态；旧状态记录没有该字段时等同 `idle`。 */
+  runtimeLoad?: RuntimeLoadState;
+  /** 供 Host 列表持久化的粗粒度活动状态；Submission 与 Approval 仍是执行真相。 */
+  activity?: RuntimeActivityProjection;
+  approvals?: ApprovalReceipt[];
+  turn?: RuntimeTurnState;
+}

package/src/kernel/submission-lifecycle.ts

@@ -0,0 +1,600 @@
+import { TurnQueue } from "agents/chat";
+import {
+  isTerminalSubmissionStatus,
+  type SubmissionStatus,
+} from "../db/submission.repo";
+
+/**
+ * 本文件统一管理一次提交从接收到结束的过程。
+ *
+ * @remarks
+ * Runtime、Port 等核心术语沿用包入口 `../index.ts` 的定义，这里不重复解释。
+ *
+ * `AgentRuntimeKernel` 通过本文件把去重、串行执行、恢复和取消收口到同一条路径。
+ *
+ * 这些规则集中在一起，是为了避免普通提交、定时提交和恢复各自维护一套状态判断。
+ */
+
+// #region 公开契约
+
+/**
+ * 表示生命周期管理所需的一条最小提交记录。
+ *
+ * @remarks
+ * 存储实现返回该形状，`SubmissionLifecycle` 在接收、等待和取消时读取它。
+ *
+ * 这里只要求生命周期判断必需的字段，业务侧可以通过泛型保留更多持久化字段。
+ */
+export interface SubmissionRecord {
+  submissionId: string;
+  requestId: string;
+  idempotencyKey?: string | null;
+  status: SubmissionStatus;
+  accepted: boolean;
+  abortReason?: string | null;
+}
+
+/**
+ * 提供生命周期判断和写入所需的持久化操作。
+ *
+ * @remarks
+ * `AgentRuntimeKernel` 在构造 `SubmissionLifecycle` 时传入实现，生命周期方法随后按需调用。
+ *
+ * 接口保持同步，是因为接收提交时必须在一个同步事务里完成查重、容量检查和创建。
+ */
+export interface SubmissionStore<TSubmission extends SubmissionRecord> {
+  /**
+   * 在一个同步事务中运行接收或取消写入。
+   *
+   * @remarks
+   * `admit` 和 `cancel` 在需要同时检查并修改持久化状态时调用，回调内只能使用同步存储操作。
+   *
+   * 不要把异步准备移入回调；当前 SQLite-backed Durable Object 的 `transactionSync` 要求回调同步完成。
+   */
+  transaction<T>(run: () => T): T;
+  /**
+   * 按提交标识读取最新记录。
+   *
+   * @remarks
+   * 查询、等待、恢复和结束路径都会调用，找不到时返回 `null`。
+   *
+   * 每次读取最新值可以避免用旧快照覆盖已经写入的终态或取消意图。
+   */
+  find(submissionId: string): TSubmission | null;
+  /**
+   * 按请求标识查找已有提交。
+   *
+   * @remarks
+   * 接收和按请求停止时调用，同一请求已存在时应返回那条记录。
+   *
+   * 请求级查重是没有幂等键时的固定后备规则。
+   */
+  findByRequestId(requestId: string): TSubmission | null;
+  /**
+   * 按调用方提供的幂等键查找已有提交。
+   *
+   * @remarks
+   * 接收路径只在输入带幂等键时调用，命中后复用已有提交。
+   *
+   * 幂等键优先于请求标识，不能调换，否则同一业务动作可能被当成两次提交。
+   */
+  findByIdempotencyKey(key: string): TSubmission | null;
+  /**
+   * 统计仍在等待或运行的提交。
+   *
+   * @remarks
+   * 接收、稳定等待和 Runtime 忙碌检查会调用。
+   *
+   * 该计数来自持久层而不是内存 Map，因此重启后的未完成工作仍会阻止新提交。
+   */
+  countUnfinished(): number;
+  countPending(): number;
+  findRunning(): TSubmission | null;
+  findNextPending(): TSubmission | null;
+  /**
+   * 列出全部等待或运行中的提交标识。
+   *
+   * @remarks
+   * `stop` 没有指定请求时调用，并逐条走统一取消路径。
+   *
+   * 只返回标识可以避免停止入口复制完整记录或状态判断。
+   */
+  /**
+   * 持久化一条取消原因。
+   *
+   * @remarks
+   * `cancel` 在中断执行器之前调用，执行器稍后激活时也能读到该原因。
+   *
+   * 先持久化意图再触发内存中断，可以让取消跨越执行启动窗口和实例重启。
+   */
+  updateAbortReason(submissionId: string, reason: string): void;
+}
+
+export const MAX_PENDING_SUBMISSIONS = 20;
+
+export class SubmissionQueueFullError extends Error {
+  readonly code = "queue_full";
+
+  constructor() {
+    super(`Pi submission queue is full (${MAX_PENDING_SUBMISSIONS})`);
+  }
+}
+
+/**
+ * 表示执行器交给终态提交器的结果类别。
+ *
+ * @remarks
+ * 执行和恢复路径在调用 `finish` 时提供该值。
+ *
+ * 生命周期只区分成功、失败和取消，具体持久化状态由调用方的 `commitTerminal` 统一映射。
+ */
+export type SubmissionOutcome = "succeeded" | "failed" | "aborted";
+
+/**
+ * 描述接收一次提交所需的标识和延迟创建步骤。
+ *
+ * @remarks
+ * 普通消息和定时消息在调用 `submit` 或 `submitWhenStable` 前创建该对象。
+ *
+ * `prepareAdmission` 先做异步准备，再返回同步创建函数，使真正写入可以留在事务边界内。
+ */
+export interface SubmissionInput<
+  TSubmission extends SubmissionRecord,
+> {
+  requestId: string;
+  idempotencyKey?: string;
+  /**
+   * 准备接收所需数据，并返回同步创建记录的函数。
+   *
+   * @remarks
+   * `submit` 只在快速查重未命中后调用；返回的函数由 `admit` 放进同步事务执行。
+   *
+   * 两阶段形状隔开异步装配和原子写入，不能直接改成在事务里返回 Promise。
+   */
+  prepareAdmission(): Promise<() => TSubmission>;
+}
+
+/**
+ * 同时返回接收回执和最终结果。
+ *
+ * @remarks
+ * 交互入口通常立即读取 `receipt` 并把 `completion` 交给 `waitUntil`，定时入口则等待完成。
+ *
+ * 分开两个阶段可以尽快确认是否接收，同时不丢失最终持久化结果。
+ */
+export interface SubmissionHandle<
+  TSubmission extends SubmissionRecord,
+> {
+  receipt: TSubmission;
+  completion: Promise<TSubmission>;
+}
+
+// #endregion
+
+// #region 内部依赖
+
+interface SubmissionLifecycleOptions<
+  TSubmission extends SubmissionRecord,
+  TActive,
+> {
+  store: SubmissionStore<TSubmission>;
+  // 作用：清理上一次聊天留下的终态标记。
+  // 调用：`admit` 只在新提交成功写入后调用。
+  // 原因：重复提交只加入旧工作，不应清除现有终态。
+  clearTerminal(): Promise<void>;
+  // 作用：执行或恢复一条已持久化的提交。
+  // 调用：`start` 在 `TurnQueue` 轮到该提交时调用。
+  // 原因：生命周期只管调度，具体 Pi Turn 执行仍由 Runtime 负责。
+  execute(submissionId: string, recovery: boolean): Promise<TSubmission>;
+  // 作用：记录可恢复的取消意图。
+  // 调用：`cancel` 在同一存储事务内与取消原因一起写入。
+  // 原因：持久化里程碑可以让恢复路径看到已经发生的取消。
+  appendAbortIntent(submission: TSubmission, reason: string): void;
+  // 作用：把一条非终态提交写成最终结果。
+  // 调用：`finish` 在重读并确认仍非终态后调用。
+  // 原因：状态映射和其他终态副作用必须由 Runtime 在一个边界完成。
+  commitTerminal(
+    submission: TSubmission,
+    outcome: SubmissionOutcome,
+    message?: string,
+  ): Promise<TSubmission>;
+  // 作用：通知当前执行器中断运行。
+  // 调用：`cancel` 命中活动执行器，或 `activate` 发现早到取消时调用。
+  // 原因：生命周期不依赖具体执行器类型，只通过这个回调中断。
+  abortActive(active: TActive): void;
+}
+
+// #endregion
+
+/**
+ * 让所有提交共用同一套接收、执行、恢复和取消规则。
+ *
+ * @remarks
+ * `AgentRuntimeKernel` 在构造时创建一个实例，之后普通消息、定时消息和恢复入口都复用它。
+ *
+ * 持久化状态负责跨重启事实，内存 Map 只合并当前实例内的重复执行，二者不能互相替代。
+ */
+export class SubmissionLifecycle<
+  TSubmission extends SubmissionRecord,
+  TActive = never,
+> {
+  private readonly queue = new TurnQueue();
+  private readonly executions = new Map<string, Promise<TSubmission>>();
+  private readonly activeBySubmission = new Map<string, TActive>();
+
+  // #region 提交与恢复
+
+  /**
+   * 用 Runtime 提供的存储和执行回调创建生命周期管理器。
+   *
+   * @remarks
+   * `AgentRuntimeKernel` 的构造函数在数据库初始化后调用一次。
+   *
+   * 依赖通过一个选项对象传入，使状态规则留在这里，业务执行和持久化细节留在 Runtime。
+   */
+  constructor(
+    private readonly options: SubmissionLifecycleOptions<
+      TSubmission,
+      TActive
+    >,
+  ) {}
+
+  /**
+   * 接收新提交，或让重复请求加入已有提交。
+   *
+   * @remarks
+   * 普通消息入口调用它；调用方读取 `receipt`，并等待或托管 `completion`。
+   *
+   * 先快速查重可跳过昂贵准备，事务内再次查重则覆盖异步准备期间出现的竞争。
+   */
+  async submit(
+    input: SubmissionInput<TSubmission>,
+  ): Promise<SubmissionHandle<TSubmission>> {
+    const duplicate = this.findDuplicate(input);
+    if (duplicate) return this.join(duplicate);
+    const admitted = await this.admit(
+      input,
+      await input.prepareAdmission(),
+    );
+    if (admitted.admitted) this.pump();
+    return {
+      receipt: admitted.submission,
+      completion: this.waitForTerminal(
+        admitted.submission.submissionId,
+      ),
+    };
+  }
+
+  /**
+   * 等 Runtime 暂时没有活动提交后再接收新提交。
+   *
+   * @remarks
+   * 定时任务入口调用它；超时返回 `null`，重复请求则直接加入已有提交。
+   *
+   * 等待发生在异步准备之前，避免稳定性超时时做无用装配；最后仍调用 `submit` 重新查重和接收。
+   */
+  async submitWhenStable(
+    input: SubmissionInput<TSubmission>,
+    timeoutMs: number,
+  ): Promise<SubmissionHandle<TSubmission> | null> {
+    const duplicate = this.findDuplicate(input);
+    if (duplicate) return this.join(duplicate);
+    if (!await this.waitUntilStable(timeoutMs)) return null;
+    return this.submit(input);
+  }
+
+  /**
+   * 从持久化记录重新启动一条未完成提交。
+   *
+   * @remarks
+   * Agent 启动恢复、审批继续和恢复 Port 在已经知道提交标识时调用。
+   *
+   * 它复用 `start` 的实例内去重和串行队列，避免重复唤醒产生两个执行器。
+   */
+  recover(submissionId: string): Promise<TSubmission> {
+    return this.start(submissionId, true);
+  }
+
+  recoverHead(): Promise<TSubmission | null> {
+    const running = this.options.store.findRunning();
+    if (running) return this.start(running.submissionId, true);
+    const pending = this.options.store.findNextPending();
+    return pending
+      ? this.start(pending.submissionId)
+      : Promise.resolve(null);
+  }
+
+  // 作用：在一个同步事务内最终决定接收新提交还是复用旧提交。
+  // 调用：`submit` 完成异步准备后调用，并把同步创建函数传进来。
+  // 原因：事务内重查幂等键、请求标识和活动数，才能关住准备期间的状态变化。
+  private async admit(
+    input: SubmissionInput<TSubmission>,
+    create: () => TSubmission,
+  ): Promise<{ submission: TSubmission; admitted: boolean }> {
+    const result = this.options.store.transaction(() => {
+      if (input.idempotencyKey) {
+        const duplicate = this.options.store.findByIdempotencyKey(
+          input.idempotencyKey,
+        );
+        if (duplicate) {
+          return {
+            submission: { ...duplicate, accepted: false } as TSubmission,
+            admitted: false,
+          };
+        }
+      }
+      const requestDuplicate = this.options.store.findByRequestId(
+        input.requestId,
+      );
+      if (requestDuplicate) {
+        return {
+          submission: {
+            ...requestDuplicate,
+            accepted: false,
+          } as TSubmission,
+          admitted: false,
+        };
+      }
+      if (
+        this.options.store.countPending() >=
+        MAX_PENDING_SUBMISSIONS
+      ) {
+        throw new SubmissionQueueFullError();
+      }
+      return { submission: create(), admitted: true };
+    });
+    if (result.admitted) await this.options.clearTerminal();
+    return result;
+  }
+
+  // 作用：按幂等键优先、请求标识其次的规则查找重复提交。
+  // 调用：`submit` 和 `submitWhenStable` 在异步准备或等待前调用。
+  // 原因：共享查找顺序可避免普通与定时提交对“重复”作出不同判断。
+  private findDuplicate(
+    input: Pick<
+      SubmissionInput<TSubmission>,
+      "requestId" | "idempotencyKey"
+    >,
+  ): TSubmission | null {
+    return (
+      (input.idempotencyKey
+        ? this.options.store.findByIdempotencyKey(input.idempotencyKey)
+        : null) ??
+      this.options.store.findByRequestId(input.requestId)
+    );
+  }
+
+  // 作用：为重复请求生成未接收回执，并连到原提交的完成结果。
+  // 调用：两个提交入口在事务外查重命中时调用。
+  // 原因：复用同一条持久化工作，同时用 `accepted: false` 告诉调用方没有新建执行。
+  private join(
+    submission: TSubmission,
+  ): SubmissionHandle<TSubmission> {
+    return {
+      receipt: { ...submission, accepted: false } as TSubmission,
+      completion: this.waitForTerminal(submission.submissionId),
+    };
+  }
+
+  // 作用：启动一次串行执行，并合并当前实例内对同一提交的重复唤醒。
+  // 调用：新提交和恢复入口在已有持久化记录后调用。
+  // 原因：`TurnQueue` 防止不同 Pi Turn 重叠，`executions` 则防止同一标识重复入队。
+  private start(
+    submissionId: string,
+    recovery = false,
+  ): Promise<TSubmission> {
+    const existing = this.executions.get(submissionId);
+    if (existing) return existing;
+    let shouldPump = false;
+    const started = this.queue
+      .enqueue(submissionId, () =>
+        this.options.execute(submissionId, recovery),
+      )
+      .then((outcome) => {
+        // TODO(待确认): 当前类没有调用 `queue.reset()`，按现有调用链不会产生 `stale` 结果。
+        if (outcome.status !== "stale") {
+          shouldPump = isTerminalSubmissionStatus(
+            outcome.value.status,
+          );
+          return outcome.value;
+        }
+        const submission = this.options.store.find(submissionId);
+        if (!submission) {
+          throw new Error(`Unknown Pi submission: ${submissionId}`);
+        }
+        shouldPump = isTerminalSubmissionStatus(submission.status);
+        return submission;
+      })
+      .finally(() => {
+        if (this.executions.get(submissionId) === started) {
+          this.executions.delete(submissionId);
+        }
+        if (shouldPump) this.pump();
+      });
+    this.executions.set(submissionId, started);
+    return started;
+  }
+
+  private pump(): void {
+    if (this.options.store.findRunning()) return;
+    const next = this.options.store.findNextPending();
+    if (!next) return;
+    void this.start(next.submissionId).catch(() => undefined);
+  }
+
+  // 作用：等待指定提交的内存执行或持久化终态。
+  // 调用：`join` 和事务内才发现的重复提交使用它返回共享的 `completion`。
+  // 原因：内存 Promise 只覆盖本实例，固定间隔查持久层才能看到其他唤醒写入的终态。
+  private async waitForTerminal(
+    submissionId: string,
+  ): Promise<TSubmission> {
+    // TODO(待确认): 持久层若长期保持非终态且没有执行者，这里没有超时或外部唤醒上限。
+    for (;;) {
+      const execution = this.executions.get(submissionId);
+      if (execution) return execution;
+      const submission = this.options.store.find(submissionId);
+      if (!submission) {
+        throw new Error(`Unknown Pi submission: ${submissionId}`);
+      }
+      if (isTerminalSubmissionStatus(submission.status)) return submission;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  }
+
+  // #endregion
+
+  // #region 查询与结束
+
+  /**
+   * 读取指定提交的最新持久化记录。
+   *
+   * @remarks
+   * Runtime 的 `getSubmission` RPC 在按标识查询回执时调用。
+   *
+   * 它不返回内存执行状态，持久化记录仍是对外查询的唯一事实来源。
+   */
+  get(submissionId: string): TSubmission | null {
+    return this.options.store.find(submissionId);
+  }
+
+  /**
+   * 在提交仍未结束时写入一次最终结果。
+   *
+   * @remarks
+   * 正常执行、错误处理、恢复和取消路径都在得出结果后调用。
+   *
+   * 写入前重读最新记录并保留已有终态，避免较晚到达的结果覆盖先完成的结果。
+   */
+  async finish(
+    submission: TSubmission,
+    outcome: SubmissionOutcome,
+    message?: string,
+  ): Promise<TSubmission> {
+    const latest = this.options.store.find(submission.submissionId);
+    if (!latest) {
+      throw new Error(`Unknown Pi submission: ${submission.submissionId}`);
+    }
+    if (isTerminalSubmissionStatus(latest.status)) return latest;
+    return this.options.commitTerminal(latest, outcome, message);
+  }
+
+  /**
+   * 判断持久层是否仍有等待或运行中的提交。
+   *
+   * @remarks
+   * Runtime 在重载配置、清空聊天、Transcript 检查和定时等待时调用。
+   *
+   * 读取持久层而不是只看 `executions`，才能覆盖重启后尚未恢复的提交。
+   */
+  isBusy(): boolean {
+    return this.options.store.countUnfinished() > 0;
+  }
+
+  // 作用：在有限时间内轮询 Runtime 是否已无活动提交。
+  // 调用：`submitWhenStable` 在准备定时提交之前调用。
+  // 原因：每次最多等待 50ms 并截断到 deadline，可以不超过调用方给定的窗口。
+  private async waitUntilStable(timeoutMs: number): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+    while (this.isBusy()) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) return false;
+      await new Promise((resolve) =>
+        setTimeout(resolve, Math.min(50, remaining)),
+      );
+    }
+    return true;
+  }
+
+  // #endregion
+
+  // #region 活动执行与取消
+
+  /**
+   * 登记一条提交当前使用的执行器，并返回配对的解除函数。
+   *
+   * @remarks
+   * Runtime 在 Pi Turn 真正开始前调用，并在执行结束的 `finally` 中调用返回函数。
+   *
+   * 登记后立即重读取消原因，可以补上取消已写入、执行器尚未激活的时间窗口。
+   */
+  activate(submission: TSubmission, active: TActive): () => void {
+    this.activeBySubmission.set(submission.submissionId, active);
+    const latest = this.options.store.find(submission.submissionId);
+    if (latest?.abortReason) this.options.abortActive(active);
+    return () => {
+      if (this.activeBySubmission.get(submission.submissionId) === active) {
+        this.activeBySubmission.delete(submission.submissionId);
+      }
+    };
+  }
+
+  /**
+   * 返回当前唯一活动的执行器。
+   *
+   * @remarks
+   * Extension Host 发送消息时调用；有活动 Turn 就 steer，没有则写入 Transcript。
+   *
+   * 它依赖接收检查和串行队列维持最多一个活动执行器，不能在允许并行 Turn 后继续只取第一个值。
+   */
+  currentActive(): TActive | undefined {
+    return this.activeBySubmission.values().next().value;
+  }
+
+  /**
+   * 为一条未结束提交记录取消，并尽快中断活动执行器。
+   *
+   * @remarks
+   * 客户端取消事件和 `cancelSubmissionById` RPC 按提交标识调用；不存在或已结束时返回 `ok: false`。
+   *
+   * 先在事务中保存取消原因和恢复意图，再按活动、已排队或未执行三种情况处理，避免丢失启动窗口内的取消。
+   */
+  async cancel(
+    submissionId: string,
+    reason = "Cancelled",
+  ): Promise<{ ok: boolean }> {
+    const submission = this.options.store.find(submissionId);
+    if (!submission || isTerminalSubmissionStatus(submission.status)) {
+      return { ok: false };
+    }
+    this.options.store.transaction(() => {
+      this.options.store.updateAbortReason(submissionId, reason);
+      this.options.appendAbortIntent(submission, reason);
+    });
+    const active = this.activeBySubmission.get(submissionId);
+    if (active) this.options.abortActive(active);
+    else {
+      await this.finish(submission, "aborted", reason);
+      this.pump();
+    }
+    return { ok: true };
+  }
+
+  /**
+   * 停止某个请求对应的提交，或停止所有未结束提交。
+   *
+   * @remarks
+   * Runtime 的 `stopTurn` RPC 调用；传入请求标识时只处理匹配项，不传时处理全部活动记录。
+   *
+   * 所有目标都逐条复用 `cancel`，确保单条取消和批量停止遵守同一套持久化顺序。
+   */
+  async stop(
+    requestId?: string,
+    reason = "Stopped",
+  ): Promise<{ ok: boolean }> {
+    const submissionIds = requestId
+      ? (() => {
+          const submission = this.options.store.findByRequestId(requestId);
+          return submission ? [submission.submissionId] : [];
+        })()
+      : (() => {
+          const submission = this.options.store.findRunning();
+          return submission ? [submission.submissionId] : [];
+        })();
+    for (const submissionId of submissionIds) {
+      await this.cancel(submissionId, reason);
+    }
+    return { ok: true };
+  }
+
+  // #endregion
+}