@dsh-workbench/core 0.3.4 → 0.3.6

package/dist/types/modules/panels/client.d.ts

@@ -1 +1 @@
-export { ALL_TOOLS, DIY_RECORD_PREPARE_TOOL, DIY_RECORD_READ_TOOL } from './unit';
+export { ALL_TOOLS, DIY_RECORD_PREPARE_TOOL, DIY_RECORD_READ_TOOL, LONG_TASKS_STOP_TOOL } from './unit';

package/dist/types/modules/panels/model/approval.d.ts

@@ -1,2 +1,10 @@
 import type { ApprovalPolicy } from '@dsh-workbench/shared/host';
+import type { LongTaskRunsLookup } from './long-task-tools';
 export declare const panelsApproval: ApprovalPolicy;
+/**
+ * 面板族的审批策略：`panelsApproval` 再认长任务那一档（写成功要用户点头）。
+ * `longTaskRuns` 用来查"这一趟是谁起的" —— 自己起的免问，别的会话起的 / 用户按的要问。
+ * @param longTaskRuns 当前挂着的单元各自那把长任务注册表；没给就按"别人的"问（保守的那一侧）。
+ * @returns 审批策略：认领的写工具回 ask / allow，不是本族的回 undefined。
+ */
+export declare function panelsApprovalFor(longTaskRuns?: LongTaskRunsLookup | undefined): ApprovalPolicy;

package/dist/types/modules/panels/model/diy-context.d.ts

@@ -1,5 +1,4 @@
 import type { DshHostContext, DshToolRunContext } from '@dsh-workbench/shared';
-import { type BrowserFindResult, type BrowserReadResult } from '@dsh-workbench/shared/host';
 import type { BundleChange } from '../../../shared/api/bundle-install';
 import type { PanelsService } from './service';
 export declare const OUTPUT_SCHEMA: {
@@ -85,18 +84,18 @@ export declare function asNumber(value: unknown): number | undefined;
 export declare function asText(value: unknown): string;
 export declare function plainJson<T>(value: T): T;
 export declare function verdictOf(change: BundleChange): string;
-export declare function renderProbe(out: BrowserReadResult): string;
-export declare function renderFind(out: BrowserFindResult): string;
 export declare function showOrReason(panels: PanelsService, unit: string, workspace: string | null): {
     readonly ok: boolean;
     readonly reason?: string;
 };
-export declare function workshopOf(ctx: DshHostContext, exec: DshToolRunContext): {
+export declare function workshopOf(ctx: DshHostContext, exec: DshToolRunContext): Promise<{
     readonly packagesDir: string;
     readonly workspace: string | null;
-};
+    readonly title: string;
+}>;
 export declare function modulesOf(ctx: DshHostContext, packagesDir: string): {
     installed: string[];
     modules: readonly import("@/shared/api/host/diy-workshop").WorkshopModule[];
 };
+export declare function moduleDirsOf(packagesDir: string): readonly string[];
 export declare function panelEntriesOf(panels: PanelsService, workspace: string | null): import("./config").PanelEntry[];

package/dist/types/modules/panels/model/diy-observers.d.ts

@@ -7,5 +7,5 @@ export interface ObserverCleanup {
 export interface CleanupLog {
     warn?(message: string): void;
 }
-export declare function stopObservers(ctx: DshHostContext, session?: string): Promise<ObserverCleanup>;
-export declare function withObserverCleanup(store: DebugStore, cleanup: () => Promise<ObserverCleanup>, logger?: CleanupLog | undefined): DebugStore;
+export declare function stopObservers(ctx: DshHostContext, workspace: string | null | undefined, session?: string): Promise<ObserverCleanup>;
+export declare function withObserverCleanup(store: DebugStore, cleanup: (workspace: string | null) => Promise<ObserverCleanup>, logger?: CleanupLog | undefined): DebugStore;

package/dist/types/modules/panels/model/diy-page.d.ts

@@ -26,5 +26,5 @@ export declare function debugForeignPactText(held: DebugState): string;
 export declare function debugOffBoardText(held: DebugState, situation?: BoardSituation): string;
 export declare function boardProbeOf(page: WorkbenchPage): BoardProbe;
 export declare function boardStateOf(page: WorkbenchPage, workshop: string | null): BoardState;
-export declare function boardGateText(situation: BoardSituation, unit: string, page: WorkbenchPage): string;
+export declare function boardGateText(situation: BoardSituation, unit: string, page: WorkbenchPage, title?: string): string;
 export declare function pageAt(ctx: DshHostContext, exec: DshToolRunContext, raw: unknown, options?: PageOptions): Promise<PageHandle>;

package/dist/types/modules/panels/model/long-task-tools.d.ts

@@ -0,0 +1,15 @@
+import type { DshHostContext } from '@dsh-workbench/shared';
+import type { LongTaskBase, LongTaskRegistry } from '@dsh-workbench/shared/host';
+/**
+ * 当前挂着的单元各自那把长任务注册表（晚绑定的取值器，形状同 `UnitMountDeps.longTaskRuns`）。
+ */
+export type LongTaskRunsLookup = () => ReadonlyMap<string, LongTaskRegistry<LongTaskBase>>;
+/**
+ * 注册长任务那两把外壳工具：看得见（`workbench_long_tasks_list`）与停得了任何单元的一趟
+ * （`workbench_long_tasks_stop`）。`longTaskRuns` 是晚绑定的取值器：两把都从它取注册表，
+ * 所以单元晚挂上 / 被摘掉都跟得上；没给的话停那把一律回"没有这一趟"。
+ * @param ctx 宿主上下文，`tools` 服务不在时什么都不注册。
+ * @param longTaskRuns 当前挂着的单元各自那把长任务注册表。
+ * @returns 注销函数（没有 tools 服务就是空数组）。
+ */
+export declare function registerLongTaskTools(ctx: DshHostContext, longTaskRuns?: LongTaskRunsLookup | undefined): Array<() => void>;

package/dist/types/modules/panels/model/long-task-tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modules/panels/unit.d.ts

@@ -20,7 +20,6 @@ export declare const DIY_PANEL_TOOL = "workbench_diy_panel";
 export declare const DIY_COMPONENTS_TOOL = "workbench_diy_components";
 export declare const DIY_RECON_TOOL = "workbench_diy_recon";
 export declare const DIY_SPEC_TOOL = "workbench_diy_spec";
-export declare const DIY_PROBE_TOOL = "workbench_diy_probe";
 export declare const DIY_INSTALL_TOOL = "workbench_diy_install";
 export declare const DIY_SHOW_TOOL = "workbench_diy_show";
 export declare const DIY_STATE_TOOL = "workbench_diy_state";
@@ -44,15 +43,17 @@ export declare const DIY_RECORD_PREPARE_TOOL = "workbench_diy_record_prepare";
 export declare const DIY_RECORD_READ_TOOL = "workbench_diy_record_read";
 export declare const DIY_RECORD_DETAIL_TOOL = "workbench_diy_record_detail";
 export declare const DIY_RECORD_STOP_TOOL = "workbench_diy_record_stop";
+export declare const LONG_TASKS_LIST_TOOL = "workbench_long_tasks_list";
+export declare const LONG_TASKS_STOP_TOOL = "workbench_long_tasks_stop";
 export declare const DIY_DEBUG_START_TOOL = "workbench_diy_debug_start";
 export declare const DIY_DEBUG_PAUSE_TOOL = "workbench_diy_debug_pause";
 export declare const DIY_DEBUG_RESUME_TOOL = "workbench_diy_debug_resume";
 export declare const DIY_DEBUG_STOP_TOOL = "workbench_diy_debug_stop";
-export declare const ALL_TOOLS: readonly ["workbench_panels_list", "workbench_panels_show", "workbench_panels_hide", "workbench_panels_move", "workbench_panels_reset", "workbench_panels_follow", "workbench_modules_list", "workbench_modules_install", "workbench_modules_update", "workbench_modules_uninstall", "workbench_modules_install_bundle", "workbench_modules_update_dependency", "workbench_modules_update_plugin", "workbench_modules_uninstall_plugin", "workbench_modules_update_workbench", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_probe", "workbench_diy_install", "workbench_diy_show", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop", "workbench_diy_record_prepare", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop", "workbench_diy_debug_start", "workbench_diy_debug_pause", "workbench_diy_debug_resume", "workbench_diy_debug_stop"];
+export declare const ALL_TOOLS: readonly ["workbench_panels_list", "workbench_panels_show", "workbench_panels_hide", "workbench_panels_move", "workbench_panels_reset", "workbench_panels_follow", "workbench_modules_list", "workbench_modules_install", "workbench_modules_update", "workbench_modules_uninstall", "workbench_modules_install_bundle", "workbench_modules_update_dependency", "workbench_modules_update_plugin", "workbench_modules_uninstall_plugin", "workbench_modules_update_workbench", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_install", "workbench_diy_show", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop", "workbench_diy_record_prepare", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop", "workbench_diy_debug_start", "workbench_diy_debug_pause", "workbench_diy_debug_resume", "workbench_diy_debug_stop", "workbench_long_tasks_list", "workbench_long_tasks_stop"];
 export type PanelsToolName = (typeof ALL_TOOLS)[number];
-export declare const READ_TOOLS: readonly ["workbench_panels_list", "workbench_modules_list", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_probe", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop"];
-export declare const WRITE_TOOLS: readonly ["workbench_panels_show", "workbench_panels_hide", "workbench_panels_move", "workbench_panels_reset", "workbench_panels_follow", "workbench_modules_install", "workbench_modules_update", "workbench_modules_uninstall", "workbench_modules_install_bundle", "workbench_modules_update_dependency", "workbench_modules_update_plugin", "workbench_modules_uninstall_plugin", "workbench_modules_update_workbench", "workbench_diy_install", "workbench_diy_show", "workbench_diy_record_prepare", "workbench_diy_debug_start", "workbench_diy_debug_pause", "workbench_diy_debug_resume", "workbench_diy_debug_stop"];
-export declare const DIY_TOOLS: readonly ["workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_probe", "workbench_diy_install", "workbench_diy_show", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop"];
+export declare const READ_TOOLS: readonly ["workbench_panels_list", "workbench_modules_list", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop", "workbench_long_tasks_list"];
+export declare const WRITE_TOOLS: readonly ["workbench_panels_show", "workbench_panels_hide", "workbench_panels_move", "workbench_panels_reset", "workbench_panels_follow", "workbench_modules_install", "workbench_modules_update", "workbench_modules_uninstall", "workbench_modules_install_bundle", "workbench_modules_update_dependency", "workbench_modules_update_plugin", "workbench_modules_uninstall_plugin", "workbench_modules_update_workbench", "workbench_diy_install", "workbench_diy_show", "workbench_diy_record_prepare", "workbench_diy_debug_start", "workbench_diy_debug_pause", "workbench_diy_debug_resume", "workbench_diy_debug_stop", "workbench_long_tasks_stop"];
+export declare const DIY_TOOLS: readonly ["workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_install", "workbench_diy_show", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop"];
 export declare const DIY_RECORD_TOOLS: readonly ["workbench_diy_record_prepare", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop"];
 export declare const DIY_DEBUG_TOOLS: readonly ["workbench_diy_debug_start", "workbench_diy_debug_pause", "workbench_diy_debug_resume", "workbench_diy_debug_stop"];
 export declare const panelsUnit: UnitManifest;

package/dist/types/shared/api/context-chips.d.ts

@@ -1,10 +1,30 @@
 import type { DshClientContext } from '@dsh-workbench/shared';
 import { type ContextRef } from '@dsh-workbench/shared';
+/**
+ * 对话 `@` 引用源报名用的名字：引用、lexicon 与编解码都挂在这个 source 名下。
+ */
 export declare const CONTEXT_SOURCE = "workbench";
+/**
+ * `addContextChip` 的结果：`inserted` 真插进输入框了、`unavailable` 这台 dsh 缺服务或当时插不进去。
+ */
 export type ChipResult = 'inserted' | 'unavailable';
+/**
+ * 装引用源要的外壳依赖：现在这个会话是哪一个 —— 拿不到 session id 就插不了。
+ */
 export interface ContextChipsDeps {
     currentSessionId(): string | undefined;
 }
+/**
+ * 外壳启动、拿到 dsh 的 client context 之后调一次：把 `@` 引用源注册进对话输入框；
+ * dsh 没给 `inputTriggers` 时不装、也不报错。
+ */
 export declare function installContextChips(ctx: DshClientContext, deps: ContextChipsDeps): void;
+/**
+ * 要往当前对话输入框插一条 `@` 引用时调用（卡片上“发到对话”那类动作）：同步返回，只反映当场这一拍 ——
+ * 没插进去会自己再试几拍，后面成功了也不会回头改这个返回值。没装过 / 没会话 / 拿不到输入框都回 `unavailable`。
+ */
 export declare function addContextChip(ref: ContextRef, label: string): ChipResult;
+/**
+ * 把编好的引用串码成带 `@` 的标记文本（输入框里显示与复制到剪贴板都是这一份）；认不出的串原样加个 `@`。
+ */
 export declare function serializeChipRef(encoded: string): string;

package/dist/types/shared/api/host/approval-call.d.ts

@@ -0,0 +1,16 @@
+import type { DshToolRunContext } from '@dsh-workbench/shared';
+import { type ApprovalCall } from '@dsh-workbench/shared/host';
+/**
+ * 审批那一拍看到的这次工具调用：工具名 / 实参 / 所在工作区 / 发起的会话。
+ */
+export interface ApprovalExec {
+    readonly arguments?: unknown;
+    readonly agent?: DshToolRunContext['agent'];
+}
+/**
+ * 把 dsh 交来的那次工具调用折成审批策略要看的那份 call：工作区与发起会话都从 `exec` 现取，取不到就不写那个键。
+ * @param exec dsh 交来的执行上下文；没有就只有实参这一格。
+ * @param name 工具名；`undefined` = 这次调用没名字，不写这个键。
+ * @returns 交给 `approvalFor` 的 `ApprovalCall`。
+ */
+export declare function approvalCallOf(exec: ApprovalExec | undefined, name: string | undefined): ApprovalCall;

package/dist/types/shared/api/host/diy-components.d.ts

@@ -18,8 +18,9 @@ export declare function scopeOf(raw: string): SurfaceScope;
 export declare function wantsPrimitives(scope: SurfaceScope): boolean;
 export declare function wantsKit(scope: SurfaceScope): boolean;
 export declare function toolchainBinOf(root: string): string | null;
+export declare function toolchainBinAmong(root: string, dirs: readonly string[]): string | null;
 export declare function queryCommandOf(bin: string, only: 'kit' | 'primitives'): string;
-export declare function runSurfaceQuery(shell: DshShell, bin: string, only: 'kit' | 'primitives', root: string): Promise<SurfacePayload>;
+export declare function runSurfaceQuery(shell: DshShell, bin: string, only: 'kit' | 'primitives', root: string, fallbackBin?: string): Promise<SurfacePayload>;
 export declare function filesOf(payload: SurfacePayload | undefined): Record<string, string>;
 export declare function rootsOf(payload: SurfacePayload | undefined): Record<string, string>;
 export declare function countsOf(payload: SurfacePayload | undefined): Record<string, number>;
@@ -31,19 +32,29 @@ export declare function findFileOf(name: string, query: SurfaceQuery): {
 } | null;
 export declare function excerptOf(text: string, maxLines?: number): string;
 export declare function excerptAt(file: string, maxLines?: number): string;
+/** 指引目录：从宿主产物往上找 `skills/workbench-module-diy`（找不到回 `null`）。 */
 export declare function skillDirOf(from: string): string | null;
-export declare function symbolsIn(heading: string): readonly string[];
-export declare function docSectionOf(name: string, dir: string | null): {
-    readonly file: string;
-    readonly lines: string;
-} | null;
 export declare function byLocationOf(payload: SurfacePayload): readonly {
     readonly where: string;
     readonly names: readonly string[];
 }[];
+export interface SurfaceBucket {
+    readonly label: string;
+    readonly key: string;
+    readonly names: readonly string[];
+}
+export declare function kitBucketsOf(payload: SurfacePayload): readonly SurfaceBucket[];
+export declare function matchesBucket(where: string, bucket: string): boolean;
+export declare function bucketNamesOf(query: SurfaceQuery): readonly {
+    readonly face: 'kit' | 'primitives';
+    readonly keys: readonly string[];
+}[];
+export declare const TWO_FACE_ALL = "\u26A0\uFE0F \u4E24\u4E2A\u9762\u4E00\u8D77\u4E0D\u7ED9\u5168\u8868 \u2014\u2014 \u8981\u5168\u8868\u5C31\u6307\u540D\u4E00\u9762\uFF1Ascope=kit \u6216 scope=primitives\u3002";
+export declare function refusesEvery(scope: SurfaceScope, all: boolean, focused: boolean): boolean;
 export declare function renderSurfaceText(query: SurfaceQuery, options: {
     scope: SurfaceScope;
     all: boolean;
+    bucket?: string;
 }): string;
 export declare function listedNamesOf(query: SurfaceQuery): readonly string[];
 export type FaceState = 'not-queried' | 'ok' | 'unreadable';

package/dist/types/shared/api/host/diy-workshop.d.ts

@@ -1,4 +1,3 @@
-import type { DshHostContext } from '@dsh-workbench/shared';
 export interface WorkshopModule {
     readonly unit: string;
     readonly name: string;
@@ -6,11 +5,9 @@ export interface WorkshopModule {
     readonly dir: string;
     readonly installed: boolean;
 }
-export declare function workshopPackagesDir(ctx: DshHostContext): string | null;
 export declare function insideWorkshop(root: string, target: string): boolean;
 export declare function workshopModules(packagesDir: string, installed?: readonly string[]): readonly WorkshopModule[];
 export declare function readDesignOfModule(dir: string): unknown;
-export declare function inWorkshopSession(ctx: DshHostContext, workspace: string | null): boolean;
 export interface WorkshopSync {
     readonly state: 'ok' | 'syncing' | 'failed';
     readonly version: string;

package/dist/types/shared/api/host/long-task-notice.d.ts

@@ -0,0 +1,30 @@
+import type { LongTaskBase, LongTaskChange } from '@dsh-workbench/shared/host';
+import { type AgentsLookup, type NoticeDelivery, type NoticeMessage } from './diy-debug-act';
+/**
+ * 这条 notice 的来源标识（`source.kind`）—— 长任务自己一格，与调试 / 录制分开。
+ */
+export declare const LONG_TASK_NOTICE_KIND = "workbench-long-task";
+/**
+ * 一条"这一趟被停了"的 notice：发给谁（`session`）、说什么（`message` / `summary`）。
+ */
+export interface LongTaskStopNotice {
+    readonly session: string;
+    readonly message: NoticeMessage;
+    readonly summary: string;
+}
+/**
+ * 判这一趟被停要不要回流给发起它的那个会话，并把话写好。
+ * 只有"结算 + `stopped` + 这一趟记得会话 + 不是它自己停的"才回一条；跑完 / 失败 / 界面起的（没记会话）/ 自己停的回 `null`。
+ * @param unit 这一趟属于哪个单元（进文案）。
+ * @param change 长任务那一次变更；只有 `kind: 'settle'` 且 `snapshot.status === 'stopped'` 才可能成。
+ * @returns 该发的那条（带收件会话），或者 `null`（不发）。
+ */
+export declare function longTaskStopNotice(unit: string, change: LongTaskChange<LongTaskBase>): LongTaskStopNotice | null;
+/**
+ * 把"这一趟被停了"送出去：正在跑的会话 inject 一条、闲着的跳过、没有这个 agent 就当没发生（模式 `drop`）。
+ * @param agents 会话表（宿主从 `ctx.get('agents')` 拿）；拿不到就什么都不发。
+ * @param unit 这一趟属于哪个单元。
+ * @param change 长任务那一次变更。
+ * @returns 送出去的结果；判据说不该发（`longTaskStopNotice` 回 `null`）就回 `null`。
+ */
+export declare function notifyLongTaskStop(agents: AgentsLookup | undefined, unit: string, change: LongTaskChange<LongTaskBase>): NoticeDelivery | null;

package/dist/types/shared/api/host/mount-units.d.ts

@@ -1,7 +1,7 @@
 import type { DshHostContext } from '@dsh-workbench/shared';
 import type { UnitManifest } from '@dsh-workbench/shared/host';
 import { type RouteTable } from '@dsh-workbench/shared/host';
-import type { ContextRenderer, UnitMountDeps, UnitMountResult, UnitCall } from '@dsh-workbench/shared/host';
+import type { ContextRenderer, LongTaskBase, LongTaskChange, LongTaskRegistry, UnitMountDeps, UnitMountResult, UnitCall } from '@dsh-workbench/shared/host';
 import type { HostUnit } from './unit-registry';
 import { type UnitReadiness } from './unit-readiness';
 export declare function declaredNotesOf(plans: Iterable<{
@@ -67,6 +67,8 @@ export declare function mountUnits(units: readonly HostUnit[], deps: {
     longTasks?: {
         readonly scope: string;
         readonly bump: (facts: readonly string[]) => void;
+        readonly notify?: ((change: LongTaskChange<LongTaskBase>) => void) | undefined;
     } | undefined;
+    longTaskRuns?: Map<string, LongTaskRegistry<LongTaskBase>> | undefined;
 }): UnitsPlan;
 export {};

package/dist/types/shared/api/host/preset-scope.d.ts

@@ -0,0 +1,16 @@
+import type { DshHostContext } from '@dsh-workbench/shared';
+import { type ToolScopeContext } from '@dsh-workbench/shared/host';
+import { type ToolScope } from './tool-scope';
+export interface SessionProjections {
+    stateOf(session: unknown, key: string): unknown;
+    onChanged(listener: (session: unknown, key: string, value: unknown, seq: unknown) => void): () => void;
+}
+export interface PresetScopeOptions {
+    readonly ctx: DshHostContext;
+    readonly deniedTools: (context: ToolScopeContext) => readonly string[];
+    readonly logger?: {
+        info?(message: string): void;
+        warn?(message: string): void;
+    } | undefined;
+}
+export declare function createPresetScope(options: PresetScopeOptions): ToolScope;

package/dist/types/shared/api/host/tool-scope.d.ts

@@ -1,4 +1,5 @@
 import type { DshPromptAssembly } from '@dsh-workbench/shared';
+import type { ToolScopeContext } from '@dsh-workbench/shared/host';
 export interface ScopedToolRegistry {
     restrict(filter: {
         readonly allow?: readonly string[];
@@ -11,13 +12,16 @@ export interface ToolScopeAgent {
         get?<T = unknown>(name: string): T | undefined;
     } | undefined;
     readonly session?: {
+        readonly id?: string | undefined;
         readonly header?: {
-            readonly cwd?: string;
+            readonly cwd?: string | undefined;
+            readonly agentPreset?: string | undefined;
         } | undefined;
     } | undefined;
 }
 export interface ToolScopeOptions {
-    deniedTools(workspace: string | null): readonly string[];
+    deniedTools(context: ToolScopeContext): readonly string[];
+    presetOf?: ((handle: ToolScopeAgent) => string | null) | undefined;
     logger?: {
         info?(message: string): void;
         warn?(message: string): void;

package/dist/types/shared/api/host/workshop-root.d.ts

@@ -0,0 +1,7 @@
+import type { DshHostContext } from '@dsh-workbench/shared';
+export interface WorkshopRoot {
+    readonly root: string;
+    readonly packagesDir: string;
+    readonly title: string;
+}
+export declare function workshopRootOf(ctx: DshHostContext, workspace: string | null): Promise<WorkshopRoot | null>;

package/dist/types/shared/components/BlockerState.d.ts

@@ -1,5 +1,8 @@
 import type { ModuleBlocker } from '@dsh-workbench/shared';
 import type { Translate } from '@dsh-workbench/shared';
+/**
+ * `<BlockerState>` 的 prop：一份 blocker 加几个回调。
+ */
 export interface BlockerStateProps {
     readonly blocker: ModuleBlocker;
     readonly t: Translate;
@@ -8,4 +11,13 @@ export interface BlockerStateProps {
     readonly flush?: boolean;
     readonly onOpenMarket?: () => void;
 }
+/**
+ * 卡片被挡住（或要给一句 notice）时渲染的那一块：按 `blocker.severity` 出块状或一行提示，动作接重试 / 跑修复 / 复制。
+ * @param props.blocker - 要显示的那份 blocker：`title` / `hint` / `detail` / `actions` / `severity`。
+ * @param props.t - 翻译函数，这一块出现的每句话都从它来。
+ * @param props.onRetry - `retry` 动作与修复成功后的重试回调。
+ * @param props.onOpenMarket - `open-market` 动作；没给就退回 `onRetry`。
+ * @param props.busy - 外层是不是在忙（默认 `false`）；为真时动作一并禁用。
+ * @param props.flush - 是否贴着容器边（默认 `false`）：去掉图标、收窄留白，给卡片内嵌用。
+ */
 export declare function BlockerState({ blocker, t, onRetry, busy, flush, onOpenMarket, }: BlockerStateProps): JSX.Element;

package/dist/types/shared/components/PanelFoot.d.ts

@@ -1,7 +1,16 @@
 import type { ReactNode } from '@dsh-workbench/shared';
+/**
+ * `<PanelFoot>` 的 prop：左边一句脚注，右边一格内容。
+ */
 export interface PanelFootProps {
     readonly text?: string;
     readonly size?: 'sm' | 'md';
     readonly children?: ReactNode;
 }
+/**
+ * 面板底部那行脚注：左侧一句 `text`，右侧放 `children`，两样都不给就是一个空的页脚壳。
+ * @param props.text - 左侧那句说明文字；不传时左侧什么都不渲染。
+ * @param props.size - 文字档（默认 `'sm'`，11px 三级色；`'md'` 是 14px 二级色，给更宽的面板用）。
+ * @param props.children - 右侧那一格内容（一般是按钮或状态），可省略。
+ */
 export declare function PanelFoot({ text, size, children }: PanelFootProps): JSX.Element;

package/dist/types/shared/components/Tip.d.ts

@@ -1,4 +1,12 @@
 import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives';
 type TooltipProps = Parameters<typeof Tooltip>[0];
+/**
+ * dsh `Tooltip` 的外壳默认值版：说明统一按右栏习惯（`bottom` / `end` / `gap 6` / 挂 body）来，其余 prop 原样转给 `Tooltip`。
+ * @param props.side - 气泡出现在锚点哪一侧（默认 `'bottom'`）。
+ * @param props.align - 底 / 顶气泡贴锚点哪条边（默认 `'end'`）。
+ * @param props.gap - 锚点到气泡的间距（默认 `6`）。
+ * @param props.portal - 是否挂到 `document.body`，以逃出裁剪容器与层叠上下文（默认 `true`）。
+ * @param props.children - 单个锚点元素；`label` / `shortcutKeys` / `openOnClick` 等其余 prop 与 dsh 同形。
+ */
 export declare function Tip({ side, align, gap, portal, ...rest }: TooltipProps): JSX.Element;
 export {};

package/dist/types/shared/hooks/bundle-queries.d.ts

@@ -1,7 +1,19 @@
 import type { ApiResponse } from '@dsh-workbench/shared';
 import { type BundleInspectionPayload, type BundleRegistriesPayload, type ModuleVersionsPayload } from '../api/bundle-install';
 import { type InstalledPluginsPayload } from '../api/installed-plugins';
+/**
+ * 读模块源注册表：装模块时能从哪些源取、当前解析到哪一个。
+ */
 export declare function readBundleRegistries(): Promise<ApiResponse<BundleRegistriesPayload>>;
+/**
+ * 装之前先看清一个 spec 是什么（收了 / 拒了 / 是个插件）；`registry` 省略或空就按默认源解析。
+ */
 export declare function readBundleInspection(spec: string, registry?: string): Promise<ApiResponse<BundleInspectionPayload>>;
+/**
+ * 问模块有没有新版；`force: true` 绕过缓存重新问源（“更新”那条路用）。
+ */
 export declare function readModuleVersions(force?: boolean): Promise<ApiResponse<ModuleVersionsPayload>>;
+/**
+ * 读已装的 opencli 插件台账；`force: true` 绕过缓存重新问一遍。
+ */
 export declare function readInstalledPlugins(force?: boolean): Promise<ApiResponse<InstalledPluginsPayload>>;

package/dist/types/shared/hooks/fact-transports.d.ts

@@ -1,2 +1,6 @@
 import { type FactTransport } from '@dsh-workbench/shared';
+/**
+ * 事实通道的传输选择：有 `EventSource` 就先用 SSE，连不上（重试一拍仍失败）自动降级成长轮询；
+ * 没有 `EventSource` 的运行时直接轮询。返回值是停掉当前这条传输的函数。
+ */
 export declare function createAdaptiveTransport(): FactTransport;

package/dist/types/shared/hooks/panel-state-report.d.ts

@@ -1,12 +1,24 @@
 import type { PanelCardError, PanelCardPhase } from '@dsh-workbench/shared';
+/**
+ * 从路由里切出单元 id（`cmdb/runs` → `cmdb`）；切不出来（没有前缀）回 `null`。
+ */
 export declare function unitOfRoute(route: string): string | null;
+/**
+ * 告诉上报这沓“现在的工作区是哪个”；换工作区会丢掉还没冲出去的待报读数。
+ */
 export declare function setPanelWorkspace(path: string | null): void;
+/**
+ * 卡片读数落地时调它（`useApiResource` 已经接好）：同一单元同一条路由只留最新一条，攒一拍再一起冲给宿主。
+ */
 export declare function reportPanelRead(input: {
     readonly unit: string;
     readonly route: string;
     readonly phase: PanelCardPhase;
     readonly error?: PanelCardError | undefined;
 }): void;
+/**
+ * 卡片崩了时调它：`unit` 与原因立刻报给宿主（不攒）；还不知道工作区时不报。
+ */
 export declare function reportPanelCrash(input: {
     readonly unit: string;
     readonly reason: string;

package/dist/types/shared/hooks/use-api-resource.d.ts

@@ -1,16 +1,38 @@
 import type { ApiError, ApiResponse, Query } from '@dsh-workbench/shared';
+/**
+ * 一次读的状态：`idle` 没开读 · `loading` 在飞 · `ready` 有值 · `error` 失败；`value` 是 `ApiResponse<T>`、
+ * `at` 是拿到这个值的时间戳。**身份没变的重取（如点刷新）进 `loading` 时上一次的 `value` 与 `at` 会留着**
+ * —— 界面照旧有得画；身份变了、本来就没值、或读到 `error` 时才没有（那时两者都是 `undefined`）。
+ */
 export interface ResourceState<T> {
     readonly phase: 'idle' | 'loading' | 'ready' | 'error';
     readonly value?: T;
     readonly error?: ApiError;
     readonly at?: number;
 }
+/**
+ * 这次读的身份：`route` 加排好序的 `query`（排序是为了同一次读只有一个 key）；给了 `override` 就用它。
+ */
 export declare function resourceIdentity(route: string, query: Query, override?: string | undefined): string;
+/**
+ * 把身份与两个版本号拼成合流用的 key：同一个 key 的并发读共享同一条请求。
+ */
 export declare function readKeyOf(identity: string, refreshToken: number, factRev: number): string;
+/**
+ * 非 hook 的取数本体（要自己管缓存时才直接调）：同一个 `key` 只发一次，并发调用共享同一个 `task`；
+ * 用它就一定要 `release`（一般放 `finally`），最后一个 `release` 才 abort，否则那条请求永不取消。
+ */
 export declare function requestResource<T>(route: string, query: Query, key: string): {
     task: Promise<ApiResponse<T>>;
     release: () => void;
 };
+/**
+ * 卡片里所有的读都走它：按身份发一次 `apiGet`，同 key 合流、订阅事实通道（这条变了自动重取）、
+ * 并把读数上报面板（`workbench_diy_panel` 看的就是它）；身份或版本号一变就换一条读，旧的当场取消。
+ * `options.enabled` 为 `false` 时不发请求、相位恒为 `idle`；`key` 覆盖身份、`fact` 换订阅哪条事实
+ * （默认 `factOfRoute(route)`）、`report: false` 不上报（夹具与后台探针用）。身份没变的重取会留住上一格
+ * 的 `value`，相位降到 `loading`。
+ */
 export declare function useApiResource<T>(route: string, query: Query, refreshToken: number, options?: {
     enabled?: boolean;
     key?: string;

package/dist/types/shared/hooks/use-blocker-actions.d.ts

@@ -1,4 +1,7 @@
 import type { BlockerAction } from '@dsh-workbench/shared';
+/**
+ * blocker 那几个动作的句柄：`run(action)` 执行、`copied` 刚复制走的文本、`running` 正在跑的修复标签、`failure` 失败信息。
+ */
 export interface BlockerActions {
     run(action: BlockerAction): void;
     copied: string | null;
@@ -8,4 +11,9 @@ export interface BlockerActions {
         detail?: string;
     } | null;
 }
+/**
+ * `<BlockerState>` 用它把 blocker 的动作接到实处：`retry` 与修复成功后的重试走 `onRetry`、`run-fix` 走 provision
+ * 写通道、`copy` 写剪贴板、`open-url` 开新窗；`open-market` 没给 `onOpenMarket` 时退回 `onRetry`。
+ * 自己画 blocker 那一块才直接用。
+ */
 export declare function useBlockerActions(onRetry: () => void, onOpenMarket?: () => void): BlockerActions;

package/dist/types/shared/hooks/use-capabilities.d.ts

@@ -1,25 +1,80 @@
 import type { CapabilityPayload } from '@dsh-workbench/shared';
+/**
+ * 纯函数：`refreshToken` 与上一次不同，这一次就该强制重探。
+ */
 export declare function shouldForce(refreshToken: number, previousToken: number): boolean;
+/**
+ * 整张能力表：单元 id → 那一格声明的能力（`design.json` 里那份）。
+ */
 export type CapabilityMap = Record<string, CapabilityPayload>;
+/**
+ * 探针状态：`checkedAt` 上一次探完的时刻（没探过是 `null`）、`checking` 是不是正在探。
+ */
 export interface CapabilityProbeState {
     readonly checkedAt: number | null;
     readonly checking: boolean;
 }
+/**
+ * 让下一次强探静默（不点亮 `checking`）—— 装机预检那类不该惊动界面的探用。
+ */
 export declare function markNextProbeSilent(): void;
+/**
+ * 探针状态的取值口，给 `useSyncExternalStore` 用；渲染里要状态请用 `useCapabilityProbe`。
+ */
 export declare function probeValue(): CapabilityProbeState;
+/**
+ * 探针状态的订阅口，返回退订函数；渲染里要状态请用 `useCapabilityProbe`。
+ */
 export declare function subscribeProbe(listener: () => void): () => void;
+/**
+ * 能力表那条事实的名字：写完之后 `useFactInvalidate(CAPABILITY_FACT)` 标它，读者自动重取。
+ */
 export declare const CAPABILITY_FACT = "capability";
+/**
+ * 当前整张能力表的取值口（没探过是 `null`），给 `useSyncExternalStore` 用；渲染里请用 `useCapabilities`。
+ */
 export declare function capabilityValue(): CapabilityMap | null;
+/**
+ * 能力表的订阅口，返回退订函数；渲染里请用 `useCapabilities`。
+ */
 export declare function subscribeCapabilities(listener: () => void): () => void;
+/**
+ * 写入口：换整张表并通知订阅者（同值不通知）；传 `null` 清探针状态，`rechecked: true` 时顺手记下 `checkedAt`。
+ */
 export declare function setCapabilities(next: CapabilityMap | null, rechecked?: boolean): void;
+/**
+ * 一次强探开始：点亮“正在探”；已经在探就跳过。
+ */
 export declare function beginProbe(): void;
+/**
+ * 一次强探收尾：熄灭“正在探”。
+ */
 export declare function endProbe(): void;
+/**
+ * 把一次探测的结果发布出去：读到了就广播并回 `true`；没读到（`null`）时已有结论就留着回 `false`，
+ * 从来没有过结论才落一张空表回 `true`（“探不动”不等于“还没探”）。
+ */
 export declare function publishCapability(result: CapabilityMap | null, rechecked?: boolean): boolean;
+/**
+ * 同一语义（同一个 `force`）的在飞探测搭车：并发调用共享同一个 promise；落地或失败就清掉，
+ * 下一次强探会真的再跑一遍；`force` 不同不搭车。
+ */
 export declare function shareCapabilityFetch(force: boolean, load: (force: boolean) => Promise<CapabilityMap | null>): Promise<CapabilityMap | null>;
+/**
+ * 探一次能力表并发布：`force` 决定这是“重探”还是顺带读 —— 只有重探负责点亮 / 熄灭探针（`silent` 时连点亮都不做），
+ * 被更新的一次重探盖过的非强制结果会丢掉。
+ */
 export declare function runCapabilityRead(options: {
     readonly force: boolean;
     readonly silent?: boolean;
     readonly load?: (force: boolean) => Promise<CapabilityMap | null>;
 }): Promise<void>;
+/**
+ * 渲染里要整张能力表时调用：所有读者共享同一份结论，没探过是 `null`。
+ * `refreshToken` 变化算一次强制重探，事实版本（`CAPABILITY_FACT`）与 `reloadToken` 变化各触发一次重读。
+ */
 export declare function useCapabilities(refreshToken: number, reloadToken?: number): CapabilityMap | null;
+/**
+ * 渲染里要探针状态（`checking` / `checkedAt`）时调用，比如“最近检查”那一行。
+ */
 export declare function useCapabilityProbe(): CapabilityProbeState;

package/dist/types/shared/hooks/use-capability-gate.d.ts

@@ -1,15 +1,27 @@
 import type { CapabilityPayload } from '@dsh-workbench/shared';
 import { type GateMode } from '@dsh-workbench/shared';
 import { type CapabilityMap } from './use-capabilities';
+/**
+ * 一格的能力门：`capability` 是这一格声明的能力（没读到是 `null`）、`gated` 放行没（为真 = 这一格能画）、
+ * `forceProbe()` 现在就去探一次。
+ */
 export interface CapabilityGate {
     readonly capability: CapabilityPayload | null;
     readonly gated: boolean;
     forceProbe(): void;
 }
+/**
+ * 卡片里判断“这一格现在能不能画”时调用：`refreshToken` 变化触发一次重探。
+ * `options.mode` 换门的口径（默认 `'capability'`）、`options.fixture` 给夹具一份假能力；
+ * `gated` 按口径算 —— 读数还没到先放行（让它去读），读到明确不通过才拦；`forceProbe()` 是“现在就去探一次”。
+ */
 export declare function useCapabilityGate(unit: string, refreshToken: number, options?: {
     readonly mode?: GateMode | undefined;
     readonly fixture?: CapabilityPayload | undefined;
 }): CapabilityGate;
+/**
+ * 整张能力表的视图：表本体加探针的 `checkedAt` / `checking`，以及 `forceProbe()` 与 `reload()`。
+ */
 export interface CapabilityMapView {
     readonly capabilities: CapabilityMap | null;
     readonly checkedAt: number | null;
@@ -17,4 +29,8 @@ export interface CapabilityMapView {
     forceProbe(): void;
     reload(): void;
 }
+/**
+ * 设置页 / 体检那类“要全部单元的能力表”时调用：`reload()` 重取整张表、`forceProbe()` 立刻探一次、
+ * `checking` 是探针在跑；没探过时 `capabilities` 是 `null`。
+ */
 export declare function useCapabilityMap(refreshToken: number): CapabilityMapView;