@shgroup/dsh-serenity-hooks 1.30.5 → 1.30.8

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.30.5",
+  "version": "1.30.8",
   "main": "lib/index.js",
   "description": "宁静号 ACC harness（Native Cordis 插件）：真实 DSH 工具 container_fs/logbook/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/autopilot-trajectory + 拦截缝机械约束（safe-mode/路径守卫）+ 高级设定面板（双端口网关/账号管理）+ Skiff 认知子集角色（实验性）。适配 DSH 公开版（0.1.0-rc，deepseek-ai/deepseek-harness）。",
   "engines": {

package/lib/access-CdL6BAYj.js

@@ -0,0 +1,49 @@
+//#region src/host/access.ts
+/**
+* host/access.ts — 宿主访问收口（S142 review F-06）
+*
+* 为什么存在：dsp 此前在 30+ 个文件里各自用 `(ctx as unknown as {…})` 断言读取宿主
+* 服务——契约表达分散、失败模式各异（多数静默 undefined）。本模块是**唯一**读取宿主
+* 的入口：所有 `ctx.get` / `ctx.<service>` 的形状断言集中在此，调用点只拿类型化结果。
+*
+* 约定：
+*  - 只读、无副作用；服务缺失一律返回 `undefined`（调用方决定降级策略），**不抛错**
+*    （宿主对插件 apply 抛错 = 整个 dsh 启动失败，访问层不能成为单点）。
+*  - 形状以 `AI_LAB/dsh-harness-public` @ 0.1.2-rc.1 为准；成员缺失由
+*    `host/contract.ts` 的探针在装载时与 `dashboard health` 中报告。
+*  - 迁移是渐进的：新代码必须走本模块；旧调用点逐轮收敛（F-06 轮次记录见 CHANGELOG）。
+*/
+/** 通用读取：`ctx.get(name)`（含异常吞掉——服务 getter 抛错视为不可用） */
+function hostService(ctx, name) {
+	const c = ctx;
+	if (typeof c?.get !== "function") return void 0;
+	try {
+		return c.get(name);
+	} catch {
+		return;
+	}
+}
+/** 直接属性读取（injected 服务：`ctx.<name>`），属性缺失时回落 `ctx.get` */
+function hostInjected(ctx, name) {
+	const direct = ctx?.[name];
+	if (direct !== void 0) return direct;
+	return hostService(ctx, name);
+}
+/** `ctx.sessions`（injected） */
+function hostSessions(ctx) {
+	return hostInjected(ctx, "sessions");
+}
+/** `ctx.agents`（injected） */
+function hostAgents(ctx) {
+	return hostInjected(ctx, "agents");
+}
+/** `ctx.webServer`（injected） */
+function hostWebServer(ctx) {
+	return hostInjected(ctx, "webServer");
+}
+/** `ctx.settings`（injected；提供 settings 面板装配通道） */
+function hostSettings(ctx) {
+	return hostInjected(ctx, "settings");
+}
+//#endregion
+export { hostSettings as a, hostSessions as i, hostInjected as n, hostWebServer as o, hostService as r, hostAgents as t };

package/lib/acp-core.d.ts

@@ -77,7 +77,7 @@ export declare class AcpServer {
      * 3100 对外只提供问答，轨迹含工具结果等内部信息；3099 调试页另走 /ask 保留）
      */
     private prompt;
-    /** session/cancel：{ sessionId } → 中断当前 prompt（DSH interrupt） */
+    /** session/cancel：{ sessionId } → 取消该会话的当前活动（Agent.cancel，宿主 rc.1 契约） */
     private cancel;
     /** session/close：{ sessionId } → 释放 agent + 注册表清理（进程内） */
     private closeSession;

package/lib/agent-idle.d.ts

@@ -0,0 +1,27 @@
+/**
+ * agent-idle.ts — 等待 agent 空闲（含销毁竞速，S142 review F-08）
+ *
+ * 为什么单独成模块：`askSkiff`（skiff 问答）与 `handyman`（杂工循环）都要"等这一轮做完"，
+ * 此前各自复制了一份只监听 `agent/status → idle` 的实现。该实现有一个静默挂死：
+ * **agent 先被销毁（会话关闭/进程回收/显式 dispose）就永远不会再发 idle 事件**，
+ * 等待方 Promise 永不结算 → 问答/杂工永久卡住（宿主的 disposal 语义：
+ * `core/agent-loop/src/agent.ts` 的 wakeDriver 在 disposed 后不再 latch 唤醒）。
+ *
+ * 结算条件（三者任一，先到先算）：
+ *  ① `agent/status` 且 status === 'idle' —— 正常路径（本轮做完）
+ *  ② `agent/disposed` 且是同一个 agent —— 销毁竞速（宿主 `runtime-types.ts:175`）
+ *  ③ `session/disposed` 且是同一会话 —— 会话先于 agent 消失（宿主 `core/session/src/index.ts:62`）
+ *
+ * 无超时：agent 工作多久等多久（handyman 可永续）。订阅后再查一次 `agent.status`——
+ * 宿主 `followup`/`steer` 会同步把 phase 置为 running（`agent.ts:181-201`），
+ * 因此此刻读到 idle 只可能是"唤醒已在订阅前收敛"，立即结算以避免漏事件挂死。
+ */
+import type { Context } from 'cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+/**
+ * 等待 agent 空闲或销毁。
+ * @param ctx 宿主插件上下文（事件通道来源）
+ * @param agent 目标 agent
+ * @returns 空闲、agent 销毁、或会话销毁时结算（永不 reject）
+ */
+export declare function waitAgentIdle(ctx: Context, agent: Agent): Promise<void>;

package/lib/{ccc-CX48YNUL.js → ccc-DAsSHsub.js}

@@ -106,13 +106,34 @@ const DEFAULT_SERENITY_CONFIG_PATHS = [".opencode/serenity.json", ".dsh/serenity
 function readUtf8(path) {
 	return readFileSync(path, "utf-8").replace(/^\uFEFF/, "");
 }
+/**
+* 已告警过的损坏配置路径（进程级去重：同一坏文件不刷屏，但绝不静默）。
+* S142 review F-07：此前损坏 → 静默返回 `{}`——安全模式黑名单/handyman 白名单/skiff 角色
+* 全部**无声失效**（用户以为配了，实际没配）。守卫的输入失败必须响亮。
+*/
+const warnedBrokenConfigs = /* @__PURE__ */ new Set();
+/**
+* 读取 CCC 配置（第一个存在且可解析的候选路径）。
+*
+* 失败语义（F-07）：文件存在但**解析失败** → 记录响亮告警（含路径与原因，每路径一次）
+* 并返回 `{}`。选择 fail-open 而非抛错的理由：apply 期抛错 = 整个 dsh 启动失败
+* （app-boot "plugin(s) failed to load"），而单个 CCC 配置损坏只应影响该 CCC 的功能降级；
+* 告警 + `dashboard health` 让损坏可见可修。
+* @param root CCC 根
+* @param paths 候选相对路径（按序取第一个存在的）
+* @returns 解析后的配置；无文件/损坏 → `{}`
+*/
 function loadSerenityConfig(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
 	for (const candidate of paths) {
 		const p = resolve(root, candidate);
 		if (!existsSync(p)) continue;
 		try {
 			return JSON.parse(readUtf8(p));
-		} catch {
+		} catch (err) {
+			if (!warnedBrokenConfigs.has(p)) {
+				warnedBrokenConfigs.add(p);
+				console.warn(`[serenity-hooks] ✗ CCC 配置解析失败，已按空配置继续（该 CCC 的安全模式黑名单/handyman 白名单/skiff 角色等全部失效，请修 JSON）: ${p} — ${String(err?.message ?? err)}`);
+			}
 			return {};
 		}
 	}

package/lib/ccc.d.ts

@@ -201,6 +201,19 @@ export declare const DEFAULT_SERENITY_CONFIG_PATHS: string[];
  * 写出的 BOM（\uFEFF）会让 JSON.parse 抛错（配置静默变空）或 frontmatter 检测失败（技能被丢弃）。
  */
 export declare function readUtf8(path: string): string;
+/** 测试辅助：清空"已告警"记忆（生产零调用） */
+export declare function __resetBrokenConfigWarningsForTest(): void;
+/**
+ * 读取 CCC 配置（第一个存在且可解析的候选路径）。
+ *
+ * 失败语义（F-07）：文件存在但**解析失败** → 记录响亮告警（含路径与原因，每路径一次）
+ * 并返回 `{}`。选择 fail-open 而非抛错的理由：apply 期抛错 = 整个 dsh 启动失败
+ * （app-boot "plugin(s) failed to load"），而单个 CCC 配置损坏只应影响该 CCC 的功能降级；
+ * 告警 + `dashboard health` 让损坏可见可修。
+ * @param root CCC 根
+ * @param paths 候选相对路径（按序取第一个存在的）
+ * @returns 解析后的配置；无文件/损坏 → `{}`
+ */
 export declare function loadSerenityConfig(root: string, paths?: string[]): SerenityConfig;
 export declare const SAFE_MODE_MARKER = ".serenity-safe-on";
 export declare function isSafeModeOn(root: string): boolean;

package/lib/gateway-proxy.d.ts

@@ -29,6 +29,27 @@ export declare function filterWorkspaceList(body: string, allowPrefixes: readonl
 export declare function workspaceAllowed(allowPrefixes: readonly string[], path: string | undefined): boolean;
 /** 构造 workspace.create 拒绝的 JSON RPC 响应体（code=forbidden） */
 export declare function workspaceDenyResponse(rpcId: string): string;
+/**
+ * 判定 workspace 创建请求的端点（v1.30.6，review F-03）。
+ *
+ * 宿主 rc.1 的 Remote 端点由 `typertEndpoint({namespace,method})` 派生为
+ * `workspace/create`，因此浏览器实际请求 `POST /api/workspace/create`
+ * （packages/typert/registry/src/service.ts:63-69；client/connection/src/client/rpc.ts:44）。
+ * 旧实现只匹配 `/api/workspace.create` → 该分支从未命中，外部白名单与禁建校验失效。
+ * 保留旧端点以兼容旧宿主。
+ */
+export declare function isWorkspaceCreatePath(pathname: string): boolean;
+/**
+ * 从 workspace 创建请求体解析 `{ rpcId, path }`（v1.30.6，review F-03）。
+ *
+ * rc.1 wire 信封：`{ type:'client-request', rpcId, method:'workspace/create',
+ * payload:{ args:{ path } } }`（packages/api/gateway/src/index.ts:955 `args: payload.args`）；
+ * 旧宿主为 `payload.path`。解析失败返回 rpcId='unknown' + path=undefined。
+ */
+export declare function parseWorkspaceCreateBody(body: string): {
+    rpcId: string;
+    path?: string;
+};
 /**
  * 在 HTML 的 </head> 前注入 polyfill（幂等：含 marker 则跳过）
  */

package/lib/gateway.d.ts

@@ -27,7 +27,7 @@
  */
 import type { Context } from 'cordis';
 import { type Server } from 'node:http';
-export { RANDOM_UUID_POLYFILL, injectPolyfillHtml, filterWorkspaceList, workspaceAllowed, workspaceDenyResponse, buildProxyHeaders, transformHtmlForProxy, } from './gateway-proxy.js';
+export { RANDOM_UUID_POLYFILL, injectPolyfillHtml, filterWorkspaceList, workspaceAllowed, workspaceDenyResponse, isWorkspaceCreatePath, parseWorkspaceCreateBody, buildProxyHeaders, transformHtmlForProxy, } from './gateway-proxy.js';
 export { loginPageHtml, verifyGatewayLogin, SESSION_TTL_MS, issueToken, revokeToken, validateToken, FAIL_LOCK_THRESHOLD, FAIL_LOCK_BASE_MS, FAIL_LOCK_MAX_MS, getFailState, resetFailState, isAccountLocked, recordLoginFailure, accountLockRemaining, newCsrfToken, isCsrfValid, csrfFromRequest, safeEqual, originAllowed, cookieValue, } from './gateway-auth.js';
 declare module 'cordis' {
     interface Events {

package/lib/host/access.d.ts

@@ -0,0 +1,53 @@
+/**
+ * host/access.ts — 宿主访问收口（S142 review F-06）
+ *
+ * 为什么存在：dsp 此前在 30+ 个文件里各自用 `(ctx as unknown as {…})` 断言读取宿主
+ * 服务——契约表达分散、失败模式各异（多数静默 undefined）。本模块是**唯一**读取宿主
+ * 的入口：所有 `ctx.get` / `ctx.<service>` 的形状断言集中在此，调用点只拿类型化结果。
+ *
+ * 约定：
+ *  - 只读、无副作用；服务缺失一律返回 `undefined`（调用方决定降级策略），**不抛错**
+ *    （宿主对插件 apply 抛错 = 整个 dsh 启动失败，访问层不能成为单点）。
+ *  - 形状以 `AI_LAB/dsh-harness-public` @ 0.1.2-rc.1 为准；成员缺失由
+ *    `host/contract.ts` 的探针在装载时与 `dashboard health` 中报告。
+ *  - 迁移是渐进的：新代码必须走本模块；旧调用点逐轮收敛（F-06 轮次记录见 CHANGELOG）。
+ */
+/** 通用读取：`ctx.get(name)`（含异常吞掉——服务 getter 抛错视为不可用） */
+export declare function hostService<T = unknown>(ctx: unknown, name: string): T | undefined;
+/** 直接属性读取（injected 服务：`ctx.<name>`），属性缺失时回落 `ctx.get` */
+export declare function hostInjected<T = unknown>(ctx: unknown, name: string): T | undefined;
+export interface HostSessionLike {
+    id?: string;
+    header?: {
+        cwd?: string;
+        id?: string;
+    };
+    snapshotEvents?: () => unknown[];
+}
+export interface HostSessions {
+    list?: () => HostSessionLike[];
+    get?: (id: unknown) => HostSessionLike | undefined;
+    create?: (...args: unknown[]) => unknown;
+}
+export interface HostAgents {
+    create?: (...args: unknown[]) => unknown;
+    get?: (id: string) => unknown;
+    resume?: (...args: unknown[]) => unknown;
+}
+export interface HostWebServer {
+    register?: (registration: unknown) => unknown;
+    port?: number;
+}
+export interface HostSettings {
+    installSection?: (...args: unknown[]) => unknown;
+}
+/** `ctx.sessions`（injected） */
+export declare function hostSessions(ctx: unknown): HostSessions | undefined;
+/** `ctx.agents`（injected） */
+export declare function hostAgents(ctx: unknown): HostAgents | undefined;
+/** `ctx.webServer`（injected） */
+export declare function hostWebServer(ctx: unknown): HostWebServer | undefined;
+/** `ctx.settings`（injected；提供 settings 面板装配通道） */
+export declare function hostSettings(ctx: unknown): HostSettings | undefined;
+/** 会话 cwd 列表（live 会话；形状不符时返回空数组而非抛错） */
+export declare function hostSessionCwds(ctx: unknown): string[];

package/lib/host/contract.d.ts

@@ -0,0 +1,99 @@
+/**
+ * host/contract.ts — 宿主契约声明 + 运行时探针（S142 review F-05/F-06）
+ *
+ * 为什么存在（R↓）：dsp 与宿主（DeepSeek Harness）的契约此前以**散落的类型断言**
+ * 表达——37 个文件里 80 处 `as unknown as`，类型检查被断言抹掉、运行时无校验，
+ * 于是宿主改名/移除成员时 dsp **静默失效**：v1.30.5 的错误码漂移
+ * （`attachment-error` → `session/attachment-invalid`）与更早的 `Session.events`
+ * → `snapshotEvents()` 都是这一类。
+ *
+ * 本模块把契约集中声明为**数据**（单一真相源），并提供纯函数探针
+ * `probeHostContract(ctx)`：在插件装载时与 `dashboard health` 中核对
+ * "运行中的宿主是否仍满足 dsp 依赖的服务与成员"。
+ *
+ * 设计约束：
+ *  - **零宿主 import**：只用结构化读取（`ctx.get` / 属性），因此 peer-only 打包
+ *    （宿主依赖不进 dsp 的 node_modules）下也成立。
+ *  - **事件名不在运行时探**：宿主事件是字符串键，`ctx.on` 对未知名不报错——
+ *    事件名的正确性由**编译期契约测试**保证（tests/host-contract.test.ts 用真实
+ *    宿主类型断言），此处只登记清单供文档/测试共用。
+ *  - **缺失分级**：`required` = 缺失即 ACC 核心能力失效；否则为可降级能力。
+ */
+export type HostAccess = 'injected' | 'lazy';
+export interface HostMember {
+    name: string;
+    kind: 'function' | 'value';
+}
+export interface HostServiceContract {
+    /** 稳定标识（报告用） */
+    id: string;
+    /** 服务名（`ctx.get(name)` 或 `ctx.<name>`） */
+    name: string;
+    /** injected = cordis inject 保证存在；lazy = 运行期按需取（可能 undefined） */
+    access: HostAccess;
+    /** 依赖的成员（空 = 只要求服务存在） */
+    members: readonly HostMember[];
+    /** 缺失时的后果（人读，进 health 报告） */
+    impact: string;
+    /** 缺失是否致命 */
+    required: boolean;
+}
+/** dsp 依赖的宿主服务与成员（对照 AI_LAB/dsh-harness-public @ 0.1.2-rc.1 逐一核对） */
+export declare const HOST_SERVICES: readonly HostServiceContract[];
+export interface HostEventContract {
+    name: HostEventName;
+    /** 订阅方（文件） */
+    site: string;
+    impact: string;
+    required: boolean;
+}
+/**
+ * **编译期契约**：事件名必须存在于宿主合并后的 `Events` 映射。
+ *
+ * 这是运行时无法验证的那一半——宿主事件是字符串键，`ctx.on('typo')` 不会报错，
+ * 只会静默不订阅。`satisfies readonly (keyof Events)[]` 让 `dsh-develop typecheck`
+ * 在名字写错/宿主改名时**编译失败**（v1.30.7，review F-04/F-05）。
+ * 该 import 为 type-only，编译期擦除，不产生运行时依赖。
+ */
+export declare const HOST_EVENT_NAMES: readonly ["agent/session-start", "agent/pre-step", "agent/turn-stopping", "agent/status", "agent/inbox/inserted", "session/event", "session/created", "tools/pre-execute", "tools/post-execute", "system-prompt/assemble"];
+export type HostEventName = (typeof HOST_EVENT_NAMES)[number];
+/**
+ * dsp 订阅的宿主事件清单（与 HOST_EVENT_NAMES 同源；impact/site 供 health 报告与文档）。
+ */
+export declare const HOST_EVENTS: readonly HostEventContract[];
+/** dsp 被验证过的宿主版本范围（与 package.json peerDependencies 同源，单一真相源） */
+export declare const REQUIRED_HOST_RANGE = "^0.1.2-rc.1";
+export interface HostContractIssue {
+    id: string;
+    kind: 'service' | 'member' | 'version';
+    detail: string;
+    impact: string;
+    required: boolean;
+}
+export interface HostContractReport {
+    ok: boolean;
+    checked: number;
+    hostVersion: string | null;
+    versionOk: boolean;
+    issues: HostContractIssue[];
+}
+/** 最小 semver 比较（无依赖）：返回 -1 / 0 / 1；解析失败返回 null */
+export declare function compareSemver(a: string, b: string): number | null;
+/**
+ * 宿主版本是否落在 dsp 被验证的范围（`^0.1.2-rc.1`）。
+ * 无版本信息 → 视为未知（ok=false，detail 说明），不猜测。
+ */
+export declare function checkHostVersion(version: string | null): {
+    ok: boolean;
+    detail: string;
+};
+/**
+ * 探针：核对运行中的宿主是否仍满足 dsp 依赖的服务与成员。
+ *
+ * @param ctx 宿主插件上下文（真实 cordis Context；测试可传结构化替身）
+ * @param hostVersion 运行中宿主版本（`readDshVersion()` 结果；null = 未知）
+ * @returns 报告（`ok:false` 时 `issues` 逐条给出缺失项与后果）
+ */
+export declare function probeHostContract(ctx: unknown, hostVersion?: string | null): HostContractReport;
+/** 单行摘要（启动告警用） */
+export declare function summarizeHostContract(report: HostContractReport): string;

package/lib/host/effect.d.ts

@@ -0,0 +1,24 @@
+/**
+ * host/effect.ts — 插件资源拆卸登记（S142 review F-08）
+ *
+ * 宿主把"注册即效果"作为统一模型：每个贡献都走 `ctx.effect()` / `ctx.on()`，
+ * 注册返回 disposer，fiber 销毁时自动回收（`cordis` Context.effect，rc.1 全量使用，
+ * 如 `core/tools/src/index.ts:943`）。
+ *
+ * 本模块是 dsp 各装配点登记自起资源（端口监听器/定时器/轮询器）的**唯一入口**，
+ * 理由：
+ *  - `ctx.effect` 是宿主成员，但**不可假定存在**（测试替身、极旧宿主、HMR 早期阶段）。
+ *    直接裸调会让 `apply` 抛错 = 整个 dsh 启动失败（app-boot "plugin(s) failed to load"），
+ *    这比"资源没拆卸"严重得多——所以缺失时**响亮降级**（记录 + 返回 false）。
+ *  - 零依赖叶模块：gateway / autopilot 等模块只引它，不会因此被拖进 skiff/rebuild 的依赖链。
+ */
+/** 测试辅助：重置"未装配"告警去重（生产零调用） */
+export declare function __resetDisposerWarningsForTest(): void;
+/**
+ * 登记一个卸载时执行的清理。
+ * @param ctx 宿主插件上下文
+ * @param label 日志标签（定位是哪个资源未装配）
+ * @param cleanup 卸载时执行；抛错被吞掉（不阻断其它清理）
+ * @returns 是否成功装配（false = 宿主无 `ctx.effect`，已告警）
+ */
+export declare function registerDisposer(ctx: unknown, label: string, cleanup: () => void): boolean;