dsh-over-ssh 0.1.0 → 0.1.1

package/lib/types/src/host/integration/takeover/takeover-api.d.ts

@@ -1,62 +0,0 @@
-/**
- * 一键接管的同源 HTTP 路由：`/api/remote-workspace/takeover`。
- *
- * 为什么是普通 HTTP 路由而不是 Typert `@Remote` 服务：与 `/api/remote-workspace/roots` 同一个理由
- * （见 `roots-api.ts` 模块头与 `doc/02-platform/roots-http-route.md`）—— 带参数的 Remote 描述符需要
- * 生成式严格 codec，本仓库无法产出；而面板与路由同源，相对路径 `fetch` 就是正规形态。
- *
- * 契约：
- *
- * | 请求 | 回答 |
- * |---|---|
- * | `GET` | `200 { ok:true, supported, state, rows:[{patchId, loaderEntryId?, enabled, readOnlyReason?}], writable, canApply, canRevert, reason?, manualRows? }` |
- * | `POST { action:'apply' }` 且已在接管态 | `200 { ok:true, action, state, changed:[], warnings:[], }`（幂等，不写盘） |
- * | `POST { action:'revert' }` 且已在交还态 | 同上 |
- * | `POST` 需要改动四行 | `501 { ok:false, reason:'not-restorable', error:'…要写的 YAML 行…', state, changed:[], warnings:[] }` |
- * | `POST` 且这台宿主没有 `pluginManager` | `501 { ok:false, reason:'unsupported', … }` |
- * | `POST` 且计划要碰的行只读 / 清单缺行 | `409 { ok:false, reason:'read-only' \| 'rows-missing', … }` |
- * | 请求体不合法 / 未知 action | `400 { ok:false, error, allowed? }` |
- * | 不同源 | `403 { ok:false, error, reason }` |
- * | 其它方法 | `405 { ok:false, error }` + `Allow: GET, HEAD, POST` |
- *
- * **`GET` 永远是 200**（只要同源）：`supported:false` 是「这台宿主不能自动切换」的正常回答，
- * 不是错误 —— 客户端据此把开关置灰并显示 `reason`。
- *
- * **`POST` 默认是拒绝的**：见 `takeover-service.ts` 模块头（宿主的写入口既不原子也无法精确还原）。
- * 唯一的 200 是「已经在目标态」那种，它一个字节都不写。`error` 里带着用户要手写的那几行 YAML，
- * 所以拒绝也是可执行的。
- *
- * 两条不变量：
- *  1. 只有 `action` 一个字段被读（白名单），请求体不会被展开进任何调用；
- *  2. 回答里只有行 id 与布尔值：`patchId` 是**规范身份**（用户 `cordis.patch.yml` 里那一行的 id），
- *     `loaderEntryId` 是 Loader 条目 id（诊断用）；`moduleName`、profile 路径与宿主内部标识一律不带出去。
- *
- * @module dsh-remote-workspace/integration/takeover-api
- */
-import type { RootsApiRequest, RootsApiResponse } from '../../app/roots/roots-api-contract.ts';
-import type { TakeoverService } from './takeover-service.ts';
-/** 本插件在这台宿主 HTTP 载体上占用的第二个路径。 */
-export declare const TAKEOVER_API_PATH = "/api/remote-workspace/takeover";
-/** `POST` 接受的唯一两个 action。 */
-export declare const TAKEOVER_ACTIONS: readonly ["apply", "revert"];
-/** 请求体上限：一个 `{ action }` 只有几十字节，64 KiB 是天花板不是预算（与 roots 路由同一个常量）。 */
-export declare const TAKEOVER_MAX_BODY_BYTES: number;
-/** 路由处理器需要的唯一依赖。 */
-export interface TakeoverApiDeps {
-    /** 执行器（宿主 `pluginManager` 的 seam 已在它里面注入）。 */
-    readonly service: TakeoverService;
-}
-/** 处理器对：`handle` 永不 reject（reject 会让 socket 没有状态码）。 */
-export interface TakeoverApi {
-    readonly handle: (req: RootsApiRequest, res: RootsApiResponse) => Promise<void>;
-    /** 不持有资源；路由注册归调用方（wiring）。 */
-    dispose(): void;
-}
-/**
- * 造路由处理器。
- *
- * @param deps - 执行器。
- * @returns {@link TakeoverApi}。
- */
-export declare function createTakeoverApi(deps: TakeoverApiDeps): TakeoverApi;
-//# sourceMappingURL=takeover-api.d.ts.map

package/lib/types/src/host/integration/takeover/takeover-route-wiring.d.ts

@@ -1,60 +0,0 @@
-/**
- * 在浏览器载体上拥有接管路由（`/api/remote-workspace/takeover`）。
- *
- * 与 `roots-wiring.ts` / `session-route-wiring.ts` 同一套 **deferred carrier** 写法，原因也是同一个实测事实：
- * 打包运行时 0.2.0-rc.2 上，插件条目激活时 `ctx.get('webServer')` 是 `undefined`（载体行之后才构造），
- * 裸 `ctx.get` 会静默漏掉注册，面板每个请求都落到 SPA 回退的 `http-404`，而插件看上去一切正常。
- * `ctx.inject(['webServer'], …)` 会在服务出现时回调。
- *
- * 没有载体的组合（headless）**不是错误**：插件照常工作，只是没有面板数据通道；原因收集成 warning，
- * 由入口在 `ctx.logger` 就绪之后打出来。
- *
- * @module dsh-remote-workspace/integration/takeover-route-wiring
- */
-import { type TakeoverApi } from './takeover-api.ts';
-import { type PluginManagerSeam, type TakeoverService } from './takeover-service.ts';
-/** 浏览器 HTTP 载体，窄到本 wiring 唯一用到的方法。 */
-export interface TakeoverRouteHost {
-    register(route: {
-        readonly kind: 'exact';
-        readonly path: string;
-        readonly handler: (req: never, res: never) => Promise<void>;
-    }): () => void;
-}
-/** 服务出现时才把载体交出来的提供者（真实实现是 `ctx` 的 `inject`）。 */
-export interface TakeoverRouteHostProvider {
-    inject(names: readonly string[], callback: (scoped: {
-        get(name: string): unknown;
-    }) => void | (() => void)): unknown;
-}
-/** 入口交给 wiring 的全部依赖。 */
-export interface TakeoverRouteWiringDeps {
-    /**
-     * 宿主 `pluginManager` 的 getter（入口传 `() => ctx.get('pluginManager')`）。
-     *
-     * 是 getter 而不是值：服务可能比本插件晚就绪，捕获成 `undefined` 会让一键接管在整个进程里永久不可用。
-     */
-    readonly pluginManager: () => PluginManagerSeam | undefined;
-    /** 私有域里的原版 provider 是否就位；见 {@link TakeoverServiceDeps.localWorld}。 */
-    readonly localWorld: () => boolean;
-    /** 延迟到达的 `ctx.webServer` 载体；headless 组合下缺省。 */
-    readonly webServerProvider?: TakeoverRouteHostProvider | undefined;
-}
-/** 入口要拿住的东西。 */
-export interface TakeoverRouteWiring {
-    readonly api: TakeoverApi;
-    readonly service: TakeoverService;
-    /** 路由可能没注册的原因；由入口在激活后（`ctx.logger` 就绪时）打日志。 */
-    readonly routeWarnings: () => readonly string[];
-    /** 延迟载体回调是否跑过（诊断用）。 */
-    readonly injectRan: () => boolean;
-    readonly dispose: () => void;
-}
-/**
- * 组装执行器 + 路由，并在载体出现时注册。
- *
- * @param deps - `pluginManager` 的 getter 与可选的载体提供者。
- * @returns {@link TakeoverRouteWiring}；卸载时调用 `dispose` 注销路由。
- */
-export declare function createTakeoverRouteWiring(deps: TakeoverRouteWiringDeps): TakeoverRouteWiring;
-//# sourceMappingURL=takeover-route-wiring.d.ts.map

package/lib/types/src/host/integration/takeover/takeover-service.d.ts

@@ -1,167 +0,0 @@
-/**
- * 一键接管的宿主侧：**只读地**回答「四行现在是什么组合」，并在能保证安全时执行切换 —— 本实现判断
- * 「现在不能」，所以只有读路径（下面「结论」给出三条理由）。
- *
- * ## 平台事实（0.2.0-rc.2 源码核实，不是推断）
- *
- * 证据：`.core/src/deepseek-harness-dsh-v0.2.0-rc.2/packages/boot/plugin-manager/src/{index,patch,types}.ts`
- * 与 `packages/host/plugin-inventory/src/{index,types}.ts`。
- *
- * | 事实 | 出处 |
- * |---|---|
- * | `listPlugins(): Promise<PluginInfo[]>` —— **异步** | `plugin-manager/src/index.ts:256` |
- * | `PluginInfo` = `{entryId, moduleName, enabled, fiberPhase, meta}` + **二选一**的 `patchId`（可改）或 `readOnlyReason`（不可改） | `types.ts:29-32`、`plugin-inventory/src/types.ts:17-26` |
- * | `enabled` = `!entry.disabled`（**运行中 Loader 条目**的开关）；`fiberPhase` 才是「fiber 是否真的在跑」 | `plugin-inventory/src/index.ts:82-96` |
- * | 唯一的写入口是 `setPluginEnabled(entryId, enabled)` —— **一次一行**，收 `entryId`；`patchId` 只是宿主内部写 patch 的目标 | `index.ts:425-435` |
- * | 写盘的格式**不是公开契约**：rc.2 的 `writePluginEnabled` 命中同名行就就地改 `disabled:`、没有就追加一行（`patch.ts:14-42`）；已安装的 0.2.1 writer 还会**删除冗余覆盖**（Lead 核实）。两者都是实现细节，跨版本不一致 |
- * | `ChangeResult.application ∈ {applied, restart-required, overridden, failed, cancelled}`；**失败不抛异常** | `index.ts:767-791`、`types.ts:111-136` |
- * | `restart-required` ⟺ 没有 `hmr`：patch 已写盘，运行中的图没变 | `index.ts:757-765,776` |
- *
- * ## 结论：写路径不存在，开关 fail closed
- *
- * 用户要的是「原样交还」：切过去、再切回来，profile patch 回到**原样**。用受支持的能力做不到，三条独立
- * 的理由（都是上面那张表推出来的，不是猜测）：
- *
- * 1. **存不下来**：`listPlugins` 只给运行态生效值（bool），**不返回** profile YAML 的原始覆盖 —— 公开
- *    接口里没有「保存原覆盖」的来源；
- * 2. **还不回去**：公开接口**不保证**精确还原。`setPluginEnabled` 只接受一个布尔值，写盘格式（就地改、
- *    追加、是否顺手删掉冗余覆盖）是实现细节 —— rc.2 只追加/就地改，0.2.1 会删冗余覆盖，跨版本不一致。
- *    这种没有契约的写-再写-回去，不能当成「原样」。若原行是 `disabled: !!js <expr>` 这类条件表达式，
- *    一次字面量写入就会把它覆盖掉，且无法从 bool 还原；
- * 3. **不原子**：一次切换要按序写 6–8 次（见 `takeover-plan.ts` 的顺序说明），宿主没有批量/事务 API；
- *    中途失败就留下「两个提供方同时在场」或「一个都没有」的半成品。原子写文件也不等于运行中的插件图
- *    原子切换。
- *
- * 所以本模块**不写** profile：不用内存里的 bool 快照假装「原样恢复」，也不自己碰 `~/.dsh`。
- * 它做两件可验证的事：
- *
- *  - **如实报状态**：组合（`enabled`）+ 运行态（`fiberPhase`）分别读，不一致时说出来；
- *  - **拒绝并交出改法**：会改文件的请求一律 `reason:'not-restorable'`，并把「用户自己该写哪几行」原样
- *    交回去（{@link manualPatchRows}），由用户在自己的 profile 里决定。
- *
- * 唯一放行的 `POST` 是**已经处于目标态**的那种：它一个字节都不写，只是回答「已经在那儿了」。
- *
- * 什么时候能真的自动切换：宿主提供**一次事务**的批量开关（全成或全不成），或提供 profile 覆盖的
- * 读回 + 精确还原。两者都没有之前，开关是停用的 —— 这是**已知的产品限制**，不是缺陷。
- *
- * @module dsh-remote-workspace/integration/takeover-service
- */
-import { type TakeoverAction, type TakeoverState } from '../../app/takeover/takeover-plan.ts';
-import { type PublicTakeoverRow } from '../../app/takeover/takeover-rows.ts';
-/**
- * 宿主 `pluginManager` 服务里本插件用到的那个方法。
- *
- * 结构类型而不是 import `@deepseek-ai/dsh-plugin-manager`：那个包不是本仓库的依赖（宿主自带），
- * 而这一层只需要读清单 —— 用结构类型既守红线（应用/领域层不碰 `@deepseek-ai/*`），
- * 也让测试可以传一个普通对象进来。
- *
- * **这里没有 `setPluginEnabled`**：写路径已按模块头注释的三条理由关闭。把它留在 seam 上只会诱导后来者
- * 用它做一件做不到的事。
- */
-export interface PluginManagerSeam {
-    /**
-     * 宿主当前的行清单（真实实现异步）。本插件只读四行的 `patchId`（规范身份）/ `entryId`（Loader 身份，
-     * 诊断用）/ `moduleName`（交叉校验）/ `enabled` / `readOnlyReason` / `fiberPhase`。
-     */
-    listPlugins(): Promise<unknown> | unknown;
-}
-/** 私有域的装配结果。 */
-export type LocalWorldState = 'ready' | 'missing';
-/** `GET` 要的那份状态。 */
-export interface TakeoverStatus {
-    /** `pluginManager` 是否可达（不可达时其余字段仍然自洽）。 */
-    readonly supported: boolean;
-    readonly state: TakeoverState;
-    /**
-     * 私有域是否装配成功：`ready` 表示原版 `fs-sandbox` / `file-reference-local` 已经在私有域里跑起来，
-     * 本地路径的写入围栏由平台执行；`missing` 表示 bridge 没拿到它们，路由器退回自己的本地后端。
-     *
-     * 单独暴露的理由：这一层装配失败时**没有任何报错**——路由器有兜底，功能看起来正常，只是围栏换了
-     * 执行者。没有这个字段就只能去翻宿主终端里的 stderr（审计 0100 未验证项）。
-     */
-    readonly localWorld: LocalWorldState;
-    /** 四行中**实际找到**的那几行（缺行时短于 4）。 */
-    readonly rows: readonly PublicTakeoverRow[];
-    /**
-     * 这台宿主**能不能真的执行切换**。
-     *
-     * 与 {@link TakeoverStatus.supported} 分开是必要的：`supported:true` 只说明 `pluginManager` 可达，
-     * 面板若据此把开关画成可操作，用户点了只会得到一条拒绝。本实现没有写路径（模块头「结论」），
-     * 所以这里恒为 `false`。
-     */
-    readonly writable: boolean;
-    /** 「接管」这个动作现在是否可用：`writable` 为真，且确实有四行需要改。 */
-    readonly canApply: boolean;
-    /** 「交还」这个动作现在是否可用：同上，方向相反。 */
-    readonly canRevert: boolean;
-    /**
-     * 状态说明：为什么这台宿主不能自动切换（没有 `pluginManager` / 缺行 / 没有原子且可还原的写入），
-     * 或者「配置说这样、运行态不是这样」。没有要说的时候不出现。
-     */
-    readonly reason?: string;
-    /**
-     * 用户自己动手时要写进 `cordis.patch.yml` 的那几行（YAML，原样可粘贴）。
-     *
-     * 为什么放在 `GET` 上：开关停用时 UI 永远不会发 `POST`，如果改法只在 `POST` 的 `error` 里，
-     * 「请按提示手动修改」就会指向一段用户拿不到的内容。方向随当前状态走：`on` 给「交还」的写法，
-     * 其余给「接管」的写法。已经不需要改时为空，此时整个字段不出现。
-     */
-    readonly manualRows?: readonly string[];
-}
-/** 一次操作失败的原因。 */
-export type TakeoverFailure = 
-/** 这台宿主没有 `pluginManager`。 */
-'unsupported'
-/** 计划要碰的行只读。 */
- | 'read-only'
-/** 插件清单里缺行。 */
- | 'rows-missing'
-/** 宿主的写入口不能保证原子 + 精确还原 —— 写下去就回不到原样，所以不写。 */
- | 'not-restorable';
-/** 一次操作的结果。失败也带 `state`，让客户端能说清楚「现在是什么样」。 */
-export type TakeoverRunResult = {
-    readonly ok: true;
-    readonly action: TakeoverAction;
-    readonly state: TakeoverState;
-    /** 与调用前相比真正变了的行；本实现永远为空（它不写）。 */
-    readonly changed: readonly string[];
-    readonly warnings: readonly string[];
-} | {
-    readonly ok: false;
-    readonly reason: TakeoverFailure;
-    readonly error: string;
-    readonly state: TakeoverState;
-    readonly changed: readonly string[];
-    readonly warnings: readonly string[];
-};
-/** 执行器对外只暴露两个动作。 */
-export interface TakeoverService {
-    /** 读当前状态（`GET`）。永不抛错：读不到就如实报 `supported:false`。 */
-    status(): Promise<TakeoverStatus>;
-    /** 处理一次 apply / revert（`POST`）。不写 profile；不能保证安全时拒绝并给出改法。 */
-    run(action: TakeoverAction): Promise<TakeoverRunResult>;
-}
-/** 执行器需要的那一件事。 */
-export interface TakeoverServiceDeps {
-    /** 每次读取，而不是构造时捕获（服务可能晚于本插件就绪）。 */
-    readonly pluginManager: () => PluginManagerSeam | undefined;
-    /**
-     * 私有域里的原版 provider 是否已经就位（`localFs` / `localFileReferences` 可注入）。
-     *
-     * 与 `pluginManager` 分开：那一组说的是「配置里的四行」，这一组说的是「运行时那套下沉组合装没装起来」。
-     * 两者可以同时成立、也可以各自失败，混成一个字段就没法判断是哪一层的问题。
-     */
-    readonly localWorld: () => boolean;
-}
-/** 没有 `pluginManager` 时的说明（`GET` 的 `reason` 与 `POST` 的 `error` 共用）。 */
-export declare const UNSUPPORTED_MESSAGE = "\u8FD9\u53F0\u5BBF\u4E3B\u6CA1\u6709 pluginManager \u670D\u52A1\uFF0C\u65E0\u6CD5\u81EA\u52A8\u5207\u6362\u63A5\u7BA1\uFF1B\u8BF7\u624B\u52A8\u4FEE\u6539 profile \u7684 cordis.patch.yml \u540E\u91CD\u542F";
-/** 没有「原子 + 可精确还原」的写入口时的说明（`GET` 的 `reason`）。 */
-export declare const NOT_RESTORABLE_REASON = "\u5BBF\u4E3B\u7684 pluginManager \u53EA\u80FD\u4E00\u6B21\u6539\u4E00\u884C\uFF0C\u800C\u4E14\u516C\u5F00\u63A5\u53E3\u4E0D\u4FDD\u8BC1\u628A profile patch \u7CBE\u786E\u8FD8\u539F\uFF08listPlugins \u4E0D\u8FD4\u56DE\u539F\u59CB\u8986\u76D6\uFF0CsetPluginEnabled \u53EA\u6536\u4E00\u4E2A\u5E03\u5C14\u503C\uFF0C\u4E5F\u6CA1\u6709\u6279\u91CF/\u4E8B\u52A1\u63A5\u53E3\uFF09\u3002\u6CA1\u6709\u8FD8\u539F\u4FDD\u8BC1\u5C31\u4E0D\u8BE5\u66FF\u4F60\u6539\u6587\u4EF6\uFF0C\u56E0\u6B64\u672C\u63D2\u4EF6\u4E0D\u81EA\u52A8\u6539 profile\uFF1B\u8BF7\u6309\u63D0\u793A\u624B\u52A8\u4FEE\u6539 cordis.patch.yml\u3002";
-/**
- * 造一个执行器。
- *
- * @param deps - 宿主 `pluginManager` 的 getter。
- * @returns {@link TakeoverService}。
- */
-export declare function createTakeoverService(deps: TakeoverServiceDeps): TakeoverService;
-//# sourceMappingURL=takeover-service.d.ts.map

package/lib/types/src/host/integration/terminal-manifest.d.ts

@@ -1,94 +0,0 @@
-/**
- * The files a terminal wrapper reads: the root manifest and per-session state.
- *
- * The wrapper is a **separate process** launched by the platform's terminal controller, so it cannot ask the
- * host anything over IPC — it reads two small JSON files instead:
- *
- *  - `roots.json` — every remote root with its local anchor and its already-credential-resolved ssh argv;
- *  - `state/<sessionId>.json` — the remote target of one session, written when the host resolves it.
- *
- * Writes are atomic (temp file + rename) because the wrapper may read them at any moment, and a half-written
- * JSON must never decide where the user's terminal goes.
- *
- * @module dsh-remote-workspace/integration/terminal-manifest
- */
-import { type ManifestRoot, type RootManifest, type SessionState, type SshInvocation } from '../domain/terminal-target.ts';
-/**
- * Build the ssh invocation the terminal wrapper spawns for one connection.
- *
- * Deliberately shared with the entry **and** with the real-host verification: a hand-written copy is exactly
- * how a wrapper ends up connecting as the local user instead of the configured one (the verification script
- * hit that: `ssh host` used `yerier@…` and was refused, because the manifest lacked `-l root`).
- *
- * Difference from the alias transport: terminals are interactive, so a password connection must be allowed to
- * prompt (`BatchMode=no`) — an agent-authenticated one must not.
- *
- * @param profile - connection facts (host, alias, port, user, auth).
- * @param limits - resolved plugin limits (`knownHostsFile`, `connectTimeoutMs`).
- * @returns destination plus credential arguments.
- */
-export declare function sshInvocationFor(profile: {
-    readonly host: string;
-    readonly alias?: string;
-    readonly port?: number;
-    readonly user?: string;
-    readonly authKind: 'agent' | 'key' | 'password';
-    readonly identityFile?: string;
-    readonly connectTimeoutMs?: number;
-}, limits?: {
-    readonly knownHostsFile?: string;
-    readonly connectTimeoutMs?: number;
-}): SshInvocation;
-/** File-system surface, injected so tests never touch the developer's home directory. */
-export interface ManifestIo {
-    readFile(path: string): Promise<string>;
-    writeFile(path: string, data: string): Promise<void>;
-    mkdir(path: string): Promise<void>;
-    rename(from: string, to: string): Promise<void>;
-    remove(path: string): Promise<void>;
-    list(dir: string): Promise<readonly string[]>;
-}
-/** Real file-system binding. */
-export declare const nodeManifestIo: ManifestIo;
-/**
- * Turn a session id into a safe file name.
- *
- * Session ids are host-chosen strings and may contain separators or colons; the name is sanitized and given a
- * short hash suffix so two distinct ids can never collide onto one file.
- *
- * @param sessionId - raw session id.
- * @returns a file name (no directory part) unique to that id.
- */
-export declare function sessionFileName(sessionId: string): string;
-/** Reads and writes the wrapper's manifest files. */
-export declare class TerminalManifestStore {
-    #private;
-    /**
-     * @param options - `dir` is the plugin state directory (usually `~/.dsh/ssh-dev`).
-     */
-    constructor(options: {
-        readonly dir: string;
-        readonly io?: ManifestIo;
-    });
-    /** Absolute path of the root manifest. */
-    get manifestPath(): string;
-    /** Absolute path of one session's state file. */
-    statePath(sessionId: string): string;
-    /**
-     * Replace the whole root manifest.
-     *
-     * @param roots - remote roots the terminal wrapper may target.
-     */
-    writeRoots(roots: readonly ManifestRoot[]): Promise<void>;
-    /** Read the root manifest; `undefined` when missing, malformed, or from another format version. */
-    readRoots(): Promise<RootManifest | undefined>;
-    /** Record one session's remote target. */
-    writeSession(state: SessionState): Promise<void>;
-    /** Read one session's target; `undefined` when missing or malformed. */
-    readSession(sessionId: string): Promise<SessionState | undefined>;
-    /** Remove one session's state (session closed); missing files are not an error. */
-    forgetSession(sessionId: string): Promise<void>;
-    /** Every readable session state (used by the wrapper when it has no session id). */
-    listSessions(): Promise<readonly SessionState[]>;
-}
-//# sourceMappingURL=terminal-manifest.d.ts.map

package/lib/types/src/host/integration/tools/management-tools.d.ts

@@ -1,245 +0,0 @@
-/**
- * The management tool surface: `remote_transfer` (upload/download) and `remote_delete` (recycle/permanent).
- *
- * `remote_delete` is the reason this module exists separately from `remote-tools.ts`: a **permanent** delete
- * bypasses `ctx.fs` and cannot be undone, so it goes through the platform's pre-execute waterfall and is
- * answered with `ask` (which the registry turns into a denial when the composition has no approval surface —
- * fail closed). Recycle mode is an ordinary call: it is recoverable and `undo` exists.
- *
- * @module dsh-over-ssh/integration/management-tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
-import { type SessionRootOutcome } from '../../domain/roots/session-roots.ts';
-import type { DiscardResult } from '../../app/recycle-bin/recycle-bin-service.ts';
-import type { RemoteCopyOutcome } from '../transfer/remote-copy.ts';
-import type { RemoteEnvResult } from '../../infra/transport/transport.ts';
-import type { TransferResult } from '../transfer/transfer-service.ts';
-/** Where one call lands. */
-export interface ManagementTarget {
-    readonly connectionId: string;
-    /** Backend-absolute root path. */
-    readonly root: string;
-}
-/** What {@link formatCopy} renders: the tool's output shape. */
-export interface RemoteCopyView {
-    readonly from: string;
-    readonly to: string;
-    readonly bytes: number;
-    readonly via: 'server' | 'relay';
-    readonly durationMs: number;
-    /** 递归复制才有：各类型条目数。 */
-    readonly files?: number;
-    readonly dirs?: number;
-    readonly symlinks?: number;
-}
-/** One entry as the bin listing shows it. */
-export interface TrashEntryView {
-    readonly id: string;
-    /** Absolute path the entry was deleted from; restoring puts it back here. */
-    readonly path: string;
-    readonly deletedAtMs: number;
-    readonly sizeBytes: number;
-    readonly isDirectory: boolean;
-}
-/**
- * What {@link ManagementToolBackend.restore} answers.
- *
- * One tool, three verbs: look at the bin, put one entry back, or undo the newest discard. They are one union
- * rather than three tools because they share every argument and differ only in which is omitted.
- */
-export type RestoreOutcome = {
-    readonly kind: 'listed';
-    readonly entries: readonly TrashEntryView[];
-} | {
-    readonly kind: 'restored';
-    readonly id: string;
-    readonly path: string;
-    readonly verified: boolean;
-} | {
-    readonly kind: 'undone';
-    readonly action: 'discard' | 'restore';
-    readonly id: string;
-    readonly message: string;
-};
-/** What the tools need, injected so the definitions stay testable without transports. */
-export interface ManagementToolBackend {
-    /** Resolve the calling agent's working directory to a remote root. */
-    resolve(cwd: string): ManagementTarget | undefined;
-    /**
-     * The remote directory this session added with 「添加目录」, when the cwd itself names no remote root.
-     *
-     * Same hook as the other tool backends (audit 0086 added it to `remote_exec`/`remote_grep`/`remote_glob` and
-     * left transfer/delete behind, so a local-cwd session could not upload to a directory it had just added).
-     * Optional so every existing composition and test keeps working.
-     *
-     * @param cwd - the agent's session cwd, used as the workspace identity the add action wrote.
-     * @returns the single added remote root, a refusal naming several, or `none`.
-     */
-    resolveSessionRoot?(cwd: string, sessionId?: string): SessionRootOutcome;
-    /** Run one upload or download. */
-    transfer(request: {
-        readonly target: ManagementTarget;
-        readonly direction: 'upload' | 'download';
-        readonly localPath: string;
-        readonly remotePath: string;
-        /**
-         * Continue from whatever prefix already exists at the destination instead of starting over.
-         *
-         * The service has supported this since it was written, but the tool never asked for it, so the "resumable"
-         * in the description was a promise the model could not reach (audit 0097).
-         */
-        readonly resume: boolean;
-        /** Chunks in flight at once; `undefined` means the service default, `1` means sequential. */
-        readonly concurrency: number | undefined;
-        /**
-         * Version token (`remote_stat`/`remote_read`'s `version`) the remote target must still have.
-         *
-         * Upload only. Without any guard the tool refuses to overwrite an existing remote file, because that is
-         * the one operation that silently destroys someone else's work (the same stance `remote_write` takes).
-         */
-        readonly expectedVersion?: string | undefined;
-        /** Content digest the remote target must currently have; passed down to the guarded first write. */
-        readonly expectedSha256?: string | undefined;
-        /** Overwrite an existing remote target without any guard. Upload only, and deliberately explicit. */
-        readonly force?: boolean | undefined;
-        readonly signal: AbortSignal;
-    }): Promise<TransferResult>;
-    /**
-     * Metadata of the remote destination, for the upload guard above.
-     *
-     * Optional so a composition (or a test double) that predates the guard keeps working; absent means the
-     * tool cannot prove anything about the target and leaves the check to the service layer.
-     */
-    statRemote?(target: ManagementTarget, absolute: string): Promise<{
-        readonly exists: boolean;
-        readonly version: string;
-        readonly size: number;
-    }>;
-    /** Discard one path, into the bin or permanently. */
-    discard(request: {
-        readonly target: ManagementTarget;
-        readonly path: string;
-        readonly mode: 'recycle' | 'permanent';
-        readonly signal: AbortSignal;
-    }): Promise<DiscardResult>;
-    /**
-     * Look at the bin, restore one entry, or undo the newest discard.
-     *
-     * The bin service has had `list` / `restore` / `undo` since it was written; only `discard` was ever exposed,
-     * so a model could delete and then had no way to put anything back (audit 0097).
-     */
-    restore(request: {
-        readonly target: ManagementTarget;
-        /** Entry to restore; `undefined` means "undo the newest discard". */
-        readonly id: string | undefined;
-        /** When true, only report what the bin holds. */
-        readonly list: boolean;
-        readonly signal: AbortSignal;
-    }): Promise<RestoreOutcome>;
-    /**
-     * Copy one remote file to another path.
-     *
-     * The service prefers a server-side copy, so on a Tier 2 connection the bytes never leave the remote host;
-     * the outcome says which path was taken rather than leaving the caller to assume.
-     */
-    copy(request: {
-        readonly target: ManagementTarget;
-        readonly from: string;
-        readonly to: string;
-        readonly overwrite: boolean;
-        readonly recursive?: boolean;
-        readonly signal: AbortSignal;
-    }): Promise<RemoteCopyOutcome>;
-    /**
-     * 采样远端环境；`undefined` 表示这条连接不支持探测（Tier 1）。
-     *
-     * 返回 `undefined` 而不是抛错：没有探测能力不是失败，只是没有答案，工具应当如实说明而不是报错。
-     */
-    probeEnv(connectionId: string, refresh: boolean, signal: AbortSignal): Promise<RemoteEnvResult | undefined>;
-}
-/** Human summary of a finished transfer. */
-export declare function formatTransfer(result: TransferResult): string;
-/**
- * What {@link formatDiscard} renders: the tool's **output** shape, not the service's.
- *
- * These are not the same object. `execute` projects `DiscardResult` onto the declared schema, where the bin
- * entry becomes a flat `entryId` string; the renderer used to read `entry.id` off that projection and therefore
- * always printed "(无条目)" for a recycle delete whose id was right there in the structured value (audit 0097).
- */
-export interface DiscardView {
-    readonly mode: 'recycle' | 'permanent';
-    readonly recoverable: boolean;
-    readonly verified: boolean;
-    /** The bin entry id, present exactly for a recycle delete that produced an entry. */
-    readonly entryId?: string | undefined;
-    readonly warning?: string | undefined;
-}
-/** Human summary of a discard. */
-export declare function formatDiscard(result: DiscardView): string;
-/**
- * What {@link formatRestore} renders: the tool's **output** shape, not the service's.
- *
- * `execute` projects {@link RestoreOutcome} onto the declared schema, which renames the discriminant from
- * `kind` to `action`. A renderer reading `kind` matches no branch, falls through to the last one, and
- * describes the wrong outcome with `undefined` fields — seen live: `list: true` rendered as
- * "已恢复 undefined → undefined" (audit 0097).
- */
-export interface RestoreView {
-    readonly action: 'listed' | 'restored' | 'undone';
-    readonly entries?: readonly TrashEntryView[] | undefined;
-    readonly id?: string | undefined;
-    readonly path?: string | undefined;
-    readonly verified?: boolean | undefined;
-    readonly message?: string | undefined;
-}
-/** Human summary of a bin listing, a restore, or an undo. */
-export declare function formatRestore(result: RestoreView): string;
-/** Human summary of a remote-to-remote copy. */
-export declare function formatCopy(result: RemoteCopyView): string;
-/**
- * `remote_env` 的**输出**形状。
- *
- * 与 `RemoteEnvResult` 分开是必要的：渲染器拿到的是输出 schema 的值，不是内部结果。早先直接
- * 复用内部类型，渲染时访问 `tools`（输出里没有这个字段）当场抛错——类型对不上，运行期才暴露。
- */
-export interface RemoteEnvView {
-    readonly os: string;
-    readonly arch: string;
-    readonly cpus: number;
-    readonly user: string;
-    readonly uid: number;
-    readonly home: string;
-    readonly probedAt: number;
-    readonly available: readonly string[];
-    readonly missing: readonly string[];
-    readonly kernel?: string | undefined;
-    readonly distro?: string | undefined;
-    readonly shell?: string | undefined;
-    readonly memTotalBytes?: number | undefined;
-    readonly memAvailableBytes?: number | undefined;
-    readonly diskFreeBytes?: number | undefined;
-    readonly diskTotalBytes?: number | undefined;
-}
-/** Render one environment sample for the model. */
-export declare function formatEnv(result: RemoteEnvView): string;
-/**
- * Build the two definitions.
- *
- * @param backend - injected implementations.
- * @returns definitions ready for `ctx.tools.register`.
- */
-export declare function managementToolDefinitions(backend: ManagementToolBackend): ToolDefinition[];
-/**
- * Gate irreversible deletions behind the platform's approval surface.
- *
- * A **denial by default** is deliberate: when the composition has no approval support, the registry turns
- * `ask` into a denial, which is the right outcome for an operation that bypasses `ctx.fs` and cannot be undone.
- *
- * @param ctx - host context with the `tools` service.
- * @returns a disposer removing the gate.
- */
-export declare function permanentDeleteGate(ctx: Context): () => void;
-/** Register both tools and the gate. */
-export declare function registerManagementTools(ctx: Context, backend: ManagementToolBackend): () => void;
-//# sourceMappingURL=management-tools.d.ts.map