@springbrand/agent-runtime 0.1.0

package/src/kernel/degradation.ts

@@ -0,0 +1,15 @@
+/**
+ * 记录某项可选 Runtime 能力为什么没有启用。
+ *
+ * @remarks
+ * Plugin 在装配可选能力失败但整体仍可运行时报告它，调用方可从最终 Snapshot 读取诊断。
+ *
+ * 必需能力不能走这个通道，而应直接让装配失败，否则会提交一个不能正常工作的 Runtime。
+ *
+ * `Plugin`、`Snapshot` 与 `degradation` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeDegradation {
+  readonly capability: string;
+  readonly reason: string;
+  readonly detail?: string;
+}

package/src/kernel/extensions.ts

@@ -0,0 +1,108 @@
+/**
+ * 声明一个 Runtime Extension 可以访问的外部能力。
+ *
+ * @remarks
+ * Host 在资源装配时生成它，Extension 加载器在创建执行隔离环境前读取。
+ *
+ * 权限与 manifest 一起传入，让未声明的网络、工作区、上下文或会话访问默认不可用。
+ *
+ * `Runtime` 与 `Host` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeExtensionPermissions {
+  readonly network?: readonly string[];
+  readonly workspace?: "read" | "read-write" | "none";
+  readonly context?: {
+    readonly read?: readonly string[] | "all";
+    readonly write?: readonly string[] | "own";
+  };
+  readonly messages?: "none" | "read";
+  readonly session?: {
+    readonly sendMessage?: boolean;
+    readonly metadata?: boolean;
+  };
+}
+
+/**
+ * 描述 Extension 想向模型上下文贡献的一个内容块。
+ *
+ * @remarks
+ * Extension 作者在 manifest 中声明，Pi 装配在 Extension 通过发布、启用和授权筛选后读取。
+ *
+ * 字段保持为纯数据，便于 Host 在运行 Extension 代码前完成校验和预算分配。
+ *
+ * `Host` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeExtensionContextDefinition {
+  readonly label: string;
+  readonly description?: string;
+  readonly type: "readonly" | "writable" | "skill" | "searchable";
+  readonly maxTokens?: number;
+}
+
+/**
+ * 把 Extension 的 manifest 与待加载源码放在同一份配置里。
+ *
+ * @remarks
+ * extension Plugin 在贡献阶段提供它，Pi Extension 适配器在候选 Runtime 装配时加载。
+ *
+ * manifest 与源码一起传递，可避免授权信息与实际执行代码在不同查找步骤中错位。
+ *
+ * `Plugin` 与 `Runtime` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeExtensionConfig {
+  readonly manifest: {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string;
+    readonly permissions?: RuntimeExtensionPermissions;
+    readonly context?: readonly RuntimeExtensionContextDefinition[];
+  };
+  readonly source: string;
+}
+
+/**
+ * 描述一个已加载 Extension 向模型暴露的 Tool。
+ *
+ * @remarks
+ * Extension 加载器在发现阶段生成，Pi 装配器用它构造最终的模型 Tool 候选。
+ *
+ * 描述与执行分开，让装配可以先校验全部 Tool，再对实际调用开放权限。
+ *
+ * `Tool` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeExtensionToolDescriptor {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: {
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly required?: readonly string[];
+  };
+}
+
+/**
+ * 提供已校验 Extension 的 Tool 目录和统一执行入口。
+ *
+ * @remarks
+ * Pi 装配器在加载 Extension 后使用它，先枚举 `tools`，再在模型真正选中 Tool 时调用 `execute`。
+ *
+ * 目录和执行句柄共享同一个加载结果，避免展示的 Tool 与实际可执行 Tool 来自不同版本。
+ *
+ * `Tool` 等核心术语见 `../index.ts`。
+ */
+export interface LoadedRuntimeExtension {
+  readonly tools: readonly RuntimeExtensionToolDescriptor[];
+  /**
+   * 执行目录中指定的 Extension Tool。
+   *
+   * @remarks
+   * Pi Tool 适配器在模型已选中 Tool 并完成审批后调用，并应传入当前 Turn 的取消信号。
+   *
+   * 所有 Extension 调用共用这一入口，使未知 Tool 校验和执行隔离不会被调用方绕过。
+   */
+  execute(
+    toolName: string,
+    args: Readonly<Record<string, unknown>>,
+    signal?: AbortSignal,
+  ): Promise<unknown>;
+}

package/src/kernel/profile.ts

@@ -0,0 +1,116 @@
+import type { ExecutionLevel } from "../lib/execution-level";
+
+/**
+ * 指定模型在一次 Turn 中可以使用的推理强度。
+ *
+ * @remarks
+ * Host 在组装 Profile 时选择它，Runtime Adapter 在发起模型请求时使用该值。
+ *
+ * 这里保留受支持值的联合类型，让错误配置在进入模型适配层前就能被类型检查发现。
+ *
+ * `Profile` 与 `Host` 等核心术语见 `../index.ts`。
+ */
+export type ThinkingEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+
+/**
+ * 保存一次装配选定的内存开关与上下文预算。
+ *
+ * @remarks
+ * memory Plugin 在贡献阶段提供它，Runtime 在构建上下文和触发压缩时读取。
+ *
+ * 预算与开关放在同一个 Profile 中，确保一次 Snapshot 只使用一套内存配置。
+ *
+ * `Plugin`、`Profile` 与 `Snapshot` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeMemoryProfile {
+  enabled: boolean;
+  memoryTokens: number;
+  preferencesTokens: number;
+  compactAfterTokens: number;
+}
+
+/**
+ * 指明本次装配允许连接的一个 MCP 服务。
+ *
+ * @remarks
+ * connector Plugin 在贡献阶段加入它，Pi 工具装配只选择 Host 已就绪且 URL 匹配的连接。
+ *
+ * 这里只保留名称和 URL；连接生命周期、凭据与重试仍由 Host 管理。
+ *
+ * `Plugin` 与 `Host` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeMcpServer {
+  name: string;
+  url: string;
+}
+
+/**
+ * Turn 期唯一还需要执行的能力筛选：拒绝清单。
+ *
+ * @remarks
+ * 「这个 Agent 有没有某个能力」在装配期就已经决定完了 —— Host Action 由
+ * `decideHostActions` 挑选后才注入，Workspace、Skill、MCP、Extension 各自由
+ * 自己的绑定决定。到了 Turn 期唯一还要做的事，就是把 `deny` 里点名的东西减掉。
+ *
+ * 这也是它只剩一个字段的原因：能表达「全集减法」的复杂策略对象，是判断时机
+ * 太晚的产物，不是需求本身。
+ *
+ * `Turn` 与 `Host Action` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeDenyPolicy {
+  deny: readonly string[];
+}
+
+/**
+ * 保存一次装配中真正会影响执行的参数。
+ *
+ * @remarks
+ * `RuntimeBuilder` 在所有 Plugin 贡献完成后生成它，Kernel 只通过已提交的 Snapshot 读取。
+ *
+ * 它不包含业务身份、归属键或存储地址，因为这些选择属于 Host，不应被冻结成执行参数。
+ *
+ * `RuntimeBuilder`、`Plugin`、`Kernel`、`Snapshot` 与 `Host` 等核心术语见 `../index.ts`。
+ */
+export interface RuntimeProfile {
+  model: string;
+  thinking: ThinkingEffort;
+  systemPrompt?: string;
+  denyPolicy?: RuntimeDenyPolicy;
+  enabledSubagents: readonly string[];
+  mcpServers: readonly RuntimeMcpServer[];
+  enabledExtensions: readonly string[];
+  executionLevel: ExecutionLevel;
+  memory: RuntimeMemoryProfile;
+}
+
+/**
+ * 复制并冻结 Profile，使本次装配的执行选择不再被改写。
+ *
+ * @remarks
+ * `RuntimeBuilder.build()` 在创建候选 Snapshot 时调用；调用方应继续使用返回值，不要再持有传入的可变数组。
+ *
+ * 实现会复制并冻结所有嵌套数组及配置对象，避免 Plugin 在提交后通过原始引用改动 Snapshot。
+ *
+ * `RuntimeBuilder`、`Plugin` 与 `Snapshot` 等核心术语见 `../index.ts`。
+ */
+export function freezeRuntimeProfile(profile: RuntimeProfile): RuntimeProfile {
+  const frozen: RuntimeProfile = {
+    ...profile,
+    denyPolicy: profile.denyPolicy
+      ? Object.freeze({
+          deny: Object.freeze([...profile.denyPolicy.deny]),
+        })
+      : undefined,
+    enabledSubagents: Object.freeze([...profile.enabledSubagents]),
+    mcpServers: Object.freeze(profile.mcpServers.map((server) => Object.freeze({ ...server }))),
+    enabledExtensions: Object.freeze([...profile.enabledExtensions]),
+    memory: Object.freeze({ ...profile.memory }),
+  };
+  return Object.freeze(frozen);
+}

package/src/kernel/public-contracts.ts

@@ -0,0 +1,17 @@
+/**
+ * 汇总浏览器与 Worker 可以安全共享的数据契约。
+ *
+ * @remarks
+ * 前端或跨边界代码应从这个入口导入 Profile、消息、回执和公开状态类型，不要依赖 Runtime 的内部模块。
+ *
+ * 单独保留这个入口，是为了让共享 DTO 与只能在服务端运行的实现保持明确边界。
+ *
+ * 核心术语见 `../index.ts`。
+ *
+ * @packageDocumentation
+ */
+export * from "./profile";
+export * from "../pi/message";
+export * from "./receipts";
+export * from "./state";
+export * from "../lib/execution-level";

package/src/kernel/receipts.ts

@@ -0,0 +1,124 @@
+import type { UIMessage } from "ai";
+import type { ExecutionLevel } from "../lib/execution-level";
+
+export type ApprovalDecision =
+  | { decision: "deny"; reason?: string }
+  | { decision: "allow_once" }
+  | { decision: "allow_level" };
+
+export const APPROVAL_DECISIONS = [
+  "deny",
+  "allow_once",
+  "allow_level",
+] as const satisfies readonly ApprovalDecision["decision"][];
+
+/**
+ * 记录一次待审批 Tool 执行的身份、摘要和原始输入。
+ *
+ * @remarks
+ * Turn 审批逻辑在请求用户决定前生成，审批生命周期会按 `requestId` 存储、查询和消费。
+ *
+ * 回执保留当时的输入与风险，使后续决定针对的是原请求，而不是可能已变的当前配置。
+ *
+ * `Turn` 与 `Tool` 等核心术语见 `../index.ts`。
+ */
+export interface ApprovalReceipt {
+  executionId: string;
+  source: "action" | "codemode" | "temporary-agent";
+  action: string;
+  summary: string;
+  executionLevel: ExecutionLevel;
+  requiredExecutionLevel: ExecutionLevel;
+  inputJson: string;
+  requestId: string;
+}
+
+/**
+ * 定时到点后要做的事。
+ *
+ * @remarks
+ * schedule Tool 或定时 API 在创建任务时提供，Scheduler 在到点后读取并分派。
+ *
+ * `prompt` 用当前用户的默认 Agent 跑；`agent` 指定由哪个 User Agent 跑。
+ *
+ * 两者的 prompt 都必须自包含，因为触发时会在独立会话中执行，不会携带创建它的那段对话上下文。
+ */
+export type ScheduleJob =
+  | { kind: "prompt"; prompt: string }
+  | { kind: "agent"; userAgentId: string; prompt: string };
+
+/**
+ * 定义一个定时任务的触发条件和到点工作。
+ *
+ * @remarks
+ * schedule Tool 或 Worker API 创建它，Scheduler 会校验后持久化，并计算下一次触发时间。
+ *
+ * 触发条件与工作放在同一份规格里，使更新时可以原地替换两者，不用改变任务标识。
+ */
+export interface ScheduleSpec {
+  trigger:
+    | { kind: "once-at"; at: string }
+    | { kind: "once-in"; seconds: number }
+    | { kind: "cron"; cron: string }
+    | { kind: "interval"; seconds: number };
+  job: ScheduleJob;
+  label?: string;
+  /**
+   * cron 里的钟点按哪个时区解释(IANA 名,如 `Asia/Shanghai`)。
+   * 缺省为 `UTC` —— 与 Cloudflare Cron Triggers 按 UTC 执行的语义一致,但对人来说几乎总是错的,
+   * 所以创建入口都应显式带上用户所在时区。
+   */
+  tz?: string;
+}
+
+/**
+ * 返回一次异步提交的当前接收与完成状态。
+ *
+ * @remarks
+ * Runtime 在接收提交时创建，Inbox RPC 和 HTTP API 在创建后或轮询时返回给调用方。
+ *
+ * 接收状态与最终结果共用同一个 `submissionId`，使调用方无需依赖长连接也能查询。
+ *
+ * `Runtime` 等核心术语见 `../index.ts`。
+ */
+export interface SubmissionReceipt {
+  submissionId: string;
+  status: string;
+  accepted: boolean;
+  error?: string;
+  createdAt: number;
+  completedAt?: number;
+}
+
+/** Shared discriminator keeps the Stop control and durable transcript semantics aligned. */
+export const USER_STOP_REASON = "Stopped by user";
+
+export type MessageDelivery = "steer" | "enqueue";
+
+export type MessageDispatchErrorCode =
+  | "queue_full"
+  | "not_steerable"
+  | "invalid_message";
+
+export type MessageDispatchReceipt =
+  | {
+      kind: "accepted";
+      submissionId: string;
+      messageId: string;
+    }
+  | {
+      kind: "steered";
+      submissionId: string;
+      messageId: string;
+      message?: UIMessage;
+    }
+  | {
+      kind: "queued";
+      submission: SubmissionReceipt;
+      position: number;
+    }
+  | {
+      kind: "rejected";
+      code: MessageDispatchErrorCode;
+      message: string;
+    };