dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/domain/tool-requests.d.ts

@@ -0,0 +1,369 @@
+/**
+ * Pure request/response logic for the remote tools.
+ *
+ * Kept in the domain layer on purpose (AGENTS.md 红线 2): no `@deepseek-ai/*` import, so command building,
+ * argument clamping and output parsing are all testable offline, in milliseconds, with no transport.
+ *
+ * Everything here is **bounded**: a tool call is model-driven, so an unbounded `grep` or `exec` would let a
+ * single call read an entire remote disk. Caps are part of the contract, and hitting one is *reported*
+ * (`truncated`) rather than silently obeyed.
+ *
+ * **One path rule for the whole tool family** (audit 0052): {@link resolveUnderRoot} is the only place that
+ * turns a model-supplied spelling into a remote path. Both spellings are accepted — an absolute path must be
+ * inside the root (an outside one is *refused*, never silently re-rooted) and a relative path is resolved
+ * against the root, where `..` folds but cannot climb out. `joinUnderRoot` is the legacy folder kept for the
+ * transfer layer; it is now idempotent for in-root absolute paths so a resolved path cannot be prefixed twice
+ * (that doubling was the cause of `remote_exec { cwd: "<the root itself>/..." }` failing).
+ *
+ * @module dsh-over-ssh/domain/tool-requests
+ */
+import { quote } from './shell.ts';
+/** Cap on matches returned by one search. */
+export declare const MAX_GREP_RESULTS = 200;
+/** Cap on paths returned by one glob. */
+export declare const MAX_GLOB_RESULTS = 500;
+/** Cap on bytes of one command's output handed back to the model. */
+export declare const MAX_OUTPUT_BYTES: number;
+/** Default cooperative timeout for a remote command. */
+export declare const DEFAULT_EXEC_TIMEOUT_MS = 30000;
+/** Hard ceiling for a model-requested command timeout. */
+export declare const MAX_EXEC_TIMEOUT_MS = 300000;
+/**
+ * Cap on environment entries one command may carry.
+ *
+ * A bound rather than a silent trim: the whole point of `env` is that the caller can see what it asked
+ * for, so an oversized map is refused by name instead of having entries quietly dropped.
+ */
+export declare const MAX_EXEC_ENV_ENTRIES = 64;
+/** A search request, after validation. */
+export interface GrepRequest {
+    /** Pattern text (literal or regular expression). */
+    readonly pattern: string;
+    /** Directory to search; a root-relative or in-root absolute spelling, `undefined` means the root itself. */
+    readonly path: string | undefined;
+    /** Whether `pattern` is a regular expression. */
+    readonly regex: boolean;
+    /**
+     * Whether matching distinguishes case. Default `false`, matching the agent's wire default
+     * (`caseSensitive: false`) — the two tiers must not disagree about one tool call.
+     */
+    readonly caseSensitive?: boolean | undefined;
+    /**
+     * Whether ignore rules are dropped: VCS ignores (`.gitignore`) **and** {@link DEFAULT_EXCLUDE_DIRS}.
+     * Default `false`.
+     *
+     * The tiers can only do part of this, and the split is deliberate rather than silent: Tier 2 (the agent)
+     * stops applying both, while Tier 1's `grep` never read `.gitignore` at all, so there the flag controls
+     * only the noise-directory list. `tests/remote-tool-backend.test.ts` pins that both tiers receive the same
+     * intent, and the residual difference is stated in `remote_grep`'s description.
+     */
+    readonly noIgnore?: boolean | undefined;
+    /** Filename filters, symmetric with the agent's `search.grep` `exclude`. */
+    readonly include?: readonly string[] | undefined;
+    readonly maxResults: number;
+}
+/** A glob request, after validation. */
+export interface GlobRequest {
+    /** Substring or suffix to match against enumerated paths. */
+    readonly pattern: string;
+    /** Directory to enumerate; a root-relative or in-root absolute spelling, `undefined` means the root itself. */
+    readonly path: string | undefined;
+    readonly maxResults: number;
+}
+/** A command request, after validation. */
+export interface ExecRequest {
+    readonly command: string;
+    /** Working directory; a root-relative or in-root absolute spelling, `undefined` means the root itself. */
+    readonly cwd: string | undefined;
+    /** Environment assignments applied to this command only; `undefined` when none were requested. */
+    readonly env?: Readonly<Record<string, string>> | undefined;
+    readonly timeoutMs: number;
+}
+/** One search hit. */
+export interface GrepHit {
+    readonly path: string;
+    /** 1-based line number. */
+    readonly line: number;
+    readonly text: string;
+}
+/** Search outcome; `truncated` is set when a cap was hit. */
+export interface GrepOutcome {
+    readonly matches: readonly GrepHit[];
+    readonly truncated: boolean;
+    /** Which tier answered (`agent` or the shell strategy). */
+    readonly strategy: string;
+    /** Why the search stopped early, when the answering tier can say (audit 0052 P7). */
+    readonly truncation?: SearchTruncation | undefined;
+}
+/** Text plus the fact that something was cut. */
+export interface BoundedText {
+    readonly text: string;
+    readonly truncated: boolean;
+}
+/**
+ * Normalize a caller-supplied permission spelling into the octal digit string `chmod` takes.
+ *
+ * A number is read as **octal digits**, because that is what a caller who writes `755` means; a string may
+ * also carry the `0o` prefix. Everything else — `"rwxr-xr-x"`, `"8"`, `true`, `""` — is refused rather than
+ * guessed: quietly ignoring a requested mode is precisely the class of failure this round removes, and a
+ * wrong-but-accepted mode on a build script is worse than a refusal.
+ *
+ * @param value - the raw `mode` argument.
+ * @returns the normalized 3-4 digit octal string, or an error naming the accepted forms.
+ */
+export declare function fileModeArg(value: unknown): {
+    readonly mode: string | undefined;
+} | {
+    readonly error: string;
+};
+/**
+ * Cap on filename filters one search may carry.
+ *
+ * Bounded for the same reason every other cap here is: the filters become `--include` argv words in the
+ * shell strategy, so an unbounded list is an unbounded command line.
+ */
+export declare const MAX_GREP_INCLUDES = 16;
+/**
+ * The noise directory names a search excludes by default.
+ *
+ * **This mirrors `dsh-over-ssh-agent/internal/index/scan.go`'s `DefaultExcludes`.** The duplication is forced:
+ * Tier 1 is a plain `grep` with no agent to ask, so it has to name the same directories itself, or the same
+ * tool call would search a different file set depending on which tier answered — the disagreement this
+ * module already refuses to allow for case sensitivity.
+ *
+ * Two consequences are deliberate:
+ *  - the list is pinned **verbatim by a test**, so editing it is always an explicit act rather than drift;
+ *  - keeping the two copies equal is a cross-repository obligation that no test in this repository can
+ *    mechanically enforce. Audit 0064 records the debt, with the Go side as the source of truth.
+ */
+export declare const DEFAULT_EXCLUDE_DIRS: readonly string[];
+/** Merge a requested sub-path with the root, refusing to escape it. */
+export declare function joinUnderRoot(root: string, path: string | undefined): string;
+/**
+ * Resolve a model-supplied path spelling into one remote path inside `root`.
+ *
+ * **One rule for the whole tool family** (`remote_exec.cwd`, `remote_grep.path`, `remote_glob.path`,
+ * `remote_delete.path`, and the file tools built on top): both spellings are accepted, and the two differ
+ * only in what an out-of-root request means.
+ *
+ *  - **Absolute** (`/…`): normalized, then required to be `root` itself or below it. An outside path is
+ *    **refused** with a message naming both the path and the root. It is never silently re-rooted — that
+ *    silent re-rooting is what turned `cwd: "/tmp"` into `<root>/tmp` and made the remote `chdir` fail with
+ *    a message about `/bin/sh` (audit 0052 P1), and it is what doubled a fully-qualified in-root path.
+ *  - **Relative**: folded onto `cwd` (itself resolved by this same function) or onto `root`, with `.`
+ *    dropped and `..` popping. `..` **cannot climb out of the root**: extra leading `..` are ignored, which
+ *    is the pre-existing, deliberately-kept clamp behaviour (audit 0052 P1.3). It also cannot climb above
+ *    `root` from a `cwd`, so `cwd: "src", path: "../../etc"` still lands in `<root>/etc`.
+ *
+ * A path that is empty/blank means the root itself. `cwd` is ignored for an absolute `path`.
+ *
+ * An `ssh://<connection>/<absolute>` spelling is accepted **when it names the connection this call runs
+ * on** (`connectionId`). Its own refusal message used to recommend that spelling while the parser did not
+ * understand it, so a caller who followed the advice got `E_NOT_FOUND` (audit 0064 P2). A reference to a
+ * *different* connection is refused by name: these tools are bound to one remote root, and silently
+ * re-rooting into another host's tree is exactly the kind of guess this module refuses to make.
+ *
+ * @param root - absolute remote root directory.
+ * @param path - requested spelling, absolute, root-relative, or `ssh://`-qualified.
+ * @param cwd - optional root-relative directory the relative spelling is resolved against.
+ * @param connectionId - the connection this call targets; required to accept an `ssh://` spelling.
+ * @returns the resolved root-absolute path, or an object whose `error` explains the refusal.
+ */
+export declare function resolveUnderRoot(root: string, path: string, cwd?: string, connectionId?: string): string | {
+    readonly error: string;
+};
+/**
+ * Validate search arguments.
+ *
+ * @param args - model arguments, however malformed.
+ * @returns the request, or an error message naming the offending field.
+ */
+export declare function parseGrepArgs(args: unknown): GrepRequest | {
+    readonly error: string;
+};
+/** Validate glob arguments (same shape as search minus `regex`). */
+export declare function parseGlobArgs(args: unknown): GlobRequest | {
+    readonly error: string;
+};
+/** Validate command arguments. */
+export declare function parseExecArgs(args: unknown): ExecRequest | {
+    readonly error: string;
+};
+/** Whether a parse result is an error. */
+export declare function isToolArgError(value: {
+    readonly error: string;
+} | object): value is {
+    readonly error: string;
+};
+/**
+ * Quote one shell word safely (single quotes, POSIX).
+ *
+ * Re-exported from {@link ./shell.ts} rather than implemented here: this file builds `grep` command lines,
+ * and the same quoting is needed by the ssh transports and the terminal wrapper. There used to be three
+ * copies and only one of them refused NUL.
+ */
+export { quote };
+/**
+ * Tier 1 search command: one bounded `grep -rn` (no ripgrep on the benchmark host).
+ *
+ * `-I` skips binaries, `-n` gives line numbers, `-E`/`-F` switch regex/literal. `-i` used to be
+ * unconditional for the reason recorded here — the agent's `search.grep` was case-insensitive by default,
+ * and the two tiers must not disagree about what the same tool call means (the real-host run caught exactly
+ * that disagreement). It is now conditional on `caseSensitive`, which the agent also honours, so the
+ * agreement is kept while the caller can finally ask for an exact match.
+ * `head` bounds the output before it crosses the wire, and `--` ends option parsing so a pattern starting
+ * with `-` is not read as a flag.
+ *
+ * `include` entries become `--include=<glob>` filters. They are **filename globs** (`*.cpp`), matching the
+ * agent's field of the same name; each entry is shell-quoted because it is model-supplied text, and the
+ * `--include=` prefix keeps a pattern that starts with `-` from being read as a flag.
+ *
+ * `noIgnore` controls {@link DEFAULT_EXCLUDE_DIRS}, emitted as `--exclude-dir=` words. **It cannot turn VCS
+ * ignores off or on**: plain `grep` never read `.gitignore`, so this tier already searches ignored files.
+ * That residual difference is stated in `remote_grep`'s description and pinned by the two-tier consistency
+ * test rather than left for a caller to discover by comparing two hosts.
+ */
+export declare function grepCommand(request: GrepRequest, root: string): string;
+/**
+ * Parse `grep -rn` output (`path:line:text`).
+ *
+ * A path containing `:` is ambiguous — the first two colon-separated fields win when the second is numeric,
+ * and the rest is text. That is the same convention every editor uses, and it degrades to "line 0" rather
+ * than dropping the hit.
+ *
+ * @param stdout - command output.
+ * @param maxResults - the cap the command was built with.
+ * @returns hits plus whether the cap was reached.
+ */
+export declare function parseGrepOutput(stdout: string, maxResults: number): {
+    readonly matches: GrepHit[];
+    readonly truncated: boolean;
+};
+/**
+ * Bound one output string by bytes, cutting on a line boundary when possible.
+ *
+ * **Which end to keep is a real decision, not a default** (审计 0052 §8.1). `tail` exists because the
+ * transports already made that decision and the renderer was contradicting them: `ssh2-transport.ts` keeps
+ * the **last** 256 KiB of stderr precisely because "every consumer of this string wants the last thing the
+ * command said", and a command's verdict — the compiler error, the failing test, the `DSH_ERROR=` refusal —
+ * is at the end. Bounding to the **head** at 64 KiB then threw away the very bytes the transport had
+ * deliberately preserved, which is the user's original complaint ("编译报错永远在最后几行，恰好被砍掉")
+ * reappearing one layer up.
+ *
+ * @param text - raw output.
+ * @param maxBytes - cap.
+ * @param keep - which end survives; defaults to `head` for callers that want the beginning.
+ * @returns the kept text plus whether anything was dropped.
+ */
+export declare function boundOutput(text: string, maxBytes?: number, keep?: 'head' | 'tail'): BoundedText;
+/**
+ * Make one enumerated path relative to the directory that was enumerated.
+ *
+ * The two enumerators disagree on shape: the Tier 2 agent answers paths relative to the root it was given,
+ * while the Tier 1 `find` fallback prints absolute ones. A glob pattern is anchored at the enumerated
+ * directory, so both have to arrive in the same shape before matching — and the tool's own output then has
+ * one shape too, instead of depending on which tier answered.
+ *
+ * @param base - absolute path of the enumerated directory.
+ * @param path - one path as the enumerator reported it.
+ * @returns the root-relative path, unchanged when it was already relative.
+ */
+export declare function relativeToRoot(base: string, path: string): string;
+/**
+ * Rank enumerated paths for a glob query: glob match, shallowest first.
+ *
+ * The matching itself lives in `./glob-pattern.ts`, whose rules are ported from the Tier 2 agent's Go
+ * implementation. It used to be a literal substring test here, which meant the same `remote_glob` call matched
+ * different files depending on the transport (audit 0052 P3 chose substring; audit 0030 added the Go fast path
+ * and the two silently diverged).
+ *
+ * @param paths - enumerated paths, relative to the enumerated root.
+ * @param pattern - glob pattern (see `./glob-pattern.ts`); the empty pattern keeps its documented meaning of
+ *   "no filter, shallowest first" rather than being compiled into a pattern that matches nothing.
+ * @param maxResults - cap.
+ * @returns matched paths plus whether the cap was reached.
+ * @throws GlobPatternError when the pattern is not a valid glob.
+ */
+export declare function matchGlob(paths: readonly string[], pattern: string, maxResults: number): {
+    readonly matches: readonly string[];
+    readonly truncated: boolean;
+};
+/** How much of one command's output was cut, per stream, plus where the full text can be read. */
+export interface ExecTruncation {
+    /** Compatibility alias: at least one stream was cut. */
+    readonly truncated: boolean;
+    readonly stdoutTruncated: boolean;
+    readonly stderrTruncated: boolean;
+    /** Remote path holding the **full** stdout, present only when stdout was cut. */
+    readonly stdoutSpillPath: string | undefined;
+    /** Remote path holding the **full** stderr, present only when stderr was cut. */
+    readonly stderrSpillPath: string | undefined;
+}
+/**
+ * Read the per-stream truncation fields out of a raw agent `proc.exec` result.
+ *
+ * Contract (agreed with the Go agent, audit 0052 §P4/§8):
+ *
+ *  - `stdoutTruncated` / `stderrTruncated` are booleans;
+ *  - `stdoutSpillPath` / `stderrSpillPath` are strings that exist **only** when that stream was cut
+ *    (`omitempty` on the Go side), so "absent" and "empty" must both read as "no spill";
+ *  - `truncated` is kept as a deprecated alias meaning `stdoutTruncated || stderrTruncated`.
+ *
+ * **The legacy fallback is stdout-only, and that is the whole point** (审计 0052 §8). An older agent sends
+ * only `truncated`, whose documented meaning is "stdout was cut at maxBytes" (`transport.ts`). Mapping it to
+ * *both* streams told the caller that compiler diagnostics on stderr had been cut when nothing said so — and
+ * that over-report is what a real agent exposed: `stderrTruncated: false` arrived, and the rendered result
+ * still claimed "被截断的流：stdout 与 stderr". Reporting less than the truth is a bug; reporting **more** is
+ * a worse one, because it sends the reader to re-run an expensive build or to open a spill file that has
+ * nothing to add.
+ *
+ * `??`-style semantics, never `||`: an explicit `false` is a real answer ("this stream was not cut") and must
+ * survive. A caller that genuinely knows stderr was cut says so by sending `stderrTruncated: true`.
+ *
+ * @param raw - the agent's result object, however malformed or old.
+ * @returns the normalized truncation report.
+ */
+export declare function readExecTruncation(raw: unknown): ExecTruncation;
+/** Why a search stopped early. Mirrors the agent's `truncatedReasons` values. */
+export type SearchTruncationReason = 'maxResults' | 'bytesScanned' | 'maxFileBytes' | 'timeout' | 'maxEntries';
+/** How a search ended, in enough detail to tell the caller what to change. */
+export interface SearchTruncation {
+    /** Compatibility flag: any bound was hit. */
+    readonly truncated: boolean;
+    /** Which bounds were hit, de-duplicated and in a stable order. Empty when nothing was cut. */
+    readonly reasons: readonly string[];
+    /**
+     * How many candidate files the filename filters removed, or `undefined` when the agent did not say.
+     *
+     * This is what makes `include` **observable**: a mistyped filter yields zero matches with every candidate
+     * filtered out, which looks identical to "the symbol is not there" unless the count is reported.
+     */
+    readonly filesFiltered: number | undefined;
+}
+/**
+ * Normalize a search result's truncation report.
+ *
+ * Contract (agreed with the Go agent, audit 0052 P7): `truncatedReasons` is a de-duplicated `[]string` whose
+ * values are `maxResults` / `bytesScanned` / `maxFileBytes` / `timeout` / `maxEntries`, and `filesFiltered`
+ * is an int. Both are **new**, so an older agent returns neither — and then the single `truncated` boolean
+ * must still work. `??` (not `||`) keeps an explicit `false` and a legitimate `0` meaningful.
+ *
+ * An unrecognized reason is kept verbatim rather than dropped: a newer agent naming a bound this build does
+ * not know about must not be silently reported as "nothing was truncated".
+ *
+ * @param raw - the agent's result object, however old or malformed.
+ * @returns the normalized report.
+ */
+export declare function readSearchTruncation(raw: unknown): SearchTruncation;
+/**
+ * Turn one truncation reason into the change that would actually help.
+ *
+ * The five bounds are not interchangeable (audit 0052 P7): `maxResults` is fixed by narrowing the *pattern*,
+ * `bytesScanned` by narrowing the *paths*, and so on. A single "results were truncated" left the caller to
+ * guess, and guessing wrong meant re-running an expensive whole-tree scan.
+ *
+ * @param reason - a value from the agent's `truncatedReasons`.
+ * @returns a model-facing, actionable sentence.
+ */
+export declare function searchTruncationAdvice(reason: string): string;
+//# sourceMappingURL=tool-requests.d.ts.map