@adep/types 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @adep/types — AgentDeploy 用户 SDK 类型契约
+
+> **纯类型包**：零运行时代码、无运行时依赖，只提供类型定义（任务单 CORE-006）。
+
+`@adep/types` 定义 AgentDeploy **云函数侧**统一的能力契约：函数上下文 `ctx`、`cloud` 挂载点以及数据库 / 存储 / 请求 / 实时等能力接口。它是平台与函数代码之间的「SDK 契约层」——FN 域实现 Provider，ST / DB 域注册 Consumer，三方只依赖这里的类型，互不 import 内部实现。
+
+```bash
+npm install -D @adep/types
+# 或
+pnpm add -D @adep/types
+```
+
+## 包含哪些契约
+
+| 模块              | 说明                                                                                     |
+| ----------------- | ---------------------------------------------------------------------------------------- |
+| `FunctionContext` | 云函数处理函数上下文（`ctx.params/query/body/headers/...`）                              |
+| `CloudContainer`  | `cloud` 挂载点容器：`cloud.db()` / `cloud.storage()` / `cloud.fetch()` / `cloud.chain()` |
+| `CloudDb`         | 数据库能力：`table()` / `query()` / `raw()` 等                                           |
+| `CloudStorage`    | 文件存储能力：`put()` / `get()` / `list()` / `signURL()` 等                              |
+| `CloudFetch`      | HTTP 请求能力：`get()` / `post()` 等                                                     |
+| `Harness`         | Web 组件（widget）在宿主中的挂载 / 卸载契约                                              |
+
+## 用法
+
+```ts
+import type { FunctionContext, CloudContainer } from '@adep/types'
+
+export default async function handler(ctx: FunctionContext) {
+  const db = (ctx.cloud as CloudContainer).db()
+  const row = await db.get('users', ctx.params.id)
+  return { ok: true, row }
+}
+```
+
+## 说明
+
+- 该包 `sideEffects: false`，可安全 tree-shake；类型测试用「import 后无值导出」钉死其纯类型属性。
+- 本包不负责运行时实现，运行时代码在 `@adep/runtime`。

package/dist/cloud-chain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 链式命令通道契约（CORE-018 上移自 functions/runtime/chain.ts，DB-003 能力运输扩展）。
+ *
+ * `cloud.storage` 的平坦式 RPC 客户端是「单方法调用」；`cloud.db` 是**链式** API——
+ * 一次终值调用要带走整条链的累积状态。本文件只含跨域共享的**纯类型**；
+ * 运行时键常量（`CHAIN_CAPABILITY_KEY` / `DB_RPC` / `RPC_CAPABILITY_KEY`）在 `shared/capability-keys`，
+ * worker 侧构造客户端 (`createChainClient`) 仍在 functions 域（worker 专属实现，非共享契约）。
+ */
+/** 链式能力的抽象规格：由宿主能力方（DB 域）装配，FN 只按规格构造客户端。 */
+export interface ChainSpec {
+    readonly kind: string;
+    /** 开启一条链的根方法名（如 `table`）；其参数作为 `rootArgs`（如表名）。 */
+    readonly rootMethod: string;
+    /** 累加链步骤的方法名集合（链式、不可变；如 select/where/orderBy/limit/offset）。 */
+    readonly stepMethods: readonly string[];
+    /** 终值方法名集合（触发一次 `DB_RPC.chain`；如 get/first/count/insert/…）。 */
+    readonly terminalMethods: readonly string[];
+    /** 直通方法名集合（不累积，方法名即传输码；如 `query`）。 */
+    readonly directMethods: readonly string[];
+    /** 事务方法名（如 `transaction`）：begin → 回调(tx) → commit，抛错回滚。 */
+    readonly transactionMethod: string;
+}
+/** 链中一步（不可变：每次 step 方法调用返回新链，克隆累积）。 */
+export interface ChainStep {
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+/** 一次终值调用的传输载荷：根参数 + 步骤累积 + 终值方法与参数（事务链带 txId）。 */
+export interface ChainRequest {
+    readonly rootArgs: readonly unknown[];
+    readonly steps: readonly ChainStep[];
+    readonly terminal: string;
+    readonly terminalArgs: readonly unknown[];
+    readonly txId?: string;
+}

package/dist/cloud-container.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `cloud` 挂载点契约（规范 §4.5 三件套的 Definition 层，任务单 CORE-006）。
+ *
+ * - **Provider（容器）**：FN-002 在 FunctionContext 上创建并暴露 `register()`，不感知任何具体能力；
+ * - **Consumer（能力注册方）**：ST-001 注册 `storage`、DB-003 注册 `db`（M3 起 RT 域注册 `realtime`）；
+ * - 三方只依赖本文件类型，禁止互相 import 内部实现。
+ *
+ * 新增能力 = 在 `CapabilityRegistry` 加一行 + `Cloud` 上用户即可获得补全——这是能力名的唯一登记处。
+ * 访问未注册的能力在**运行时**必须抛带可操作提示的错误（如 `DB_NOT_PROVISIONED`），
+ * 禁止返回 undefined（§4.5 硬规则 3）；类型侧不表达"未注册"，实现方负责。
+ */
+import type { CloudDb } from './cloud-db';
+import type { CloudStorage } from './cloud-storage';
+import type { CloudFetch } from './cloud-fetch';
+/** 已注册能力名 → 实现契约的映射。M3 起追加 `realtime: CloudRealtime`（规范 §4.5）。 */
+export interface CapabilityRegistry {
+    db: CloudDb;
+    storage: CloudStorage;
+    /**
+     * 沙箱受控网络（GAME-007）：未配置 `FUNCTIONS_FETCH_ALLOWLIST` 时不注入（无网络安全默认）。
+     * 注入时仅可访问白名单主机，受超时与响应体上限约束。
+     */
+    fetch: CloudFetch;
+}
+/**
+ * 用户函数侧的 `ctx.cloud`：只能**访问**能力，不能注册/注销（那是 Provider/Consumer 的特权）。
+ * 已知能力有精确类型补全；自定义能力经索引签名访问（运行时未注册即抛错）。
+ */
+export type Cloud = {
+    readonly [K in keyof CapabilityRegistry]: CapabilityRegistry[K];
+} & {
+    readonly [capability: string]: unknown;
+};
+/**
+ * Provider/Consumer 共享的注册面。
+ *
+ * `register` 是单泛型方法而非重载：已知能力名（`CapabilityRegistry` 的键）的实现类型**必须精确匹配**，
+ * 传错实现编译期即报错（`NoInfer` 阻止 TS 在匹配失败时把 K 回退放宽成 string——否则守卫形同虚设）；
+ * 未知能力名（如 FN-002 验收用的 `'test'`）放宽为 unknown。
+ * 注册必须可逆：Consumer 在插件 `apply` 里经 `ctx.effect()` 注册、disposer 里 `unregister`（§4.5 硬规则 2）。
+ */
+export interface CloudContainer {
+    register<K extends string>(name: K, impl: NoInfer<K extends keyof CapabilityRegistry ? CapabilityRegistry[K] : unknown>): void;
+    unregister(name: string): void;
+}

package/dist/cloud-db.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `cloud.db` 契约（CORE-006 定义骨架；真实实现在 DB-002 查询构建器 + DB-003 注入）。
+ *
+ * 设计依据 DB-002 / PRD §2.7.3 / ADR-0006：项目数据库的表是**运行时**创建的，编译期不存在，
+ * 因此这里没有表级泛型——行一律是 `Row`（Record<string, unknown>），用户自行断言列类型。
+ * 链式方法全部返回 `CloudDbTable`（ Builder 本身），这是 CORE-006 类型测试钉死的关键签名。
+ *
+ * 安全语义（由实现保证，类型侧标注意图）：值全部参数化绑定；标识符白名单；
+ * `update` / `delete` 不带 `where` 直接抛 `DB_UNSAFE_OP`（DB-002 安全硬约束）。
+ */
+/** 可绑定到 SQLite 的参数值。 */
+export type SqlValue = string | number | bigint | boolean | null | Uint8Array;
+/** `where(col, op, value)` 支持的比较符。 */
+export type SqlOperator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'like' | 'in' | 'not in';
+/** 一行查询结果。列类型编译期未知（运行时建表），由用户代码自行收窄。 */
+export type Row = Record<string, unknown>;
+/** owned 表变更操作类型。 */
+export type ChangeOp = 'insert' | 'update' | 'delete';
+/** owned 表 `__changes` 变更流记录（追加式、可重放；before/after 为整行，未涉及侧为 null）。 */
+export interface ChangeRecord {
+    /** 表内自增序号（时间升序，重放顺序依据）。 */
+    seq: number;
+    /** 变更时间（ISO 8601）。 */
+    ts: string;
+    op: ChangeOp;
+    /** 行主键（ULID）。 */
+    id: string;
+    /** 行归属分区（null = 未归属）。 */
+    ownerKey: string | null;
+    /** 变更前整行（insert 为 null）。 */
+    before: Row | null;
+    /** 变更后整行（delete 为 null）。 */
+    after: Row | null;
+}
+/** `cloud.db.changes(table, query)` 的过滤条件（全部可选）。 */
+export interface ChangeQuery {
+    /** 只取 `seq > afterSeq`（增量拉取 / 收件批次）。 */
+    afterSeq?: number;
+    /** 只取某分区行；`null` = 只取未归属行（缺省不过滤）。 */
+    ownerKey?: string | null;
+    /** 最多返回条数（配合 afterSeq 做分页）。 */
+    limit?: number;
+}
+/**
+ * 单表链式 Builder。所有链式方法返回新 Builder（不可变），终值方法（get/first/count/insert/update/delete）
+ * 返回 Promise。复用同一 Builder 实例派生多个查询是安全的（实现不得有共享可变状态）。
+ */
+export interface CloudDbTable {
+    /** 限定返回列；不调即 `select *`。 */
+    select(...columns: string[]): CloudDbTable;
+    /**
+     * 声明为 owned 表（DB-006）：写入自动生成 ULID 主键 + 追加 `__changes` 变更流。
+     * 表须已声明 owned（存在 `_adep_changes_<table>` 变更流表），否则抛 `DB_UNSAFE_OP`。
+     */
+    owned(): CloudDbTable;
+    /** 等值过滤：`where('status', 'active')`。 */
+    where(column: string, value: SqlValue): CloudDbTable;
+    /** 带操作符过滤：`where('age', '>', 18)`。 */
+    where(column: string, operator: SqlOperator, value: SqlValue | readonly SqlValue[]): CloudDbTable;
+    orderBy(column: string, direction?: 'asc' | 'desc'): CloudDbTable;
+    limit(n: number): CloudDbTable;
+    offset(n: number): CloudDbTable;
+    /** 结果数组（可能为空）。 */
+    get(): Promise<Row[]>;
+    /** 首行或 null。 */
+    first(): Promise<Row | null>;
+    /** 行数（忽略 select/orderBy）。 */
+    count(): Promise<number>;
+    /** 插入一行；`where` 对插入无意义，实现应忽略或拒绝。 */
+    insert(row: Record<string, SqlValue>): Promise<void>;
+    /** 批量插入。 */
+    insertMany(rows: ReadonlyArray<Record<string, SqlValue>>): Promise<void>;
+    /** 更新（必须先 `where`，否则 `DB_UNSAFE_OP`）；返回受影响行数。 */
+    update(values: Record<string, SqlValue>): Promise<number>;
+    /** 删除（必须先 `where`，否则 `DB_UNSAFE_OP`）；返回受影响行数。 */
+    delete(): Promise<number>;
+}
+/**
+ * 项目数据库句柄。句柄必须闭包封装：不得暴露连接串、schema 名（§4.5 硬规则 4）。
+ */
+export interface CloudDb {
+    /** 打开单表 Builder。表名由运行时白名单校验（`^[a-zA-Z_][a-zA-Z0-9_]{0,62}$`）。 */
+    table(name: string): CloudDbTable;
+    /**
+     * 事务：fn 收到同形状的受控事务句柄；抛错即整体回滚。
+     * 事务内禁止 `await` 事务外的本库操作（实现可检测并拒绝）。
+     */
+    transaction<T>(fn: (tx: CloudDb) => Promise<T>): Promise<T>;
+    /** 受控裸 SQL；`params` 必填（无参传 `[]`），单语句，禁多语句堆叠。 */
+    query(sql: string, params: readonly SqlValue[]): Promise<Row[]>;
+    /**
+     * 读取 owned 表 `__changes` 变更流（按 seq 升序，可重放）。表非 owned → `DB_UNSAFE_OP`。
+     * `afterSeq` / `ownerKey` / `limit` 过滤条件参数化绑定。
+     */
+    changes(table: string, query?: ChangeQuery): Promise<ChangeRecord[]>;
+}

package/dist/cloud-fetch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `cloud.fetch` 用户 SDK 契约（GAME-007 前置平台能力）。
+ *
+ * 平台函数沙箱默认无网络（FN-002 隔离）。本能力为**受控 fetch**：
+ * 仅可访问部署配置允许的主机（`FUNCTIONS_FETCH_ALLOWLIST` 域名白名单），
+ * 单次请求受超时（`FUNCTIONS_FETCH_TIMEOUT_MS`）与响应体上限约束；
+ * 未配置白名单 = 不注入，沙箱保持无网络默认。
+ *
+ * 用户函数侧发起 HTTPS 请求（如 npm-relay 直连 registry）返回结构化响应，
+ * 文本/JSON/二进制读取与标准 fetch 等价。命中白名单/超时/体上限违规时
+ * 抛 `cloud.fetch` 专用错误（`FN_FETCH_FORBIDDEN` / `FN_FETCH_TIMEOUT` / `FN_FETCH_TOO_LARGE`）。
+ */
+/** `cloud.fetch` 请求选项（受控子集，`body` 限制为字符串/JSON，二进制上传不在本能力范围）。 */
+export interface CloudFetchInit {
+    method?: string;
+    /** 请求头（小写化后逐条透传）。 */
+    headers?: Record<string, string>;
+    body?: string;
+    /** 调用方中止信号（与平台超时叠加，二者任一触发即中止）。 */
+    signal?: AbortSignal;
+}
+/** `cloud.fetch` 的结构化响应（文本/JSON/二进制读取受响应体上限约束）。 */
+export interface CloudFetchResponse {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    /** 归一化响应头（键小写）。 */
+    headers: Record<string, string>;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** `cloud.fetch`：受控的 HTTPS 请求。URL 主机不在白名单则抛 `FN_FETCH_FORBIDDEN`。 */
+export type CloudFetch = (url: string, init?: CloudFetchInit) => Promise<CloudFetchResponse>;

package/dist/cloud-storage.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `cloud.storage` 契约（CORE-006 定义骨架；真实实现在 ST-001，经 `cloud.register('storage', impl)` 注入）。
+ *
+ * 依据 ST-001 / PRD §2.4：项目级桶、三级访问控制（M1：private 签名 URL 15 分钟 / public 直连）、
+ * 配额 1GB/项目。路径一律是项目桶内相对路径（禁止 `../` 穿越，由实现拒绝）。
+ */
+/** 上传数据：文本、二进制、或直接透传请求里的文件对象（PRD §2.1.3 示例的用法）。 */
+export type StorageUploadData = string | Uint8Array | ArrayBuffer | FunctionFile;
+export type FileVisibility = 'public' | 'private';
+/** 上传 / 列举返回的文件元数据（不含内容）。 */
+export interface StoredFile {
+    /** 桶内相对路径，如 `avatars/avatar.png`。 */
+    readonly path: string;
+    readonly size: number;
+    readonly contentType?: string;
+    readonly visibility: FileVisibility;
+    /** ISO 8601 时间戳。 */
+    readonly updatedAt?: string;
+}
+/** 函数 HTTP 触发时 `ctx.files` 里的单个上传文件（multipart 解析产物）。 */
+export interface FunctionFile {
+    /** 客户端提供的文件名（含扩展名）。 */
+    readonly name: string;
+    /** MIME 类型。 */
+    readonly type: string;
+    /** 字节数。 */
+    readonly size: number;
+    readonly data: Uint8Array;
+}
+export interface CloudStorage {
+    /** 上传 / 覆盖文件；路径非法（穿越、超限）由实现抛错。 */
+    upload(path: string, data: StorageUploadData): Promise<StoredFile>;
+    /** 读取文件内容；不存在时抛 `STORAGE_NOT_FOUND`。 */
+    get(path: string): Promise<Uint8Array>;
+    /** 删除文件；不存在时抛 `STORAGE_NOT_FOUND`。 */
+    remove(path: string): Promise<void>;
+    /** 按前缀列举（缺省全桶）。 */
+    list(prefix?: string): Promise<StoredFile[]>;
+    /** 生成签名 URL（private 文件的外发通道）；缺省 TTL 由实现定（M1：15 分钟）。 */
+    getSignedUrl(path: string, ttlSeconds?: number): Promise<string>;
+}

package/dist/function-context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 用户云函数的执行上下文（CORE-006 定义骨架；注入实现在 FN-002）。
+ *
+ * `body` 是 `unknown`：函数签名编译期不可知（OpenAPI 推导走 FN-006 的运行时推导），
+ * 用户用类型断言收窄——PRD §2.1.3 的示例 `ctx.body as { name: string }` 即为此约定。
+ */
+import type { Cloud } from './cloud-container';
+import type { FunctionFile } from './cloud-storage';
+import type { ExecutorUser } from './function-executor';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+export interface FunctionContext {
+    /** 请求方法。 */
+    readonly method: HttpMethod;
+    /** 触发路径（不含 host），如 `/hello`。 */
+    readonly path: string;
+    /** 解析后的 query；同名多值收为数组。 */
+    readonly query: Readonly<Record<string, string | readonly string[]>>;
+    /** 请求头（键为小写）。 */
+    readonly headers: Readonly<Record<string, string>>;
+    /** 请求体；形状由用户用类型断言收窄（PRD §2.1.3 示例即 `ctx.body as {...}`）。 */
+    readonly body: unknown;
+    /** multipart 上传的文件（无文件时为空数组）。 */
+    readonly files: readonly FunctionFile[];
+    /** 平台能力挂载点：`cloud.db` / `cloud.storage`（M3 起 `cloud.realtime`）。 */
+    readonly cloud: Cloud;
+    /**
+     * 调用者身份投影（FN-010）：网关解析会话后注入；`null` = 匿名 / 未注入。
+     * 函数据此自行做成员 / 权限判断（身份是透传信息，不是强制门）。
+     */
+    readonly user: ExecutorUser | null;
+}

package/dist/function-executor.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 函数执行器契约（CORE-018 上移自 functions 域）。
+ *
+ * 被 gateway / functions / storage / database / realtime / mcp 多域共享的执行契约：
+ * Platform 侧平台域插件按本项目产出能力 bundle，经组合根注入执行链路；
+ * mcp / realtime 消费同一 `FunctionExecutor` 接口，不新建运行时。
+ *
+ * 纯类型文件，零运行时代码（规范 §4.5 / CORE-006 纯类型包约束）；
+ * 运行时部分（ExecutorError / 能力键常量）在 `shared/`，见 function-executor-runtime。
+ */
+/** 一次执行的项目投影（网关 / HTTP 触发器构造；函数不可见原始 Request）。 */
+export interface ExecutorProject {
+    id: string;
+    slug: string;
+}
+/** 被执行的函数投影。 */
+export interface ExecutorFunction {
+    id: string;
+    name: string;
+}
+/**
+ * 执行者身份投影（FN-010 auth-in-function）：网关解析会话后注入调用者身份。
+ * 缺省 / 匿名 / 未接解析器时，`ExecutorRequest.user` 为 `null`——
+ * 身份是**透传信息**（供函数自行做权限判断），不是强制门，缺身份不阻塞执行。
+ */
+export interface ExecutorUser {
+    /** 平台用户 id（= better-auth session.user.id）。 */
+    id: string;
+    email?: string;
+    name?: string;
+}
+/** 触发请求的平台侧投影（网关 / HTTP 触发器构造；函数不可见原始 Request）。 */
+export interface ExecutorRequest {
+    method: string;
+    path: string;
+    query: Record<string, string | readonly string[]>;
+    headers: Record<string, string>;
+    /** 已解析的 body（JSON / 文本）；非对象原样传入。 */
+    body?: unknown;
+    /** multipart 文件（M1 由 ST-001 前置解析后传入，缺省空）。 */
+    files?: ReadonlyArray<{
+        name: string;
+        type: string;
+        size: number;
+        data: Uint8Array;
+    }>;
+    /** 调用者身份投影（FN-010）；`null` = 匿名 / 未注入，缺省与 `null` 等价。 */
+    user?: ExecutorUser | null;
+}
+/** 可克隆的能力句柄（CORE-006 挂载点）：ST/DB 域经此把能力带进执行环境。 */
+export interface ExecutorCapability {
+    name: string;
+    /**
+     * 可结构化克隆的实现句柄；持有宿主资源的能力由 DB-003/ST-001 以命令通道句柄形式提供。
+     * 若 value 是 RPC 标记（见 `RPC_CAPABILITY_KEY`），worker 侧会把它替换成命令通道客户端，
+     * 调用转发回宿主 `rpcHandlers[name]` 执行（宿主资源不可克隆，见 ST-001 命令通道设计）。
+     */
+    value: unknown;
+}
+/** 宿主侧一次能力调用的执行器；`method` 为能力接口方法名，`args` 为实参。 */
+export type CapabilityRpcHandler = (method: string, args: readonly unknown[]) => Promise<unknown>;
+/**
+ * CORE-006 挂载点 Provider 侧装配产物（ST-001 / DB-003）：一组能力 + 对应宿主 RPC 实现。
+ * 主入口组合根按项目产出一份，经 `ForwardHandlerOptions.capabilities` 传给执行链路。
+ */
+export interface CapabilityBundle {
+    capabilities: readonly ExecutorCapability[];
+    rpcHandlers: Readonly<Record<string, CapabilityRpcHandler>>;
+}
+/** 一次执行的完整入参（网关 HTTP / mcp tools-call / realtime 派发共用同一执行器接口）。 */
+export interface ExecuteInput {
+    project: ExecutorProject;
+    fn: ExecutorFunction;
+    /** 草稿源码（多文件；entry 缺省 index.ts）。 */
+    files: Readonly<Record<string, string>>;
+    entry?: string;
+    request: ExecutorRequest;
+    capabilities?: readonly ExecutorCapability[];
+    /**
+     * 命令通道能力的宿主实现（CORE-006 挂载点 Provider 侧注入）：
+     * 键 = 能力名，值执行 worker 转发来的 `(method, args)` 调用。
+     */
+    rpcHandlers?: Readonly<Record<string, CapabilityRpcHandler>>;
+    /** 执行超时毫秒；缺省 10_000。 */
+    timeoutMs?: number;
+    /** 内存上限 MB；缺省 128（M1 收紧值）。 */
+    memoryLimitMb?: number;
+    /**
+     * 注入执行沙箱的环境变量（CLI-002：`adep dev` 从 `.env.local` 装载后经此通道传入）。
+     * 提供时沙箱内以 `process.env[KEY]` 可见；**缺省不注入**——平台路径不传，
+     * 沙箱保持「process 不可达」的安全默认（与 FN-002 沙箱隔离一致）。
+     */
+    env?: Readonly<Record<string, string>>;
+}
+export interface ExecuteResult {
+    /** 函数返回的值（执行器统一 JSON 序列化）。 */
+    body: unknown;
+    /** 沙箱 console 输出（日志链路 FN-003 起持久化）。 */
+    logs: string[];
+}
+/**
+ * `FunctionExecutor` 接口（FN-002，能力缝 Definition 层）。
+ *
+ * M1 实现 = WorkerFunctionExecutor（worker_threads + vm + 资源限额）；
+ * M6 容器池实现同接口替换（Definition/Provider/Consumer 三件套的 Definition）。
+ */
+export interface FunctionExecutor {
+    execute(input: ExecuteInput): Promise<ExecuteResult>;
+    /** 释放执行器持有的资源（worker 池 / 容器池）。 */
+    dispose(): Promise<void>;
+}

package/dist/harness.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Harness 插件包与 Widget 运行时契约（FE-001，PRD §2.3.2 / §2.3.4）。
+ *
+ * 「能力插件」= 后端函数 + 前端组件的组合包：`plugin.yaml`（清单）+ `functions/` +
+ * `widgets/`（微前端组件 + `manifest.json` props schema）+ `pages/`。
+ * 组件经 Module Federation 暴露为框架无关 ESM；宿主用 `<RemoteWidget name props>` 按需拉取，
+ * React / Vue 异构经 Web Component 桥互相嵌套。`manifest.json` 的 props JSON Schema 同时
+ * 与对应 MCP Tool 返回定义做字段子集契约（见 `contracts/`，`pnpm run test:contracts` 校验）。
+ *
+ * 本文件只做**纯类型声明**（与 CORE-006 对 `packages/types` 的约束一致）：零运行时代码、
+ * 不 import 运行时依赖。DOM、框架（vue/react）运行库一律不在此引用——`HarnessMountHost`
+ * 用最小结构投影，使宿主与单测（Node 环境）都能构造而无需真实 DOM。
+ */
+/** 最小 JSON Schema 子集（仅覆盖 Widget props / Tool output 需要表达能力）。 */
+export interface JsonSchemaNode {
+    type?: string | undefined;
+    properties?: Record<string, JsonSchemaNode> | undefined;
+    required?: string[] | undefined;
+}
+export type WidgetFramework = 'vue3' | 'react';
+/** `widgets/<name>/manifest.json`：单组件的 props schema 与入口。 */
+export interface HarnessWidgetSpec {
+    name: string;
+    framework: WidgetFramework;
+    /** props JSON Schema：与对应 Tool output.schema 做字段子集契约（contracts/）。 */
+    props: JsonSchemaNode;
+    /** 远程模块入口 URL（发布时经 Module Federation 暴露；FE-002 注入具体地址）。 */
+    entry: string;
+}
+export interface HarnessFunctionSpec {
+    name: string;
+    entry: string;
+}
+export interface HarnessPageSpec {
+    route: string;
+    entry: string;
+}
+/** `plugin.yaml`（Harness 插件包清单）解析后的统一形态。 */
+export interface HarnessPlugin {
+    name: string;
+    version: string;
+    functions?: HarnessFunctionSpec[] | undefined;
+    widgets?: HarnessWidgetSpec[] | undefined;
+    pages?: HarnessPageSpec[] | undefined;
+}
+/** Widget 挂载容器的宿主投影。浏览器侧为 `ShadowRoot`（CSS/事件隔离），单测可为 mock。 */
+export interface HarnessMountHost {
+    appendChild(node: unknown): void;
+    removeChild(node: unknown): void;
+}
+/**
+ * Widget 远程模块的运行时契约（Web Component 桥）：
+ * 每个 widget entry 导出 `mount`/`unmount`，宿主校验 props 后把组件挂进 Shadow DOM 隔离容器。
+ * `mount(host, props)` 返回 void 即成同步挂载；异步（如动态 import CSS）可返回 Promise。
+ */
+export interface HarnessWidgetRuntime {
+    readonly __harness: true;
+    mount(host: HarnessMountHost, context: HarnessWidgetContext): void | Promise<void>;
+    unmount(host: HarnessMountHost): void;
+}
+/** 宿主经桥暴露给 Widget 沙箱的**白名单能力**。未在其中的宿主能力不可达（沙箱边界，FE-001 验收 3）。 */
+export interface HarnessHostApi {
+    /** 读取当前项目 id。 */
+    getProjectId(): string;
+    /** 以函数名调用平台云函数（`input` 进函数 `ctx.input`）。命名与 `invokeFunction` 对齐 runtime RPC。 */
+    invokeFunction(name: string, input: unknown): Promise<unknown>;
+}
+/** Widget 挂载时宿主注入的上下文（沙箱 props + 白名单 host api）。 */
+export interface HarnessWidgetContext {
+    widgetName: string;
+    framework: WidgetFramework;
+    props: Record<string, unknown>;
+    host: HarnessHostApi;
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `@adep/types` —— 用户 SDK 类型契约（任务单 CORE-006）。
+ *
+ * 约束（规范 §1、§4.5、CORE-006）：
+ * 1. **纯类型包**：零运行时代码、`dependencies` 为空，本文件只有 `export type`——
+ *    类型测试（`src/__tests__/contract.test.ts`）以「import 后无值导出」钉死这一点；
+ * 2. **`cloud` 挂载点的 Definition 层**：FN 域（Provider，容器）与 ST / DB 域（Consumer，能力注册方）
+ *    三方只依赖这里的类型，禁止互相 import 内部实现（规范 §4.5）。
+ *
+ * 能力名与实现契约的唯一登记处在 `cloud-container.ts` 的 `CapabilityRegistry`；
+ * 新增能力（如 M3 的 `realtime`）在那里加一行即可让用户侧获得补全。
+ * 「平台 API 错误码」是 CORE-001 先行落地的契约，已被 `server/` 与 `packages/cli/` 共用。
+ */
+/** 错误码按域分段（规范 §5）。APP 段归网关/项目路由（CORE-005）。 */
+export type ApiErrorCodePrefix = 'AUTH' | 'FN' | 'MCP' | 'STORAGE' | 'BILLING' | 'DB' | 'APP';
+/**
+ * 平台 API 统一错误码，形如 `FN_NOT_FOUND`。
+ *
+ * 平台级通用码（不按域分段，语义与域无关）：
+ * - `INTERNAL`：5xx，只回传 traceId，不泄露内部细节（规范 §5）；
+ * - `VALIDATION_FAILED`：请求体 / query / params 校验失败；
+ * - `NOT_FOUND`：Elysia 未匹配到任何路由（路由层无法预知该请求属于哪个域）。
+ */
+export type ApiErrorCode = `${ApiErrorCodePrefix}_${string}` | 'INTERNAL' | 'VALIDATION_FAILED' | 'NOT_FOUND';
+export type { CapabilityRegistry, Cloud, CloudContainer } from './cloud-container';
+export type { ChangeOp, ChangeQuery, ChangeRecord, CloudDb, CloudDbTable, Row, SqlOperator, SqlValue, } from './cloud-db';
+export type { ChainRequest, ChainSpec, ChainStep } from './cloud-chain';
+export type { CapabilityBundle, CapabilityRpcHandler, ExecuteInput, ExecuteResult, ExecutorCapability, ExecutorFunction, ExecutorProject, ExecutorRequest, ExecutorUser, FunctionExecutor, } from './function-executor';
+export type { CloudStorage, FileVisibility, FunctionFile, StoredFile, StorageUploadData, } from './cloud-storage';
+export type { CloudFetch, CloudFetchInit, CloudFetchResponse } from './cloud-fetch';
+export type { FunctionContext, HttpMethod } from './function-context';
+export type { SecretScanHit, SecretScanLevel, SecretScanResult, SecretScanRule, } from './secret-scan';
+export type { HarnessPlugin, HarnessWidgetSpec, HarnessFunctionSpec, HarnessPageSpec, HarnessWidgetRuntime, HarnessWidgetContext, HarnessHostApi, HarnessMountHost, JsonSchemaNode, WidgetFramework, } from './harness';
+export type { RealtimeRole, RealtimeTicketClaims, RealtimeClientEvent, RealtimeServerEvent, RealtimeChannelMessage, RealtimeDispatchEvent, RealtimeTriggerHandle, RealtimeMeterSnapshot, PresenceEvent, } from './realtime';
+export type { WebContainer, WebContainerDirectoryTree, WebContainerEventMap, WebContainerFile, WebContainerFsEntry, WebContainerFsEntryType, WebContainerProcess, WebContainerSpawnMethod, WebContainerSpawnOptions, PreviewServerOptions, } from './web-container';

package/dist/realtime.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `@adep/types` 实时通道契约（RT-002 定义骨架；RT-003 起补充派发语义）。
+ *
+ * M3 实时通道（PRD `docs/agent-deploy-platform-prd.md` §2.12）：用户函数 / panel 通过
+ * 单次票据建立的 WebSocket 订阅 channel 并收发消息。这里只放**跨边界交换的类型形状**：
+ * - `RealtimeTicketClaims`：握手票据内嵌的身份声明（单次有效，见 realtime/auth/ticket）。
+ * - `RealtimeClientEvent` / `RealtimeServerEvent`：客户端 ↔ 服务端之间的往返帧。
+ * - `RealtimeChannelMessage`：单条 channel 消息（per-channel 串行序号），RT-003 负责派发。
+ *
+ * 纯类型契约（对齐 cloud-db.ts）：只声明形状，不引任何运行时依赖。态射（订阅授权求值、
+ * 防重放、seq 递增）一律发生在服务端，**绝不下发客户端**。
+ */
+/** 票据内嵌的调用方角色（当前换票固定签发 'user'，后续按需扩展）。 */
+export type RealtimeRole = 'user' | 'admin' | 'system';
+/**
+ * 握手票据的 claims（`issue`/`redeem` 后随 `exp` 与一次性 nonce 内嵌在 HMAC 签名 token 里）。
+ * - `subjectId` 绑定换票时经过会话鉴权的用户 id，防票据被跨主体复用。
+ * - `projectId` 决定订阅授权的求值域（`SubscriptionPolicy` 按 project 存规则）。
+ */
+export interface RealtimeTicketClaims {
+    projectId: string;
+    subjectId: string;
+    role: RealtimeRole;
+}
+/**
+ * 客户端 → 服务端帧（订阅 / 退订 / 上行消息 / 握手票据）。
+ * 票据正常经 `Sec-WebSocket-Protocol` 交互（RT-002 换票握手），
+ * `type:'auth'` 帧是子协议不可读环境下的回退通道，仅安全起见保留契约。
+ */
+export type RealtimeClientEvent = {
+    type: 'auth';
+    ticket: string;
+} | {
+    type: 'subscribe';
+    channel: string;
+} | {
+    type: 'unsubscribe';
+    channel: string;
+} | {
+    type: 'message';
+    channel: string;
+    data: unknown;
+};
+/** 服务端 → 客户端帧（订阅结果 / 错误信封）。 */
+export type RealtimeServerEvent = {
+    type: 'subscribed';
+    channel: string;
+} | {
+    type: 'unsubscribed';
+    channel: string;
+} | {
+    type: 'error';
+    code: string;
+    message: string;
+};
+/**
+ * 一条已投递的 channel 消息（RT-003 的派发队列输出）。
+ * `seq` 为服务端在该 channel 内的单调递增序号（PRD §3.2.9 每 channel 串行保序）。
+ */
+export interface RealtimeChannelMessage {
+    channel: string;
+    seq: number;
+    data: unknown;
+    publishedAt: string;
+    publisher?: string;
+}
+/**
+ * 上行消息注入函数执行沙箱的**受控投影**（RT-003 派发层构造，CORE-006 挂载点）。
+ * - 含事件类型 / 通道 / 连接标识 / 主语身份；**绝不含任何 socket / ElysiaWS 引用**（函数只持受控句柄）。
+ * - `seq` 为服务端在该 channel 内的单调递增序号（PRD §3.2.9 每 channel 串行保序），供保序断言。
+ */
+export interface RealtimeDispatchEvent {
+    /** 上游帧类型（RT-002 `RealtimeClientEvent` 的 `type`，当前为 `'message'`）。 */
+    type: string;
+    channel: string;
+    seq: number;
+    /** 事件负载（平台投影，非客户端原始对象）。 */
+    data: unknown;
+    publishedAt: string;
+}
+/**
+ * 注入函数执行沙箱的触发句柄（RT-003）：身份与通道的**只读标识**，可结构化克隆。
+ * 派发层在 `ExecutorRequest.body.trigger` 内嵌该句柄；函数可据 `kind === 'realtime'` 识别实时触发。
+ */
+export interface RealtimeTriggerHandle {
+    kind: 'realtime';
+    /** 事件类型（对应 `RealtimeDispatchEvent.type`，当前为 `'message'`）。 */
+    event: string;
+    channel: string;
+    connectionId: string;
+    subjectId: string;
+    projectId: string;
+}
+/**
+ * 某项目实时计量的运行期快照（RT-004 `RealtimeMeter`）。
+ * 计量口径对齐 PRD §2.12.6：`pushCount` 按实际命中的连接数累加（非 +1），
+ * `upstreamCount` 复用「函数调用次数」。计费档位数值不在此（BILL 域 M4）。
+ */
+export interface RealtimeMeterSnapshot {
+    projectId: string;
+    /** 累计推送消息数（按命中连接数累加）。 */
+    pushCount: number;
+    /** 累计上行消息数（= 函数调用次数，受限的洪泛也计入）。 */
+    upstreamCount: number;
+    /** 最近一次推送的 ISO 时间（从未推送为 null）。 */
+    lastPushAt: string | null;
+}
+/**
+ * presence 进出广播的对外事件（RT-004 `PresenceTracker`）。
+ * join/leave 突发经**去抖窗口**合并后产出：`type` 为该 (project,channel)
+ * 窗口内的净方向，`delta` 为净进出数（合并后 ≤N 条，不逐帧刷屏）。
+ */
+export interface PresenceEvent {
+    projectId: string;
+    channel: string;
+    type: 'join' | 'leave';
+    /** 窗口内净进出数（join+1 / leave-1 累计后的绝对值）。 */
+    delta: number;
+    /** 去抖产出（flush）时刻的 ISO 时间戳。 */
+    at: string;
+}

package/dist/secret-scan.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 密钥泄露静态检测结果类型（FN-013，PRD §4.2）。
+ *
+ * `@adep/types` 是纯类型包：本文件只有 `export type`，零运行时代码。
+ * 检测引擎本体在 `server/domains/functions/security/`，本处只公开「结果形状」，
+ * 供 SDK / 控制台 / CLI 消费展示（命中项、级别、位置）。
+ *
+ * 口令：secret 明文值**永不**进入类型或任何响应——命中只带键名（key）与源码位置，
+ * 引用密钥本身的出处不构成泄露。
+ */
+/** 命中级别：danger = 阻断不可 override（fail loud）；warn = 可疑须显式 --force 放行。 */
+export type SecretScanLevel = 'danger' | 'warn';
+/** 触发规则：按「密钥值可能逃离函数」的确定性语法特征判定。 */
+export type SecretScanRule = 
+/** 密钥被拼进 return / 响应体 / 显式下发 → 阻断。 */
+'response'
+/** 密钥被写入日志（console.* / 环境 logger 输出）→ 阻断。 */
+ | 'log'
+/** 密钥作为请求体/头下发到外部服务 → 阻断。 */
+ | 'request'
+/** 读取 path.get.name 但未在当行明显逃离（风险低，须人工兜底确认）→ 警告。 */
+ | 'reference';
+/** 单条命中：级别 + 规则 + 密钥名 + 源码定位（建议展示 file:line 与命中断言）。 */
+export type SecretScanHit = {
+    level: SecretScanLevel;
+    rule: SecretScanRule;
+    /** 被引用的 secret 环境变量名（非值）。 */
+    key: string;
+    /** 命中源码文件路径（草稿文件组内相对路径）。 */
+    file: string;
+    /** 1-based 行号。 */
+    line: number;
+    /** 命中行的源码片段（截断，用于展示定位）。 */
+    snippet: string;
+};
+/** 一次静态扫描的完整结果：全部命中（danger 与 warn 混合，由调用方按级别分流）。 */
+export type SecretScanResult = {
+    hits: SecretScanHit[];
+};

package/dist/web-container.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `@adep/web-container` —— 平台浏览器原生开发环境（FN-012）对外 SDK 的类型契约。
+ *
+ * 对标 WebContainers API 形态（`bootstrap` / `mount` / `spawn` / `writeFile` / `on(event)`），
+ * 本文件只声明 SDK 对外暴露的类型（纯类型，零运行时代码，约束同 CORE-006 `@adep/types`）。
+ * 实现与平台侧在 `packages/web-container/`；服务端 npm 中继契约见 `@adep/types` 的
+ * `NpmRelayFetchRequest` / `NpmRelayFetchResponse`。
+ *
+ * 能力分层（task FN-012 / tech-stack §2.5：虚拟运行时 / 包管理器适配 / 终端协议均为接口）：
+ * - 浏览器内 WASM 虚拟 Linux（QuickJS 或等效引擎，可替换）；
+ * - npm 经平台 `/npm-relay/*` 中继取真实 registry（浏览器跨域限制）。
+ */
+/** 虚拟文件系统条目类型。 */
+export type WebContainerFsEntryType = 'file' | 'directory';
+/** 虚拟文件系统中的一个条目。 */
+export interface WebContainerFsEntry {
+    /** 相对宿主根目录的路径（POSIX 风格，如 `src/index.ts`）。 */
+    path: string;
+    type: WebContainerFsEntryType;
+}
+/** 挂载一棵文件树（WebContainers `mount` 入参形态：目录 vs 文件嵌套）。 */
+export interface WebContainerDirectoryTree {
+    [name: string]: string | WebContainerDirectoryTree | null;
+}
+/** 单个文件条目。 */
+export interface WebContainerFile {
+    /** 相对路径（POSIX 风格，无前导 `/`）。 */
+    path: string;
+    /** 文本内容；二进制暂以 UTF-8 文本承载。 */
+    contents: string;
+}
+/**
+ * `spawn` 进程返回的进程句柄。数据经真实 `ReadableStream<Uint8Array>` 双工，方便 IDE 直连终端。
+ */
+export interface WebContainerProcess {
+    /** 进程退出码（`null` = 仍在运行）。 */
+    readonly exit: Promise<number>;
+    /** 进程标准输入流（写入即喂给进程 stdin）。 */
+    readonly input: WritableStream<Uint8Array>;
+    /** 进程标准输出流。 */
+    readonly output: ReadableStream<Uint8Array>;
+    /** 进程标准错误流。 */
+    readonly stderr: ReadableStream<Uint8Array>;
+}
+export type WebContainerSpawnMethod = 'load' | 'start' | 'run';
+export type WebContainerSpawnArgs = string[] | (() => Promise<string[]>);
+export interface WebContainerSpawnOptions {
+    /** `load` 只解析入口；`start` 常驻（如 dev server）；`run` 单次执行（默认）。 */
+    method?: WebContainerSpawnMethod;
+    /** 工作目录。 */
+    cwd?: string;
+    /** 环境变量覆盖。 */
+    env?: Record<string, string>;
+    /** `method: 'start'` 时常驻超时（ms），超时强制回收。 */
+    timeout?: number;
+    /** 进程能力：置 false 以关闭该进程的文件系统访问（差异分层，task §3.7）。 */
+    capabilities?: {
+        files?: boolean;
+        network?: boolean;
+        shell?: boolean;
+    };
+    /** 需要时异步解析实参（如经平台 `readdir` 解析 glob 后注入文件列表）。 */
+    prepareArgs?: WebContainerSpawnArgs;
+}
+/** WebContainer 对外事件名及其载荷。 */
+export interface WebContainerEventMap {
+    /** 进程生命周期。 */
+    process: {
+        pty: WebContainerProcess;
+        event: 'start' | 'exit' | 'error' | 'message';
+        code?: number;
+        error?: Error;
+        message?: string;
+    };
+    /** 端口转发 / 内联预览：虚拟系统内 dev server 端口经 Service Worker 暴露到外部。 */
+    serverready: {
+        port: number;
+        url: string;
+    };
+    /** npm 安装进度。 */
+    installprogress: {
+        kind: 'start' | 'complete' | 'fail';
+        spec?: string;
+        message?: string;
+    };
+}
+/** `preview()` 内联预览选项。 */
+export interface PreviewServerOptions {
+    /** 入口所在工作目录（缺省 '/'）。 */
+    cwd?: string;
+    /** 入口文件名（缺省 'index.html'；不存在则降级为目录清单页）。 */
+    entry?: string;
+}
+/** WebContainer 对外 API 主体（对标 WebContainers `WebContainer`）。 */
+export interface WebContainer {
+    /** 挂载一棵文件树到工作区根目录。 */
+    mount(tree: WebContainerDirectoryTree): Promise<void>;
+    /** 写一个文件（不存在则创建父目录）。 */
+    writeFile(path: string, contents: string): Promise<void>;
+    /** 读一个文件（返回 UTF-8 文本）。 */
+    readFile(path: string): Promise<string>;
+    /** 列目录条目（相对路径，POSIX）。 */
+    listDirectory(path: string): Promise<WebContainerFsEntry[]>;
+    /** 创建目录（`recursive` 默认 true）。 */
+    createDirectory(path: string, recursive?: boolean): Promise<void>;
+    /** 删除文件 / 递归删除目录。 */
+    deleteFile(path: string): Promise<void>;
+    /** 判断路径是否存在。 */
+    exists(path: string): Promise<boolean>;
+    /** 派生进程（内置 shell 命令 / node 脚本）。 */
+    spawn(command: string, args: string[], options?: WebContainerSpawnOptions): WebContainerProcess;
+    /** 便捷包装：spawn 并把进程输出收集为文本（用于一次性命令）。 */
+    run(command: string, args: string[], options?: WebContainerSpawnOptions): Promise<string>;
+    /** 订阅事件（`process` / `serverready` / `installprogress`）。 */
+    on<K extends keyof WebContainerEventMap>(event: K, callback: (payload: WebContainerEventMap[K]) => void): void;
+    /** 取消订阅。 */
+    off<K extends keyof WebContainerEventMap>(event: K, callback: (payload: WebContainerEventMap[K]) => void): void;
+    /** 启动虚拟静态 dev server（内联预览）：首次调用创建、后续返回同一实例。 */
+    preview(options?: PreviewServerOptions): Promise<{
+        url: string;
+        port: number;
+    }>;
+    /** npm：经平台 npm-relay 安装依赖（拉取 manifest + tarball 写入 node_modules）。 */
+    install(spec: string): Promise<void>;
+    /** 列出平台允许的 npm registry（来自 npm-relay `/registry`）。 */
+    registries(): Promise<string[]>;
+    /** 关闭：终止所有常驻进程并释放资源。 */
+    close(): Promise<void>;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@adep/types",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "AgentDeploy 用户 SDK 类型契约（纯类型包，零运行时代码，见任务单 CORE-006）",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "build": "bun run ../../scripts/build-package.ts types"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  }
+}