@ai-setting/roy-agent-core 1.7.52 → 1.7.55

package/dist/env/task/backend/roy-sidecar-task-port.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview Roy-sidecar task port — 通用 duck-typed 存储适配器
+ *
+ * Task #4380。有些 agent 插件的任务存储**已经有自己的业务模型**（自己的
+ * status 词表、自己的 uuid 主键、自己的 audit log），但愿意额外存一个
+ * roy 侧车（sidecar）字段来保留 roy 的全部语义。这类存储的共同形状是稳定
+ * 的，所以适配逻辑不该在每个 agent 插件里重写一遍。
+ *
+ * 本模块把这个形状抽象成 {@link RoySidecarTaskStore}，并给出唯一实现
+ * {@link createRoySidecarTaskPort}。插件侧因此只剩「词表映射」这一件真正
+ * 属于它自己的事（business status ↔ roy status）。
+ *
+ * ```
+ *   TaskStoreBackend            roy 语义（shared，唯一实现）
+ *        ↓ TaskPersistencePort
+ *   createRoySidecarTaskPort(store, vocabulary)   ← 本文件（shared）
+ *        ↓ RoySidecarTaskStore
+ *   plugin TaskStore            （openCode / Claude / Codex 各自的业务库）
+ * ```
+ */
+import type { StoredTaskRecord, TaskPersistencePort } from "./types";
+/**
+ * 一条「带 roy 侧车」的存储记录。
+ *
+ * - `id`：存储自己的主键（uuid / 十进制字符串）
+ * - `num`：数值句柄（rowid），roy 用它做 task id
+ * - `roy`：roy 侧车（type / progress / project_path / context …）
+ * - `data`：operation 的 JSON payload（roy 的 milestone 字段住在这里）
+ */
+export interface SidecarTask {
+    id: string;
+    num?: number;
+    title: string;
+    description?: string;
+    status: string;
+    priority: number;
+    tags?: string;
+    parent_id: string | null;
+    session_id?: string | null;
+    roy?: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+export interface SidecarOperation {
+    id: string;
+    num?: number;
+    task_id: string | null;
+    type: string;
+    data: Record<string, unknown>;
+    created_at: string;
+}
+/** 带 roy 侧车的存储最小契约（各 agent 插件的 store 都长这样）。 */
+export interface RoySidecarTaskStore {
+    createTask(input: {
+        title: string;
+        description?: string;
+        priority?: number;
+        owner?: string;
+        tags?: string;
+        parent_id?: string | null;
+        session_id?: string | null;
+        roy?: Record<string, unknown>;
+    }): Promise<SidecarTask>;
+    updateTask(id: string, input: {
+        title?: string;
+        description?: string;
+        status?: string;
+        priority?: number;
+        tags?: string;
+        roy?: Record<string, unknown>;
+    }): Promise<SidecarTask | null>;
+    getTask(id: string): Promise<SidecarTask | null>;
+    /** 按数值句柄读（O(1)）；没实现就退化成全表扫描。 */
+    getTaskByNum?(num: number): Promise<SidecarTask | null>;
+    /**
+     * 纯分页读取（不做语义过滤 —— 那些由 `TaskStoreBackend` 统一负责）。
+     *
+     * 刻意**不**声明 `status` / `parent_id`：backend 从不需要它们，而声明一个
+     * 用不到的过滤字段只会让签名的结构兼容性变差（业务 store 的 status 通常是
+     * 自己的联合类型，`string` 反而不兼容 —— CV round 1）。
+     */
+    listTasks(filter?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        tasks: SidecarTask[];
+        total: number;
+    }>;
+    deleteTask(id: string): Promise<boolean>;
+    /** 重挂父任务（`null` = 提升为根）。 */
+    setParentId?(id: string, parentId: string | null): Promise<void>;
+    appendOperation(input: {
+        task_id: string | null;
+        type: string;
+        data: Record<string, unknown>;
+    }): Promise<SidecarOperation>;
+    listOperations(filter?: {
+        task_id?: string;
+        type?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        operations: SidecarOperation[];
+        total: number;
+    }>;
+    getOperationByNum?(num: number): Promise<SidecarOperation | null>;
+    updateOperation?(num: number, patch: {
+        type?: string;
+        data?: Record<string, unknown>;
+    }): Promise<SidecarOperation | null>;
+    deleteOperation?(num: number): Promise<boolean>;
+}
+/**
+ * 业务词表 ↔ roy 词表的映射。
+ *
+ * 这是**唯一**需要每个 agent 插件自己提供的东西：它的业务 status 叫什么，
+ * priority 怎么编码。roy 的语义（BFS / depth / deliverable / total …）不需要管。
+ */
+export interface SidecarVocabulary {
+    /** 存储 status → roy status。 */
+    toRoyStatus(storeStatus: string): StoredTaskRecord["status"];
+    /** roy status → 存储 status。 */
+    toStoreStatus(royStatus: string): string;
+    /** 存储数值 priority → roy priority 桶。 */
+    toRoyPriority(storePriority?: number): StoredTaskRecord["priority"];
+    /** roy priority → 存储数值 priority。 */
+    toStorePriority(royPriority?: string): number;
+    /** 存储逗号串 tags → roy string[]。 */
+    toRoyTags(storeTags?: string | null): string[];
+    /** roy string[] tags → 存储逗号串。 */
+    toStoreTags(royTags?: string[]): string | undefined;
+}
+export interface RoySidecarPortOptions {
+    /** audit log 里表示 roy milestone 的 type 值。 */
+    operationType?: string;
+    /** 建任务时写入的 owner。 */
+    agent?: string;
+    /** 全量扫描的分页大小。 */
+    scanLimit?: number;
+}
+/**
+ * 把任意「带 roy 侧车」的存储接成一个 {@link TaskPersistencePort}。
+ *
+ * ⚠️ 只做形状翻译 + num↔nativeId 解析：不做 BFS、不做 depth、不拼
+ * `Deliverable:`、不自动写 create operation —— 那些是 `TaskStoreBackend`
+ * 的职责，所有 agent 插件共享同一份。
+ */
+export declare function createRoySidecarTaskPort(store: RoySidecarTaskStore, vocabulary: SidecarVocabulary, options?: RoySidecarPortOptions): TaskPersistencePort;

package/dist/env/task/backend/sqlite-task-port.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview SQLite Task Port — roy 自己的 store 的 port 实现
+ *
+ * Task #4380。`SQLiteTaskStore` 已经实现了 roy 的完整 `TaskStore` 接口（含
+ * depth / search / tags 等原生能力）。这个 adapter 只做两件事：
+ *
+ * 1. 把 `TaskStore` 的入参/出参翻译成 {@link TaskPersistencePort} 的纯原语
+ * 2. 补齐 `StoredTaskRecord.nativeId`（roy 的数字 id 直接当 nativeId 用）
+ *
+ * 语义（BFS / depth / deliverable / create-operation / total …）一律**不在**
+ * 这里实现 —— 那些由 `TaskStoreBackend` 统一负责，保证 roy 自己与所有
+ * agent 插件跑的是同一套逻辑。
+ */
+import type { TaskStore } from "../storage/sqlite-task-store";
+import type { ActionType } from "../types";
+import type { TaskPersistencePort } from "./types";
+/** 让 `TaskOperation.milestoneType` 与 port 的 `ActionType` 对齐。 */
+declare function asActionType(value: string): ActionType;
+/**
+ * 把 roy 的 `TaskStore`（`SQLiteTaskStore`）接成一个 port。
+ *
+ * ```ts
+ * const store = new SQLiteTaskStore();
+ * const backend = new TaskStoreBackend(createSQLiteTaskPort(store));
+ * ```
+ */
+export declare function createSQLiteTaskPort(store: TaskStore): TaskPersistencePort;
+export { asActionType };

package/dist/env/task/backend/task-store-backend.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview TaskStoreBackend — roy 语义的唯一实现
+ *
+ * Task #4380。这个类把「roy 的 task 语义」从各 agent 插件里收回来，只留一份：
+ *
+ * - 建任务自动写 `create` operation（review B2）
+ * - 完成任务把 deliverable merge 进 `context.deliverable_storage_path`（B3）
+ * - operation 列表返回扁平数组（B4）
+ * - `total` 是过滤后的真实条数（B5）
+ * - 子树 BFS（B1）、`depth` 展开（Y1）
+ * - 搜索的 8 个过滤项全部生效（Y2）
+ * - `milestoneType` 过滤（Y3）
+ * - 词汇单一来源：直接用 roy 的 `TaskStatusEnum` / `ActionTypeEnum`（Y4）
+ *
+ * 它只依赖 {@link TaskPersistencePort}（纯存取原语），所以：
+ *
+ * ```ts
+ * // roy 自己
+ * import { SQLiteTaskStore } from "@ai-setting/roy-agent-core/env/task/storage";
+ * import { TaskStoreBackend, createSQLiteTaskPort } from "@ai-setting/roy-agent-core/env/task/backend";
+ * const backend = new TaskStoreBackend(createSQLiteTaskPort(new SQLiteTaskStore()));
+ *
+ * // 任何 agent 插件（openCode / Claude Code / Codex …）
+ * const backend = new TaskStoreBackend(myPortOverMyStore);
+ * ```
+ */
+import type { Task, TaskListResult, TaskOperation } from "../types";
+import type { BackendCreateOperationOptions, BackendCreateTaskOptions, BackendListOperationsOptions, BackendListTasksOptions, BackendSearchTasksOptions, BackendUpdateOperationOptions, BackendUpdateTaskOptions, TaskBackend, TaskBackendOptions, TaskId, TaskPersistencePort } from "./types";
+/** roy Task #2778 v2: deliverable 在 operation 里的统一前缀。 */
+export declare const DELIVERABLE_OPERATION_PREFIX = "Deliverable: ";
+/** 把 deliverable 路径格式化成 operation 的 milestoneDescription。 */
+export declare function formatDeliverableForOperation(deliverableStoragePath?: string): string | undefined;
+export declare class TaskStoreBackend implements TaskBackend {
+    private readonly port;
+    private readonly options;
+    constructor(port: TaskPersistencePort, options?: TaskBackendOptions);
+    private get defaultSessionId();
+    /**
+     * 把任意句柄解析成存储记录。
+     *
+     * - 数字（或全数字字符串）：先问 port 有没有 `getTaskByNum`，没有就扫全表
+     * - 其它字符串：当作存储主键（uuid）
+     */
+    private resolve;
+    /** 去掉 port 的 `nativeId`，还原成纯 roy `Task`。 */
+    private toTask;
+    private toOperation;
+    /**
+     * Read every row, **including archived** ones.
+     *
+     * `includeArchived: true` is mandatory here: most stores hide archived rows by
+     * default (roy's SQLite appends `status != 'archived'`), so without it
+     * `status:"archived"` and `include_archived` would silently match nothing.
+     */
+    private scanAllTasks;
+    createTask(input: BackendCreateTaskOptions): Promise<Task>;
+    getTask(id: TaskId): Promise<Task | null>;
+    getTaskWithOperations(id: TaskId): Promise<(Task & {
+        operations: TaskOperation[];
+    }) | null>;
+    listTasks(options?: BackendListTasksOptions): Promise<TaskListResult>;
+    updateTask(id: TaskId, input: BackendUpdateTaskOptions): Promise<Task | null>;
+    deleteTask(id: TaskId): Promise<boolean>;
+    completeTask(id: TaskId, sessionId?: string, deliverable?: string): Promise<Task | null>;
+    /**
+     * review B1 — roy 的 `task-tree-tool.ts` 在子树模式下调这个方法；
+     * 老 facade 缺它导致 `task_tree(parent_task_id=…)` 直接抛
+     * `taskComponent.getTaskTree is not a function`。
+     *
+     * @returns 所有后代（**不含** root 自身），BFS 按层展开并扁平化
+     */
+    getTaskTree(id: TaskId, depth?: number): Promise<Task[]>;
+    searchTasksByKeywords(keywords: string[], options?: BackendSearchTasksOptions): Promise<TaskListResult>;
+    createOperation(input: BackendCreateOperationOptions): Promise<TaskOperation>;
+    listOperations(options?: BackendListOperationsOptions): Promise<TaskOperation[]>;
+    getOperation(id: number): Promise<TaskOperation | null>;
+    updateOperation(id: number, patch: BackendUpdateOperationOptions): Promise<TaskOperation | null>;
+    deleteOperation(id: number): Promise<boolean>;
+    /**
+     * roy 的过滤语义，一处实现，`listTasks` 与 `searchTasksByKeywords` 共用。
+     *
+     * 关键点：
+     * - 默认排除 `archived`，但**显式** `status="archived"` 时豁免（否则那个
+     *   过滤器自相矛盾、永远返回 0 —— #4375 交叉验证 nit #3）
+     * - `depth` 的根 = 「父不在可见集合里」的任务，与 roy 的孤儿提升规则一致
+     * - `parent_task_id` 只有 `listTasks` 会传（roy 的 `SearchTasksOptions` 没有
+     *   这个字段），`searchTasksByKeywords` 永远走不到那个分支
+     */
+    private applyFilters;
+}
+/** `3` / `"3"` → `3`；其它（uuid、非数字串）→ `undefined`。 */
+export declare function toNumericHandle(id: TaskId): number | undefined;
+/**
+ * roy 的 `depth` 语义：`0` 只根 / `1` 根+一层 / `N` N 层 / `-1` 全部。
+ *
+ * 根的定义：父不在可见集合里（孤儿提升，避免某任务因为父被过滤掉而消失）。
+ */
+export declare function allowedIdsByDepth<T extends {
+    id: number;
+    parent_task_id?: number;
+}>(views: T[], depth: number): Set<number>;
+/**
+ * roy Task #2778 契约：`context` 是 JSON 对象，deliverable 作为
+ * `deliverable_storage_path` merge 进去，保留所有兄弟 key。
+ * 坏 JSON ⇒ 从空对象开始（绝不抛错：完成任务不能被脏 context 打断）。
+ */
+export declare function mergeDeliverableIntoContext(rawContext: unknown, deliverable: string): string;

package/dist/env/task/backend/types.d.ts

@@ -0,0 +1,282 @@
+/**
+ * @fileoverview Task Backend Contract + Persistence Port
+ *
+ * Task #4380 — 「roy 语义上移」的接口层。
+ *
+ * ## 为什么需要这一层
+ *
+ * roy 的工具工厂（`createTaskTool` / `listTasksTool` / …）只依赖一个
+ * **duck-typed** 的对象：它们只调用 14 个方法，并不关心底层是不是
+ * `TaskComponent`。历史上有两个实现：
+ *
+ * 1. `TaskComponent`（roy-agent 自己）—— SQLite + hooks + events + tags
+ * 2. `roy_task_plugin_for_opencode` 的 `facade.ts`（869 行）—— 把同样的
+ *    14 个方法落到插件自己的 store 上
+ *
+ * 第 2 个实现里混着大量 **roy 语义**（子树 BFS、depth 展开、deliverable 落
+ * context、create operation 自动写、扁平 operation 列表、真实 total、搜索
+ * 的 8 个过滤…）。这些语义本不属于任何 agent 框架，却因为写着"opencode
+ * 插件"而无法被 claude / codex 复用。
+ *
+ * 本模块把它们收回 core，拆成两层：
+ *
+ * ```
+ *   @ai-setting/roy-agent-core/env/task/backend
+ *     ├── TaskBackend           roy 语义（BFS / depth / deliverable / total …）
+ *     │                          ← 本文件定义契约，task-store-backend.ts 实现
+ *     └── TaskPersistencePort   纯粹的存取原语（不含量级语义）
+ *                                ← roy 的 SQLite 与各 agent 插件的 store 各实现一份
+ *
+ *   plugin-opencode / plugin-claude / plugin-codex
+ *     └── 只实现 TaskPersistencePort（约 100 行形状对接）→ 自动获得全部 roy 语义
+ * ```
+ *
+ * ## 设计约束
+ *
+ * - **类型全部来自 roy 自己**（`Task` / `TaskOperation` / `TaskStatusEnum` …），
+ *   不手抄、不 re-declare —— 单一词汇来源（review finding Y4）。
+ * - 入参直接复用 roy 的 `CreateTaskOptions` / `ListTasksOptions` /
+ *   `SearchTasksOptions`（只把 `sessionId` 放宽为可选，因为 adapter 有默认值）。
+ * - **语义只写一次**：adapter 里不许再出现 BFS / depth / total 之类的逻辑，
+ *   这些一律由 `TaskStoreBackend` 负责。
+ */
+import type { ActionType, CreateOperationOptions, CreateTaskOptions, ListOperationsOptions, ListTasksOptions, SearchTasksOptions, Task, TaskListResult, TaskOperation, UpdateTaskOptions } from "../types";
+/**
+ * roy 工具工厂实际调用的方法集合。
+ *
+ * ⚠️ 这是**契约**，不是建议：`TaskComponent` 与所有 adapter 都必须满足它。
+ * 任何缺失的方法都会让工具在运行时抛 `is not a function`（review finding
+ * B1 就是这么来的：`task_tree` 子树模式直接崩）。
+ */
+export interface TaskBackend {
+    /**
+     * 创建任务。
+     *
+     * 契约（与 `TaskComponent.createTask` 对齐，review finding B2）：
+     * 成功后会**自动**写入一条 `milestoneType: "create"` 的 operation。
+     */
+    createTask(input: BackendCreateTaskOptions): Promise<Task>;
+    /** 按 id 读取。id 可以是 roy 数字 id，也可以是 adapter 认得的其它句柄（如 uuid）。 */
+    getTask(id: TaskId): Promise<Task | null>;
+    /**
+     * 任务 + 它的 operations。
+     *
+     * ⚠️ 返回形状必须是 `Task & { operations }`（扁平展开），
+     * **不是** `{ task, operations }` —— `task_get` 工具直接 JSON.stringify 它。
+     */
+    getTaskWithOperations(id: TaskId): Promise<(Task & {
+        operations: TaskOperation[];
+    }) | null>;
+    /** 列表 + 真实总数（`total` 必须是过滤后的真实 COUNT，不能是当前页长度）。 */
+    listTasks(options?: BackendListTasksOptions): Promise<TaskListResult>;
+    updateTask(id: TaskId, input: BackendUpdateTaskOptions): Promise<Task | null>;
+    deleteTask(id: TaskId): Promise<boolean>;
+    /**
+     * 完成任务。
+     *
+     * 契约（review finding B3）：
+     * - `status` → `completed`，`progress` → 100
+     * - 若给了 `deliverable`，merge 进 `context.deliverable_storage_path`
+     *   并写入 completion operation 的 `milestoneDescription`
+     * - `cycle` 类型任务拒绝完成（roy 语义）
+     */
+    completeTask(id: TaskId, sessionId?: string, deliverable?: string): Promise<Task | null>;
+    /** 子树（所有后代，**不含** root），BFS 按层展开，`depth` 限制层数。 */
+    getTaskTree(id: TaskId, depth?: number): Promise<Task[]>;
+    /** 关键词检索 + 全部 roy 过滤项（review finding Y2）。 */
+    searchTasksByKeywords(keywords: string[], options?: BackendSearchTasksOptions): Promise<TaskListResult>;
+    /** 写一条 operation。`action_*` 别名会被映射到 `milestone_*`。 */
+    createOperation(input: BackendCreateOperationOptions): Promise<TaskOperation>;
+    /**
+     * 读 operation 列表。
+     *
+     * ⚠️ 返回**扁平数组**（review finding B4）。`task_operation_list` 工具会做
+     * `JSON.stringify({ operations, count: operations.length })`，任何额外嵌套
+     * 都会让模型读到 `{"operations":{"operations":[…]}}`。
+     */
+    listOperations(options?: BackendListOperationsOptions): Promise<TaskOperation[]>;
+    getOperation(id: number): Promise<TaskOperation | null>;
+    updateOperation(id: number, patch: BackendUpdateOperationOptions): Promise<TaskOperation | null>;
+    deleteOperation(id: number): Promise<boolean>;
+}
+/**
+ * 任务 / operation 句柄。
+ *
+ * roy 自己用数字 id；插件 store 用 uuid 主键 + rowid 数值句柄。adapter 负责
+ * 把两者都接受进来（全数字字符串按数字处理）。
+ */
+export type TaskId = number | string;
+/** `createTask` 放宽版：`sessionId` 可由 backend 的默认值补上。 */
+export type BackendCreateTaskOptions = Omit<CreateTaskOptions, "sessionId"> & {
+    sessionId?: string;
+};
+/** `listTasks` 放宽版：`depth` 语义与 roy 一致。 */
+export type BackendListTasksOptions = ListTasksOptions;
+/** `updateTask` 放宽版。 */
+export type BackendUpdateTaskOptions = UpdateTaskOptions;
+/** `searchTasksByKeywords` 放宽版。 */
+export type BackendSearchTasksOptions = SearchTasksOptions;
+/** `createOperation` 放宽版：`sessionId` 可省略。 */
+export type BackendCreateOperationOptions = Omit<CreateOperationOptions, "sessionId"> & {
+    sessionId?: string;
+};
+/** `listOperations` 放宽版：`taskId` 接受任意句柄。 */
+export interface BackendListOperationsOptions extends Omit<ListOperationsOptions, "taskId"> {
+    taskId?: TaskId;
+}
+/**
+ * operation 更新 payload。
+ *
+ * 比 `UpdateOperationOptions` 多了 `sessionId` / `mdPath` / `milestoneType`，
+ * 因为 adapter 需要能重写整条 operation 的 data blob（插件的 operation 是
+ * 一个 JSON 列，roy 的是独立列）。
+ */
+export interface BackendUpdateOperationOptions {
+    sessionId?: string;
+    milestoneType?: ActionType;
+    milestoneTitle?: string;
+    milestoneDescription?: string;
+    processDescription?: string;
+    mdPath?: string;
+    /** @deprecated 旧别名，映射到 milestoneType。 */
+    actionType?: ActionType;
+    /** @deprecated 旧别名，映射到 milestoneTitle。 */
+    actionTitle?: string;
+    /** @deprecated 旧别名，映射到 milestoneDescription。 */
+    actionDescription?: string;
+}
+/** 构造 backend 时的可选配置。 */
+export interface TaskBackendOptions {
+    /** 创建 task / operation 时默认写入的 session id（缺省 `"unknown"`）。 */
+    sessionId?: string;
+}
+/**
+ * 一条已持久化的任务记录：roy `Task` + 存储自己的主键。
+ *
+ * - `nativeId` 是存储的主键（uuid / 字符串 rowid），adapter 内部用
+ * - `id` / `parent_task_id` 是 roy 的数字句柄，adapter 负责转换
+ */
+export interface StoredTaskRecord extends Task {
+    /** 存储自己的主键（uuid / 十进制字符串）。 */
+    nativeId: string;
+}
+/**
+ * 一条已持久化的 operation 记录：roy `TaskOperation` + 存储自己的主键。
+ */
+export interface StoredOperationRecord extends TaskOperation {
+    /** 存储自己的主键（uuid / 十进制字符串）。 */
+    nativeId: string;
+}
+/** port 的建任务入参（roy 实体 + 可选的 owner）。 */
+export interface PortCreateTaskInput {
+    title: string;
+    description?: string;
+    status?: Task["status"];
+    priority?: Task["priority"];
+    type?: Task["type"];
+    progress?: number;
+    current_status?: string;
+    goals_and_expected_deliverables?: string;
+    parent_task_id?: number;
+    due_date?: string;
+    tags?: string[];
+    project_path: string;
+    context: string;
+    sessionId?: string;
+    /**
+     * 记录创建者。**可选**，roy 自己的 store 忽略它；带业务模型的 adapter
+     * （插件）用它写自己的 `owner` 列。放这里是刻意的：port 已经是"桥接层"，
+     * 与其让每个 adapter 在闭包里偷偷注入，不如显式声明。
+     */
+    owner?: string;
+}
+/** port 的更新入参。`null` 表示显式置空（用于把子任务提升为根）。 */
+export interface PortUpdateTaskInput {
+    title?: string;
+    description?: string;
+    status?: Task["status"];
+    priority?: Task["priority"];
+    type?: Task["type"];
+    progress?: number;
+    current_status?: string;
+    goals_and_expected_deliverables?: string;
+    due_date?: string;
+    tags?: string[];
+    project_path?: string;
+    context?: string;
+    /** `null` = 提升为根任务。 */
+    parent_task_id?: number | null;
+}
+/** port 的建 operation 入参。 */
+export interface PortCreateOperationInput {
+    taskId: number;
+    /** 存储主键（adapter 用；缺省时由 port 从 taskId 反查）。 */
+    taskNativeId?: string;
+    sessionId: string;
+    milestoneType: ActionType;
+    milestoneTitle: string;
+    milestoneDescription: string;
+    processDescription: string;
+    mdPath?: string;
+}
+/** port 的更新 operation 入参。 */
+export interface PortUpdateOperationInput {
+    sessionId?: string;
+    milestoneType?: ActionType;
+    milestoneTitle?: string;
+    milestoneDescription?: string;
+    processDescription?: string;
+    mdPath?: string;
+}
+/**
+ * 纯存取原语。
+ *
+ * 这里**不允许**出现任何 roy 语义：
+ * - 不解释 `depth`（那是 backend 的事）
+ * - 不拼 `Deliverable: …`（那是 backend 的事）
+ * - 不自动写 create operation（那是 backend 的事）
+ * - 不做 total 收敛（原样返回存储自己的 COUNT / 长度）
+ *
+ * 只有 `num ↔ nativeId` 的解析是 port 的职责，因为只有它知道自己的主键。
+ */
+export interface TaskPersistencePort {
+    createTask(input: PortCreateTaskInput): Promise<StoredTaskRecord>;
+    /** 按存储主键读取。 */
+    getTask(nativeId: string): Promise<StoredTaskRecord | null>;
+    /** 按 roy 数字句柄读取。没实现时 backend 会退回全表扫描。 */
+    getTaskByNum?(num: number): Promise<StoredTaskRecord | null>;
+    /**
+     * 列任务（**纯分页原语**）。
+     *
+     * 不带任何语义过滤：需要 status / depth / priority 等过滤时由 backend
+     * 自行在内存里做（adapter 的库都很小，实测 < 2k 行）。
+     *
+     * ⚠️ `includeArchived` 不是语义过滤，而是「让 archived 行可见」这条存储层
+     * 开关：很多 store（含 roy 自己的 SQLite）默认在 SQL 里排除它们。backend
+     * 在做全量扫描时必须传 `true`，否则 `status="archived"` 之类的查询永远空。
+     */
+    listTasks(options?: {
+        limit?: number;
+        offset?: number;
+        includeArchived?: boolean;
+    }): Promise<{
+        tasks: StoredTaskRecord[];
+        total: number;
+    }>;
+    updateTask(nativeId: string, patch: PortUpdateTaskInput): Promise<StoredTaskRecord | null>;
+    deleteTask(nativeId: string): Promise<boolean>;
+    createOperation(input: PortCreateOperationInput): Promise<StoredOperationRecord>;
+    listOperations(options?: {
+        taskNativeId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        operations: StoredOperationRecord[];
+        total: number;
+    }>;
+    getOperationByNum?(num: number): Promise<StoredOperationRecord | null>;
+    updateOperationByNum?(num: number, patch: PortUpdateOperationInput): Promise<StoredOperationRecord | null>;
+    deleteOperationByNum?(num: number): Promise<boolean>;
+}
+/** `TaskBackend` 的方法名（编译期守卫用）。 */
+export type TaskBackendMethodName = keyof TaskBackend;

package/dist/env/task/delegate/bg-task-id-storage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 在异步作用域内暴露 bgTaskId 给 fn。
+ */
+export declare function runWithBgTaskIdAsync<T>(bgTaskId: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * 当前 ALS 栈顶的 bgTaskId（如果存在）。
+ * 在 workflow_run 工具中调用：若返回 undefined 则跳过 attach（主 session 场景）。
+ */
+export declare function getCurrentBgTaskId(): string | undefined;