dsh-over-ssh 0.1.0 → 0.1.1

package/lib/types/src/host/integration/fs/remote-file-tools.d.ts

@@ -1,369 +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-over-ssh/integration/remote-file-tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import type { ContentBlock } from '@deepseek-ai/dsh-llm';
-import { type ToolDefinition, type ToolRunContext } from '@deepseek-ai/dsh-tools';
-import type { Backend } from '../../app/backend.ts';
-import { type SessionRootOutcome, type SessionRootTarget } from '../../domain/roots/session-roots.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;
-}
-/** 测试用：清空记忆，避免用例之间互相影响。 */
-export declare function resetRememberedVersions(): void;
-export interface RemoteFileBackend {
-    /** Resolve an agent working directory to a remote root. */
-    resolve(cwd: string): RemoteFileTarget | undefined;
-    /**
-     * The remote directory this session added with 「添加目录」, when the cwd itself names no remote root.
-     *
-     * Without this hook the three file tools were the only ones in the family that could not reach a directory
-     * the user explicitly added to the conversation (audit 0086 fixed the fallback for `remote_exec`/`remote_grep`/
-     * `remote_glob` and left these behind, so a session opened on a local folder could run a command in the added
-     * directory but not read a file in it). The rule itself lives in `domain/roots/session-roots.ts`.
-     *
-     * Optional so every existing composition and test keeps working: absent means "no session fallback", which is
-     * exactly the pre-existing behaviour.
-     *
-     * @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;
-    /** Whether one session-added root admits writes; absent means "read-only", the safe default. */
-    writableForSessionRoot?(target: SessionRootTarget): boolean;
-    /**
-     * 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;
-    }>;
-    /**
-     * Atomic in-place edit done **by the agent** — one round trip, no file transfer.
-     *
-     * Absent on a backend that cannot do it (Tier 1 shell): the caller falls back to read → replace → write.
-     * That fallback costs two round trips and ships the whole file down and back up; a 1 MiB file moves
-     * ~2 MiB instead of ~200 bytes. The agent has had `fs.edit` for exactly this reason.
-     */
-    edit?(target: RemoteFileTarget, absolute: string, oldText: string, newText: string, all: boolean, expectedVersion: string | undefined, signal: AbortSignal): Promise<{
-        readonly replaced: number;
-        readonly version: string;
-        readonly bytes: number;
-    } | undefined>;
-    /**
-     * The version this process last saw for a path, if any.
-     *
-     * Used to guard `remote_write` / `remote_patch` when the caller omits `expectedVersion`.
-     */
-    recall(target: RemoteFileTarget, absolute: string): string | undefined;
-    /**
-     * Move (or rename) one path.
-     *
-     * `createParents` decides whether a missing destination directory is created or refused.
-     */
-    move(target: RemoteFileTarget, from: string, to: string, createParents: boolean, signal: AbortSignal): Promise<void>;
-    /**
-     * Metadata for one root-absolute path, without reading its content.
-     *
-     * This is the cheap question ("does it exist, how big, when did it change") that the tool surface
-     * previously answered by reading the whole file or by shelling out to `ls -l` and parsing text.
-     */
-    stat(target: RemoteFileTarget, absolute: string, signal: AbortSignal): Promise<{
-        readonly exists: boolean;
-        readonly isDirectory: boolean;
-        readonly isFile: boolean;
-        readonly isSymlink: boolean;
-        readonly size: number;
-        readonly mtimeMs: number;
-        readonly version: string;
-    }>;
-    /**
-     * Apply a unified diff to one file, atomically.
-     *
-     * @param expectedVersion - when non-empty, the patch must fail if the current version differs.
-     */
-    patch(target: RemoteFileTarget, absolute: string, diff: string, expectedVersion: string | undefined, signal: AbortSignal): Promise<{
-        readonly bytes: number;
-        readonly version: string;
-        readonly hunks: number;
-    }>;
-    /**
-     * 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;
-    /** See {@link RemoteFileBackend.resolveSessionRoot}. */
-    readonly resolveSessionRoot?: ((cwd: string, sessionId?: string) => SessionRootOutcome) | undefined;
-    /**
-     * Whether one session-added root admits writes.
-     *
-     * Kept separate from {@link resolveSessionRoot} because the persisted session entry does not carry the flag
-     * (the domain rule deliberately ignores it) while `RemoteFileTarget` requires it. Absent means read-only:
-     * an unknown root must not silently accept writes.
-     */
-    readonly writableForSessionRoot?: ((target: SessionRootTarget) => boolean) | 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;
-/** Turn a plain string into model-facing content. */
-export declare function text(value: string): ContentBlock[];
-/**
- * Resolve the caller's target, or fail loudly.
- *
- * Two rules, in the same order as the rest of the tool family (audit 0086):
- *
- *  1. **The session cwd decides** when it names a remote root.
- *  2. **Otherwise, the remote directories this session added with 「添加目录」** are the candidates: exactly
- *     one is used, several are refused by name rather than guessed.
- *
- * @param backend - file backend.
- * @param exec - tool run context (carries the calling agent).
- * @returns the remote target.
- * @throws Error when neither rule names exactly one remote root.
- */
-export declare function targetFor(backend: RemoteFileBackend, exec: ToolRunContext): RemoteFileTarget;
-/**
- * Resolve one model-supplied path against the target root, or fail with the refusal's own message.
- *
- * @param target - the call's target: its root and the connection it belongs to.
- * @param path - the model's spelling (absolute, root-relative, or same-connection `ssh://`).
- * @returns the root-absolute path.
- * @throws Error naming the offending path and the root.
- */
-export declare function resolveOrThrow(target: RemoteFileTarget, path: string): string;
-/** The shared wording for "which spelling is accepted", used by every path-bearing parameter. */
-export declare const PATH_SPELLING: string;
-/**
- * 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 (`replaceLiteral` in
- *    `domain/literal-text.ts`), 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. */
-/** `remote_stat` 的输出形状。 */
-export interface StatView {
-    readonly path: string;
-    readonly exists: boolean;
-    readonly kind: string;
-    readonly size: number;
-    readonly mtimeMs: number;
-    readonly version: string;
-}
-/** Render one stat result for the model. */
-export declare function formatStat(result: StatView): string;
-/** `remote_patch` 的输出形状。 */
-export interface PatchView {
-    readonly path: string;
-    readonly hunks: number;
-    readonly bytes: number;
-    readonly version: string;
-}
-/** Render one patch result for the model. */
-export declare function formatPatch(result: PatchView): string;
-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;
-/** Read a non-empty string argument. */
-export declare function requiredString(value: unknown, field: string): 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/fs/remote-index.d.ts

@@ -1,177 +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-over-ssh/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;
-    /** Byte cap for the cached paths; defaults to {@link DEFAULTS.maxBytes}. */
-    readonly maxBytes?: 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;
-/**
- * The cheap "is this root a git work tree" probe.
- *
- * `git ls-files` in the enumeration command is piped into `head`, so its failure (exit 128 in a
- * non-repository directory) never reaches the caller. This command has no pipe, so its status is git's own:
- * exit 0 plus `true` on stdout for a work tree, exit non-zero (or `false`) for anything else.
- */
-export declare function gitRepoProbeCommand(root: string): string;
-/** The cheap "does this directory exist" probe for the find strategy (see `#confirmEmpty`). */
-export declare function directoryProbeCommand(root: string): 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