@wingsky-1/dsh-decision-gateway 0.2.6

package/lib/server/api/deps.d.ts

@@ -0,0 +1,53 @@
+/** api 域出口：注入面（纯类型，零运行时）。 */
+import type { ConfigV1, HistoryEntry } from "../../shared/interface.js";
+/** 最小日志面。 */
+export interface LoggerPort {
+    readonly warn: (message: string) => void;
+    readonly info?: (message: string) => void;
+}
+/** 路由注册口（组合根唯一够得着 ctx.webServer 的地方转交）。 */
+export interface RouteRegistration {
+    (route: {
+        readonly kind: "exact";
+        readonly path: string;
+        readonly handler: (req: unknown, res: unknown) => void;
+    }): () => void;
+}
+/** 历史查询形（api  own 窄面，防腐：history 域签名演进不直接扩散）。 */
+export interface HistoryQuery {
+    readonly root?: string;
+    readonly sessionId?: string;
+    readonly limit?: number;
+}
+/** 预设清单项（api 回显面；出题规范随目录下发）。 */
+export interface PresetListItem {
+    readonly id: string;
+    readonly enabled: boolean;
+    readonly templateVersion: 1;
+    readonly automationCap: number;
+    readonly label: string;
+    readonly description: string;
+    readonly custom: boolean;
+}
+/** api 域运行所需注入（全部由组合根装配，域内无 ctx、无直接跨域引用）。 */
+export interface ApiDeps {
+    readonly logger: LoggerPort;
+    readonly register: RouteRegistration;
+    readonly version: () => string;
+    readonly readConfig: () => ConfigV1;
+    readonly writeConfig: (body: unknown) => ConfigV1;
+    readonly readPresets: () => PresetListItem[];
+    readonly readHistory: (query: HistoryQuery) => HistoryEntry[];
+    readonly removeHistory: (query: HistoryQuery) => {
+        readonly deleted: boolean;
+    };
+    readonly probeConnection: (body: unknown) => Promise<{
+        readonly ok: true;
+        readonly latencyMs: number;
+    } | {
+        readonly ok: false;
+        readonly errorCode: string;
+        readonly category: string;
+        readonly message: string;
+    }>;
+}

package/lib/server/api/impl/handlers.d.ts

@@ -0,0 +1,11 @@
+import type { ApiDeps } from "../deps.js";
+import type { Endpoint } from "./route.js";
+/** 组装端点表（处理器全部经 ports 注入能力）。 */
+export declare function buildEndpoints(ports: ApiDeps): Endpoint[];
+/** 结构化抛错信封（组合根 writeConfig 按此 JSON 抛错，免跨域值引用）。 */
+export interface ThrownFailure {
+    readonly status: number;
+    readonly errorCode: string;
+    readonly category: string;
+    readonly message: string;
+}

package/lib/server/api/impl/route.d.ts

@@ -0,0 +1,28 @@
+/**
+ * api 域实现：路由围栏（回环 403 先于方法 405，异常收口 500）。
+ *
+ * - 非回环一律 403（默认参数，不放行 cross-site：普通 /api 路由）；
+ * - 方法不在表里给 405（Allow 头带合法方法），不给 404；
+ * - 处理器抛错收口 500（已发头则不再写头）。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LoggerPort } from "../deps.js";
+/** 端点方法表（键为大写方法名）。 */
+export type MethodTable = Record<string, (req: IncomingMessage, res: ServerResponse) => void | Promise<void>>;
+/** 端点（path 精确匹配）。 */
+export interface Endpoint {
+    readonly path: string;
+    readonly methods: MethodTable;
+}
+/** 注册口（组合根转交的 ctx.webServer.register 窄面）。 */
+export type RegisterRoute = (route: {
+    readonly kind: "exact";
+    readonly path: string;
+    readonly handler: (req: IncomingMessage, res: ServerResponse) => void;
+}) => () => void;
+/** JSON 成功体。 */
+export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
+/** 失败包络（必含 errorCode + category，供客户端 failureCategory 识别）。 */
+export declare function sendFailure(res: ServerResponse, status: number, errorCode: string, category: string, message: string): void;
+/** 注册端点组（返回摘除器；与装配顺序逆序释放由调用方组织）。 */
+export declare function registerEndpoints(register: RegisterRoute, endpoints: Endpoint[], logger: LoggerPort): (() => void)[];

package/lib/server/api/impl/service.d.ts

@@ -0,0 +1,4 @@
+/** api 域实现：装配（端点表 + 围栏注册；无状态，释放器由调用方持有）。 */
+import type { ApiDeps } from "../deps.js";
+/** 装配浏览器出口（组合根在 apply 期调用一次；返回摘除器）。 */
+export declare function installApi(deps: ApiDeps): (() => void)[];

package/lib/server/api/interface.d.ts

@@ -0,0 +1,3 @@
+/** api 域门面：只转出组合根实际用的符号（无逻辑）。 */
+export type { ApiDeps } from "./deps.js";
+export { installApi } from "./impl/service.js";

package/lib/server/config/deps.d.ts

@@ -0,0 +1,32 @@
+/**
+ * config 域出口：本域对上游（组合根）声明的注入面（纯类型，零运行时）。
+ *
+ * 跨域运行时能力一律经此注入：落盘原语由组合根从 store 域取来传入，
+ * 本域不直引 store 实现（跨域值边零新增）。
+ */
+/** 最小日志面（宿主 ctx.logger 的结构子集）。 */
+export interface LoggerPort {
+    readonly warn: (message: string) => void;
+    readonly info?: (message: string) => void;
+}
+/** 落盘原语面（组合根用 store 域实现装配）。 */
+export interface FileIoPorts {
+    readonly readJsonSync: (file: string) => {
+        readonly ok: true;
+        readonly value: unknown;
+    } | {
+        readonly ok: false;
+    };
+    readonly readTextSync: (file: string) => {
+        readonly ok: true;
+        readonly text: string;
+    } | {
+        readonly ok: false;
+    };
+    readonly atomicWrite0600Sync: (file: string, text: string) => void;
+}
+/** config 域运行所需注入（io + 日志）。 */
+export interface ConfigDeps {
+    readonly io: FileIoPorts;
+    readonly logger: LoggerPort;
+}

package/lib/server/config/impl/envelope.d.ts

@@ -0,0 +1,9 @@
+import type { PutFailure } from "./model.js";
+/** 嵌套包络归一化（成功即扁平体，失败即 400 负载）。 */
+export declare function normalizePutEnvelope(body: unknown): {
+    readonly ok: true;
+    readonly flat: Record<string, unknown>;
+} | {
+    readonly ok: false;
+    readonly failure: PutFailure;
+};

package/lib/server/config/impl/model.d.ts

@@ -0,0 +1,54 @@
+import type { AutomationCap, ConfigV1, CustomPreset } from "../../../shared/interface.js";
+/** PUT 允许键（白名单；之外一律 400。envelope.ts 共用，故导出）。 */
+export declare const ALLOWED_PUT_KEYS: readonly ["apiKeyRef", "apiKeyPlaintext", "confirm", "timeoutMs", "maxConcurrency", "truncBudget", "presets", "customPresets", "history"];
+/** PUT 补丁（调用方只填变更键；null 表清除 ENV 引用）。 */
+export interface ConfigPutPatch {
+    readonly apiKeyRef?: string | null;
+    readonly apiKeyPlaintext?: string;
+    readonly confirm?: boolean;
+    readonly timeoutMs?: number;
+    readonly maxConcurrency?: number;
+    readonly truncBudget?: number;
+    readonly presets?: readonly {
+        readonly id: string;
+        readonly enabled: boolean;
+        readonly automationCap: AutomationCap;
+    }[];
+    readonly history?: {
+        readonly perSession?: number;
+        readonly totalSessions?: number;
+    };
+    readonly customPresets?: readonly CustomPreset[];
+}
+/** 校验失败（HTTP 400 的负载来源；必含 errorCode + category）。 */
+export interface PutFailure {
+    readonly errorCode: string;
+    readonly category: string;
+    readonly message: string;
+}
+/** 包络归一化已迁 envelope.ts（normalizePutEnvelope），此处删除避免双事实源。 */
+/** 新鲜默认配置（每次调用返回新对象，不共享引用）。 */
+export declare function buildDefaultConfig(): ConfigV1;
+/** 是否为普通记录（数组/空不算。envelope.ts 共用，故导出）。 */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** 归一化磁盘读到的 config.json（退役键剥离+缺口补默认；返回剥离名单供告警）。 */
+export declare function normalizeLoadedConfig(raw: unknown): {
+    readonly config: ConfigV1;
+    readonly retired: string[];
+};
+/** 校验 PUT 体（成功即补丁；失败只回类别+码，不回显原文）。 */
+/** 校验自建自定义预设整列（全量替换语义；id 保留字/形状/唯一，名与描述长度，cap 三档）。 */
+export declare function validateCustomPresets(raw: unknown): {
+    readonly ok: true;
+    readonly list: CustomPreset[];
+} | {
+    readonly ok: false;
+    readonly failure: PutFailure;
+};
+export declare function validatePutBody(body: unknown): {
+    readonly ok: true;
+    readonly patch: ConfigPutPatch;
+} | {
+    readonly ok: false;
+    readonly failure: PutFailure;
+};

package/lib/server/config/impl/paths.d.ts

@@ -0,0 +1,12 @@
+/** 本插件在 DSH home 下的独立命名空间目录。 */
+export declare function decisionGatewayHome(home?: string): string;
+/** config.json 完整路径。 */
+export declare function configFile(home?: string): string;
+/** presets.json 完整路径（开关覆盖层）。 */
+export declare function presetsFile(home?: string): string;
+/** custom-presets.json 完整路径（自建存储；缺席即空列表）。 */
+export declare function customPresetsFile(home?: string): string;
+/** secrets.json 完整路径（明文密钥唯一落盘处，0600）。 */
+export declare function secretsFile(home?: string): string;
+/** VERSION 完整路径（存储版本刻度）。 */
+export declare function versionFile(home?: string): string;

package/lib/server/config/impl/service.d.ts

@@ -0,0 +1,37 @@
+import type { ConfigDeps } from "../deps.js";
+import type { ConfigPutPatch } from "./model.js";
+import type { ConfigV1, CustomPreset } from "../../../shared/interface.js";
+/**
+ * 无版本文件时的起点（BASELINE 语义钉死：字面 "0.0.0"，与 "0" 数值等价——
+ * compareVersions 缺位补零，故 upgrade 侧“缺失按 0”与本字面是同一事实的两面写法）。
+ */
+export declare const BASELINE_VERSION = "0.0.0";
+/** 已加载状态（组合根持有，活对象不进模块级变量）。 */
+export interface LoadedState {
+    readonly config: ConfigV1;
+    readonly plaintext: string | undefined;
+    readonly retired: string[];
+    readonly storedVersion: string;
+    readonly customPresets: readonly CustomPreset[];
+}
+/** 读存储版本（缺席/空即基线）。 */
+export declare function readStoredVersion(home: string | undefined, deps: ConfigDeps): string;
+/** 写存储版本（一步升级完成即推进一档）。 */
+export declare function writeStoredVersion(home: string | undefined, version: string, deps: ConfigDeps): void;
+/** 版本号比较（逐段数值；段数不同缺位补零；预发布后缀不参与比较）。 */
+export declare function compareVersions(left: string, right: string): number;
+/** 本插件版本（读包根 package.json；产物形态下本模块位于 lib/server/config/impl/）。 */
+export declare function pluginVersion(): string;
+/** 读自建自定义预设（缺席/非法即空列表 + 告警；文件缺席不播种，首存即建）。 */
+export declare function loadCustomPresets(home: string | undefined, deps: ConfigDeps): CustomPreset[];
+/** 加载全部状态（三文件合并：presets.json 覆盖 config.json 的开关；退役键剥离告警）。 */
+export declare function loadState(home: string | undefined, deps: ConfigDeps): LoadedState;
+/** 应用已校验补丁并落盘（config.json + presets.json + secrets.json 各归其位）。 */
+export declare function savePatch(home: string | undefined, patch: ConfigPutPatch, deps: ConfigDeps): LoadedState;
+/** 掩码视图（GET 回显：形状同 v1，只含 apiKeyRef 名与 hasPlaintextKey，永无原文）。 */
+export declare function toMaskedConfig(state: LoadedState): ConfigV1;
+/** 解析可用密钥（ENV 引用优先；手改的坏形状明文视同无 key 并告警）。 */
+export declare function resolveApiKey(state: LoadedState, env: Record<string, string | undefined>, deps: ConfigDeps): {
+    readonly key: string | undefined;
+    readonly source: "env" | "plaintext" | "none";
+};

package/lib/server/config/interface.d.ts

@@ -0,0 +1,12 @@
+/**
+ * config 域门面：只转出组合根与 upgrade 域实际用的符号（无逻辑）。
+ *
+ * upgrade 复用本域路径与版本语义（单一事实源）；其余内部符号经 impl 直引，不走门面。
+ */
+export type { ConfigDeps } from "./deps.js";
+export { buildDefaultConfig, validateCustomPresets, validatePutBody } from "./impl/model.js";
+export type { ConfigPutPatch } from "./impl/model.js";
+export { normalizePutEnvelope } from "./impl/envelope.js";
+export type { LoadedState } from "./impl/service.js";
+export { BASELINE_VERSION, compareVersions, loadState, pluginVersion, readStoredVersion, resolveApiKey, savePatch, toMaskedConfig, writeStoredVersion, } from "./impl/service.js";
+export { configFile, customPresetsFile, presetsFile, secretsFile, versionFile, } from "./impl/paths.js";

package/lib/server/history/deps.d.ts

@@ -0,0 +1,25 @@
+/** history 域出口：注入面（纯类型，零运行时）。 */
+/** 最小日志面。 */
+export interface LoggerPort {
+    readonly warn: (message: string) => void;
+    readonly info?: (message: string) => void;
+}
+/** 落盘原语面（组合根用 store 域实现装配）。 */
+export interface HistoryIoPorts {
+    readonly readTextSync: (file: string) => {
+        readonly ok: true;
+        readonly text: string;
+    } | {
+        readonly ok: false;
+    };
+    readonly atomicWrite0600Sync: (file: string, text: string) => void;
+    readonly listFilesSync: (dir: string) => string[];
+    readonly mtimeMs: (file: string) => number;
+    readonly removeFileSync: (file: string) => void;
+    readonly ensureDir0700: (dir: string) => void;
+}
+/** history 域运行所需注入。 */
+export interface HistoryDeps {
+    readonly io: HistoryIoPorts;
+    readonly logger: LoggerPort;
+}

package/lib/server/history/impl/entry.d.ts

@@ -0,0 +1,29 @@
+import type { AutomationLevel, HistoryEntry } from "../../../shared/interface.js";
+/** 调用题目快照元素（tools 域 ValidQuestion 的结构子集，避免跨域值引用）。 */
+export interface EntryQuestion {
+    readonly id: string;
+    readonly text: string;
+    readonly kind: "choice" | "score";
+    readonly options?: readonly string[];
+    readonly levels?: readonly string[];
+}
+/** 事件面（tools 域 DecideEvent 的结构子集，避免跨域值引用）。precheckHit 命中即 snippet 强制全掩码（S1-A：长 PEM/残缺头不断字节上限，命中文本不存任何原文）。questions 为调用题目快照（文本/选项同 snippet 脱敏后存）。 */
+export interface EntryEvent {
+    readonly precheckHit: boolean;
+    readonly presetId: string;
+    readonly text: string;
+    readonly lang: "en" | "zh" | "unknown";
+    readonly truncated: boolean;
+    readonly originalLength: number;
+    readonly resultKind: string;
+    readonly questions: readonly EntryQuestion[];
+    readonly choice?: string;
+    readonly score?: number;
+    readonly confidence: number;
+    readonly tier: "none" | "high" | "low";
+    readonly automation: AutomationLevel;
+    readonly latencyMs: number;
+    readonly errorCode?: string;
+}
+/** 组装完整条目（now 由调用方注入，单测可定钟）。 */
+export declare function assembleEntry(root: string, sessionId: string, event: EntryEvent, now: number): HistoryEntry;

package/lib/server/history/impl/hash.d.ts

@@ -0,0 +1,8 @@
+/** 工作目录指纹（分文件键；归一化换行差异不影响同一目录）。 */
+export declare function rootHashOf(root: string): string;
+/** 状态指纹（原文不出境存证，只存哈希）。 */
+export declare function stateHashOf(text: string): string;
+/** 根展示名（仅 basename，完整路径永不入库）。 */
+export declare function rootDisplayOf(root: string): string;
+/** 查询 root 参数归一：hex 指纹直用，路径即哈希（调用方传哪种都可）。 */
+export declare function resolveRootHash(root: string): string;

package/lib/server/history/impl/paths.d.ts

@@ -0,0 +1,2 @@
+/** 历史根目录。 */
+export declare function historyRoot(home?: string): string;

package/lib/server/history/impl/redact.d.ts

@@ -0,0 +1,2 @@
+/** 脱敏并截断（≤200 字，按 codepoints 不断字）。 */
+export declare function redactSnippet(text: string): string;

package/lib/server/history/impl/service.d.ts

@@ -0,0 +1,30 @@
+import type { HistoryDeps } from "../deps.js";
+import type { HistoryEntry } from "../../../shared/interface.js";
+/** 会话文件名（sessionId 形状先行校验，防路径穿越）。 */
+export declare function historyFile(home: string | undefined, rootHash: string, sessionId: string): string;
+/** sessionId 形状校验（非法即 400，不落盘）。 */
+export declare function assertSessionId(sessionId: string): void;
+/** 追加条目并轮转（返回落盘文件）。 */
+export declare function appendEntry(home: string | undefined, entry: HistoryEntry, limits: {
+    readonly perSession: number;
+    readonly totalSessions: number;
+}, deps: HistoryDeps): string;
+/** 查询条目（root/sessionId 可选过滤；limit 上限 500；按 ts 倒序）。 */
+export declare function queryEntries(home: string | undefined, query: {
+    readonly root?: string;
+    readonly sessionId?: string;
+    readonly limit?: number;
+}, deps: HistoryDeps): HistoryEntry[];
+/**
+ * 删除单会话（root 与 sessionId 双必填，否则 400；仅删单文件，返回真实 deleted）。
+ *
+ * D2：root 走与查询对称的三形态——hex/路径直定位文件；basename 走 display 回落：
+ * 扫描会话文件找 rootDisplay+sessionId 命中的那一个，0 个即 deleted:false，
+ * 多个即 400 歧义（不同目录同 basename 时不猜删）。
+ */
+export declare function deleteSession(home: string | undefined, query: {
+    readonly root?: string;
+    readonly sessionId?: string;
+}, deps: HistoryDeps): {
+    readonly deleted: boolean;
+};

package/lib/server/history/interface.d.ts

@@ -0,0 +1,4 @@
+/** history 域门面：只转出组合根实际用的符号（无逻辑）。 */
+export type { HistoryDeps } from "./deps.js";
+export { appendEntry, deleteSession, queryEntries } from "./impl/service.js";
+export { assembleEntry } from "./impl/entry.js";

package/lib/server/store/deps.d.ts

@@ -0,0 +1,6 @@
+/** store 域出口：本域对上游声明的注入面（纯类型，零运行时）。 */
+/** 最小日志面（宿主 ctx.logger 的结构子集）。 */
+export interface LoggerPort {
+    readonly warn: (message: string) => void;
+    readonly info?: (message: string) => void;
+}

package/lib/server/store/impl/io.d.ts

@@ -0,0 +1,24 @@
+/** 确保目录存在且为 0700（chmod best-effort，非 POSIX 平台不抛）。 */
+export declare function ensureDir0700(dir: string): void;
+/** 原子写文件并置 0600（同目录临时文件 + rename；崩溃不留半截文件）。 */
+export declare function atomicWrite0600Sync(file: string, text: string): void;
+/** 读文本文件（缺席即 ok:false，由调用方回落默认值）。 */
+export declare function readTextSync(file: string): {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+};
+/** 读 JSON 文件（缺席/解析失败即 ok:false，不抛）。 */
+export declare function readJsonSync(file: string): {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+};
+/** 文件 mtime 毫秒（取不到即 -1，排序时沉底）。 */
+export declare function mtimeMs(file: string): number;
+/** 列目录下全部文件名（非目录/不可读即空数组，不抛）。 */
+export declare function listFilesSync(dir: string): string[];
+/** 删文件（缺席不抛）。 */
+export declare function removeFileSync(file: string): void;

package/lib/server/store/interface.d.ts

@@ -0,0 +1,4 @@
+/**
+ * store 域门面：只转出组合根实际用的落盘原语（无逻辑）。
+ */
+export { atomicWrite0600Sync, ensureDir0700, listFilesSync, mtimeMs, readJsonSync, readTextSync, removeFileSync, } from "./impl/io.js";

package/lib/server/tools/deps.d.ts

@@ -0,0 +1,83 @@
+/** tools 域出口：注入面（纯类型，零运行时）。 */
+import type { AutomationCap, AutomationLevel, ConfigV1, CustomPreset, DecisionLang, DecisionTier } from "../../shared/interface.js";
+/** 最小日志面。 */
+export interface LoggerPort {
+    readonly warn: (message: string) => void;
+    readonly info?: (message: string) => void;
+}
+/** 密钥解析器（组合根用 config 域装配：ENV 优先）。 */
+export interface KeyResolver {
+    (): {
+        readonly key: string | undefined;
+        readonly source: "env" | "plaintext" | "none";
+    };
+}
+/** 决议事件（tools 域的记录事实面；组合根映射为 HistoryEntry 再落盘，tools 不直引 history 域）。sessionId 由 decide 落史前校验（非法回落 unknown，随事件同行）。precheckHit 为本地密形命中旗（S1-A：命中即 snippet 强制全掩码）。questions 为调用题目快照（含候选项全列）。 */
+export interface DecideEvent {
+    readonly sessionId: string;
+    readonly precheckHit: boolean;
+    readonly presetId: string;
+    readonly text: string;
+    readonly lang: DecisionLang;
+    readonly truncated: boolean;
+    readonly originalLength: number;
+    readonly resultKind: string;
+    readonly questions: readonly ValidQuestion[];
+    readonly choice?: string;
+    readonly score?: number;
+    readonly confidence: number;
+    readonly tier: DecisionTier;
+    readonly automation: AutomationLevel;
+    readonly latencyMs: number;
+    readonly errorCode?: string;
+}
+/** 事件记录器（组合根用 history 域装配；测试可注入内存实现）。 */
+export interface EventRecorder {
+    (event: DecideEvent): void;
+}
+/** fetch 注入缝（默认全局 fetch 适配；单测注入 mock，全程离线）。 */
+export interface FetchImpl {
+    (url: string, init: {
+        readonly method: string;
+        readonly headers: Record<string, string>;
+        readonly body: string;
+        readonly signal: AbortSignal;
+    }): Promise<{
+        readonly status: number;
+        readonly text: string;
+    }>;
+}
+/** decide 运行所需注入（连接参数取自配置快照，调用方按需刷新）。 */
+export interface DecideDeps {
+    readonly logger: LoggerPort;
+    readonly connection: ConfigV1["connection"];
+    readonly isEnabled: (presetId: string) => boolean;
+    readonly capOf: (presetId: string) => AutomationCap;
+    readonly customPresets?: ReadonlyMap<string, CustomPreset>;
+    readonly resolveKey: KeyResolver;
+    readonly recordEvent?: EventRecorder;
+    /** 并发门（组合根按 maxConcurrency 创建信号量后传入；缺席即直行）。 */
+    readonly limit?: <T>(task: () => Promise<T>, signal?: AbortSignal) => Promise<T>;
+    readonly fetchImpl?: FetchImpl;
+    readonly root: string;
+    readonly sessionId: string;
+    readonly now?: () => number;
+    /** 调用方取消信号（ToolRunContext.signal 经 depsFor 透传）。 */
+    readonly signal: AbortSignal;
+}
+/** 校验后问题（文本已做 255 长度校验，id 已做 ASCII 校验；score 可带 2-10 levels，缺省即默认五档）。 */
+export interface ValidQuestion {
+    readonly id: string;
+    readonly text: string;
+    readonly kind: "choice" | "score";
+    readonly options?: readonly string[];
+    readonly levels?: readonly string[];
+}
+/** 校验后决议输入。 */
+export interface ValidDecide {
+    readonly presetId: string;
+    readonly text: string;
+    readonly lang: DecisionLang;
+    readonly questions: readonly ValidQuestion[];
+    readonly appliedSource: "override" | "custom";
+}

package/lib/server/tools/impl/client.d.ts

@@ -0,0 +1,62 @@
+import type { Questions, SystemOneResult } from "@typesafe-ai/sdk";
+import type { FetchImpl } from "../deps.js";
+import type { ValidQuestion } from "../deps.js";
+/** 上游失败（可重试性由本模块判定，调用方只读 code/category）。 */
+export interface DecisionFailure {
+    readonly code: string;
+    readonly category: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly status?: number;
+}
+/** 远端原始决议（已做形状校验的最小面）。 */
+export interface RemoteVerdict {
+    readonly resultKind: "choice" | "score";
+    readonly choice?: string;
+    readonly score?: number;
+    readonly confidence: number;
+    readonly tier: number;
+    readonly automation: number;
+    readonly codepoints: number;
+}
+/** 默认 fetch 适配（全局 fetch 转窄面；无全局 fetch 即抛未实现）。 */
+export declare function defaultFetchImpl(): FetchImpl;
+/** 请求体（官方 SystemOne 形状：model + 字符串 state + 字典 questions）。 */
+export interface DecisionRequestBody {
+    readonly model: string;
+    readonly state: string;
+    readonly questions: Questions;
+}
+/** confidence 派生分层（0.8 对齐 UI high 线；0.5 低分界）。 */
+export declare function confidenceTier(confidence: number): number;
+/** 远端问题投影（内部 ValidQuestion 转 SDK 字典；choice criteria 置空描述，score 用自带 levels 或默认数字 legend）。 */
+export declare function toWireQuestions(questions: readonly ValidQuestion[]): Questions;
+/**
+ * 融合调用方信号与内部信号（SDK 超时信号）：任一 abort 即取消外调。
+ *
+ * AbortSignal.any 优先（原子融合），缺席回落手动级联（已 abort 即取已取消侧，
+ * 否则建中继控制器双向转发，移除监听防泄漏）。调用方缺席即回内部信号原样。
+ */
+export declare function combineSignals(callerSignal: AbortSignal | undefined, innerSignal: AbortSignal): AbortSignal;
+/** 首题答案转 verdict（多题时首题驱动输出；noul/未知形状即 bad-payload 不重试）。 */
+export declare function mapFirstAnswer(body: DecisionRequestBody, result: SystemOneResult<Questions>): {
+    readonly ok: true;
+    readonly verdict: RemoteVerdict;
+} | {
+    readonly ok: false;
+    readonly failure: DecisionFailure;
+};
+/** SDK 错误转失败面（状态码沿旧映射；客户端校验错不重试；裸抛错归网络可重试；调用方取消单列 ABORTED 不重试）。 */
+export declare function sdkErrorToFailure(cause: unknown): DecisionFailure;
+/**
+ * 有限重试调用（最多 2 次重试；返回重试次数供输出计费面）。
+ *
+ * timeoutMs 是整次调用的总预算（非逐次）：每次尝试按剩余预算设置 SDK 超时，
+ * 预算耗尽后的重试即时失败——慢上游不会把单次决议拖成 3 倍超时（锁定的超时探针
+ * 用 timeoutMs=1000 + 2s 轮询钉死该语义：逐次预算下 3 次尝试必超窗）。
+ */
+export declare function callWithRetry(body: DecisionRequestBody, key: string, timeoutMs: number, fetchImpl: FetchImpl, callerSignal?: AbortSignal): Promise<{
+    readonly verdict?: RemoteVerdict;
+    readonly failure?: DecisionFailure;
+    readonly retries: number;
+}>;

package/lib/server/tools/impl/define.d.ts

@@ -0,0 +1,30 @@
+/**
+ * tools 域实现：模型工具定义（ws_request_verdict / ws_list_verdict_guides）。
+ *
+ * - 注册面只经组合根的 ctx.tools.register 进入宿主；本模块只产出定义；
+ * - exec 上下文防御式读取（sessionId/cwd 缺席即回落 unknown/process.cwd()）；
+ * - output 附 JSON 渲染（文本块），失败包络同样可读（无概率字段）；
+ * - ws_list_verdict_guides 只读（不记录历史、不触网络）。
+ */
+import type { ToolDefinition, ToolRunContext } from "@deepseek-ai/dsh-tools";
+import type { CustomPreset } from "../../../shared/interface.js";
+import type { DecideDeps } from "../deps.js";
+/** 工具装配（组合根绑定：exec→deps 映射 + 快照取数）。 */
+export interface ToolAssembly {
+    readonly depsFor: (exec: ToolRunContext) => DecideDeps;
+    readonly snapshot: () => {
+        readonly isEnabled: (presetId: string) => boolean;
+        readonly capOf: (presetId: string) => number;
+        readonly customs?: readonly CustomPreset[];
+    };
+}
+/**
+ * exec 取 sessionId（多形态防御读取）。
+ *
+ * 本函数是两处解析规则收敛后的唯一实现（D4）：组合根直接引用本导出，不再自写根侧版本。
+ */
+export declare function sessionOf(exec: unknown): string;
+/** exec 取工作目录（缺席回落进程 cwd；与 sessionOf 同源收敛，见上）。 */
+export declare function rootOf(exec: unknown): string;
+/** 产出两工具定义。 */
+export declare function buildToolDefinitions(assembly: ToolAssembly): ToolDefinition[];

package/lib/server/tools/impl/precheck.d.ts

@@ -0,0 +1,8 @@
+/**
+ * tools 域实现：本地密形预检（命中即不离境、直转人工；纯函数）。
+ *
+ * secret-leak 预设默认关闭是第一道闸；本预检是第二道——对全部预设生效：
+ * 正文命中密钥密形时，本次决议不发任何出境请求，直接返回人工接管。
+ */
+/** 是否命中密形（命中即不离境）。 */
+export declare function localPrecheckHit(text: string): boolean;

package/lib/server/tools/impl/probe.d.ts

@@ -0,0 +1,24 @@
+/**
+ * tools 域实现：连接探针（空体合法；密钥由调用方解析后传入；不记历史）。
+ *
+ * 从组合根沉入本域（内聚收窄）：探针的远端调用本就是 tools 能力，组合根只做密钥解析与装配。
+ */
+import type { FetchImpl } from "../deps.js";
+/** 探针结果。 */
+export type ProbeResult = {
+    readonly ok: true;
+    readonly latencyMs: number;
+} | {
+    readonly ok: false;
+    readonly errorCode: string;
+    readonly category: string;
+    readonly message: string;
+};
+/** 探针输入（key 缺席即 NO_KEY，不触网络）。 */
+export interface ProbeInput {
+    readonly key: string | undefined;
+    readonly timeoutMs: number;
+    readonly fetchImpl?: FetchImpl;
+}
+/** 执行连接探针（general 模板最小体；成功/失败均不记历史）。 */
+export declare function probeConnection(input: ProbeInput): Promise<ProbeResult>;

package/lib/server/tools/impl/semaphore.d.ts

@@ -0,0 +1,4 @@
+/** 并发信号量（闭包状态；max≤0 即视同 1）。 */
+export declare function createSemaphore(max: number): {
+    readonly run: <T>(task: () => Promise<T>, signal?: AbortSignal) => Promise<T>;
+};