dsh-over-ssh 0.1.0 → 0.2.0

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

@@ -1,247 +0,0 @@
-/**
- * The recycle-bin service: the domain's pure decisions wired to injected I/O primitives.
- *
- * The seam is deliberate (AGENTS.md 红线 3): every path that touches a real filesystem or a real SSH
- * connection arrives as a function, so this module is testable offline and a test can inject a move that fails.
- *
- * Two contracts matter more than the rest:
- *
- *  1. **Move first, then confirm.** In `recycle` mode a success is reported only after `stat` shows the entry
- *     inside the bin **and** the original path gone. A move that throws is confirmed before anything is
- *     claimed: if the move actually landed (a lost response) it counts as success, otherwise the call fails
- *     and nothing is recorded — "deleted but not in the bin" must never be reported as success.
- *  2. **The index write is never swallowed.** If the index cannot be written after a successful move, the move
- *     is rolled back and the failure is reported; a physical delete has no rollback, so that case is reported
- *     with `purged: true, indexStale: true` instead of being hidden.
- *
- * Other decisions worth knowing:
- *
- *  - A `permanent` discard is irreversible by construction and says so in its result (`recoverable: false`),
- *    and its undo record is refused as `irreversible`.
- *  - Restoring onto an occupied original path is **refused** (`TRANSFER_CONFLICT`, with the informational
- *    `suggestedPath` in `details`); this module never silently restores to a different name.
- *  - `*Remote` primitives are the **remote world's** mutators. A local root additionally needs `localIo`; when it
- *    is missing the call fails with `REMOTE_UNSUPPORTED` rather than reusing remote primitives on local paths.
- *  - Every destructive call takes an `AbortSignal`, propagated to every injected primitive.
- *  - Error codes are reused from the existing table (no new code is registered): `TRASH_NOT_FOUND` (missing
- *    entry, unreadable index), `REMOTE_NOT_FOUND` (target gone), `TRANSFER_CONFLICT` (occupied restore path),
- *    `ROOT_OUTSIDE` (symlink target refused), `ROOT_AMBIGUOUS` (one id in two bins), `REMOTE_UNSUPPORTED`
- *    (local root without local primitives), `REMOTE_COMMAND_FAILED` (an operation that could not be confirmed),
- *    `ROOT_INVALID` (unusable configuration/input), `CANCELLED` (aborted signal).
- *
- * @module dsh-remote-workspace/integration/recycle-bin-service
- */
-import type { BackendEntry, BackendStat } from '../app/backend.ts';
-import { type RecycleBinEntry, type RecycleBinEntryId } from '../domain/recycle-bin.ts';
-import { type RootRef } from '../domain/root.ts';
-/** Removal options for one physical delete. */
-export interface RecycleBinRemovalOptions {
-    /** Whether the target is a directory that must be removed with its content. */
-    readonly recursive: boolean;
-    /** Caller cancellation. */
-    readonly signal?: AbortSignal;
-}
-/** The mutating primitives of one execution world, shaped like the remote group. */
-export interface RecycleBinWorldIo {
-    /**
-     * Move (rename) a path.
-     *
-     * Contract: the implementation must create a missing destination parent directory (equivalent to
-     * `mkdir -p` + `rename`). A cross-device move that cannot be done by rename must **fail loudly**; silently
-     * degrading to copy-then-delete would break the "don't delete until it is in the bin" guarantee.
-     */
-    readonly move: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
-    /** Physically delete a path. */
-    readonly remove: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
-    /** List one directory. */
-    readonly list: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
-    /** Read a text file (the index). */
-    readonly readText: (path: string, signal?: AbortSignal) => Promise<string>;
-    /** Write a text file as UTF-8 **without BOM** (the index). */
-    readonly writeText: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
-}
-/** Everything {@link createRecycleBinService} needs; each field is injected so tests need no host. */
-export interface RecycleBinServiceDeps {
-    /** Bin root directory for one root; a deployment setting, never hardcoded here. */
-    readonly binRootFor: (root: RootRef) => string;
-    /** Find a root by its `rootKey()`; `undefined` means the root is no longer registered. */
-    readonly resolveRoot: (key: string) => RootRef | undefined;
-    /** `stat` in the local world. */
-    readonly statLocal: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
-    /** `stat` in the remote world. */
-    readonly statRemote: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
-    /** Move primitive of the remote world. */
-    readonly moveRemote: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
-    /** Remove primitive of the remote world. */
-    readonly removeRemote: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
-    /** List primitive of the remote world. */
-    readonly listRemote: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
-    /** Index read primitive of the remote world. */
-    readonly readTextRemote: (path: string, signal?: AbortSignal) => Promise<string>;
-    /** Index write primitive of the remote world (UTF-8, no BOM). */
-    readonly writeTextRemote: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
-    /** Clock, injected so a test can pin "now". */
-    readonly now: () => number;
-    /** Undo depth from configuration (a non-positive value keeps no history). */
-    readonly undoDepth: number;
-    /** Roots whose bins exist, so `sweep()` can walk them all. */
-    readonly knownRoots: () => readonly RootRef[];
-    /**
-     * Local-world mutators.
-     *
-     * Optional: a service built for remote work omits it, and touching a local target then fails with
-     * `REMOTE_UNSUPPORTED` instead of misapplying the remote primitives to a local path.
-     */
-    readonly localIo?: RecycleBinWorldIo;
-}
-/** One deletion target: a root plus a path inside it. */
-export interface RecycleBinTarget {
-    readonly root: RootRef;
-    /** Absolute path in the root's own spelling. */
-    readonly path: string;
-}
-/** A bin view scope: one root, optionally narrowed to targets deleted under one directory. */
-export interface RecycleBinScope {
-    readonly root: RootRef;
-    /** Optional directory prefix, matched per path segment. */
-    readonly path?: string;
-}
-/** How {@link RecycleBinService.discard} removes a target. */
-export type DiscardMode = 'permanent' | 'recycle';
-/** Options for {@link RecycleBinService.discard}. */
-export interface DiscardOptions {
-    readonly mode: DiscardMode;
-    readonly signal?: AbortSignal;
-}
-/** Result of a discard. */
-export interface DiscardResult {
-    readonly mode: DiscardMode;
-    /** The bin entry in `recycle` mode; `undefined` for `permanent`. */
-    readonly entry: RecycleBinEntry | undefined;
-    /** Whether the content can still be recovered. **Always `false` for `permanent`.** */
-    readonly recoverable: boolean;
-    /** Post-operation confirmation: the original path is gone. */
-    readonly verified: boolean;
-    /** Human-facing note, mandatory for an irreversible delete. */
-    readonly warning: string | undefined;
-}
-/** What a bin actually holds for one root. */
-export interface RecycleBinListing {
-    readonly entries: readonly RecycleBinEntry[];
-    /** Ids the index knows but the bin directory no longer contains. */
-    readonly missing: readonly RecycleBinEntryId[];
-    /** Directory names in the bin that no index record claims. */
-    readonly orphans: readonly string[];
-    /** Index records that were unusable and skipped. */
-    readonly skipped: number;
-}
-/** Result of a restore. */
-export interface RestoreResult {
-    readonly entry: RecycleBinEntry;
-    readonly restoredPath: string;
-    readonly verified: boolean;
-}
-/** Result of a physical delete from the bin. */
-export interface PurgeResult {
-    readonly id: RecycleBinEntryId;
-    readonly sizeBytes: number;
-    /** Always true when the call returns; a failed delete throws instead. */
-    readonly purged: boolean;
-    readonly warning: string;
-}
-/** Options for `list`, `restore`, `purge`, `undo` and `redo`. */
-export interface OperationOptions {
-    readonly signal?: AbortSignal;
-}
-/** Result of an undo or redo step. */
-export interface UndoResult {
-    /** The action that was executed. */
-    readonly action: 'discard' | 'restore';
-    readonly entry: RecycleBinEntry;
-    /** Human-facing description of what happened. */
-    readonly message: string;
-}
-/** Retention limits for one sweep; all optional. */
-export interface SweepOptions {
-    /** Keep at most this many entries per bin; non-positive/absent = unlimited. */
-    readonly maxEntries?: number;
-    /** Keep at most this many bytes per bin; non-positive/absent = unlimited. */
-    readonly maxBytes?: number;
-    /** Keep entries at most this old; non-positive/absent = unlimited. */
-    readonly maxAgeMs?: number;
-    readonly signal?: AbortSignal;
-}
-/** One entry physically removed by a sweep. */
-export interface SweepPurge {
-    readonly rootKey: string;
-    readonly id: RecycleBinEntryId;
-    readonly sizeBytes: number;
-    readonly dimension: 'age' | 'count' | 'bytes';
-}
-/** One entry a sweep could not delete; the sweep continues with the rest. */
-export interface SweepFailure {
-    readonly rootKey: string;
-    readonly id?: RecycleBinEntryId;
-    readonly message: string;
-}
-/** Per-root summary of a sweep. */
-export interface SweepRootReport {
-    readonly rootKey: string;
-    readonly considered: number;
-    readonly purged: readonly RecycleBinEntryId[];
-    readonly kept: readonly RecycleBinEntryId[];
-    readonly reasons: readonly {
-        readonly id: RecycleBinEntryId;
-        readonly dimension: 'age' | 'count' | 'bytes';
-    }[];
-}
-/** Outcome of a sweep. */
-export interface SweepReport {
-    readonly purged: readonly SweepPurge[];
-    readonly roots: readonly SweepRootReport[];
-    readonly failures: readonly SweepFailure[];
-    /** `false` when no dimension was limited: nothing was touched (an unconfigured 0 must not empty a bin). */
-    readonly policyApplied: boolean;
-}
-/** Read-only undo state, for a UI that needs to enable or disable the buttons. */
-export interface RecycleBinHistory {
-    readonly canUndo: boolean;
-    readonly canRedo: boolean;
-    readonly undo: readonly {
-        readonly kind: string;
-        readonly id: string;
-    }[];
-    readonly redo: readonly {
-        readonly kind: string;
-        readonly id: string;
-    }[];
-    readonly dropped: number;
-    readonly undoDepth: number;
-}
-/** The service surface. */
-export interface RecycleBinService {
-    /** Delete a target permanently or into the recycle bin. */
-    discard(target: RecycleBinTarget, options: DiscardOptions): Promise<DiscardResult>;
-    /** List one bin, reconciled against the directory that actually exists. */
-    list(scope: RecycleBinScope, options?: OperationOptions): Promise<RecycleBinListing>;
-    /** Restore one entry to its original path. */
-    restore(id: RecycleBinEntryId, options?: OperationOptions): Promise<RestoreResult>;
-    /** Physically delete one entry from the bin. */
-    purge(id: RecycleBinEntryId, options?: OperationOptions): Promise<PurgeResult>;
-    /** Apply retention limits to every known bin. */
-    sweep(options: SweepOptions): Promise<SweepReport>;
-    /** Undo the newest operation. */
-    undo(options?: OperationOptions): Promise<UndoResult>;
-    /** Re-apply the newest undone operation. */
-    redo(options?: OperationOptions): Promise<UndoResult>;
-    /** Current undo/redo state. */
-    history(): RecycleBinHistory;
-}
-/**
- * Build the service.
- *
- * @param deps - injected I/O, clock, configuration and root lookup.
- * @returns a {@link RecycleBinService}; its undo stack is per-instance, in memory and not persisted.
- */
-export declare function createRecycleBinService(deps: RecycleBinServiceDeps): RecycleBinService;
-//# sourceMappingURL=recycle-bin-service.d.ts.map

package/lib/types/src/host/integration/remote/connection-test.d.ts

@@ -1,73 +0,0 @@
-/**
- * The connectivity probe behind the panel's 「测试」 button.
- *
- * What "testing a connection" means here, and why it is a real connection rather than a TCP ping:
- *
- *  - it goes through the **same transport service** the rest of the plugin uses, so it answers the only question
- *    that matters to the user  - "would a remote operation work right now"  - including the transport the
- *    selector picked and whether that pick was a degradation;
- *  - the last step is an actual command round-trip (`printf`), so a host that accepts TCP but has no usable
- *    shell (or a transport that cannot execute) is reported as a failure, not as a success;
- *  - the probe **warms the connection** the caller will use next, because `acquire` is memoized per connection.
- *
- * Everything it needs is injected (红线 3: 外部依赖走注入), so the whole classification is testable without a
- * server, and the entry is the only place that knows about profiles.
- *
- * @module dsh-over-ssh/integration/connection-test
- */
-/** The slice of `Transport` the probe uses. Narrow on purpose: the probe must not be able to do more. */
-export interface ProbeTransport {
-    readonly id: string;
-    connect(signal?: AbortSignal): Promise<void>;
-    exec(request: {
-        readonly argv: readonly string[];
-        readonly maxBytes?: number;
-    }, signal?: AbortSignal): Promise<{
-        readonly exitCode: number;
-        readonly stdout: string;
-    }>;
-}
-/** One acquisition: the transport plus the decision that produced it. */
-export interface ProbeAcquisition {
-    readonly transport: ProbeTransport;
-    readonly decision: {
-        readonly kind: string;
-        readonly degradations?: readonly {
-            readonly code: string;
-        }[];
-    };
-}
-/** What the probe needs. */
-export interface ConnectionProbeDeps {
-    /** Acquire (and, on first use, connect) the connection's transport. Rejects with `CONNECTION_NOT_FOUND` for an unknown id. */
-    readonly acquire: (connectionId: string) => Promise<ProbeAcquisition>;
-    /** Budget for the whole probe; each transport keeps its own timeouts on top of it. */
-    readonly timeoutMs?: number;
-    /** Clock, injected so a test can assert the reported milliseconds. */
-    readonly now?: () => number;
-}
-/** The wire answer: success carries the facts the row shows, failure carries a reason it can print. */
-export type ConnectionProbeResult = {
-    readonly ok: true;
-    readonly transport: string;
-    readonly degraded: boolean;
-    readonly degradation?: string;
-    readonly ms: number;
-} | {
-    readonly ok: false;
-    readonly code: string;
-    readonly message: string;
-    readonly ms: number;
-};
-/**
- * Probe one connection.
- *
- * Never throws: a refused or broken connection is a **result** the panel prints, because a button that rejects
- * leaves the user with nothing to read.
- *
- * @param connectionId - the connection to test.
- * @param deps - the injected acquisition, clock and budget.
- * @returns the outcome, with the elapsed milliseconds either way.
- */
-export declare function probeConnection(connectionId: string, deps: ConnectionProbeDeps): Promise<ConnectionProbeResult>;
-//# sourceMappingURL=connection-test.d.ts.map

package/lib/types/src/host/integration/remote/remote-face.d.ts

@@ -1,127 +0,0 @@
-/**
- * 宿主数据通道面：把「连接列表 + 每条连接的传输/降级」暴露成 Typert Remote 端点。
- *
- * 这一片只解决「宿主 → 客户端」的**只读**通道，契约见 [`doc/02-platform/remote-data-channel.md`](../../../doc/02-platform/remote-data-channel.md)。
- * 三条设计约束：
- *
- *  1. **不出凭据。** 行只挑 `id/host/transport/degraded/note` 五个字段；`ConnectionProfile.auth`
- *     （`keyPath` / `credentialKey`）、`password`、`alias`、`proxyJump` 一律不进返回值——凭据只经
- *     `ctx.credentials` 在真正建连时解析。
- *  2. **降级必须可见。** 传输决策与 Tier 2 回退原因都变成一行里的 `degraded` + `note`，用户看到的是
- *     「为什么慢」，而不是一个沉默的默认值。
- *  3. **没有代码生成也不伪造严格契约。** 0.2.0-rc.2 里 `@Remote` 装饰器写下的是一份版本化原型描述符；
- *     本仓库的**测试链路**（`node --test` + Node 24 原生类型剥离）不接受装饰器语法，而红线 1 要求每个源
- *     文件都有测试，所以这里用 {@link markRemoteMethod} 等价地写下同一份描述符。宿主网关据此走 SRC 兜底
- *     路径（`packages/api/gateway/src/index.ts:756-794`），**不需要** `lib/typert.host.js`。
- *     代价写清楚了：SRC 描述符的 codec 是 `src-json`，因此只能承载**零入参**方法；带参数的端点必须
- *     由 Typert 生成器产出严格描述符，本仓库目前产不出来。
- *
- * @module dsh-over-ssh/integration/remote-face
- */
-import { Service, type Context } from '@deepseek-ai/cordis';
-import { type TypertGatewayBinding } from '@deepseek-ai/dsh-typert-protocol';
-import type { TransportDecision } from '../../app/transport/transport-selector.ts';
-import type { ConnectionProfile, TransportKind } from '../../domain/roots/connection.ts';
-import type { AgentPreflightOutcome } from '../agent/agent-preflight.ts';
-/**
- * 线命名空间。**客户端半有一份同样的常量拷贝**（`src/client/remote.ts`）：客户端半与宿主半分属两个
- * tsconfig，不能互相 import，所以这一对常量是手工同步的契约，改一处必须改另一处。
- */
-export declare const SSH_DEV_REMOTE_NAMESPACE = "sshdev";
-/** 承载本面的 Cordis 服务键；调用方（插件入口）必须原样注册这个名字。 */
-export declare const SSH_DEV_REMOTE_SERVICE = "sshDevRemote";
-/** 端点方法名（`sshdev/connections`）。 */
-export declare const SSH_DEV_REMOTE_CONNECTIONS_METHOD = "connections";
-/** 一条连接在设置页里要显示的东西。**没有凭据字段，也不要加。** */
-export interface ConnectionStatusRow {
-    /** 连接 id（profile 主键）。 */
-    readonly id: string;
-    /** 主机名（`ConnectionProfile.host`，不是别名，也不是密钥路径）。 */
-    readonly host: string;
-    /** 当前生效的传输；尚未建立过连接时为 `unknown`（选择器只在建连时决策一次）。 */
-    readonly transport: TransportKind | 'unknown';
-    /** 是否有降级（传输替换 / Tier 2 回退）。 */
-    readonly degraded: boolean;
-    /** 一句给人看的原因：优先降级原因，其次决策说明，最后是「还没连过」。 */
-    readonly note: string;
-}
-/** 构建行所需的三个只读事实源；全部注入，所以这个模块可以离线测。 */
-export interface ConnectionStatusSource {
-    /** 当前配置里的全部连接。 */
-    readonly profiles: () => readonly ConnectionProfile[];
-    /** 该连接**当前生效**的传输决策；从未建连（或已释放）时返回 `undefined`。 */
-    readonly decisionFor: (connectionId: string) => TransportDecision | undefined;
-    /** Tier 2 安装梯子对这条连接的结果，跑过才有。 */
-    readonly agentOutcomeFor: (connectionId: string) => AgentPreflightOutcome | undefined;
-}
-/**
- * 把三个事实源折叠成面板要显示的行（纯函数）。
- *
- * @param source - 连接、决策、Tier 2 结果三个读取器。
- * @returns 每个连接一行，顺序与 `profiles()` 一致。
- */
-export declare function buildConnectionStatusRows(source: ConnectionStatusSource): readonly ConnectionStatusRow[];
-/**
- * 在一个类的 prototype 上登记一个直接调用的 Remote 方法——`@Remote` 装饰器的**可擦除等价物**。
- *
- * 为什么不用装饰器（两条实测事实）：
- *
- *  - `tsc` 本身**不**拒绝它：用本仓库 `tsconfig.json` 的真实选项（含 `erasableSyntaxOnly: true`）编译一个
- *    带标准装饰器的类，语法/语义错误为 0 条；
- *  - **测试链路拒绝它**：Node 24 的原生类型剥离直接报 `SyntaxError`（`node --input-type=module-typescript`
- *    试过），而测试运行器就是 `node --test`。红线 1 要求每个源文件都有测试，含装饰器的模块因此无法被任何
- *    测试导入。
- *
- * 这个函数写下的字节与装饰器相同（`version: 1` 描述符，见协议运行时 `lib/index.js:248-268`），并且由
- * `tests/remote-face.test.ts` 用真的 `remoteMethods()` 读回来验证——协议包若改了这个属性名，测试先红。
- *
- * @param prototype - 目标类的 `prototype`。
- * @param method - 公开实例方法名（必须真的存在于该 prototype 上）。
- */
-export declare function markRemoteMethod(prototype: object, method: string): void;
-/**
- * 数据通道的宿主面。
- *
- * 方法必须写在类里（原型方法），不能是箭头函数字段：宿主网关的 SRC 路径用
- * `Function.prototype.toString()` 解析参数名（`packages/api/gateway/src/index.ts:1434-1468`），
- * 原型上的普通方法才有稳定的 `()` 参数表。
- */
-export declare class SshDevRemoteFace extends Service {
-    #private;
-    /** 网关按这个可见绑定把端点认到本服务上（`readBinding`，同文件 1387-1427）。 */
-    readonly typertRemote: TypertGatewayBinding<this>;
-    /**
-     * 注册服务并绑定线命名空间。
-     *
-     * @param ctx - 宿主插件上下文（必须已提供 `sshDevConnections` / `sshDevTransports` / `sshDevAgent`）。
-     * @param source - 三个只读事实源。
-     */
-    constructor(ctx: Context, source: ConnectionStatusSource);
-    /**
-     * 全部连接及其当前传输状态。
-     *
-     * **零入参是刻意的**：SRC 描述符的入参 codec 是 `src-json`，客户端 Remote 挂载时会因为
-     * 「has no strict codec」拒绝带参数的 SRC 描述符（`packages/api/gateway/src/client/index.ts:790-805`），
-     * 而零入参的方法不触发那条检查（同文件 449-451 只对 `result.decode` 做严格解码）。
-     *
-     * @returns 每个连接一行；返回值里没有任何凭据字段。
-     */
-    connections(): Promise<readonly ConnectionStatusRow[]>;
-}
-declare module '@deepseek-ai/cordis' {
-    interface Context {
-        /** 数据通道的宿主面，由 {@link installRemoteFace} 注册（网关按服务键反射调用）。 */
-        sshDevRemote: SshDevRemoteFace;
-    }
-}
-/**
- * 安装宿主面：从插件自己提供的三个服务上取事实源。
- *
- * 用 `ctx.get(name)`（宽松读取）而不是 `ctx.<service>`：即使某个服务没挂上，通道也只是少一行数据，
- * 不该让插件在激活期直接抛错。
- *
- * @param ctx - 宿主插件上下文。
- * @returns 已注册的服务实例（调用方通常不需要它）。
- */
-export declare function installRemoteFace(ctx: Context): SshDevRemoteFace;
-//# sourceMappingURL=remote-face.d.ts.map

package/lib/types/src/host/integration/remote/remote-tool-backend.d.ts

@@ -1,108 +0,0 @@
-/**
- * The `remote_grep` / `remote_glob` / `remote_exec` backend.
- *
- * Extracted from the plugin entry for two reasons: the entry was growing a second responsibility, and the
- * Tier 2/Tier 1 decision below could not be exercised by any test while it lived inline (the tools'
- * end-to-end verification needs to build exactly this object against a real host).
- *
- * Two decisions worth naming:
- *
- *  - **Structural capability checks, not `instanceof`.** The agent path is chosen by asking the transport what
- *    it can do (`agentCapabilities.grep` + a `searchGrep` method), so a wrapper or a future transport that
- *    speaks the same protocol still gets Tier 2 — and a test can supply one.
- *  - **Tier 2 first, Tier 1 always available.** The agent measured ~0.16 ms/file for scans against ~635 ms per
- *    per-file round trip (审计 0009), so search prefers it; when it is absent or fails to answer the shell
- *    path takes over. Failing over is reported through `strategy`, never hidden.
- *
- * @module dsh-over-ssh/integration/remote-tool-backend
- */
-import type { Transport } from '../../infra/transport/transport.ts';
-import type { RemoteToolBackend } from '../tools/remote-tools.ts';
-import type { SessionRootOutcome } from '../../domain/roots/session-roots.ts';
-/** One search hit as the agent transport reports it (only the fields this module reads). */
-export interface AgentSearchHit {
-    readonly path: string;
-    readonly line: number;
-    readonly text: string;
-}
-/** The agent search result shape this module consumes. */
-export interface AgentSearchOutcome {
-    readonly matches: readonly AgentSearchHit[];
-    readonly strategy: string;
-    readonly truncated: boolean;
-    /** Which bounds stopped the scan (agent `truncatedReasons`); empty when the agent did not say. */
-    readonly truncatedReasons?: readonly string[] | undefined;
-    /** Candidate files the `include` filters removed; `undefined` when the agent did not say. */
-    readonly filesFiltered?: number | undefined;
-}
-/** The slice of an agent-capable transport the backend uses. */
-export interface AgentSearchCapable {
-    readonly agentCapabilities: {
-        readonly grep?: boolean;
-    };
-    searchGrep(request: {
-        readonly paths: readonly string[];
-        readonly query: string;
-        readonly literal?: boolean;
-        /** Case-insensitive matching; the agent's own default is `true`. */
-        readonly ignoreCase?: boolean;
-        /** Drop VCS ignore rules and the agent's built-in noise directories (audit 0064 P3). */
-        readonly noIgnore?: boolean;
-        readonly maxResults?: number;
-        /** Filename patterns to keep, e.g. `*.cpp` (audit 0052 P10). */
-        readonly include?: readonly string[];
-    }, signal?: AbortSignal): Promise<AgentSearchOutcome>;
-}
-/** What the backend needs from its owner. All injected, so it is testable without a real host. */
-export interface RemoteToolBackendDeps {
-    /**
-     * Resolve a caller's working directory to a remote root.
-     *
-     * @param cwd - the agent's session cwd.
-     * @returns the target, or `undefined` when no remote root contains it.
-     */
-    readonly resolveRoot: (cwd: string) => {
-        readonly connectionId: string;
-        readonly root: string;
-    } | undefined;
-    /**
-     * The remote directories **this session** added with 「添加目录」, used when `resolveRoot` finds none.
-     *
-     * Optional: a composition that does not track session-scoped roots keeps the pre-existing behaviour
-     * (a cwd outside every remote root is an error). The rule lives in `domain/roots/session-roots.ts`.
-     *
-     * @param cwd - the agent's session cwd, which is the workspace identity the add action wrote.
-     * @returns the single added remote root, a refusal naming several, or `none`.
-     */
-    readonly resolveSessionRoot?: ((cwd: string, sessionId?: string) => SessionRootOutcome) | undefined;
-    /**
-     * Acquire the connection's transport.
-     *
-     * @param connectionId - configured connection id.
-     * @returns the transport (the caller owns its lifetime).
-     */
-    readonly acquire: (connectionId: string) => Promise<Transport>;
-    /**
-     * Enumerate a remote root (the shared index).
-     *
-     * @param connectionId - connection owning the root.
-     * @param root - backend-absolute root path.
-     * @param signal - caller cancellation.
-     * @returns enumerated paths, whether a cap was hit, and which strategy answered.
-     */
-    readonly enumerate: (connectionId: string, root: string, signal?: AbortSignal) => Promise<{
-        readonly paths: readonly string[];
-        readonly truncated: boolean;
-        readonly source: string;
-    }>;
-}
-/** Whether a transport can answer agent-side searches. */
-export declare function isAgentSearchCapable(transport: unknown): transport is AgentSearchCapable;
-/**
- * Build the tool backend the entry registers.
- *
- * @param deps - injected host wiring.
- * @returns the backend consumed by {@link registerRemoteTools}.
- */
-export declare function createRemoteToolBackend(deps: RemoteToolBackendDeps): RemoteToolBackend;
-//# sourceMappingURL=remote-tool-backend.d.ts.map