@springbrand/agent-runtime 0.1.0

package/src/kernel/bindings.ts

@@ -0,0 +1,898 @@
+import type { SkillSource } from "agents/skills";
+import type { ScheduleSpec } from "./receipts";
+import type { RuntimeActivityProjection } from "./state";
+import type { ExecutionLevel } from "../lib/execution-level";
+
+// #region Workspace 端口
+
+/**
+ * 描述 Workspace 中一个目录项的当前元数据。
+ *
+ * @remarks
+ * Workspace 实现在 `stat`、`lstat`、`readDir` 和 `glob` 返回它。
+ *
+ * Runtime 只依赖这个窄投影，核心术语见 `../index.ts`。
+ */
+export interface WorkspaceFileInfo {
+  path: string;
+  name: string;
+  type: "file" | "directory" | "symlink";
+  mimeType: string;
+  size: number;
+  createdAt: number;
+  updatedAt: number;
+  target?: string;
+}
+
+/**
+ * 向 Runtime 提供已限定作用域的文件操作。
+ *
+ * @remarks
+ * Workspace 工具、记忆组装和 Host RPC 在读写当前会话文件时调用它。
+ *
+ * Host 负责路径隔离、配额和持久化；Runtime 不得绕过该 Port 接触底层存储。
+ */
+export interface WorkspacePort {
+  /**
+   * 把文本文件读成字符串，文件不存在时返回 `null`。
+   *
+   * @remarks
+   * Workspace 工具、记忆组装或 Host 文件 RPC 在需要文本内容时调用。
+   *
+   * 缺失用 `null` 表示，让调用方能区分“没有文件”与存储故障。
+   */
+  readFile(path: string): Promise<string | null>;
+  /**
+   * 把文件读成原始字节，文件不存在时返回 `null`。
+   *
+   * @remarks
+   * 需要保留二进制内容的 Workspace 或 Sandbox 边界调用它。
+   *
+   * 它与 `readFile` 分开，避免 Runtime 猜测字符编码。
+   */
+  readFileBytes(path: string): Promise<Uint8Array | null>;
+  /**
+   * 覆盖写入一个文本文件。
+   *
+   * @remarks
+   * Workspace 工具、记忆服务和 Host RPC 在提交完整文本时调用，并可传入 MIME 类型。
+   *
+   * 写入语义由 Host 统一实现，便于在一个边界内做作用域与配额检查。
+   */
+  writeFile(path: string, content: string, mimeType?: string): Promise<void>;
+  /**
+   * 覆盖写入一个二进制文件。
+   *
+   * @remarks
+   * Workspace 或 Sandbox 边界在提交原始字节时调用，并可传入 MIME 类型。
+   *
+   * 接受 `Uint8Array` 和 `ArrayBuffer` 是为了直接承接当前调用方，不在 Runtime 内复制或转码。
+   */
+  writeFileBytes(
+    path: string,
+    data: Uint8Array | ArrayBuffer,
+    mimeType?: string,
+  ): Promise<void>;
+  /**
+   * 把文本追加到文件末尾。
+   *
+   * @remarks
+   * 需要增量记录内容的 Workspace 调用方使用它，并可传入 MIME 类型。
+   *
+   * 追加由 Host 实现，避免 Runtime 通过先读后写制造丢更新窗口。
+   */
+  appendFile(path: string, content: string, mimeType?: string): Promise<void>;
+  /**
+   * 判断一个 Workspace 路径是否存在。
+   *
+   * @remarks
+   * 需要分支处理缺失路径的 Workspace 或 Host 逻辑在操作前调用。
+   *
+   * 存在性查询保留在 Port 内，让作用域映射与实际访问使用同一套规则。
+   */
+  exists(path: string): Promise<boolean>;
+  /**
+   * 读取路径指向目标的元数据。
+   *
+   * @remarks
+   * Workspace 工具和 Host 计量逻辑在需要文件类型、大小或时间时调用。
+   *
+   * 实现可以解析最终目标；需要检查符号链接本身时应改用 `lstat`。
+   */
+  stat(path: string): Promise<WorkspaceFileInfo | null>;
+  /**
+   * 读取路径项本身的元数据。
+   *
+   * @remarks
+   * 作用域安全检查在识别路径中的符号链接时调用。
+   *
+   * 它不与 `stat` 合并，因为跟随符号链接会破坏当前的边界检查。
+   */
+  lstat(path: string): Promise<WorkspaceFileInfo | null>;
+  /**
+   * 创建一个 Workspace 目录。
+   *
+   * @remarks
+   * Workspace 工具、记忆服务或 Host 初始化逻辑在写入目录树前调用。
+   *
+   * `recursive` 透传给 Host，Runtime 不自行拆成多次非原子调用。
+   */
+  mkdir(path: string, opts?: { recursive?: boolean }): Promise<void>;
+  /**
+   * 按页列出一个 Workspace 目录的直接内容。
+   *
+   * @remarks
+   * Workspace 工具、Host RPC 和用量扫描在枚举目录时调用；省略 `dir` 表示当前根目录。
+   *
+   * 端口保留 `limit` 和 `offset`，避免大目录被强制一次载入。
+   */
+  readDir(
+    dir?: string,
+    opts?: { limit?: number; offset?: number },
+  ): Promise<WorkspaceFileInfo[]>;
+  /**
+   * 删除一个 Workspace 路径。
+   *
+   * @remarks
+   * Workspace 删除工具或 Host RPC 在用户明确请求删除时调用。
+   *
+   * `recursive` 和 `force` 由 Host 按存储语义执行，根目录与作用域保护也必须留在 Host。
+   */
+  rm(path: string, opts?: { recursive?: boolean; force?: boolean }): Promise<void>;
+  /**
+   * 在 Workspace 内复制文件或目录。
+   *
+   * @remarks
+   * Workspace 工具在需要保留原件时调用，复制目录时显式传入 `recursive`。
+   *
+   * 源和目标都经过同一 Port，让 Host 能在一处强制路径边界。
+   */
+  cp(src: string, dest: string, opts?: { recursive?: boolean }): Promise<void>;
+  /**
+   * 在 Workspace 内移动或重命名文件与目录。
+   *
+   * @remarks
+   * Workspace 工具在不再保留原路径时调用，移动目录时显式传入 `recursive`。
+   *
+   * 由 Host 执行移动，避免 Runtime 用“复制后删除”造成部分成功。
+   */
+  mv(src: string, dest: string, opts?: { recursive?: boolean }): Promise<void>;
+  /**
+   * 在 Workspace 中创建一个符号链接。
+   *
+   * @remarks
+   * 只有允许符号链接的 Workspace 实现才应接受该调用；当前会话作用域实现会拒绝它。
+   *
+   * 权限决定留给 Host，因为链接解析会直接影响作用域隔离。
+   */
+  symlink(target: string, linkPath: string): Promise<void>;
+  /**
+   * 读取一个符号链接保存的目标。
+   *
+   * @remarks
+   * Workspace 调用方在已知路径是符号链接且需要显示目标时调用。
+   *
+   * 返回值仍经 Host 投影，避免泄露底层物理 Workspace 路径。
+   */
+  readlink(path: string): Promise<string>;
+  /**
+   * 按模式查找 Workspace 目录项。
+   *
+   * @remarks
+   * Workspace 搜索工具在路径模式已明确时调用。
+   *
+   * 匹配与作用域投影交给 Host，Runtime 不先枚举全部文件再自行过滤。
+   */
+  glob(pattern: string): Promise<WorkspaceFileInfo[]>;
+}
+
+/**
+ * 汇总一个已限定作用域的 Workspace 用量。
+ *
+ * @remarks
+ * Host 管理面在展示或检查当前会话用量时使用它。
+ *
+ * Runtime 不自行计数，因为计费边界由 Host 的作用域决定。
+ */
+export interface WorkspaceUsage {
+  fileCount: number;
+  directoryCount: number;
+  totalBytes: number;
+}
+
+/**
+ * 说明一个 Workspace 作用域的持久存储配额。
+ *
+ * @remarks
+ * Host 管理面在返回 Workspace 限额时使用，`null` 表示 Host 未配置该项。
+ *
+ * HTTP 上传大小等传输限制不属于这组持久存储配额，不能混用。
+ */
+export interface WorkspaceQuota {
+  maxFiles: number | null;
+  maxTotalBytes: number | null;
+  maxFileBytes: number | null;
+}
+
+/**
+ * 向 Host 提供一个已限定作用域 Workspace 的生命周期和计量操作。
+ *
+ * @remarks
+ * Inbox 等可信 Host 代码在创建、查询或清理会话 Workspace 时调用它。
+ *
+ * 它故意不继承 `WorkspacePort`，防止 Runtime 通过数据面引用取得管理能力。
+ */
+export interface WorkspaceAdminPort {
+  /**
+   * 确保当前作用域所需的 Workspace 目录已存在。
+   *
+   * @remarks
+   * Host 在会话初始化或首次使用 Workspace 前调用。
+   *
+   * 初始化留在管理面，不让 Runtime 知道物理目录布局。
+   */
+  ensure(): Promise<void>;
+  /**
+   * 统计当前 Workspace 作用域的持久存储用量。
+   *
+   * @remarks
+   * Host 在展示用量或执行配额相关检查时调用。
+   *
+   * 实现负责排除不应归属当前作用域的共享数据。
+   */
+  getUsage(): Promise<WorkspaceUsage>;
+  /**
+   * 返回当前 Workspace 作用域的持久存储配额。
+   *
+   * @remarks
+   * Host 在响应配额查询时调用。
+   *
+   * 配额由 Host 配置与解释，Runtime 只接收数据面能力。
+   */
+  getQuota(): Promise<WorkspaceQuota>;
+  /**
+   * 删除当前 Workspace 作用域的全部私有数据。
+   *
+   * @remarks
+   * Host 仅在清理或删除对应会话时调用。
+   *
+   * 该危险操作不暴露给 Runtime，并必须由实现保护用户级共享目录。
+   */
+  removeAll(): Promise<void>;
+}
+
+/**
+ * 读写当前 Agent 与会话范围内的热记忆块。
+ *
+ * @remarks
+ * Memory Plugin 在装配时绑定它，Runtime 在生成 Turn 系统上下文时读取。
+ *
+ * 作用域与存储细节留给 Host，核心术语见 `../index.ts`。
+ */
+export interface RuntimeMemoryPort {
+  /**
+   * 按标签读取一块热记忆，不存在时返回 `null`。
+   *
+   * @remarks
+   * Pi 系统上下文组装在 Turn 开始前读取 `memory` 和 `preferences`。
+   *
+   * 标签查询由 Host 限定到当前 Agent 与会话，Runtime 不携带业务 ID。
+   */
+  get(label: string): Promise<string | null>;
+  /**
+   * 按标签覆盖一块热记忆。
+   *
+   * @remarks
+   * Host 实现提供该能力，但当前 `packages/agent-runtime/src` 没有调用点。
+   *
+   * TODO(待确认): 确认后续写入方是否仍需通过这个公开 Port 提交热记忆。
+   */
+  set(label: string, content: string): Promise<void>;
+}
+
+// #endregion
+
+// #region Sandbox 端口
+
+/**
+ * 描述一次前台 Sandbox 命令。
+ *
+ * @remarks
+ * `sandbox_exec` 工具在执行前组装它，Host Adapter 负责校验目录与超时。
+ *
+ * 它只传输执行所需的最小字段，不暴露 Sandbox SDK 对象。
+ */
+export interface SandboxExecInput {
+  command: string;
+  cwd?: string;
+  stdin?: string;
+  timeoutMs?: number;
+}
+
+/**
+ * 描述一次后台 Sandbox 进程启动。
+ *
+ * @remarks
+ * `sandbox_start_process` 工具在启动长运行进程前组装它。
+ *
+ * 进程生命周期由 Host Adapter 管理，因此输入不携带 SDK 会话对象。
+ */
+export interface SandboxStartProcessInput {
+  command: string;
+  cwd?: string;
+  stdin?: string;
+}
+
+/**
+ * 返回一次前台 Sandbox 命令的有界输出。
+ *
+ * @remarks
+ * `sandbox_exec` 工具在命令完成后将它投影给模型。
+ *
+ * 截断标记必须与文本一起返回，让调用方不会把不完整输出当成全量结果。
+ */
+export interface SandboxExecResult {
+  success: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+}
+
+/**
+ * 描述一个 Sandbox 后台进程的当前状态。
+ *
+ * @remarks
+ * 启动进程或后续查询时，Sandbox 工具用它向模型返回稳定投影。
+ *
+ * Runtime 不暴露提供商进程对象，避免 SDK 类型越过 Port 边界。
+ */
+export interface SandboxProcessSummary {
+  id: string;
+  command: string;
+  status: string;
+  exitCode?: number;
+}
+
+/**
+ * 返回一个 Sandbox 后台进程的有界日志。
+ *
+ * @remarks
+ * `sandbox_process_logs` 工具按进程 ID 查询时使用它。
+ *
+ * stdout 和 stderr 分开且携带截断标记，避免丢失命令的错误语义。
+ */
+export interface SandboxProcessLogs {
+  id: string;
+  stdout: string;
+  stderr: string;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+}
+
+/**
+ * 描述一个没有发布成功的 Sandbox 文件。
+ *
+ * @remarks
+ * Sandbox Adapter 在批量发布回 Workspace 时为每个失败项生成它。
+ *
+ * 按文件保留错误码，让部分成功不需被折叠成一个模糊异常。
+ */
+export interface SandboxSyncFailure {
+  path: string;
+  errorCode: string;
+}
+
+/**
+ * 汇总 Sandbox 文件发布回 Workspace 的结果。
+ *
+ * @remarks
+ * `sandbox_publish_files` 工具在显式持久化文件后把它返回给模型。
+ *
+ * 成功、跳过和失败分开记录，因为一次批量发布可以部分成功。
+ */
+export interface SandboxSyncResult {
+  files: readonly string[];
+  skipped: readonly string[];
+  failed: readonly SandboxSyncFailure[];
+  bytes: number;
+}
+
+/**
+ * 列出 Runtime 能稳定识别的 Sandbox 失败类别。
+ *
+ * @remarks
+ * Host Adapter 在映射提供商异常时使用，工具层可据此返回一致错误。
+ *
+ * 该联合类型是 Port 协议；改名或删除值会破坏 Host 映射与调用方分支。
+ */
+export type SandboxErrorCode =
+  | "capacity_unavailable"
+  | "startup_failed"
+  | "workspace_hydration_failed"
+  | "timeout"
+  | "not_found"
+  | "invalid_path"
+  | "output_limit_exceeded"
+  | "rate_limited"
+  | "concurrency_limited"
+  | "publish_too_large"
+  | "publish_limit_exceeded"
+  | "workspace_conflict"
+  | "operation_failed";
+
+/**
+ * 把 Sandbox 失败作为与提供商无关的 Port 异常抛出。
+ *
+ * @remarks
+ * Host Adapter 在命令、进程或发布失败时构造它，Runtime 和 E2E 调用方可检查 `code`。
+ *
+ * 错误消息同时携带固定前缀与结构化代码，保留日志可读性和程序分支能力。
+ */
+export class SandboxPortError extends Error {
+  /**
+   * 创建一个带稳定错误码的 Sandbox Port 异常。
+   *
+   * @remarks
+   * Sandbox Adapter 在把 SDK 或策略失败转换到 Runtime 边界时调用。
+   *
+   * 构造器统一设置前缀和 `name`，不应由每个抛出点重复拼接。
+   */
+  constructor(
+    readonly code: SandboxErrorCode,
+    message: string,
+  ) {
+    super(`sandbox_error:${code}:${message}`);
+    this.name = "SandboxPortError";
+  }
+}
+
+/**
+ * 向 Runtime 工具提供隔离的 Linux Sandbox 执行与发布能力。
+ *
+ * @remarks
+ * Sandbox Plugin 在装配时把它交给 Sandbox 工具候选，工具在 Turn 内调用。
+ *
+ * 命令限制、工作目录校验、水合与冲突安全发布都留在 Host Adapter；术语见 `../index.ts`。
+ */
+export interface RuntimeSandboxPort {
+  /**
+   * 在 Sandbox 前台执行一条命令并等待完成。
+   *
+   * @remarks
+   * `sandbox_exec` 工具在用户 Turn 内调用，并把 Turn 的取消信号传入。
+   *
+   * 超时、输出上限和 Workspace 水合由 Adapter 统一执行，不在工具层复制。
+   */
+  exec(
+    input: SandboxExecInput,
+    signal?: AbortSignal,
+  ): Promise<SandboxExecResult>;
+  /**
+   * 在 Sandbox 中启动一个后台进程。
+   *
+   * @remarks
+   * `sandbox_start_process` 工具在需要长时间运行的命令时调用，后续用返回的 ID 查日志或停止。
+   *
+   * 进程上限、命名和清理属于 Host 策略，Runtime 只依赖稳定摘要。
+   */
+  startProcess(
+    input: SandboxStartProcessInput,
+  ): Promise<SandboxProcessSummary>;
+  /**
+   * 读取一个 Sandbox 后台进程的有界日志。
+   *
+   * @remarks
+   * `sandbox_process_logs` 工具在拿到进程 ID 后按需调用。
+   *
+   * Adapter 负责验证 ID 归属和截断输出，避免工具越过当前 Sandbox 作用域。
+   */
+  getProcessLogs(id: string): Promise<SandboxProcessLogs>;
+  /**
+   * 停止一个 Sandbox 后台进程。
+   *
+   * @remarks
+   * `sandbox_stop_process` 工具在用户或模型明确要求结束进程时调用。
+   *
+   * 返回 `{ stopped: false }` 而不必然抛错，让“进程已不在运行”与系统故障分开。
+   */
+  stopProcess(id: string): Promise<{ stopped: boolean }>;
+  /**
+   * 把选定的 Sandbox 文件显式发布回持久 Workspace。
+   *
+   * @remarks
+   * `sandbox_publish_files` 工具仅在需要保留临时 Sandbox 产物时调用。
+   *
+   * 发布不与命令执行自动绑定，避免失败或未确认的临时文件污染持久 Workspace。
+   */
+  publishFiles(paths: readonly string[]): Promise<SandboxSyncResult>;
+}
+
+// #endregion
+
+// #region Runtime 服务端口
+
+/**
+ * 描述一条模型可见的定时任务。
+ *
+ * @remarks
+ * `list_schedules` 工具在用户查询或取消任务前展示它。
+ *
+ * 这是窄投影，故意不携带归属、历史等 Host 管理面字段。
+ */
+export interface RuntimeScheduleSummary {
+  id: string;
+  label?: string;
+  /** 人读的触发描述，如 `cron 0 9 * * *`、`每 3600 秒`或`一次性`。 */
+  trigger: string;
+  tz: string;
+  nextRun: number | null;
+  enabled: boolean;
+  status: "active" | "paused" | "completed" | "error_paused";
+  prompt: string;
+}
+
+export interface RuntimeScheduleUpdate {
+  trigger?: ScheduleSpec["trigger"];
+  prompt?: string;
+  label?: string;
+  tz?: string;
+}
+
+/**
+ * 让 Runtime 通过 Host 管理当前用户的定时任务。
+ *
+ * @remarks
+ * Schedule Plugin 在装配时把它交给基础工具，模型在用户要求创建、查询或取消时调用。
+ *
+ * 任务归属和持久化留在 Host，Runtime 只传递 `ScheduleSpec` 和窄结果。
+ */
+export interface RuntimeSchedulePort {
+  /**
+   * 创建一条定时任务并返回它的 ID。
+   *
+   * @remarks
+   * `schedule` 工具在把用户的时间与提示词组成 `ScheduleSpec` 后调用。
+   *
+   * Host 在该边界内绑定用户与会话，Runtime 不携带业务归属 ID。
+   */
+  create(spec: ScheduleSpec): Promise<{ id: string }>;
+  /**
+   * 列出当前用户的定时任务。
+   *
+   * @remarks
+   * `list_schedules` 工具在用户查询任务或取消前查找 ID 时调用。
+   *
+   * 模型必须能查询已创建任务，否则用户无法在对话中可靠地管理它们。
+   */
+  list(): Promise<RuntimeScheduleSummary[]>;
+  update(
+    id: string,
+    changes: RuntimeScheduleUpdate,
+  ): Promise<{ ok: boolean }>;
+  pause(id: string): Promise<{ ok: boolean }>;
+  resume(id: string): Promise<{ ok: boolean }>;
+  /**
+   * 按 ID 取消一条定时任务。
+   *
+   * @remarks
+   * `cancel_schedule` 工具先列出任务并确定目标后调用。
+   *
+   * 不存在的 ID 用 `{ ok: false }` 表示，与 Host 运行故障的异常分开。
+   */
+  cancel(id: string): Promise<{ ok: boolean }>;
+}
+
+/**
+ * 表示一次 Subagent 运行的完成或非完成结果。
+ *
+ * @remarks
+ * Subagent 工具在 Host 返回运行状态后用它决定输出正常结果还是失败投影。
+ *
+ * `completed` 分支必须携带 `output`，其他状态保留 Host 返回的字符串。
+ */
+export type RuntimeSubagentRunResult =
+  | {
+      status: "completed";
+      runId: string;
+      output: unknown;
+      error?: undefined;
+    }
+  | {
+      status: string;
+      runId: string;
+      output?: unknown;
+      error?: string;
+    };
+
+/**
+ * 让 Runtime 通过 Host 启动已授权的 Subagent。
+ *
+ * @remarks
+ * Subagent Plugin 在装配时把它交给启用的 Subagent 工具，工具在 Turn 内调用。
+ *
+ * 运行记录、后台通知和实际 Agent 路由由 Host 保持，Runtime 只传入类型与结构化输入。
+ */
+export interface RuntimeSubagentPort {
+  /**
+   * 启动一次 Subagent 运行并返回当前结果。
+   *
+   * @remarks
+   * 同步 Subagent 工具直接调用；`dispatch_background` 会额外传入 `detached`、时间预算和通知来源。
+   *
+   * 可选项不拆成另一个方法，因为两种路径共用同一 Host 运行协议与 `runId`。
+   */
+  run(
+    agentType: string,
+    input: Readonly<Record<string, unknown>>,
+    options?: Readonly<{
+      detached?: boolean;
+      maxBudgetMs?: number;
+      notifySource?: string;
+    }>,
+  ): Promise<RuntimeSubagentRunResult>;
+}
+
+/**
+ * 投影一条 Turn 完成后的用户或助手文本消息。
+ *
+ * @remarks
+ * Runtime 在终态投影时从完整转录中提取这两种角色。
+ *
+ * 只保留角色与文本，避免 Host 投影端口依赖 Pi 的内部消息结构。
+ */
+export interface RuntimeTurnMessage {
+  readonly role: "user" | "assistant";
+  readonly text: string;
+}
+
+export interface RuntimeModelUsageEvent {
+  readonly eventId: string;
+  readonly submissionId: string;
+  readonly kind: "assistant" | "compaction";
+  readonly api: string;
+  readonly provider: string;
+  readonly model: string;
+  readonly responseModel?: string;
+  readonly stopReason?: string;
+  readonly usage: {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly cacheWrite1h?: number;
+    readonly reasoning?: number;
+    readonly totalTokens: number;
+    readonly cost: {
+      readonly input: number;
+      readonly output: number;
+      readonly cacheRead: number;
+      readonly cacheWrite: number;
+      readonly total: number;
+    };
+  };
+}
+
+export interface RuntimeToolSettlementEvent {
+  readonly eventId: string;
+  readonly submissionId: string;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly status: "success" | "error";
+}
+
+/**
+ * 把已持久化的 Turn 文本和逐步用量事件投影给 Host。
+ *
+ * @remarks
+ * `onResponse` 只在 Turn 终态后调用；用量回调在对应事实与
+ * durable outbox 同事务提交后调用。
+ *
+ * 一次传入当前文本投影，让 Host 保持唯一的后续写入顺序。
+ */
+export interface RuntimeTurnEventsPort {
+  /**
+   * 把 Turn 终态的可见文本消息交给 Host。
+   *
+   * @remarks
+   * Runtime `projectTerminal` 在更新转录与客户端后调用；Host 实现应把它当作后续投影。
+   *
+   * Runtime 会捕获该回调的失败，避免应用投影反过来改写已完成 Turn 的结果。
+   */
+  onResponse(
+    messages: readonly RuntimeTurnMessage[],
+  ): Promise<void>;
+  /** 投递 Assistant 或 Compaction 的原始 provider usage。 */
+  onModelUsage?(event: RuntimeModelUsageEvent): Promise<void>;
+  /** 投递不含参数与结果的 Tool 最终结算事件。 */
+  onToolSettled?(event: RuntimeToolSettlementEvent): Promise<void>;
+  onApproval?(input: {
+    readonly submissionId: string;
+    readonly approvalExecutionId: string;
+  }): Promise<void>;
+  onActivityChanged?(
+    projection: RuntimeActivityProjection,
+  ): Promise<void>;
+  onSubmissionTerminal?(input: {
+    readonly submissionId: string;
+    readonly status: "completed" | "aborted" | "skipped" | "error";
+    readonly error?: string;
+    readonly resultMessageId?: string;
+  }): Promise<void>;
+}
+
+/**
+ * 向 Runtime 浏览器工具提供 Browser Run Quick Action 调用。
+ *
+ * @remarks
+ * Platform Plugin 在 Browser 绑定存在时生成快捷操作工具，工具在读取、提取或抓取页面时调用。
+ *
+ * 该 Port 保留 Browser Run 的通用 `action + options` 协议，具体工具仍由 `agents/browser` 辅助函数组装。
+ */
+export interface RuntimeBrowserPort {
+  /**
+   * 执行一个 Browser Run Quick Action 并返回原始响应。
+   *
+   * @remarks
+   * `agents/browser` 的快捷操作辅助函数在对应 Pi 工具执行期调用。
+   *
+   * Runtime 不复制 Browser Run 的选项联合类型，避免两份协议随上游漂移。
+   */
+  quickAction(
+    action: string,
+    options: unknown,
+  ): Promise<Response>;
+}
+
+// #endregion
+
+// #region 模型与 Cloudflare 平台端口
+
+/**
+ * 列出 Runtime 可选的模型调用协议。
+ *
+ * @remarks
+ * Provider Plugin 在组装模型端点时设置，Pi Adapter 在注册模型时读取。
+ *
+ * 这是 Runtime 与 Pi Adapter 的稳定协议，新值必须先有对应的 Adapter 实现。
+ */
+export type RuntimeModelProtocol =
+  | "openai-chat"
+  | "anthropic-messages"
+  | "google-generative-ai"
+  | "openai-codex-responses";
+
+/**
+ * 描述一个已解析凭据的模型 API 端点。
+ *
+ * @remarks
+ * Provider Plugin 在装配时构造，Pi Adapter 启用时依次注册其中的模型。
+ *
+ * 凭据只留在 Port 对象，不进入 `RuntimeProfile` 或持久状态；术语见 `../index.ts`。
+ */
+export interface RuntimeModelEndpoint {
+  protocol: RuntimeModelProtocol;
+  /** Resolved credential; never enters RuntimeProfile or persisted state. */
+  apiKey: string;
+  /** Resolved request headers; never enter RuntimeProfile or persisted state. */
+  headers?: Readonly<Record<string, string>>;
+  baseURL: string;
+  models: readonly string[];
+}
+
+/**
+ * 向 Runtime 提供本次装配可用的模型端点。
+ *
+ * @remarks
+ * Provider Plugin 贡献它，Builder 在提交前校验，Pi Adapter 在激活与每次解析模型时读取。
+ *
+ * Runtime 只依赖已解析结果，不知道环境变量或业务模型配置的来源。
+ */
+export interface RuntimeProviderPort {
+  endpoints: readonly RuntimeModelEndpoint[];
+  /** First configured model; used by auxiliary consumers and legacy fallback. */
+  defaultModel: string;
+}
+
+/**
+ * 向 Runtime 提供 Cloudflare 执行平台上的可授权能力。
+ *
+ * @remarks
+ * Platform Plugin 贡献它，Workspace Codemode、Browser 工具、遥测和工具门卫按需使用。
+ *
+ * Worker Loader 与网络出口由 Host 选择，使 Dynamic Worker 只获得已授权绑定；术语见 `../index.ts`。
+ */
+export interface RuntimePlatformPort {
+  /** Workspace Codemode 在创建 Dynamic Worker 执行器时使用的 Worker Loader。 */
+  loader: WorkerLoader;
+  /** Platform Plugin 存在 Browser Run 绑定时用它生成浏览器工具。 */
+  browser?: RuntimeBrowserPort;
+  /**
+   * 为一次 Dynamic Worker 组装取得已限定的网络出口。
+   *
+   * @remarks
+   * Workspace Plugin 创建 Codemode 工具时调用，并把返回的 `Fetcher` 交给 `DynamicWorkerExecutor`。
+   *
+   * 出口由 Host 通过 Service Binding 等平台边界控制，不使用无约束的 Runtime 全局网络能力。
+   */
+  outbound: () => Fetcher;
+  telemetryConsole?: boolean;
+  /**
+   * 在 Pi 工具真正执行前请 Host 审查本次调用。
+   *
+   * @remarks
+   * Pi 执行器包装每个工具候选时调用，Host 可根据名称、输入、执行档位与取消信号拒绝。
+   *
+   * 门卫留在 Host，因为它依赖本次调用的应用策略，不能被静态工具可见性取代。
+   */
+  gateTool?(request: {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    requiredExecutionLevel: ExecutionLevel;
+    signal: AbortSignal;
+  }): Promise<void>;
+}
+
+/**
+ * 汇总本次装配已授权的 Skill 来源。
+ *
+ * @remarks
+ * Builder 在生成候选 Snapshot 时创建，Pi 组装在生成 Skill 工具时读取。
+ *
+ * catalog、来源与脚本策略一起保留，避免装配期访问来源或让授权在 Skill 之间漂移。
+ */
+export interface RuntimeSkillBindings {
+  /** Already-authorized external sources and their isolated script policy. */
+  sources: readonly RuntimeSkillSourceBinding[];
+}
+
+/**
+ * 限定一个 Skill 脚本可使用的网络、Workspace 和工具。
+ *
+ * @remarks
+ * Skill Plugin 在贡献来源时设置，Pi Skill 工具在决定是否注入脚本执行能力时读取。
+ *
+ * 这是已授权结果，执行期不应为某个 Skill 自动放宽。
+ */
+export interface RuntimeSkillScriptPolicy {
+  network: "none" | "full";
+  workspace: "none" | "read" | "read-write";
+  tools: readonly string[];
+}
+
+/**
+ * 把一个已授权 Skill 来源与其脚本策略绑定。
+ *
+ * @remarks
+ * Builder 为每个 Skill 贡献创建，Pi 组装和 Skill 工具按名称查找并读取。
+ *
+ * 名称、内容来源与权限不分开存放，防止脚本改用其他 Skill 的授权。
+ */
+export interface RuntimeSkillSourceBinding {
+  name: string;
+  /** Persisted catalog text used without loading the remote Skill source. */
+  description: string;
+  source: SkillSource;
+  script: RuntimeSkillScriptPolicy;
+}
+
+/**
+ * 汇总当前 Runtime Snapshot 已选中的外部依赖。
+ *
+ * @remarks
+ * Builder 在候选装配通过校验后创建，Runtime 和 Pi Adapter 在 Snapshot 生效期间读取。
+ *
+ * 它不携带业务 ID、Repository、数据库 Key、任意能力注册表或凭据配置；术语见 `../index.ts`。
+ */
+export interface RuntimeBindings {
+  provider: RuntimeProviderPort;
+  platform: RuntimePlatformPort;
+  workspace?: WorkspacePort;
+  memory?: RuntimeMemoryPort;
+  skills: RuntimeSkillBindings;
+  turnEvents?: RuntimeTurnEventsPort;
+}
+
+// #endregion