@eddyskywalker/dsh-chatgpt-subscription 0.58.0 → 0.60.0

package/lib/types/host/cache-warmup/projection.d.ts

@@ -15,6 +15,23 @@
  * @module dsh-chatgpt-subscription/host/cache-warmup/projection
  */
 import { type PreviewBudget, type ProjectionResult, type ProjectToolResultInput } from './contracts.ts';
+/**
+ * PTC 家族的**程序传输**工具名（一个集合，两个名字）。
+ *
+ * 「模型写一段程序、工具调用发生在程序内部」是同一种传输，只是不同预设给主工具起
+ * 了不同名字：PTC 预设叫 `run_code`，Code Mode 预设叫 `code_run`。凡是按工具名判断
+ * 「这条结果来自程序传输」的地方都必须认这**整个集合**——名字只写一个，预设一换，
+ * 大结果的 `ref://` 预览与精确补读就会静默失效。
+ */
+export declare const CACHE_WARMUP_PTC_TRANSPORT_TOOLS: ReadonlySet<string>;
+/**
+ * 这个名字是否属于 PTC 家族的程序传输工具。
+ *
+ * 只做**精确**匹配：`code_runner` 之类的近似名不算，宁可少投影也不能误伤。
+ * @param name - 工具名。
+ * @returns 属于 {@link CACHE_WARMUP_PTC_TRANSPORT_TOOLS} 时为 true。
+ */
+export declare function isPtcTransportName(name: string): boolean;
 /**
  * 投影一条工具结果。
  *

package/lib/types/host/cache-warmup/projection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../../src/host/cache-warmup/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAErB,KAAK,sBAAsB,EAG5B,MAAM,gBAAgB,CAAA;AAspDvB;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuFhG;AAED,iCAAiC;AACjC,wBAAgB,oBAAoB,IAAI,aAAa,CAEpD"}
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../../src/host/cache-warmup/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAErB,KAAK,sBAAsB,EAG5B,MAAM,gBAAgB,CAAA;AAYvB;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,EAAE,WAAW,CAAC,MAAM,CAAqC,CAAA;AAEtG;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AA6oDD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuFhG;AAED,iCAAiC;AACjC,wBAAgB,oBAAoB,IAAI,aAAa,CAEpD"}

package/lib/types/host/codemode/discovery.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 程序内的工具发现 API：`code_tools_list` / `code_tools_search` / `code_tools_describe`。
+ *
+ * 三个都是注册表上的**普通工具**，因此只存在于本预设里，也必然被本包自己的名字规则遮蔽——
+ * 模型只能在程序内部调用它们，这与「遮蔽的工具只能从程序里够到」是同一条规则。
+ *
+ * 它们走完整执行管线（参数校验、策略、审批、守卫、超时），不是旁路接口。
+ *
+ * @module @eddyskywalker/dsh-chatgpt-subscription/host/codemode/discovery
+ */
+import type { CatalogEntry } from './transport.ts';
+import type { CodemodeRules } from './rules.ts';
+/** 一条公开的检索结果。 */
+export interface ToolHit {
+    /** 工具名。 */
+    readonly name: string;
+    /** 描述。 */
+    readonly description: string;
+    /** namespace（MCP 服务端名或 `plugin`）。 */
+    readonly namespace: string;
+}
+/**
+ * 造三个发现工具（外加可选的 `code_debug`）。
+ *
+ * @param rules - 已归一化的规则。
+ * @param catalog - 当前清单的读取函数。
+ * @param debug - 调试信息读取函数（`code_debug` 用）。
+ * @returns 原始工具定义数组。
+ */
+export declare function createDiscoveryDefinitions(rules: CodemodeRules, catalog: () => readonly CatalogEntry[], debug: () => unknown): unknown[];
+/** 一个工具名所属的 namespace。 */
+export declare function namespaceOfName(name: string): string;
+//# sourceMappingURL=discovery.d.ts.map

package/lib/types/host/codemode/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../../src/host/codemode/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,iBAAiB;AACjB,MAAM,WAAW,OAAO;IACtB,WAAW;IACX,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,UAAU;IACV,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,MAAM,SAAS,YAAY,EAAE,EACtC,KAAK,EAAE,MAAM,OAAO,aAWrB;AA+OD,0BAA0B;AAC1B,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD"}

package/lib/types/host/codemode/executor.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Code Mode 的工具执行器：本包遮蔽与拒绝的唯一接缝。
+ *
+ * ## 为什么是 executor
+ *
+ * DSH 0.2.2 把「模型看到的工具清单」的归属权从 `system-prompt/assemble` 瀑布搬到了
+ * per-scope `ToolExecutor`：注册表向当前作用域选中的 executor 要 schema，所以
+ * `describe()` 就是请求面。它同时解决了归属问题——executor **按作用域链选择**，只有挂
+ * 在本预设里的这一份会服务本预设的会话，因此不需要判断「这个 agent 是不是我的」。
+ *
+ * 三件事：
+ *
+ * 1. `describe()` 丢掉一切不该出现在模型清单里的名字，其余交给原生 executor 投影；
+ * 2. `sections` 提供**恒定**的 Code Mode 说明段（见 rules.ts 的恒定契约）；
+ * 3. `execute()` 在派发**之前**拒绝模型对被遮蔽名字的直接调用，其余整批委托给原生
+ *    executor——委托而不是重写，是因为手写 pre-policy / 审批 / around-dispatch /
+ *    post-execute 管线正是插件静默丢策略的方式。
+ *
+ * ## 程序内子调用怎么与模型直呼区分
+ *
+ * 批量 `execute()` 的入参没有 `parent` 字段（执行令牌由注册表自己的管线铸造，插件
+ * 造不出来），所以传输层把自己持有的 `AbortSignal` 打上 {@link NESTED_MARK}，并让子调用 id
+ * 形如 `<outer>:ptc:<n>`。signal 是模型无法伪造的对象，call id 不可改，两个标记互为兜底。
+ *
+ * @module @eddyskywalker/dsh-chatgpt-subscription/host/codemode/executor
+ */
+import { type CodemodeRules, type CodemodeView } from './rules.ts';
+/** 传输层打在 AbortSignal 上的嵌套标记。 */
+export declare const NESTED_MARK: unique symbol;
+/** 子调用 id 里的一段：`<outer>:ptc:<n>`，与内核自己的命名一致。 */
+export declare const NESTED_CALL_ID_MARKER = ":ptc:";
+/**
+ * 给一个 signal 打上嵌套标记。
+ *
+ * @param signal - 传给 `tools.execute()` 的那一个 signal。
+ * @returns 同一个 signal（便于链式使用）。
+ */
+export declare function markNested(signal: AbortSignal | undefined): AbortSignal | undefined;
+/**
+ * 判断一批调用是不是来自程序内部。
+ *
+ * @param call - 批里的一条调用（结构探测）。
+ * @param batchSignal - 批级 signal（`tools.execute()` 只收一份，注册表会复制给每条执行）。
+ * @returns 来自程序内部时为 `true`。
+ */
+export declare function isNestedCall(call: unknown, batchSignal: unknown): boolean;
+/** 执行器对外暴露的能力（结构契约，不 import 内核类型）。 */
+export interface CodemodeExecutor {
+    /** 执行器自带的提示词段。 */
+    readonly sections: readonly CodemodeSection[];
+    /** 本步的模型可见 schema。 */
+    describe(tools: readonly unknown[]): {
+        schemas: readonly unknown[];
+    };
+    /** 执行一整批调用。 */
+    execute(input: CodemodeBatchInput): Promise<CodemodeBatchResult>;
+}
+/** 一条 executor 所属的提示词段。 */
+export interface CodemodeSection {
+    /** 段名。 */
+    readonly name: string;
+    /** 排序位。 */
+    readonly order?: number;
+    /** 是否做 `{{variable}}` 插值。 */
+    readonly interpolate?: boolean;
+    /** 段正文（恒定）。 */
+    readonly text: string | ((tools: readonly unknown[]) => string);
+}
+/** 批入参里本模块会读的部分。 */
+export interface CodemodeBatchInput {
+    /** 原始调用。 */
+    readonly calls: readonly unknown[];
+    /** 批级 signal。 */
+    readonly signal: AbortSignal;
+    /** 辅助字段透传。 */
+    readonly [key: string]: unknown;
+}
+/** 批结果。 */
+export interface CodemodeBatchResult {
+    /** 与入参一一对应的结果。 */
+    readonly results: readonly unknown[];
+    /** 需要附加到下一步的上下文。 */
+    readonly additionalContexts: readonly unknown[];
+    /** 本批是否结束了这一轮。 */
+    readonly concluded: boolean;
+}
+/** 委托目标（原生 executor 的实例，结构描述）。 */
+export interface DelegateExecutor {
+    /** 见 {@link CodemodeExecutor.describe}。 */
+    describe(tools: readonly unknown[]): {
+        schemas: readonly unknown[];
+    };
+    /** 见 {@link CodemodeExecutor.execute}。 */
+    execute(input: CodemodeBatchInput): Promise<CodemodeBatchResult>;
+}
+/** 执行器钩子。 */
+export interface ExecutorHooks {
+    /** 归属视图（整个清单）。 */
+    view(): CodemodeView;
+    /** 归属视图（单个名字，供拒绝路径使用）。 */
+    viewForName(name: string): CodemodeView;
+    /** 说明段正文。 */
+    sectionText(): string;
+    /** 每次 describe 收到的完整定义集（含被遮蔽的），供程序内清单使用。 */
+    onCatalog?(tools: readonly unknown[]): void;
+    /** 每次 describe 的决策（写日志 / debug 环）。 */
+    onDescribe?(decision: DescribeDecision): void;
+    /** 委托目标；缺省时执行器不可用（入口保证它存在）。 */
+    delegate: DelegateExecutor;
+}
+/** 一次 describe 的决策。 */
+export interface DescribeDecision {
+    /** 保持原生的名字。 */
+    readonly visible: readonly string[];
+    /** 被遮蔽的名字。 */
+    readonly masked: readonly string[];
+}
+/**
+ * 造一个 Code Mode 执行器。
+ *
+ * @param ctx - 本包的行上下文（读取系统提示段的排序位）。
+ * @param rules - 已归一化的规则。
+ * @param hooks - 归属视图、说明段与委托目标。
+ * @returns 执行器。
+ */
+export declare function createCodemodeExecutor(ctx: unknown, rules: CodemodeRules, hooks: ExecutorHooks): CodemodeExecutor;
+/**
+ * 一条模型直呼调用的拒绝理由，或 `undefined` 表示放行。
+ *
+ * @param call - 批里的一条调用。
+ * @param rules - 已归一化的规则。
+ * @param hooks - 归属视图与说明段。
+ * @param batchSignal - 批级 signal。
+ * @returns 拒绝理由或 `undefined`。
+ *
+ * 判定不读「本步可见名清单」：那份集合是**执行器级**的，多个会话并发时会被后一次 describe
+ * 覆盖，用它放行等于给另一个会话开一个不该开的口子。这里只按名字自身的归属判一次。
+ */
+export declare function denialFor(call: unknown, rules: CodemodeRules, hooks: Pick<ExecutorHooks, 'viewForName' | 'sectionText'>, batchSignal: unknown): string | undefined;
+//# sourceMappingURL=executor.d.ts.map

package/lib/types/host/codemode/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../../src/host/codemode/executor.ts"],"names":[],"mappings":"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"}

package/lib/types/host/codemode/retention.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 常驻执行环境的生命周期。
+ *
+ * 部署把 `@deepseek-ai/dsh-ptc-runtime-node` 配成 `executionMode: persistent-in-memory` 时，
+ * 同一个 agent 的多次 `code_run` 会共用一个常驻 REPL：顶层变量、函数与 `import` 的模块
+ * 跨调用存活。可以不去用，但**不能只注册不释放**——常驻环境没有空闲过期，忘了释放会让子进程
+ * 活到进程结束。
+ *
+ * 所以这里把「传了 owner」与「注册了释放」写进同一个动作：结构性无法表达「传了却没释放」。
+ * 清理有两条路，覆盖两种死亡：
+ *
+ * 1. 挂在 **agent** 上的释放：即使本包早已卸载，agent 销毁也会释放它的环境；
+ * 2. 挂在**插件**上的 teardown：卸载或热重载本包时释放所有遗留环境。
+ *
+ * @module @eddyskywalker/dsh-chatgpt-subscription/host/codemode/retention
+ */
+import type { PtcRuntimeLike } from './transport.ts';
+/** 常驻环境管理句柄。 */
+export interface CodemodeRetention {
+    /** 取一个 agent 的 owner（缺省用 agent 本身，保证同一 agent 复用一个环境）。 */
+    owner(agent: unknown): object;
+    /** 释放一个 owner 的常驻环境（幂等）。 */
+    release(owner: object): Promise<void>;
+    /** 释放所有遗留环境（插件卸载时调用）。 */
+    dispose(): Promise<void>;
+}
+/**
+ * 造一个常驻环境管理器。
+ *
+ * @param runtimeOf - 读当前运行时的函数（每次调用重读，运行时可能晚于本插件挂载）。
+ * @returns 管理句柄。
+ */
+export declare function createRetention(runtimeOf: () => PtcRuntimeLike | undefined): CodemodeRetention;
+//# sourceMappingURL=retention.d.ts.map

package/lib/types/host/codemode/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../../../src/host/codemode/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,gBAAgB;AAChB,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;IAC7B,4BAA4B;IAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,yBAAyB;IACzB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,cAAc,GAAG,SAAS,GAAG,iBAAiB,CAgC9F"}

package/lib/types/host/codemode/rules.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Code Mode 的遮蔽规则与恒定说明段。
+ *
+ * 这一层只回答三件事：
+ *
+ * 1. 一个工具名该不该出现在**模型看到的清单**里（{@link isMaskedName}）；
+ * 2. 被遮蔽的工具有哪些（{@link summarizeHidden}，只给日志与 `code_debug` 用，
+ *    **绝不出现在系统提示词里**）；
+ * 3. `tools:sdk` 段写什么（{@link buildCodemodeSectionText}）。
+ *
+ * ## 为什么说明段里没有任何计数
+ *
+ * 系统提示是缓存前缀的第一段。参考实现在这一段里写「有 N 个工具被遮蔽，按
+ * namespace 分布如下」，于是挂一个 MCP 服务端就改写系统提示，前缀缓存从那里起
+ * 全部作废——在 kimi-code / minimax-code 这类按前缀缓存计费的线路上，一次 MCP
+ * 增删就是几万 token 的全价重建。
+ *
+ * 本实现的说明段只依赖 `programFormat`（部署内恒定）与两个工具名（配置常量），
+ * 因此同一部署下逐字节恒定。
+ *
+ * @module @eddyskywalker/dsh-chatgpt-subscription/host/codemode/rules
+ */
+/** 本包自带的程序传输工具名。`run_code` 是内核保留名，注册会抛错。 */
+export declare const DEFAULT_RUN_TOOL_NAME = "code_run";
+/** 发现工具名契约：`[list, search, describe, debug?]`。第一个同时用作 Code Mode 标记。 */
+export declare const DEFAULT_META_TOOLS: readonly string[];
+/** 默认额外遮蔽的名字前缀。 */
+export declare const DEFAULT_HIDDEN_PREFIXES: readonly string[];
+/**
+ * 默认始终原生呈现的名字。
+ *
+ * 恒定系统提示词或子代理运行时契约里点名要求直接调用这些工具（大输出预览补读、调度账本查询、
+ * 进展更新汇报、结构化子代理输出提交，以及 Windows 下替代被撤回 `pwsh` 的 `win_bash`）：
+ * 遮蔽它们要么让提示词指向模型看不见的名字并触发整批 `UNKNOWN_TOOL` 重跑，要么让会话顶层
+ * 失去唯一可用的 Shell。若某个工具当前未在宿主/子会话注册，保留在此集合中不会凭空暴露它。
+ */
+export declare const DEFAULT_NATIVE_TOOLS: readonly string[];
+/** 校验后、脱离原对象并冻结的配置。 */
+export interface CodemodeOptions {
+    /** 是否遮蔽一切不是本预设自己注册的工具。 */
+    readonly nativeScope: boolean;
+    /** 额外剥离的名字前缀。 */
+    readonly hiddenPrefixes: readonly string[];
+    /** 始终原生呈现的名字。 */
+    readonly nativeTools: readonly string[];
+    /** 始终遮蔽的名字。 */
+    readonly hiddenTools: readonly string[];
+    /** 发现工具名。 */
+    readonly metaTools: readonly string[];
+    /** 程序传输工具名。 */
+    readonly runToolName: string;
+    /** 一个程序内可并发的只读子调用上限。 */
+    readonly maxParallelSubCalls: number;
+    /** 一次程序最多允许的子调用次数（固定兜底下限）。 */
+    readonly maxSubCalls: number;
+    /** 调用方是否显式指定了 `maxSubCalls`（显式指定时优先于按分钟折算）。 */
+    readonly explicitMaxSubCalls: boolean;
+    /** 按解析后超时折算的每分钟子调用配额（对齐内核 PTC `maxSubCallsPerMinute`）。 */
+    readonly maxSubCallsPerMinute: number;
+    /** 是否拒绝模型对被遮蔽工具的直接调用。 */
+    readonly guard: boolean;
+    /** 是否注入 / 替换 Code Mode 说明段。 */
+    readonly sdkSection: boolean;
+    /** 是否注册 `code_debug`。 */
+    readonly debug: boolean;
+}
+/** 原始配置（全部可选）。 */
+export interface CodemodeConfig {
+    /** 见 {@link CodemodeOptions.nativeScope}。 */
+    nativeScope?: boolean;
+    /** 见 {@link CodemodeOptions.hiddenPrefixes}。 */
+    hiddenPrefixes?: readonly string[];
+    /** 见 {@link CodemodeOptions.nativeTools}。 */
+    nativeTools?: readonly string[];
+    /** 见 {@link CodemodeOptions.hiddenTools}。 */
+    hiddenTools?: readonly string[];
+    /** 见 {@link CodemodeOptions.metaTools}。 */
+    metaTools?: readonly string[];
+    /** 见 {@link CodemodeOptions.runToolName}。 */
+    runToolName?: string;
+    /** 见 {@link CodemodeOptions.maxParallelSubCalls}。 */
+    maxParallelSubCalls?: number;
+    /** 见 {@link CodemodeOptions.maxSubCalls}。 */
+    maxSubCalls?: number;
+    /** 见 {@link CodemodeOptions.maxSubCallsPerMinute}。 */
+    maxSubCallsPerMinute?: number;
+    /** 见 {@link CodemodeOptions.guard}。 */
+    guard?: boolean;
+    /** 见 {@link CodemodeOptions.sdkSection}。 */
+    sdkSection?: boolean;
+    /** 见 {@link CodemodeOptions.debug}。 */
+    debug?: boolean;
+}
+/** 名字集合与已归一化配置：判定遮蔽所需的全部输入。 */
+export interface CodemodeRules {
+    /** 归一化后的配置。 */
+    readonly options: CodemodeOptions;
+    /** `hiddenTools` + 发现工具的集合形态（只留给程序内部调用）。 */
+    readonly hidden: ReadonlySet<string>;
+    /** `nativeTools` + 传输工具的集合形态。 */
+    readonly native: ReadonlySet<string>;
+}
+/**
+ * 把原始配置归一化。
+ *
+ * @param config - 行配置；`null` / 省略表示默认值。
+ * @returns 冻结的配置与集合。
+ */
+export declare function createRules(config?: CodemodeConfig | null): CodemodeRules;
+/**
+ * 校验并冻结一份配置。
+ *
+ * @param config - 原始配置。
+ * @returns 规范化后的只读配置。
+ */
+export declare function normalizeConfig(config?: CodemodeConfig | null): CodemodeOptions;
+/**
+ * 归属视图：哪些名字在全局层、哪些在本预设层。
+ *
+ * `enabled === false` 表示作用域探测失败（本包被挂在了 host 层而不是预设里），
+ * 此时作用域规则整体失效，只保留名字规则——绝不因为读不到归属就误遮蔽。
+ */
+export interface CodemodeView {
+    /** 作用域规则是否可用。 */
+    readonly enabled: boolean;
+    /** 全局层（MCP 服务端、profile 级 bundle）能解析到的名字。 */
+    readonly globalNames: ReadonlySet<string>;
+    /** 本预设层能解析到的名字（含祖先层，因此包含全局层）。 */
+    readonly presetNames: ReadonlySet<string>;
+}
+/** 作用域不可用时的空视图。 */
+export declare const DISABLED_VIEW: CodemodeView;
+/**
+ * 判定一个名字是否要从模型清单里剥离。
+ *
+ * 顺序：显式例外（`nativeTools` / 传输工具 / 发现工具）→ 显式遮蔽
+ * （`hiddenTools`）→ 名字前缀 → 作用域归属。
+ *
+ * 作用域归属只在能确认归属时遮蔽：
+ *
+ * - 在全局视图里解析得到 → 全局层注册的，遮蔽；
+ * - 只在预设视图里解析得到 → 本预设自己注册的，保持原生；
+ * - 两处都解析不到 → 只可能注册在本预设之下（agent 层），遮蔽。
+ *
+ * @param name - 工具名。
+ * @param rules - 已归一化的规则。
+ * @param view - 归属视图。
+ * @returns 要遮蔽时为 `true`。
+ */
+export declare function isMaskedName(name: string | undefined, rules: CodemodeRules, view: CodemodeView): boolean;
+/** 被遮蔽工具的汇总：只用于日志与 `code_debug`。 */
+export interface HiddenSummary {
+    /** 被遮蔽的工具总数。 */
+    readonly total: number;
+    /** 按 namespace 分组的计数。 */
+    readonly namespaces: readonly {
+        readonly namespace: string;
+        readonly kind: 'mcp' | 'plugin';
+        readonly count: number;
+    }[];
+}
+/**
+ * 汇总被遮蔽的工具。
+ *
+ * @param names - 被遮蔽的名字。
+ * @returns 计数与分组。
+ */
+export declare function summarizeHidden(names: readonly string[]): HiddenSummary;
+/** 生成说明段所需的最小输入。 */
+export interface SectionInput {
+    /** 程序传输工具名。 */
+    readonly runToolName: string;
+    /** 发现工具名。 */
+    readonly metaTools: readonly string[];
+    /** 运行时的源码语言（默认 `typescript`）。 */
+    readonly language?: string;
+    /** 运行时的程序形态；`repl` 表示常驻 REPL。 */
+    readonly programFormat?: string;
+}
+/**
+ * 生成 `tools:sdk` 段的正文。
+ *
+ * ## 恒定契约
+ *
+ * 这段正文**只**依赖入参里的两个工具名与部署级的 `language` / `programFormat`。它刻意不含遮蔽
+ * 工具的数量、namespace 分布、会话 id 或时间，因此同一部署下逐字节恒定：挂载或卸载
+ * MCP 服务端不会改写它，前缀缓存不会因为它失效。
+ *
+ * @param input - 传输工具名、发现工具名与程序形态。
+ * @returns 说明段正文。
+ */
+export declare function buildCodemodeSectionText(input: SectionInput): string;
+//# sourceMappingURL=rules.d.ts.map

package/lib/types/host/codemode/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../../src/host/codemode/rules.ts"],"names":[],"mappings":"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"}

package/lib/types/host/codemode/scope.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 工具归属判定：一个名字是**全局层**注册的，还是**本预设**注册的。
+ *
+ * ## 为什么要这么绕
+ *
+ * 注册表没有公开「某个工具注册在哪个作用域」的 API。`@deepseek-ai/dsh-scope` 把作用域标签
+ * 写在一个模块私有的 `Symbol('dsh.scope')` 上，链关系（parent）也在私有 WeakMap 里，
+ * 都不导出。能用的只有两件事：
+ *
+ * 1. 本包自己所在作用域的 key —— 按符号描述从 ctx 上扫出来（{@link findScopeKey}）；
+ * 2. 公开的 `ctx.tools.get(name)`（全局视图）与 `ctx.tools.get(name, key)`（该作用域视图）。
+ *
+ * 于是归属判定变成两次公开查询：
+ *
+ * - 全局视图能解析 → 全局层（MCP 服务端、profile 级 bundle）；
+ * - 只有本预设视图能解析 → 本预设自己注册的；
+ * - 两处都解析不到 → 只可能注册在本预设之下（agent 层）。
+ *
+ * 探测失败（本包被挂在 host 层而不是预设里）时返回 `enabled: false`：规则整体降级为
+ * 纯名字匹配，绝不因为读不到归属就误遮蔽。
+ *
+ * @module @eddyskywalker/dsh-chatgpt-subscription/host/codemode/scope
+ */
+import { type CodemodeView } from './rules.ts';
+/** 作用域不可用时的空视图（从规则模块转出，调用方只需认识一个模块）。 */
+export { DISABLED_VIEW } from './rules.ts';
+/**
+ * 从一个 ctx 上找出「本包所在作用域」的 key。
+ *
+ * Cordis 的 scoped context 把作用域标签写成自有（或原型上）的一个 symbol 属性，
+ * 描述是 `dsh.scope`。这里按描述扫，不猜符号本身——写法与参考实现一致，因为
+ * 直接 `import` 内核的 scope 包在 profile 插件里解析不到。
+ *
+ * @param ctx - 本包的行上下文。
+ * @returns 作用域 key；读不到时为 `undefined`。
+ */
+export declare function findScopeKey(ctx: unknown): object | undefined;
+/**
+ * 为一个名字清单建立归属视图。
+ *
+ * @param tools - 工具注册表（结构探测，不看类身份）。
+ * @param scopeKey - 本预设的作用域 key；`undefined` 表示探测失败。
+ * @param names - 要判定的名字（通常是本步的模型可见清单）。
+ * @returns 归属视图；读不到任何归属时返回禁用视图。
+ */
+export declare function resolveCatalogView(tools: unknown, scopeKey: object | undefined, names: readonly string[]): CodemodeView;
+/**
+ * 判定一个名字在**调用时**是否属于本预设之外的层。
+ *
+ * 拒绝路径（模型直呼被遮蔽的名字）没有当步清单可用，只能按同一个视图单独判一次；
+ * 判定规则与 {@link resolveCatalogView} 完全一致，两处因此不可能给出互相矛盾的结论。
+ *
+ * @param tools - 工具注册表。
+ * @param scopeKey - 本预设的作用域 key。
+ * @param name - 工具名。
+ * @returns 归属视图（只含这一个名字）。
+ */
+export declare function resolveNameView(tools: unknown, scopeKey: object | undefined, name: string): CodemodeView;
+//# sourceMappingURL=scope.d.ts.map

package/lib/types/host/codemode/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../../src/host/codemode/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAE7D,wCAAwC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAW1C;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI7D;AA0BD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,YAAY,CAWd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAQxG"}