dsh-over-ssh 0.1.0 → 0.2.0

package/lib/types/src/host/integration/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-remote-workspace/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-selector.ts';
-import type { ConnectionProfile, TransportKind } from '../domain/connection.ts';
-import type { AgentPreflightOutcome } from './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-file-tools.d.ts

@@ -1,241 +0,0 @@
-/**
- * Reading and writing one remote file: `remote_read`, `remote_write`, `remote_edit`.
- *
- * The pain these close (audit 0053): the only way to look at a remote file was `cat` through `remote_exec`,
- * which inherited that tool's 64 KiB per-stream truncation and printed no line numbers — and the only way to
- * change one was to run `python`/`sed` through `remote_exec`, which is how a `\n` in a patch string turned
- * into a real newline and produced an unterminated string literal that then needed a second repair.
- *
- * Three decisions worth naming:
- *
- *  - **`remote_read` numbers its lines.** A window is rendered as `${number}: ${text}`, so a caller can name
- *    a line in a follow-up edit instead of guessing from context. `offset`/`limit` are **lines**, and the
- *    footer states what was shown and what to ask for next.
- *  - **`remote_edit` replaces a LITERAL string.** `old` containing the two characters `\` and `n` matches
- *    exactly those two characters, never a newline; the replacement is spliced in by index, so `$&`, `` $` ``,
- *    `` $' `` and `$$` inside `new` are inserted verbatim rather than being interpreted (verified:
- *    `String.prototype.replace` with a string replacement expands all four — `.verify/probe-replace-semantics.mjs`).
- *    A default edit must match **exactly once**; a non-unique match is refused with the occurrence count, and
- *    `all: true` is the caller's explicit opt-in to replace every occurrence.
- *  - **`remote_write` and `remote_edit` are guarded by a version token.** `expectedVersion` comes from a
- *    previous `remote_read`; when it does not match, the write is refused instead of clobbering an edit
- *    somebody else made in between. The comparison is done by the backend, which knows how each tier spells
- *    its version (the Tier 2 agent reports `size:mtimeNs`, the ssh transports report `size:seconds` and
- *    verify a digest), so the tool never has to assume one spelling.
- *
- * Every path goes through `resolveUnderRoot`, the same one rule the rest of the tool family uses: an
- * absolute path outside the root is refused by name, and a relative one is resolved against the root.
- *
- * @module dsh-remote-workspace/integration/remote-file-tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
-import type { Backend } from '../app/backend.ts';
-/** Default number of lines one read returns. */
-export declare const DEFAULT_READ_LINES = 2000;
-/** Hard cap on the number of lines one read returns. */
-export declare const MAX_READ_LINES = 5000;
-/** Default maximum characters returned for a single line. */
-export declare const DEFAULT_MAX_LINE_LENGTH = 2000;
-/**
- * Byte cap applied to the whole file read that feeds a window.
- *
- * Pinned to the transport's own default read cap (`DEFAULT_MAX_READ_BYTES`): asking for more would only make
- * the transport truncate instead, and the truncation would then be reported one layer deeper where the
- * renderer cannot see it.
- */
-export declare const MAX_READ_FILE_BYTES: number;
-/** The remote root one file call targets. */
-export interface RemoteFileTarget {
-    readonly connectionId: string;
-    readonly root: string;
-    /** Whether the root admits writes; `false` refuses every write tool before it touches the host. */
-    readonly writable: boolean;
-}
-/** One read window request, after validation. */
-export interface ReadWindowRequest {
-    /** 1-based first line. */
-    readonly offset: number;
-    /** Maximum number of lines. */
-    readonly limit: number;
-    /** Maximum characters per returned line. */
-    readonly maxLineLength: number;
-}
-/** One numbered line of a window. */
-export interface ReadLine {
-    /** 1-based line number **in the file**. */
-    readonly number: number;
-    readonly text: string;
-}
-/** The window {@link buildLineWindow} produces. */
-export interface LineWindow {
-    readonly lines: readonly ReadLine[];
-    /** Lines counted in the text that was read; **not** the file's total when `sourceTruncated` is true. */
-    readonly totalLines: number;
-    /** Whether the byte cap cut the scan short, so `totalLines` is a lower bound. */
-    readonly truncatedByBytes: boolean;
-}
-/** What the file tools need from a backend, injected so the definitions stay testable. */
-export interface RemoteFileBackend {
-    /** Resolve an agent working directory to a remote root. */
-    resolve(cwd: string): RemoteFileTarget | undefined;
-    /**
-     * The whole-file read cap this backend actually applies, in bytes.
-     *
-     * Exposed because the refusal messages name the cap, and a deployment may override it: a message quoting
-     * the default while the backend applied a different one would send the caller to the wrong number.
-     */
-    readonly maxReadBytes: number;
-    /** Read one root-absolute file as text, capped by the backend's own limit. */
-    read(target: RemoteFileTarget, absolute: string, signal: AbortSignal): Promise<{
-        readonly text: string;
-        readonly size: number;
-        readonly truncated: boolean;
-        readonly version: string;
-    }>;
-    /**
-     * Write one root-absolute file as text.
-     *
-     * @param expectedVersion - when non-empty, the write must fail if the current version differs.
-     */
-    write(target: RemoteFileTarget, absolute: string, text: string, expectedVersion: string | undefined, signal: AbortSignal): Promise<{
-        readonly bytes: number;
-        readonly version: string;
-    }>;
-    /**
-     * Change one file's permission bits, after a write.
-     *
-     * @param mode - 3- or 4-digit octal string (already normalized by `fileModeArg`).
-     */
-    chmod(target: RemoteFileTarget, absolute: string, mode: string, signal: AbortSignal): Promise<void>;
-}
-/** What the backend needs from its owner. All injected, so it is testable without a real host. */
-export interface RemoteFileBackendDeps {
-    /** Resolve a caller's working directory to a remote root. */
-    readonly resolveRoot: (cwd: string) => RemoteFileTarget | undefined;
-    /**
-     * The backend serving one target.
-     *
-     * `undefined` means the root outlived its backend (the connection was removed), which is refused rather
-     * than served by some other host's backend.
-     */
-    readonly backendFor: (target: RemoteFileTarget) => Backend | undefined;
-    /** Override the whole-file read cap. */
-    readonly maxReadBytes?: number;
-}
-/**
- * Build the file backend the entry registers.
- *
- * @param deps - injected host wiring.
- * @returns the backend consumed by {@link registerRemoteFileTools}.
- */
-export declare function createRemoteFileBackend(deps: RemoteFileBackendDeps): RemoteFileBackend;
-/**
- * Build one line window from a file's text.
- *
- * The scan always walks the whole text so `totalLines` is exact for what was read — the alternative (stop at
- * `limit`) would make the footer's "of N lines" a lie, and that number is what tells the caller whether to
- * page on. A line over `maxLineLength` is truncated **in place** rather than dropped, because dropping it
- * would silently renumber the window.
- *
- * @param source - the file text as read.
- * @param request - the validated window.
- * @returns the numbered lines plus the total line count of `source`.
- */
-export declare function buildLineWindow(source: string, request: ReadWindowRequest): LineWindow;
-/** The read value as rendered: the window plus what the read learned about the file. */
-export interface ReadView {
-    /** Root-absolute path that was read. */
-    readonly path: string;
-    /** 1-based first line requested. */
-    readonly offset: number;
-    readonly lines: readonly ReadLine[];
-    /** Exact line count of the file when the whole file was read; a lower bound when `sourceTruncated`. */
-    readonly totalLines: number;
-    /** The whole-file read was cut by the byte cap, so the window may be missing later lines. */
-    readonly sourceTruncated: boolean;
-    /** The byte cap that produced `sourceTruncated`, as the backend actually applied it. */
-    readonly maxReadBytes: number;
-    readonly size: number;
-    /** Version token to pass to `remote_write` / `remote_edit` as `expectedVersion`. */
-    readonly version: string;
-    readonly limit: number;
-}
-/**
- * Model-facing rendering of one read window.
- *
- * The numbered lines and the footer mirror the platform's own `read` tool (`formatReadOutput`): a caller that
- * has used that tool already knows how to page with the footer's `offset=…`, and the last line number tells
- * it exactly which line it just saw.
- *
- * @param view - the read to render.
- * @returns the model-facing text block body.
- */
-export declare function formatRead(view: ReadView): string;
-/** The outcome of applying one literal edit. */
-export interface LiteralEditResult {
-    readonly text: string;
-    /** How many occurrences were replaced. */
-    readonly replacements: number;
-    /** How many occurrences the literal `old` had in the file. */
-    readonly occurrences: number;
-}
-/**
- * Replace a literal string inside `text`.
- *
- * Two properties are the whole point of this function, and both are pinned by tests:
- *
- *  - **The match is literal.** `old` is compared as text; a backslash-n in `old` matches a backslash and an
- *    `n`, never a newline. The caller writes real newlines when it means newlines.
- *  - **The replacement is verbatim.** The new text is spliced in by index, so `$&`, `` $` ``, `$'` and `$$`
- *    inside `new` are inserted as those characters. `String.prototype.replace` with a string replacement
- *    would expand all four, silently corrupting any patch that mentions a shell variable.
- *
- * @param source - the current file text.
- * @param request - `old`, `new` and the `all` opt-in.
- * @returns the new text plus the occurrence and replacement counts.
- * @throws Error when `old` is empty, absent, or ambiguous without `all`.
- */
-export declare function applyLiteralEdit(source: string, request: {
-    readonly old: string;
-    readonly new: string;
-    readonly all: boolean;
-}): LiteralEditResult;
-/** The edit value as rendered. */
-export interface EditView {
-    readonly path: string;
-    readonly replacements: number;
-    readonly occurrences: number;
-    readonly version: string;
-    readonly bytes: number;
-    readonly all: boolean;
-}
-/** Model-facing rendering of one edit. */
-export declare function formatEdit(view: EditView): string;
-/** The write value as rendered. */
-export interface WriteView {
-    readonly path: string;
-    readonly bytes: number;
-    readonly version: string;
-    readonly guarded: boolean;
-    /** The permission bits applied, when the caller asked for any. */
-    readonly mode?: string | undefined;
-}
-/** Model-facing rendering of one write. */
-export declare function formatWrite(view: WriteView): string;
-/**
- * Build the three file definitions.
- *
- * @param backend - injected implementations.
- * @returns the definitions, ready for `ctx.tools.register`.
- */
-export declare function remoteFileToolDefinitions(backend: RemoteFileBackend): ToolDefinition[];
-/**
- * Register the three file tools on one context.
- *
- * @param ctx - host context with the `tools` service.
- * @param backend - injected implementations.
- * @returns a disposer removing every registration (idempotent).
- */
-export declare function registerRemoteFileTools(ctx: Context, backend: RemoteFileBackend): () => void;
-//# sourceMappingURL=remote-file-tools.d.ts.map

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

@@ -1,69 +0,0 @@
-/**
- * Resolve a connection's **home directory** on the remote host.
- *
- * Why this exists: the directory browser used to start remote listings at `/` (the filesystem root), which is
- * almost never what someone adding a remote folder wants — and on a shared server it shows every other
- * account's home. The obvious "fix" of spelling `home/<user>` is **wrong**, and this host proves it: the login
- * user's home is `/home1/yezhiyuan` while `/home/yezhiyuan` does not exist, because the site spreads accounts
- * across `/home`, `/home1`, `/home2`, … (an NFS/automount convention). Only the host can answer the question,
- * so the answer is **probed, never guessed**.
- *
- * Precedence, highest first:
- *
- *  1. `remoteDefaultRoot` from the connection's own configuration — an explicit choice always wins.
- *  2. A probe of the login user's home (`printf %s "$HOME"`), run over the connection's transport.
- *  3. `/`, the old behaviour, when the probe cannot answer (a transport without command execution, a shell
- *     that prints nothing, a path that is not absolute). Degrading to the previous behaviour keeps a browse
- *     surface usable instead of empty.
- *
- * Results are cached per connection: the answer is a property of the account, not of the moment, and browsing
- * re-asks on every level change. {@link RemoteHomeResolver.forget} drops one entry when a connection changes.
- *
- * @module dsh-remote-workspace/integration/remote-home
- */
-/** The fallback every path of last resort uses. */
-export declare const REMOTE_ROOT_FALLBACK = "/";
-/** Options for {@link createRemoteHomeResolver}. */
-export interface RemoteHomeResolverOptions {
-    /**
-     * Probe the login user's home over the connection's transport.
-     *
-     * @returns the absolute path, or `undefined` when the host could not answer.
-     */
-    readonly probe: (connectionId: string) => Promise<string | undefined>;
-    /** The connection's configured `remoteDefaultRoot`, when it has one. */
-    readonly configuredRoot?: (connectionId: string) => string | undefined;
-}
-/** The resolver the route calls. */
-export interface RemoteHomeResolver {
-    /**
-     * The directory a remote browse should start at.
-     *
-     * @param connectionId - the connection to resolve for.
-     * @returns an absolute path; never empty, and never throws (failures degrade to `/`).
-     */
-    resolve(connectionId: string): Promise<string>;
-    /** Drop one connection's cached answer (its profile changed, or it was removed). */
-    forget(connectionId: string): void;
-    /** Drop every cached answer. */
-    disposeAll(): void;
-}
-/**
- * Whether a string is usable as a remote directory to list.
- *
- * The same fence the route applies to client-supplied paths: absolute, and no `..` segment. A probe that
- * answers something else (a shell banner, a relative path, a trailing newline artefact) must not become the
- * listing target.
- *
- * @param value - candidate path.
- * @returns the normalised path, or `undefined` when it is unusable.
- */
-export declare function normalizeRemoteDir(value: string | undefined): string | undefined;
-/**
- * Build the resolver.
- *
- * @param options - injected probe and configuration reader.
- * @returns the resolver.
- */
-export declare function createRemoteHomeResolver(options: RemoteHomeResolverOptions): RemoteHomeResolver;
-//# sourceMappingURL=remote-home.d.ts.map

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

@@ -1,165 +0,0 @@
-/**
- * The remote file index behind `@` completion.
- *
- * Requirement FR-2.5 asks for completion over a remote root: prefer `git ls-files` (fast, respects
- * `.gitignore`), fall back to a **bounded** `find` on hosts without git (our benchmark host has no git),
- * cache the result, and keep a 900 ms budget so typing never stalls.
- *
- * Two tiers serve it, and the choice is reported rather than hidden:
- *
- *  - **Tier 2** (`agentScan`) runs the agent's `index.scan`, which measured ~0.16 ms/file on a real host;
- *  - **Tier 1** runs one shell command over the transport (measured 187–248 ms for 2000 files).
- *
- * Budgets are enforced by passing them down (`timeoutMs`), not by hoping: an over-budget result comes back
- * with `timedOut: true` and whatever was enumerated, so the UI can show partial completion instead of
- * freezing. Nothing here silently returns a short list as if it were complete.
- *
- * @module dsh-remote-workspace/integration/remote-index
- */
-import { type RemoteCapabilities } from '../domain/capability.ts';
-/** Where a result came from. */
-export type IndexSource = 'agent-index' | 'git-ls-files' | 'find-bounded' | 'cache';
-/** What the index needs from the two tiers. All injected, so this module stays offline-testable. */
-export interface RemoteIndexTiers {
-    /** Tier 2: the agent's `index.scan`. Absent when the connection has no agent. */
-    readonly agentScan?: (root: string, options: {
-        readonly maxEntries: number;
-        readonly timeoutMs: number;
-        readonly signal?: AbortSignal;
-    }) => Promise<{
-        readonly paths: readonly string[];
-        readonly strategy: string;
-        readonly truncated: boolean;
-    }>;
-    /**
-     * Tier 2: the agent's `index.refresh` (incremental).
-     *
-     * Only useful **after** a scan the agent still holds a snapshot for; the agent falls back to a full scan
-     * on its own when it cannot refresh, so a caller may always prefer this once it has scanned once. A
-     * transport that predates the method reports `REMOTE_UNSUPPORTED`, which this module treats as "use
-     * agentScan" — never as a failed completion.
-     */
-    readonly agentRefresh?: (root: string, options: {
-        readonly maxEntries: number;
-        readonly timeoutMs: number;
-        readonly signal?: AbortSignal;
-    }) => Promise<{
-        readonly paths: readonly string[];
-        readonly strategy: string;
-        readonly truncated: boolean;
-    }>;
-    /** Tier 1: one shell command over the transport. */
-    readonly exec: (command: string, options: {
-        readonly timeoutMs: number;
-        readonly maxBytes: number;
-        readonly signal?: AbortSignal;
-    }) => Promise<{
-        readonly exitCode: number;
-        readonly stdout: string;
-        readonly stderr: string;
-        readonly truncated?: boolean;
-    }>;
-    /** Tier 1 capability facts, used to pick the enumeration command. */
-    readonly capabilities: () => Promise<RemoteCapabilities>;
-}
-/** Options for {@link RemoteIndex}. */
-export interface RemoteIndexOptions {
-    readonly tiers: RemoteIndexTiers;
-    /** How long an enumerated root stays usable. Default 30 s. */
-    readonly ttlMs?: number;
-    /** How many roots to keep. Default 8. */
-    readonly maxRoots?: number;
-    /**
-     * Cap for the "already scanned" hint set (default {@link DEFAULTS.maxScannedRoots}).
-     *
-     * Exposed so a test can drive the bound with a small number instead of allocating 257 roots.
-     */
-    readonly maxScannedRoots?: number;
-    /** Default enumeration budget. Default 900 ms (FR-2.5). */
-    readonly budgetMs?: number;
-    /** Default entry cap. Default 20 000. */
-    readonly maxEntries?: number;
-    /** Injectable clock, for the TTL and the budget assertions. */
-    readonly now?: () => number;
-}
-/** One enumeration result. */
-export interface IndexResult {
-    readonly paths: readonly string[];
-    readonly source: IndexSource;
-    /** The agent's own strategy string, when Tier 2 served it (`find-bounded`, `git`, …). */
-    readonly agentStrategy?: string;
-    readonly truncated: boolean;
-    /** True when the enumeration stopped because the budget ran out. */
-    readonly timedOut: boolean;
-    /**
-     * Whether the result was cached.
-     *
-     * `false` only for an enumeration that never completed (killed at the deadline, connection lost): such a
-     * result must not be remembered, while a slow-but-successful one must be — the whole point of the cache
-     * is to spare the *next* keystroke, and throwing away a good list because it took 1.2 s would mean
-     * re-running it for every keystroke (found by the real-host measurement).
-     */
-    readonly cacheable: boolean;
-    readonly ms: number;
-    readonly cached: boolean;
-}
-/** One completion request. */
-export interface CompletionRequest {
-    readonly root: string;
-    /** What the user has typed after `@`. */
-    readonly query: string;
-    readonly limit?: number;
-    readonly budgetMs?: number;
-    readonly signal?: AbortSignal;
-}
-/** One completion result. */
-export interface CompletionResult {
-    readonly matches: readonly string[];
-    readonly source: IndexSource;
-    readonly truncated: boolean;
-    readonly timedOut: boolean;
-    readonly ms: number;
-    readonly cached: boolean;
-}
-/** Enumerates a remote root, with TTL caching, ranking and budget accounting. */
-export declare class RemoteIndex {
-    #private;
-    constructor(options: RemoteIndexOptions);
-    /** Enumerate one root (or serve it from cache while fresh). */
-    enumerate(root: string, options?: {
-        readonly maxEntries?: number;
-        readonly budgetMs?: number;
-        readonly force?: boolean;
-        readonly signal?: AbortSignal;
-    }): Promise<IndexResult>;
-    /**
-     * Completion for a partially typed `@` query.
-     *
-     * Ranking is deliberate and cheap: a basename prefix match beats a path prefix match, which beats a
-     * substring match — so typing `@main` prefers `main.ts` over `src/domain/main-helper.ts`.
-     */
-    complete(request: CompletionRequest): Promise<CompletionResult>;
-    /** Drop one root (its files changed) or everything. */
-    invalidate(root?: string): void;
-    /** Whether a root is currently cached and fresh (used by tests and by the status UI). */
-    isFresh(root: string): boolean;
-}
-/**
- * `git ls-files` for one root.
- *
- * `--cached --others --exclude-standard` lists tracked and untracked-but-not-ignored files, which is what
- * completion should offer; `head -n` bounds the output before it crosses the wire.
- */
-export declare function gitCommand(root: string, maxEntries: number): string;
-/** Bounded `find` for hosts without git (the benchmark host): files only, no `.git` internals. */
-export declare function findCommand(root: string, maxEntries: number): string;
-/**
- * Rank paths for a partially typed query.
- *
- * @param paths - enumerated paths (absolute or root-relative; both work).
- * @param query - what the user typed; empty means "show the shallowest entries first".
- * @param limit - maximum matches.
- * @returns up to `limit` paths, best first.
- */
-export declare function rankMatches(paths: readonly string[], query: string, limit: number): readonly string[];
-//# sourceMappingURL=remote-index.d.ts.map