@shgroup/dsh-serenity-hooks 1.34.0 → 1.34.2

package/lib/fs-ops.d.ts

@@ -10,7 +10,7 @@
  * 保留 dsp 增强：win32 reveal 用 spawn+unref（explorer GUI 进程退出码不可靠，fire-and-forget）。
  */
 import type { JsonValue } from './json.js';
-export type CcFsAction = 'root' | 'resolve' | 'exists' | 'list' | 'tree' | 'relative' | 'mkdir' | 'rm' | 'mv' | 'cp' | 'touch' | 'append' | 'reveal' | 'info' | 'find';
+type CcFsAction = 'root' | 'resolve' | 'exists' | 'list' | 'tree' | 'relative' | 'mkdir' | 'rm' | 'mv' | 'cp' | 'touch' | 'append' | 'reveal' | 'info' | 'find';
 export declare const CC_FS_ACTIONS: readonly CcFsAction[];
 export interface CcFsArgs {
     action: CcFsAction;
@@ -32,5 +32,6 @@ export interface CcFsArgs {
     /** 对齐 osp：find 最大递归深度（缺省不限） */
     maxDepth?: number;
 }
-export type CcFsResult = JsonValue;
+type CcFsResult = JsonValue;
 export declare function runCcFs(root: string, args: CcFsArgs): CcFsResult;
+export {};

package/lib/gateway-auth.d.ts

@@ -37,7 +37,7 @@ export declare const FAIL_LOCK_THRESHOLD = 5;
 export declare const FAIL_LOCK_BASE_MS: number;
 /** 锁定时长指数退避上限 */
 export declare const FAIL_LOCK_MAX_MS: number;
-export interface FailState {
+interface FailState {
     /** 连续失败计数（成功登录后清零） */
     count: number;
     /** 当前锁定截止时间（0 = 未锁定） */
@@ -55,10 +55,6 @@ export declare function isAccountLocked(user: string): boolean;
 export declare function recordLoginFailure(user: string): number;
 /** 剩余锁定毫秒（0 = 未锁定） */
 export declare function accountLockRemaining(user: string): number;
-/** CSRF token 有效期（毫秒）：10 分钟窗口（扫码/多标签场景留足时间） */
-export declare const CSRF_TTL_MS: number;
-/** CSRF token 集合上限（防内存膨胀；超限清理最旧） */
-export declare const CSRF_MAX_TOKENS = 50;
 /** 生成 CSRF token（随机 32B hex）并入集合 */
 export declare function newCsrfToken(): string;
 /** token 是否有效（在集合且未过期；过期自动清理） */
@@ -87,3 +83,4 @@ export declare function cookieValue(header: string | undefined, name: string): s
  * @param csrf - CSRF token（隐藏字段随表单双提交；无 = 旧调用方兼容）
  */
 export declare function loginPageHtml(extra: string, csrf?: string): string;
+export {};

package/lib/gateway.d.ts

@@ -26,7 +26,6 @@
  * 保持既有 import 面兼容（tests/gateway.test.ts 直接 import 两模块导出）。
  */
 import type { Context } from 'cordis';
-import { type Server } from 'node:http';
 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' {
@@ -37,39 +36,6 @@ declare module 'cordis' {
         'serenity/settings-changed'(): void;
     }
 }
-export interface GatewayConfig {
-    host: string;
-    port: number;
-    /** 登录态 cookie 名 */
-    cookieName: string;
-    /** 主端口（ctx.webServer.port） */
-    mainPort: number;
-    /** 登录失败后的重定向延迟（秒） */
-    loginDelayMs: number;
-    /** 外部可访问的工作区路径前缀白名单（v1.22；空 = 全部允许） */
-    allowWorkspaces?: string[];
-    /** Cookie Secure 属性（v1.22.4；反代 TLS 时开启；明文 HTTP 下必须关，否则 cookie 不落） */
-    cookieSecure?: boolean;
-    /** 允许外部新建工作区（v1.22.4；false = workspace.create 一律 403 RPC error） */
-    allowWorkspaceCreate?: boolean;
-    /** 启用 Authenticator 第二因素（v1.22.4；false = TOTP 完全禁用） */
-    totpEnabled?: boolean;
-}
-/**
- * 启动第二监听器。返回 { server, dispose }——dispose 关 server（**不清 token**：
- * token 模块级，进程重启自然清空；热重建清 token → 已登录用户 WS 断 + 重连 cookie 无效）。
- * @param config - 监听/代理配置。
- * @param getAccounts - 运行时读取账号列表（plugin 全局文件；gateway.enabled 开关在调用方判）。
- */
-export declare function startGateway(config: GatewayConfig, getAccounts: () => readonly {
-    id: string;
-    user: string;
-    passHash: string;
-    totpSecret?: string;
-}[], getDshCookie?: () => string | undefined): {
-    server: Server;
-    dispose: () => void;
-};
 /** 注册 gateway（index.ts apply 调用）。
  * 归属原则（v1.22）：gateway 是 plugin 全局能力——enabled 开关读 DSH settings
  * （readSimpleSettings().gatewayEnabled），host/port/accounts 读 plugin 全局文件

package/lib/git-ops.d.ts

@@ -11,9 +11,9 @@
  * 保留 dsp 增强：localstore git 合规联动（S134：deny 且 .gitignore 未覆盖 → status 提示 / commit 拒绝）。
  */
 import type { JsonValue } from './json.js';
-export type GitAction = 'status' | 'commit' | 'push' | 'log' | 'pull' | 'diff';
+type GitAction = 'status' | 'commit' | 'push' | 'log' | 'pull' | 'diff';
 export declare const GIT_ACTIONS: readonly GitAction[];
-export interface GitArgs {
+interface GitArgs {
     action: GitAction;
     message?: string;
     /** log 条数（对齐 osp 参数 n，默认 10，max 100） */
@@ -26,3 +26,4 @@ export interface GitArgs {
     path?: string;
 }
 export declare function runGit(root: string, args: GitArgs): JsonValue;
+export {};

package/lib/handyman-ops.d.ts

@@ -5,7 +5,7 @@
  * 进度文件（handyman-<label>.md/.json）、续跑、轮次 prompt 结构、stop token。
  * 不兼容旧 loop- 进度文件（用户拍板：仅新 handyman- 前缀）。
  */
-export interface HandymanProgress {
+interface HandymanProgress {
     round: number;
     done: boolean;
     label: string;
@@ -56,7 +56,7 @@ export declare function buildRoundPrompt(opts: {
  */
 export declare const HANDYMAN_GUIDE = "# handyman \u2014 Scale-Up Usage Guide (guide)\n\n## Two modes (v1.31.3; default = foreground)\n| | foreground (default) | background |\n|---|---|---|\n| What | one serial child agent runs the task ONCE and returns its final text | loop-validated worker: hard while-loop + random completion code |\n| Use when | you need exactly one result back now (per-case testers, single conversions) | long/unattended work needing anti-early-finish, resumability, or parallel jobs |\n| Loop / validation | none | stop-token is the ONLY completion condition; round cap (default 100); auto-restart (\u2264100) |\n| Progress file | none | AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes) |\n| Parallel jobs | no (call once per task) | yes (jobs=[...], handyman.maxParallel default 10) |\n| Mechanism | host delegation service ctx.subagents.start(\"spawn\") + agentOptions | ctx.agents.create + internal while-loop |\n| Model source | CCC handyman.models whitelist (same for both) | same |\n\n## \u26A0\uFE0F Before using: load eap and design the plan\nBefore calling handyman, load eap (acc-eap skill) and design the \"scale-up handyman plan\" based on the EAP framework.\n\n### 1. Task decomposition (E\u2191 Explicit)\n- Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria\n- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel (background mode)\n\n### 2. Prompt design (handyman's task parameter)\n- task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria\n- foreground mode: the child does NOT share your conversation \u2014 restate everything it needs in task\n- Anti-example \"handle this file\" \u2014 ambiguous; good example \"read <path>, extract all rows of the\u300C\u5173\u952E\u51B3\u7B56\u300Dtable,\n  output a JSON array (fields id/conclusion/evidence), do not modify the original file\"\n- Reading/curating or text-writing work (extracting from files, summarizing, writing docs, generating text, etc.):\n  the handyman-internal agent is also required to load eap and organize output per the EAP standard\n\n### 3. Model whitelist (CCC-configured, mandatory)\n- handyman only uses models listed in .opencode/serenity.json \"handyman.models\" \u2014 never arbitrary models\n- The CCC is expected to point this whitelist at LOW-COST models: handyman is the bulk-execution channel\n- background mode: recursive subagents inside a worker inherit the worker's model automatically (DSH native)\n- foreground mode: the child is started through the host delegation service with the resolved model\n\n### 4. Parallel strategy (background mode only)\n- Independent subtasks can run in parallel via handyman(mode=\"background\", jobs=[...]): each job gets its own label + task + stop token + progress file\n- Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label\n  (AGENT_SESSIONS/handyman-<label>.json) \u2014 same label resumes, different labels never interfere\n- Parallel cap: handyman.maxParallel (default 10 \u2014 cheap models are cheap)\n- Aggregation: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)\n- For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead\n\n## Completion criteria\n- foreground: the child's run settles; done=true only when stopReason=\"completed\" (otherwise read diagnostic)\n- background (osp loop standard): the only completion condition = the worker echoes this round's random verification\n  code (stop token); dialogue round cap (default 100, osp fail-safe, forced stop beyond the cap, resumable);\n  automatic restart on abnormal agent stop (\u2264100 restarts, anti-infinite-loop)\n\n## Waiting UI\n- The WebUI session-header Serenity detail card shows running background handymen's progress\n  (label / round / last response), one line per parallel job, ~3s refresh (foreground mode writes no progress)\n";
 /** handyman 运行状态（进度文件摘要；WebUI 等待界面数据源） */
-export interface HandymanRunInfo {
+interface HandymanRunInfo {
     label: string;
     round: number;
     done: boolean;
@@ -66,3 +66,4 @@ export interface HandymanRunInfo {
 }
 /** 列出 AGENT_SESSIONS/handyman-*.json 的全部进度（按 updated 倒序；坏文件跳过） */
 export declare function listActiveHandymen(root: string): HandymanRunInfo[];
+export {};

package/lib/handyman-preset-inherit.d.ts

@@ -20,7 +20,7 @@
  */
 import type { Context } from 'cordis';
 /** 从父 agent ctx 解析 preset 继承的创建期组合。 */
-export interface HandymanPresetInheritance {
+interface HandymanPresetInheritance {
     /** 父 agent 的 preset id（写入子 session meta.agentPreset，供持久化重建）；无则不写。 */
     readonly agentPreset?: string;
     /** 创建 setup 钩子：子 scope join 父的 standing preset + deny handyman 工具；无 preset 继承时仅 deny。 */
@@ -32,3 +32,4 @@ export interface HandymanPresetInheritance {
  * @returns 继承结果：meta 用的 agentPreset 与创建 setup 钩子。
  */
 export declare function handymanPresetInheritance(parentCtx: Context | undefined): HandymanPresetInheritance;
+export {};

package/lib/host/access.d.ts

@@ -33,7 +33,7 @@ export declare function hostService<T = unknown>(ctx: unknown, name: string): T
  * （宿主对插件 apply 抛错 = 整个 dsh 启动失败）。读取失败 = 服务不可用，等价于缺失。
  */
 export declare function hostInjected<T = unknown>(ctx: unknown, name: string): T | undefined;
-export interface HostSessionLike {
+interface HostSessionLike {
     id?: string;
     header?: {
         cwd?: string;
@@ -41,25 +41,25 @@ export interface HostSessionLike {
     };
     snapshotEvents?: () => unknown[];
 }
-export interface HostSessions {
+interface HostSessions {
     list?: () => HostSessionLike[];
     get?: (id: unknown) => HostSessionLike | undefined;
     create?: (...args: unknown[]) => unknown;
 }
-export interface HostAgents {
+interface HostAgents {
     create?: (...args: unknown[]) => unknown;
     get?: (id: string) => unknown;
     resume?: (...args: unknown[]) => unknown;
 }
-export interface HostWebServer {
+interface HostWebServer {
     register?: (registration: unknown) => unknown;
     port?: number;
 }
-export interface HostSettings {
+interface HostSettings {
     installSection?: (...args: unknown[]) => unknown;
 }
 /** `ctx.web`（injected；v1.30.12：fetch provider 注册通道） */
-export interface HostWeb {
+interface HostWeb {
     registerFetchProvider?: (provider: unknown) => unknown;
     registerSearchProvider?: (provider: unknown) => unknown;
 }
@@ -82,9 +82,10 @@ export declare function hostWeb(ctx: unknown): HostWeb | undefined;
  * 注（v1.31.4）：本服务**不在** dsp 的 `inject` 列表内，因此走 `hostInjected` 的
  * 回落分支（`ctx.get`）——见 `hostInjected` 的 v1.31.4 说明与真实 cordis 用例。
  */
-export interface HostSubagents {
+interface HostSubagents {
     start?: (name: string, request: unknown) => Promise<unknown>;
 }
 export declare function hostSubagents(ctx: unknown): HostSubagents | undefined;
 /** 会话 cwd 列表（live 会话；形状不符时返回空数组而非抛错） */
 export declare function hostSessionCwds(ctx: unknown): string[];
+export {};

package/lib/host/contract.d.ts

@@ -19,12 +19,12 @@
  *    宿主类型断言），此处只登记清单供文档/测试共用。
  *  - **缺失分级**：`required` = 缺失即 ACC 核心能力失效；否则为可降级能力。
  */
-export type HostAccess = 'injected' | 'lazy';
-export interface HostMember {
+type HostAccess = 'injected' | 'lazy';
+interface HostMember {
     name: string;
     kind: 'function' | 'value';
 }
-export interface HostServiceContract {
+interface HostServiceContract {
     /** 稳定标识（报告用） */
     id: string;
     /** 服务名（`ctx.get(name)` 或 `ctx.<name>`） */
@@ -40,7 +40,7 @@ export interface HostServiceContract {
 }
 /** dsp 依赖的宿主服务与成员（对照 `_tmp/host-0.1.5-rc.1/`（`dsh-develop host-fetch` 产物）逐一核对） */
 export declare const HOST_SERVICES: readonly HostServiceContract[];
-export interface HostEventContract {
+interface HostEventContract {
     name: HostEventName;
     /** 订阅方（文件） */
     site: string;
@@ -56,14 +56,14 @@ export interface HostEventContract {
  * 该 import 为 type-only，编译期擦除，不产生运行时依赖。
  */
 export declare const HOST_EVENT_NAMES: readonly ["agent/session-start", "agent/pre-step", "agent/turn-stopping", "agent/status", "agent/inbox/inserted", "agent/disposed", "session/event", "session/created", "session/disposed", "settings/updated", "tools/pre-execute", "tools/post-execute", "system-prompt/assemble"];
-export type HostEventName = (typeof HOST_EVENT_NAMES)[number];
+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.5-rc.2";
-export interface HostContractIssue {
+interface HostContractIssue {
     id: string;
     kind: 'service' | 'member' | 'version';
     detail: string;
@@ -100,5 +100,28 @@ export declare function checkHostVersion(version: string | null): {
  * @returns 报告（`ok:false` 时 `issues` 逐条给出缺失项与后果）
  */
 export declare function probeHostContract(ctx: unknown, hostVersion?: string | null): HostContractReport;
+/**
+ * 取宿主契约报告——**每次调用现探**（`ctx` 决定"问谁"，**不缓存"答案"**）。
+ *
+ * 为什么**不缓存**（R↓：一个被实测推翻的设计，留档以免重犯）：
+ * v1.34.1 曾把 `apply()` 时的探针结果存为模块级快照，理由是"两者对**同一个已装载的宿主**
+ * 问同一个问题，第二次计算的答案**不可能不同**，成本却是一次全服务遍历"。
+ * **该前提被实测证伪**（本机 2026-09-15，v1.34.1 部署后）：
+ *  - `apply()` 跑在装载早期，表中 `access:'lazy'` 的服务**尚未实例化**（`ctx.get` 返回 undefined）
+ *    ⇒ 启动探针把它们记为 `not available (lazy)`；
+ *  - 到 `dashboard health` 被调用时它们早已可用 ⇒ **现探给的是相反结论**。
+ *  - 实测差异：快照 = `checked 36 / issues 3`（含 `workspaceRegistry not available` ＋ 后果
+ *    "工作区白名单下拉为空"），而**同一时刻** `GET /serenity/cccs` 正常返回 **4 个工作区**
+ *    （含 3 个无 live 会话的冷 CCC）⇒ 快照渲染出的是**假阴性**。
+ * ⇒ 「两次探针」**不是重复计算，问的是两个时刻**；缓存答案 = 把装载瞬间的观测冒充运行态事实。
+ *
+ * 保留统一入口的收益（这才是 C5 的正确部分）：取数口唯一——`container-status` / `kit-ops`
+ * 只问这一个函数；将来若要"筛掉装载期噪声"，只需改这一处。
+ *
+ * @param ctx 宿主上下文；**未给** ⇒ 返回 `null`（不猜、不暗跑探针）
+ * @param hostVersion 运行中宿主版本（`readDshVersion()`；null = 未知）
+ */
+export declare function hostContractReport(ctx?: unknown, hostVersion?: string | null): HostContractReport | null;
 /** 单行摘要（启动告警用） */
 export declare function summarizeHostContract(report: HostContractReport): string;
+export {};

package/lib/host/type-contract.d.ts

@@ -40,5 +40,4 @@
  *
  * 注：本文件**没有任何运行时语句**，编译产物只有 `export {}`，不影响包体行为。
  */
-/** 哨兵：确保本模块不是空文件被 tree-shake 掉（无运行时副作用，值为类型） */
-export type HostTypeContractSatisfied = true;
+export {};

package/lib/im-bridge.d.ts

@@ -32,7 +32,7 @@ export type ImUserEntry = {
     id: string;
 };
 /** 文本发送输入（通道实现负责凭据解析与记录） */
-export interface ImSendInput {
+interface ImSendInput {
     root: string;
     /** 通道内用户 id（别名已由本模块解析） */
     userId: string;
@@ -40,14 +40,14 @@ export interface ImSendInput {
     accountId?: string;
 }
 /** 文本发送结果（与既有主动发送返回一致，便于记录/诊断） */
-export interface ImSendResult {
+interface ImSendResult {
     accountId: string;
     userId: string;
     sessionId: string;
     role: string;
 }
 /** 文件发送输入（`data` 由本模块读盘并校验后传入——通道不碰 CCC 路径） */
-export interface ImSendFileInput {
+interface ImSendFileInput {
     root: string;
     userId: string;
     data: Buffer;
@@ -95,7 +95,7 @@ export type ImJson = null | boolean | number | string | ImJson[] | {
     [key: string]: ImJson;
 };
 /** 分发结果（工具面直接渲染；错误码稳定，便于模型与日志消费） */
-export type ImToolResult = {
+type ImToolResult = {
     ok: true;
     channel: string;
     action: string;
@@ -106,7 +106,7 @@ export type ImToolResult = {
     error: string;
     remediation?: string;
 };
-export interface ImToolRequest {
+interface ImToolRequest {
     channel?: string;
     action?: string;
     user?: string;
@@ -125,3 +125,4 @@ export interface ImToolRequest {
  * @param req 工具参数
  */
 export declare function runImBridge(root: string, req: ImToolRequest): Promise<ImToolResult>;
+export {};