@william2000/dsh-nova-ui-task-board 0.1.0

package/lib/types/host-ledger.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Host 权威账本（DSH-REQ-001 §8 架构 / §9.1 / §17 可靠性）。
+ *
+ * 「Host 权威、浏览器只是异步视图」的数据底座：所有任务状态持久化到
+ * `$DSH_HOME/nova-ui/task-board/ledger-v2.json`（0600，原子写），保证重启不丢、
+ * 并发一致、损坏可隔离。T003（协议）/T005（执行）/T006（调度）等在此之上工作。
+ *
+ * 可靠性机制（§17 / §19-7 数据部分）：
+ * - **原子写**：临时文件 + fsync + 原子 rename + 目录 fsync；任何失败清理临时
+ *   文件并重新抛出，绝不产生半写文件；
+ * - **损坏隔离**：schema 不兼容/不可解析的账本 rename 为 `ledger-v2.json.corrupt-*`
+ *   （保留原字节）并以空账本重建，不崩溃；
+ * - **单写者锁**：`ledger-v2.lock`（0600，`wx` 排他创建）记录 PID + token +
+ *   进程启动时间探测；PID 复用通过启动时间不匹配识别为陈旧锁并接管（防误判），
+ *   僵尸/死亡进程（Z/X）不阻塞启动；
+ * - **幂等缓存**：`recentRequests`（最近 256 条 requestId→SHA-256 指纹）随账本
+ *   原子持久化，Host 重启后浏览器重试仍安全（§11.3）；
+ * - **v1 迁移**：`importSource` 按 sourceId 一次性导入、按 id 合并，导入 marker
+ *   随原子落账持久化（Host 确认后浏览器才清除 v1 原值，见 core/migrate.ts）。
+ *
+ * 串行性：本类全部方法为同步实现（无 await），单进程内天然串行；跨进程互斥
+ * 由锁保证。`revision` 每次原子落账严格 +1（scheduler 心跳类补丁除外，见
+ * `setScheduler`）。
+ */
+import type { AutomationRule, LedgerDocument, LedgerScheduler, LedgerState, SchedulerSnapshot, TaskRecord } from './core/model.ts';
+/**
+ * 尽力而为的单字母进程状态（'R','S','D','Z',...），平台不支持时返回 undefined。
+ * Linux 直接读 /proc（无子进程）；其他 POSIX 用 `ps -o stat=`；Windows 无僵尸
+ * 态，返回 undefined（此时 kill(0) 探测为唯一权威）。
+ */
+export declare function processState(pid: number): string | undefined;
+/** PID 是否存活（僵尸/死亡态视为不存活）。 */
+export declare function processIsAlive(pid: number): boolean;
+/**
+ * 尽力而为的进程启动时间（Unix epoch ms），用于证明锁记录里的 PID 是否真的是
+ * 之前那个进程（PID 复用会被识别为陈旧锁而不是永久阻塞启动）。平台探测不可用
+ * 时返回 undefined，调用方 fail closed。
+ */
+export declare function processStartTimeMs(pid: number): number | undefined;
+/** 记录的启动时间是否证明记录的 PID 已是另一个进程（PID 复用探测核心）。 */
+export declare function startTimeMismatch(recorded: number, actual: number, exact: boolean): boolean;
+/**
+ * 进程探测面（§17 可测试性：Host 编排用结构面注入 fake）。生产默认用真实
+ * 平台探测；测试可注入假实现来覆盖 PID 复用接管等分支（真实探测在部分
+ * 沙箱/系统上不可用——如 macOS 限制 ps——会 fail closed 而非误判）。
+ */
+export interface ProcessProbes {
+    isAlive(pid: number): boolean;
+    /** 进程启动时间（Unix epoch ms）；平台探测不可用时返回 undefined。 */
+    startTimeMs(pid: number): number | undefined;
+    /** 本进程启动时间（带缓存）。 */
+    ownStartTimeMs(): number | undefined;
+}
+/**
+ * Host 权威账本。构造即获取单写者锁并加载/恢复账本；进程内所有写入经
+ * `applyRequest`/`importSource`/`mutate`/`setScheduler` 串行原子落账。
+ */
+export declare class HostLedger {
+    private readonly now;
+    /** 账本文件绝对路径。 */
+    readonly file: string;
+    /** 锁文件绝对路径。 */
+    readonly lockFile: string;
+    /** 账本目录。 */
+    readonly dir: string;
+    private document;
+    private readonly listeners;
+    private readonly requestCache;
+    private readonly lockToken;
+    private lockFd;
+    private readonly probes;
+    /**
+     * @param dir - 账本目录（默认 `$DSH_HOME/nova-ui/task-board/`，见 AGENTS.md D2）。
+     * @param now - 时间源（测试可注入）。
+     * @param probes - 进程探测面（默认真实探测；测试可注入 fake，见 §17 可测试性）。
+     */
+    constructor(dir?: string, now?: () => number, probes?: ProcessProbes);
+    /** revision + scheduler（不克隆任务），供 SSE 事件帧使用。 */
+    summary(): {
+        revision: number;
+        scheduler: SchedulerSnapshot;
+    };
+    /** 全量状态快照（任务/规则深拷贝，调用方修改不影响账本）。 */
+    state(): LedgerState;
+    /**
+     * 只读任务数组（不克隆，O(1)）。仅供服务层扫描/计数（如 power 快照的
+     * runningSessions/armedSchedules）；**绝不可修改**——任何变更必须走
+     * `applyRequest`/`mutate` 的原子落账路径。
+     */
+    peekTasks(): readonly TaskRecord[];
+    /** 只读自动化规则数组（不克隆；变更必须走 applyRequest/mutate 原子落账）。 */
+    peekAutomationRules(): readonly AutomationRule[];
+    /** 订阅账本变更（每次原子落账后触发）。 */
+    subscribe(listener: () => void): () => void;
+    /** 释放锁（仅当锁仍属本实例时删除锁文件，避免误删外部替换的锁）。 */
+    dispose(): void;
+    /**
+     * 幂等 action 应用（§11.3）。调用方（T003 协议层）提供序列化的 action（仅
+     * 用于 SHA-256 指纹）与变更闭包；闭包返回 true 表示文档有实际变更。
+     *
+     * - 重复 requestId + 相同指纹 → 直接返回当前 state（不重新应用、不 bump）；
+     * - 同 requestId + 不同动作 → 抛错（`request id was reused with a different action`）；
+     * - 首次请求 → 指纹先行入缓存，随后应用；变更闭包抛错则回滚缓存条目；
+     * - 成功且 changed → 原子落账（revision+1），指纹随账本一并持久化——
+     *   Host 重启后浏览器重试仍安全。
+     *
+     * @param requestId - 浏览器侧 uuid。
+     * @param action - 序列化 action（指纹源；必须可 JSON 序列化）。
+     * @param apply - 变更闭包，就地修改文档；返回 true 表示发生变更（需落账）。
+     */
+    applyRequest(requestId: string, action: unknown, apply: (doc: LedgerDocument) => boolean): LedgerState;
+    /**
+     * v1 迁移导入（§11.2 `import` / §9.5）：按 sourceId 一次性导入、按 id 合并、
+     * 写入 importedSources marker（原子落账确认后才写入）。重复 sourceId 幂等
+     * no-op（不落账不 bump）。浏览器以成功响应 + 记住 ledgerId 作为确认凭证
+     * （T003/T004 接线；marker 不进 state/summary，见 `summary`）。
+     */
+    importSource(requestId: string, sourceId: string, tasks: readonly TaskRecord[]): LedgerState;
+    /**
+     * 通用原子变更（Host 编排用，T005/T006 的 runner/scheduler 也走这里）。
+     * `apply` 返回 true 才落账（revision+1）；返回 false 保持 revision 不变。
+     */
+    mutate(apply: (doc: LedgerDocument) => boolean): LedgerState;
+    /**
+     * 更新 scheduler 补丁（心跳 lastTickAt、错误可见性等，§9.1）。
+     * 不 bump revision（避免 30s 心跳驱动客户端全量重拉）；无实际变更不写盘。
+     */
+    setScheduler(patch: Partial<LedgerScheduler>): void;
+    private syncRecentRequests;
+    /**
+     * 原子落账：临时文件 + fsync + 原子 rename + 目录 fsync（0600）。
+     * 任一步失败清理临时文件并重新抛出——绝不产生半写文件。
+     */
+    private commit;
+    /** 加载账本；损坏/schema 不兼容 → 隔离原文件并以空账本重建（§17 损坏隔离）。 */
+    private load;
+    /** 损坏隔离：原文件 rename 为 `ledger-v2.json.corrupt-<ts>-<pid>-<uuid>`，原字节保留。 */
+    private quarantine;
+    private notify;
+    /**
+     * 获取单写者锁：`wx` 排他创建（已存在则 EEXIST 走锁主判定）。
+     * 锁记录 PID + token + 启动时间探测；PID 复用（启动时间不匹配）识别为陈旧锁
+     * 并接管；锁不可读时 fail closed（提示人工清理）。
+     */
+    private acquireLock;
+}

package/lib/types/host-routes.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 路由层（DSH-REQ-001 §11.1 三端点 + §16 安全栅栏）。
+ *
+ * 端点（同源，前缀 `/api/nova-task-board`）：
+ * - `GET  /api/nova-task-board/state`   → 全量快照 `{schemaVersion, revision,
+ *   tasks, scheduler, power, automationRules}`；
+ * - `POST /api/nova-task-board/action`  → 幂等信封 `{requestId, action}`，返回
+ *   新 snapshot；
+ * - `GET  /api/nova-task-board/events`  → SSE 推送 `{revision, scheduler,
+ *   power}`（15s 心跳注释帧），revision 变化时客户端重拉 state；
+ * - `POST /api/nova-task-board/webhooks/github` → GitHub `issues` 事件接收
+ *   （T010 §14.1）：HMAC-SHA256 签名校验（`X-Hub-Signature-256`，密钥来自
+ *   环境变量，不落配置）；未配置密钥 → 503；签名不匹配 → 401。该端点不走
+ *   浏览器同源栅栏（GitHub 无法携带浏览器信号），HMAC 即权威边界。
+ *
+ * 安全栅栏（§16.1/16.2/16.3）：
+ * - 浏览器同源标记（sec-fetch-site/Origin）为触发器而非权威校验——裸命令行
+ *   请求（curl 无任何浏览器信号）直接 403；权威边界是回环 socket + Host +
+ *   origin 等价校验（loopback.ts + isTrustedTaskBoardRequest）；
+ * - 同机认证反代必须白名单（trustedProxyHosts 规范化 authority）+ 服务端注入
+ *   token（`x-dsh-task-board-proxy-token`，timingSafeEqual 比较）；
+ * - POST 必须 application/json（否则 415）；普通 action ≤ 64 KiB、import /
+ *   propose-batch / start-split ≤ 2 MiB（超限 413）；非法信封/未知 action → 400
+ *   invalid-action；状态机守卫失败 → 400 + 错误信息。
+ */
+import type { IncomingMessage } from 'node:http';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { TaskBoardHostService } from './host-service.ts';
+/** 普通 action 载荷上限（§11.1）。 */
+export declare const ACTION_LIMIT: number;
+/** import（批量候选同限）载荷上限（§11.1）。 */
+export declare const IMPORT_LIMIT: number;
+/** SSE 心跳间隔（§17 性能：SSE 心跳 15s）。 */
+export declare const HEARTBEAT_MS = 15000;
+/** 同机认证反代在自身认证后替换注入的服务端 token 头（§16.1）。 */
+export declare const TASK_BOARD_PROXY_TOKEN_HEADER = "x-dsh-task-board-proxy-token";
+/** GitHub Webhook 签名头（HMAC-SHA256，`sha256=<hex>`，§14.1）。 */
+export declare const GITHUB_SIGNATURE_HEADER = "x-hub-signature-256";
+/** 路由访问面：默认仅回环 + 浏览器同源标记；反代须白名单 + token。 */
+export interface TaskBoardRouteAccess {
+    trustedProxyHosts?: readonly string[];
+    proxyToken?: string;
+    /** GitHub Webhook HMAC 密钥（env 解析，不落配置；缺省 = Webhook 端点不可用）。 */
+    webhookSecret?: string;
+}
+interface ResolvedRouteAccess {
+    trustedProxyHosts: ReadonlySet<string>;
+    proxyToken?: string;
+    webhookSecret?: string;
+}
+/** 解析访问面并校验白名单条目的规范化形态（配置错误直接 throw，插件加载失败）。 */
+export declare function resolveAccess(access: TaskBoardRouteAccess): ResolvedRouteAccess;
+/**
+ * GitHub Webhook 签名校验（§14.1）：`X-Hub-Signature-256: sha256=<hex>`，
+ * 对原始请求体做 HMAC-SHA256 并恒定时间比较。签名头缺失/畸形/不匹配 → false。
+ */
+export declare function verifyGithubSignature(rawBody: string, signature: string | string[] | undefined, secret: string): boolean;
+/**
+ * 请求级信任判定：浏览器同源标记 + （回环请求 | 白名单反代 + token）。
+ * 回环判定包含 socket 地址、Host 头与 origin 等价校验（loopback.ts）。
+ */
+export declare function isTrustedTaskBoardRequest(req: IncomingMessage, access: ResolvedRouteAccess): boolean;
+/** 组装三个端点路由（宿主的 webServer.register 对重复 (kind, path) 直接 throw，勿重复注册）。 */
+export declare function makeTaskBoardRoutes(service: TaskBoardHostService, access?: TaskBoardRouteAccess): WebRoute[];
+export {};

package/lib/types/host-runner.d.ts

@@ -0,0 +1,177 @@
+/**
+ * 真实执行与结算（DSH-REQ-001 §13，T005）。
+ *
+ * HostExecutionRunner 是「点击执行 → 独立 DSH 会话 → 按 turn 结算」的执行驱动：
+ *
+ * - **launch（§13.2）**：fail-closed 钉住目标——工作区必须存在于 workspace.list、
+ *   agent 预设必须存在且未损坏，任一失败直接抛错（服务层结算 failed，绝不发送
+ *   任务 Prompt）；随后创建独立会话（sessions.create，携带钉住的 workspaceId/
+ *   agentPreset）→ rename 为任务标题（**可失败但仅装饰**，§13.2）→ 钉住权限经
+ *   `/permission <id>` 命令应用（被拒/未匹配 → 失败）→ `sessions.prompt(mode:
+ *   'queue', text = prompt || title)`。会话创建后的失败包装为
+ *   `SessionLaunchError`（携带 sessionId，服务层先回填再结算，保留跳转线索）。
+ * - **listRunning（§13.3）**：轮询会话列表（会话列表 RPC 失败 → known:false，
+ *   服务层据此标记 sessionStateKnown=false）。
+ * - **inspect（§13.3）**：单条执行的结算判定——会话消失 → cancelled；仍在运行
+ *   → pending；已结束 → 翻页读历史，取时间 ≥ startedAt 的首条 `turn/end`
+ *   判定：`reason.kind === 'error'` → failed，否则 → succeeded。
+ *
+ * 依赖面（§17 可测试性）：本类只依赖 `ctx.apiProxy` 的窄子集（ExecutionApi）与
+ * 命令调度器（ExecutionCommandDispatcher，`/permission` 走宿主 commands
+ * 注册表、不经模型），测试注入 fake 即可脱离宿主单测；生产接线在 index.ts。
+ *
+ * 执行隔离（§16.4）：任务 Prompt 只作为发给 agent 的数据；权限只能经
+ * `/permission` 命令应用，Prompt 不能提权。
+ */
+import type { HistoryEntry, PromptContentPart, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { TaskRecord } from './core/model.ts';
+/** `/permission <id>` 命令的超时（对齐参考实现 30s）。 */
+export declare const PERMISSION_COMMAND_TIMEOUT_MS = 30000;
+/** inspect 历史翻页上限（对齐参考实现）。 */
+export declare const MAX_HISTORY_PAGES = 100;
+/** inspect 每页事件数（对齐参考实现）。 */
+export declare const HISTORY_PAGE_SIZE = 100;
+/** 会话列表行（inspect 所需的最小面；SDK SessionSummary 是其超集）。 */
+export interface ExecutionSessionRow {
+    sessionId: string;
+    running: boolean;
+}
+/** 5s 轮询的会话列表状态（§13.3）：RPC 失败时 known:false（服务层据此降级）。 */
+export type ExecutionSessionState = {
+    known: true;
+    count: number;
+    items: readonly ExecutionSessionRow[];
+} | {
+    known: false;
+};
+/** 单条执行的结算判定（§13.3）。 */
+export type ExecutionOutcome = 'pending' | 'cancelled' | 'failed' | 'succeeded';
+export interface ExecutionInspection {
+    outcome: ExecutionOutcome;
+    error?: string;
+    /** 本次执行（startedAt 之后）最近的 assistant 消息文本（B5：Host 侧摘取摘要源）。 */
+    lastAssistantText?: string;
+}
+/** `/permission <id>` 命令调度面（index.ts 接线到宿主 ctx.commands，见 §16.4）。 */
+export interface ExecutionCommandDispatcher {
+    /**
+     * 在会话上执行一条斜杠命令（不经模型）。undefined = 未被承认（命令名不匹配/
+     * 语法未解析）；kind:'error' = 被拒/未匹配。
+     */
+    execute(sessionId: string, line: string, signal: AbortSignal): Promise<{
+        kind: 'success';
+        text?: string;
+    } | {
+        kind: 'error';
+        text: string;
+    } | undefined>;
+}
+/**
+ * HostExecutionRunner 依赖的 API 窄面（ctx.apiProxy 的结构子集）。只声明
+ * launch/inspect 用到的域方法；生产传完整 ApiProxy（结构兼容），测试传 fake。
+ */
+export interface ExecutionApi {
+    workspace: {
+        list(request: RpcRequest<{}>): Promise<RpcResponse<{
+            items: Array<{
+                workspaceId: string;
+            }>;
+        }>>;
+    };
+    agentPresets: {
+        list(request: RpcRequest<{}>): Promise<RpcResponse<{
+            presets: readonly {
+                id: string;
+                broken?: string;
+            }[];
+        }>>;
+    };
+    sessions: {
+        create(request: RpcRequest<{
+            workspaceId?: string;
+            agentPreset?: string;
+        }>): Promise<RpcResponse<{
+            sessionId: SessionId;
+        }>>;
+        rename(request: RpcRequest<{
+            sessionId: string;
+            title: string;
+        }>): Promise<RpcResponse<{
+            title: string;
+            seq: number;
+        }>>;
+        prompt(request: RpcRequest<{
+            sessionId: SessionId;
+            mode: 'queue' | 'steer';
+            content: PromptContentPart[];
+            clientTimeZone?: string;
+        }>): Promise<RpcResponse<{
+            accepted: true;
+        }>>;
+        list(request: RpcRequest<{}>): Promise<RpcResponse<{
+            items: readonly ExecutionSessionRow[];
+        }>>;
+        history(request: RpcRequest<{
+            sessionId: string;
+            beforeSeq?: number;
+            maxMessages?: number;
+        }>): Promise<RpcResponse<{
+            events: HistoryEntry[];
+            hasMore: boolean;
+        }>>;
+    };
+}
+/** 会话创建后的启动失败：仍标识会话（服务层先回填 sessionId 再结算 failed）。 */
+export declare class SessionLaunchError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string, cause: unknown);
+}
+/** 会话 transcript 全文读取上限（T012/B8：拆分会话结果解析；防超大会话内存放大）。 */
+export declare const TRANSCRIPT_TEXT_LIMIT = 200000;
+/**
+ * 真实执行与结算驱动（§13.2/§13.3）。无状态、无计时器——轮询调度由
+ * TaskBoardHostService 持有（5s 间隔）；本类只做单次 launch/inspect。
+ */
+export declare class HostExecutionRunner {
+    private readonly api;
+    private readonly commands;
+    /** @param api - apiProxy 窄面（workspace/agentPresets/sessions 的读写子集）。 */
+    constructor(api: ExecutionApi, commands: ExecutionCommandDispatcher | undefined);
+    /**
+     * 启动一次执行（§13.2 流程）：
+     * 1. fail-closed 校验钉住目标（工作区存在、预设存在且未损坏）——任一失败抛
+     *    错，调用方结算 failed，**不发送任务 Prompt**；
+     * 2. `sessions.create` 创建独立会话（携带钉住的 workspaceId/agentPreset）；
+     * 3. rename 为任务标题（可失败但仅装饰）；权限经 `/permission` 命令应用
+     *    （被拒/未匹配 → 失败）；
+     * 4. `sessions.prompt(mode:'queue', text = prompt || title)`。
+     *
+     * 会话创建之后的任何失败抛 `SessionLaunchError`（携带 sessionId）。
+     * @returns 创建的会话 id。
+     */
+    launch(task: TaskRecord): Promise<string>;
+    /**
+     * 轮询会话列表（§13.3，5s 一次由服务层调度）。RPC 失败/不可用 → known:false
+     * （服务层据此把 sessionStateKnown 置 false，不据此结算）。
+     */
+    listRunning(): Promise<ExecutionSessionState>;
+    /**
+     * 单条执行的结算判定（§13.3）：
+     * - 会话不在列表中 → cancelled（`execution session no longer exists`）；
+     * - 会话仍在运行 → pending；
+     * - 已结束 → 翻页读历史直到越过 startedAt 边界，取时间 ≥ startedAt 的首条
+     *   `turn/end`：reason.kind==='error' → failed，否则 → succeeded；边界内无
+     *   turn/end（如 prompt 从未被消费）→ pending（保持观察）。
+     * @param sessions - 本次轮询已取的会话列表（避免 1 + E 次 list RPC，对齐参考
+     *   实现）；缺省时自行拉取。
+     */
+    inspect(sessionId: string, startedAt: number, sessions?: readonly ExecutionSessionRow[]): Promise<ExecutionInspection>;
+    /**
+     * 读取会话 transcript 全文（T012/B8：拆分会话结果解析用）。翻页读取历史事件，
+     * 拼接全部 assistant 消息文本（顺序拼接、换行分隔；总长封顶
+     * TRANSCRIPT_TEXT_LIMIT）。会话不存在/历史不可读 → undefined（调用方按失败
+     * 处理）。拆分会话是独立专用会话，全文即拆分结果（无需按 startedAt 截取）。
+     */
+    readTranscriptText(sessionId: string): Promise<string | undefined>;
+}