dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/infra/transport/transport-base.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 两个传输（AgentTransport / Ssh2Transport）共用的**状态机与能力记录**。
+ *
+ * 为什么需要：这两个类各自持有一份一模一样的 `#state / #capabilities / #probedAt` 字段、
+ * 一对同样的 getter，以及同样"探测后记录时间戳"的写法。抽出来之后：
+ *
+ *   - 状态迁移只有一个入口（`markState`），不会出现"一个类记得置 lost、另一个忘了"；
+ *   - `capabilities` 的写入口只有 `setCapabilities`，探测时间戳不可能忘记同步；
+ *   - 子类不再声明同名字段，`Transport` 接口里的 `state`/`capabilities` 由基类满足。
+ *
+ * **不抽的部分（有意）**：`exec / readFile / writeFile / rename / remove …` 在两个类里是
+ * **同名但不同实现**——一个走代理 RPC，一个走 SFTP/系统 ssh。它们是"实现同一个端口"，
+ * 不是重复代码；强行拉一个公共基类只会把两套完全不同的机制耦在一起。
+ *
+ * @module dsh-over-ssh/infra/transport/transport-base
+ */
+import { type RemoteCapabilities } from '../../domain/capability.ts';
+import type { TransportState } from './transport.ts';
+export declare abstract class TransportBase {
+    #private;
+    get state(): TransportState;
+    get capabilities(): RemoteCapabilities;
+    /** When `capabilities` was last probed (undefined before the first probe). */
+    get probedAt(): number | undefined;
+    /** The single write path for the state machine. */
+    protected markState(state: TransportState): void;
+    /** Record a probe result. `probedAt` is optional so a caller that has its own clock can pass it. */
+    protected setCapabilities(capabilities: RemoteCapabilities, probedAt?: number): void;
+    /** Mark the probe timestamp (used right after {@link setCapabilities} by callers with their own clock). */
+    protected markProbed(at: number): void;
+    /** Forget the probe (a reconnect must not keep a stale timestamp). */
+    protected clearProbed(): void;
+}
+//# sourceMappingURL=transport-base.d.ts.map

package/lib/types/src/host/infra/transport/transport.d.ts

@@ -0,0 +1,527 @@
+/**
+ * The transport contract: one pluggable remote execution world.
+ *
+ * Implementations are `alias` (system `ssh` + ControlMaster, inheriting `~/.ssh/config`) and
+ * `ssh2` (pure-JS client, needed for password auth and dynamic ProxyJump). Keeping the
+ * contract here lets the application layer and every test run without either implementation.
+ *
+ * @module dsh-over-ssh/infra/transport/transport
+ */
+import type { RemoteCapabilities } from '../../domain/capability.ts';
+/** Lifecycle of one transport instance. */
+export type TransportState = 'idle' | 'connecting' | 'ready' | 'lost';
+/** A remote command expressed as argv (preferred) or as an explicit script. */
+export interface ExecRequest {
+    /** Executable and arguments; quoted and joined for the remote shell. */
+    readonly argv?: readonly string[];
+    /** Raw script body; used only when `argv` is absent. */
+    readonly script?: string;
+    /** Working directory; omitted leaves the transport default. */
+    readonly cwd?: string;
+    /** Environment assignments for the command. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Command deadline; falls back to the connection's `commandTimeoutMs`. */
+    readonly timeoutMs?: number;
+    /** Cap on retained stdout bytes; output beyond it is dropped and flagged. */
+    readonly maxBytes?: number;
+    /** Bytes fed to the command's stdin. */
+    readonly stdin?: string;
+    /**
+     * Bytes fed to the command's stdin, base64-encoded for the wire.
+     *
+     * Separate from {@link stdin} because the two have different meanings — `stdin` is **text** (written
+     * verbatim), this is **bytes**. A transport that only understands text must refuse this field rather
+     * than send the base64 text to the command (found on the real host: a positioned write wrote the
+     * *encoded* payload into the file, i.e. silent corruption).
+     */
+    readonly stdinBase64?: string;
+}
+/** One finished remote command. */
+export interface ExecResult {
+    readonly exitCode: number;
+    /**
+     * The signal that ended the command, or `null` when it exited on its own.
+     *
+     * `-1` + this pair is what separates the two ways a command can fail without an exit code: a **timeout**
+     * (below) and a **signal** (a crash, an OOM kill, a `kill -TERM`). Reporting only the exit code made those
+     * indistinguishable, and a signal was read as "the timeout fired" (audit 0064 P4).
+     */
+    readonly signal: string | null;
+    /**
+     * Whether this transport's own deadline ended the command.
+     *
+     * `true` means the budget ran out and the transport stopped waiting; it does **not** claim the remote
+     * process is dead. An agent reports this explicitly. The `ssh2` transport answers a deadline by throwing
+     * `REMOTE_COMMAND_FAILED` naming the timeout, so every result it *returns* is truthfully `false`.
+     */
+    readonly timedOut: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly durationMs: number;
+    /**
+     * Whether **stdout** was cut at `maxBytes`.
+     *
+     * This keeps its long-standing meaning and must not be widened: `remote-backend` reads it as "this batch
+     * read lost paths", so folding stderr truncation in would report readable files as missing (see
+     * `ssh2-transport.ts`'s `STDERR_TRUNCATION_NOTICE`). A transport whose backend reports one combined flag
+     * passes that value through unchanged for compatibility; the per-stream fields below are what callers must
+     * read when they need to know **which** stream was cut.
+     */
+    readonly truncated: boolean;
+    /**
+     * Whether stdout was cut — the authoritative stdout flag (审计 0052 §8).
+     *
+     * Distinct from {@link truncated} only for a backend that reports one combined flag; every transport here
+     * states it explicitly so a caller never has to infer it.
+     */
+    readonly stdoutTruncated: boolean;
+    /**
+     * Whether stderr was cut.
+     *
+     * **A transport must report only what it actually knows.** Claiming `true` here when the stream was
+     * complete is worse than claiming nothing: the reader is told to distrust compiler diagnostics that are in
+     * fact intact, and re-runs an expensive build for nothing. A transport that cannot observe stderr
+     * truncation reports `false` and says so in its own documentation.
+     */
+    readonly stderrTruncated: boolean;
+    /**
+     * Remote path holding the **full** stdout, present only when stdout was cut **and** the backend spilled it.
+     *
+     * `undefined` means "no such file was produced", never "the path is unknown".
+     */
+    readonly stdoutSpillPath: string | undefined;
+    /** Remote path holding the **full** stderr; same rules as {@link stdoutSpillPath}. */
+    readonly stderrSpillPath: string | undefined;
+    /**
+     * **Tier 1 only**: this command was stopped locally (deadline or cancellation), but the host has no agent,
+     * so there is no protocol channel that could confirm the remote process group died.
+     *
+     * `true` is an honest limitation, not an error: the result/exit code is unchanged, and the caller must not
+     * read it as "the command is still running" either — it means **unknown**. Tier 2 does not set it (a
+     * cancelled `proc.exec` is killed by the agent and reported through the protocol).
+     */
+    readonly remoteMayStillRun?: boolean;
+    /** Human-readable explanation for {@link remoteMayStillRun}; model-facing when present. */
+    readonly hint?: string;
+}
+/**
+ * The hint a Tier 1 transport attaches when it stops waiting on a command: the local `ssh` was killed, but
+ * without an agent there is no way to confirm the remote process group is gone.
+ *
+ * Deliberately worded as "may still be running … cannot confirm": claiming it died would be a lie on a host
+ * where `sshd` does not signal the child on channel close, and claiming it lives would be a lie on hosts that
+ * do. The error code is untouched; this travels in `details.hint` (throw path) or `ExecResult.hint` (result
+ * path) so the model can tell the user to look before re-running a build.
+ */
+export declare const TIER1_REMOTE_MAY_STILL_RUN_HINT = "\u8FDC\u7AEF\u547D\u4EE4\u53EF\u80FD\u4ECD\u5728\u8FD0\u884C\uFF08Tier 1 \u65E0\u4EE3\u7406\uFF0C\u65E0\u6CD5\u786E\u8BA4\uFF09\uFF1A\u672C\u5730\u5DF2\u505C\u6B62\u7B49\u5F85\u5E76\u7EC8\u6B62\u4E86\u672C\u5730 ssh\uFF0C\u4F46\u8FDC\u7AEF\u8FDB\u7A0B\u7EC4\u6CA1\u6709\u534F\u8BAE\u901A\u9053\u53BB\u786E\u8BA4\u6216\u6740\u6B7B\u3002";
+/** One remote file read. */
+export interface ReadFileRequest {
+    /** Absolute remote path. */
+    readonly path: string;
+    /** Inclusive byte cap for the retained content. */
+    readonly maxBytes: number;
+}
+/**
+ * One **offset** read: the primitive a chunked download needs.
+ *
+ * `readFile` always starts at 0, so a caller paging through a large file had to read `[0, offset+len)` and
+ * slice — which defeats the point of a byte cap on a big file. Optional: a transport that cannot seek must
+ * simply not implement it, and the transfer layer degrades instead of silently reading the whole file.
+ */
+export interface ReadFileRangeRequest {
+    /** Absolute remote path. */
+    readonly path: string;
+    /** Byte offset to start at (0-based). */
+    readonly offset: number;
+    /** Maximum bytes to read from `offset`. */
+    readonly maxBytes: number;
+}
+/**
+ * Metadata for one remote path, as the **transport itself** observes it.
+ *
+ * This exists because a version token is only meaningful next to the token source that produced it. The
+ * Tier 1 shell `stat` (`RemoteBackend.stat`) can only run `stat -c '%Y'` and therefore reports seconds,
+ * while the Tier 2 agent's `fs.read` reports `size:mtimeNs` (`dsh-over-ssh-agent/internal/agent/fileops.go`,
+ * `Version.String()`). Comparing the two is comparing two different quantities, which made every
+ * read→write version guard fail on Tier 2.
+ *
+ * @see Transport.statPath - the member that produces this, and the one place that reconciles the two.
+ */
+export interface RemoteStatResult {
+    readonly exists: boolean;
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+    /** Size in bytes; 0 when the path does not exist. */
+    readonly size: number;
+    /** Milliseconds since the epoch; 0 when unknown. */
+    readonly mtimeMs: number;
+    /**
+     * The transport's own version token for this path, or `''` when it has none.
+     *
+     * It must be the **same token the same transport's `readFile` reports for the same state** — that
+     * identity is the whole point of this member.
+     */
+    readonly version: string;
+}
+/** Raw bytes read from a remote file. */
+export interface RemoteFileChunk {
+    readonly bytes: Uint8Array;
+    /** Full size reported by the remote when known. */
+    readonly size: number;
+    /** Whether `bytes` is shorter than the full file. */
+    readonly truncated: boolean;
+    /** The version token observed by the same round trip, when the host can provide one. */
+    readonly version?: string;
+}
+/** One remote file write. */
+export interface WriteFileRequest {
+    /** Absolute remote path. */
+    readonly path: string;
+    readonly bytes: Uint8Array;
+    /** Refuse the write when the current content digest differs. */
+    readonly expectedSha256?: string;
+    /**
+     * Refuse the write unless the target still carries this **version token**.
+     *
+     * Distinct from {@link expectedSha256}, and the distinction is the point: a digest and a version token
+     * are different quantities, and overloading one field with both meanings is what broke the guarded
+     * read→write flow on Tier 2 (the agent's `fs.write` guard is a version comparison — see
+     * `agent-transport.ts`'s `writeFile` notes).
+     *
+     * A transport that guards on version tokens honours this field; a transport that guards on digests
+     * ignores it. A caller that wants a guard on **either** tier must therefore pass whichever one that
+     * tier actually verifies, which is what `RemoteBackend` does.
+     */
+    readonly expectedVersion?: string;
+    /** Create missing parent directories. */
+    readonly createParents?: boolean;
+}
+/**
+ * One **positioned** write: the primitive a chunked upload needs.
+ *
+ * `writeFile` replaces the whole file atomically, so putting a 1 GiB file in place required holding it in
+ * memory first. A positioned write follows **POSIX `pwrite` semantics**, and every transport must agree on
+ * them — they did not at first (the ssh2 path truncated the tail and required the file to exist at offset 0
+ * while the shell path did the opposite), which is exactly the kind of difference nobody notices until a
+ * resumed upload corrupts a file:
+ *
+ *  - bytes outside `[offset, offset + bytes.length)` are **left untouched** — never truncated;
+ *  - `offset === 0` creates the file when it does not exist, otherwise writes from 0 and keeps the tail;
+ *  - `offset > 0` requires the file to exist (a hole is not conjured up);
+ *  - the length grows when needed, but a caller that wants a shorter file must say so (`writeFile`, or an
+ *    explicit truncate) — silently shortening on every chunk would break resumable uploads.
+ */
+export interface WriteFileRangeRequest {
+    /** Absolute remote path. */
+    readonly path: string;
+    /** Byte offset to write at (0-based); the file must already be at least this long, or be created by offset 0. */
+    readonly offset: number;
+    readonly bytes: Uint8Array;
+    /** Create missing parent directories. */
+    readonly createParents?: boolean;
+}
+/** A server-side copy: one remote path to another, bytes never crossing this process. */
+export interface CopyFileRequest {
+    /** Absolute remote source path. */
+    readonly from: string;
+    /** Absolute remote destination path. */
+    readonly to: string;
+    /** Create missing parent directories of `to`. */
+    readonly createParents?: boolean;
+    /** Replace an existing destination. When absent the copy refuses to clobber. */
+    readonly overwrite?: boolean;
+    /** Require the destination to still have exactly this version before replacing it. */
+    readonly expectedVersion?: string;
+}
+/** Outcome of a remote write. */
+/** What the remote host reported about itself. Every field is best-effort; absent means "not known". */
+export interface RemoteEnvResult {
+    readonly os: string;
+    readonly arch: string;
+    readonly kernel?: string | undefined;
+    readonly distro?: string | undefined;
+    readonly shell?: string | undefined;
+    readonly cpus: number;
+    readonly memTotalBytes?: number | undefined;
+    readonly memAvailableBytes?: number | undefined;
+    readonly diskFreeBytes?: number | undefined;
+    readonly diskTotalBytes?: number | undefined;
+    readonly user: string;
+    readonly uid: number;
+    readonly home: string;
+    readonly path: string;
+    /** Commands that exist, mapped to their resolved absolute path. */
+    readonly tools: Readonly<Record<string, string>>;
+    /** Commands from the probe list that were not found. */
+    readonly missing: readonly string[];
+    /** Unix seconds of the sample this answer came from (not of the call). */
+    readonly probedAt: number;
+}
+/** One patch request: a unified diff applied to one file. */
+export interface PatchFileRequest {
+    readonly path: string;
+    /** Unified diff text. Line numbers are used for error messages only; hunks are located by context. */
+    readonly diff: string;
+    readonly expectedVersion?: string;
+}
+/** What a patch did. */
+export interface PatchFileResult {
+    readonly hunks: number;
+    readonly bytes: number;
+    readonly version: string;
+}
+/** One recursive copy request; both paths are absolute on the remote host. */
+export interface CopyTreeRequest {
+    readonly from: string;
+    readonly to: string;
+}
+/** What a recursive server-side copy did. */
+export interface CopyTreeOutcome {
+    readonly files: number;
+    readonly dirs: number;
+    readonly symlinks: number;
+    readonly bytes: number;
+}
+export interface RemoteWriteOutcome {
+    readonly bytes: number;
+    /** Digest of the written content when the host can compute it. */
+    readonly sha256?: string;
+    /**
+     * Opaque version token of the written content when the host reports one.
+     *
+     * The two ssh transports report a digest instead; the Tier 2 agent reports `size:mtimeNs`, which is
+     * the token its own `fs.write` guard expects — so a caller that wants to chain another guarded write
+     * must use this value rather than a locally derived digest.
+     */
+    readonly version?: string;
+}
+/** One rename/move inside the remote file system. */
+export interface RenameRequest {
+    readonly from: string;
+    readonly to: string;
+    /** Create the destination's parent directories. Implementations must not silently copy across devices. */
+    readonly createParents?: boolean;
+}
+/** One removal. */
+export interface RemoveRequest {
+    /** Absolute remote path. */
+    readonly path: string;
+    /** Remove directories and their contents; a directory without this flag must fail, not half-succeed. */
+    readonly recursive?: boolean;
+}
+/** Retained stdout cap applied when the caller does not choose one. */
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+/** Default file read cap; larger files must be paged by the caller. */
+export declare const DEFAULT_MAX_READ_BYTES: number;
+/** Request for {@link Transport.editFile}: an atomic in-place edit done **by the agent** (审计 0030). */
+export interface EditFileRequest {
+    readonly path: string;
+    readonly oldString: string;
+    readonly newString: string;
+    readonly replaceAll?: boolean;
+    readonly expectedVersion?: string;
+}
+/** Result of {@link Transport.editFile}. */
+export interface EditFileResult {
+    readonly bytes: number;
+    readonly version: string;
+    readonly replaced: number;
+}
+/** Request for {@link Transport.removePath}. */
+export interface RemovePathRequest {
+    readonly path: string;
+    readonly recursive?: boolean;
+    readonly expectedVersion?: string;
+}
+/** Request for {@link Transport.renamePath}. */
+export interface RenamePathRequest {
+    readonly from: string;
+    readonly to: string;
+    readonly createParents?: boolean;
+    readonly expectedVersion?: string;
+}
+/** Request for {@link Transport.hashFile}: sha256 of a whole file or a byte range. */
+export interface HashFileRequest {
+    readonly path: string;
+    readonly offset?: number;
+    readonly length?: number;
+}
+/** Result of {@link Transport.hashFile}. */
+export interface HashFileResult {
+    readonly sha256: string;
+    readonly size: number;
+    readonly bytes: number;
+    readonly version: string;
+}
+/** Request for {@link Transport.makeDir}. */
+export interface MakeDirRequest {
+    readonly path: string;
+    readonly mode?: number;
+    readonly recursive?: boolean;
+}
+/**
+ * Outcome of {@link Transport.makeDir}.
+ *
+ * `created` exists so the **policy** can live in one place. The agent treats `fs.mkdir` as an idempotent
+ * primitive (a repeat answers `created: false`, and its e2e pins that), while the product rule for
+ * `recursive: false` is "refuse a name that is already taken" — that rule belongs to the caller, which
+ * applies it identically on the shell path. Reporting the fact and deciding elsewhere is what keeps the two
+ * tiers from drifting.
+ */
+export interface MakeDirResult {
+    /** `true` when this call created the directory, `false` when it already existed as a directory. */
+    readonly created: boolean;
+}
+/** Request for {@link Transport.globPaths}. */
+export interface GlobPathsRequest {
+    readonly root: string;
+    readonly pattern: string;
+    readonly maxResults?: number;
+    readonly includeDirs?: boolean;
+    readonly timeoutMs?: number;
+}
+/** Result of {@link Transport.globPaths}. */
+export interface GlobPathsResult {
+    readonly paths: readonly string[];
+    readonly truncated: boolean;
+    readonly scanned: number;
+}
+/** Request for {@link Transport.jobStdin}. */
+export interface JobStdinRequest {
+    readonly id: string;
+    readonly data?: string;
+    readonly dataBase64?: string;
+    readonly close?: boolean;
+}
+/** Result of {@link Transport.jobStdin}. */
+export interface JobStdinResult {
+    readonly id: string;
+    readonly bytes: number;
+    readonly closed: boolean;
+}
+/**
+ * 系统 ssh 多路复用（ControlMaster）的失败缓存。
+ *
+ * 放在**端口模块**而不是 `alias-transport.ts`：`app/transport-selector.ts` 需要这个类型
+ * 来做传输选择，而 app 层只允许依赖端口、不允许依赖具体适配器（架构测试会断言）。
+ * 适配器模块继续 re-export，既有调用方无需改动。
+ */
+export interface MultiplexingCache {
+    /** Whether this client+alias pair is already known to lack multiplexing. */
+    isUnsupported(key: string): boolean;
+    /** Record a mux failure so later connects skip the master attempt. */
+    markUnsupported(key: string, reason: string): void;
+    /** The recorded reason, for diagnostics and the UI. */
+    reasonFor(key: string): string | undefined;
+}
+/** One remote execution world. */
+export interface Transport {
+    /** Connection id this transport serves. */
+    readonly id: string;
+    readonly state: TransportState;
+    /** Remote tool availability discovered by {@link probeCapabilities} (or the conservative default). */
+    readonly capabilities: RemoteCapabilities;
+    /** Establish the connection; idempotent. */
+    connect(signal?: AbortSignal): Promise<void>;
+    /** Release the connection and any cached sessions. */
+    dispose(): Promise<void>;
+    /** Run one command to completion. */
+    exec(request: ExecRequest, signal?: AbortSignal): Promise<ExecResult>;
+    /** Read a remote file as bytes. */
+    readFile(request: ReadFileRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /**
+     * Stat a path using **this transport's own** token source, so the answer is comparable with its
+     * {@link readFile}.
+     *
+     * Optional, and its absence is meaningful: Tier 1's shell transports have no native stat, so
+     * `RemoteBackend` keeps using its `stat -c '%Y'` script for them and their long-standing
+     * `size:mtimeSeconds` tokens are untouched. The Tier 2 agent implements it from `fs.stat`, whose
+     * `version` is the very string its `fs.write` guard expects.
+     *
+     * A transport that implements this must report the same token for the same file state as its
+     * `readFile`; a test pins that identity because it is the contract's entire purpose.
+     */
+    statPath?(path: string, signal?: AbortSignal): Promise<RemoteStatResult>;
+    /**
+     * Atomic in-place edit performed by the agent itself (`fs.edit`).
+     *
+     * Optional and its absence is meaningful: Tier 1 has no such primitive, so callers fall back to
+     * read → replace → write. Present, it is one round trip with no file transfer and a version guard
+     * that holds across the whole read-modify-write (审计 0030).
+     */
+    editFile?(request: EditFileRequest, signal?: AbortSignal): Promise<EditFileResult>;
+    /**
+     * Apply a unified diff to one file, atomically.
+     *
+     * Absent on transports without a server-side patcher. The caller must **not** silently fall back to a
+     * client-side apply: the whole point is one round trip, and a fallback would also have to re-implement the
+     * hunk matching rules, which is where a patch applier goes wrong.
+     */
+    patchFile?(request: PatchFileRequest, signal?: AbortSignal): Promise<PatchFileResult>;
+    /** Native delete (`fs.remove`); absent on Tier 1, which uses its shell primitive instead. */
+    removePath?(request: RemovePathRequest, signal?: AbortSignal): Promise<void>;
+    /** Native rename/move (`fs.rename`); absent on Tier 1, which uses its shell primitive. */
+    renamePath?(request: RenamePathRequest, signal?: AbortSignal): Promise<void>;
+    /** Content digest (`fs.hash`): the primitive that makes `expectedSha256` a digest guard. */
+    hashFile?(request: HashFileRequest, signal?: AbortSignal): Promise<HashFileResult>;
+    /** Create a directory (`fs.mkdir`); reports whether it was created rather than deciding the policy. */
+    makeDir?(request: MakeDirRequest, signal?: AbortSignal): Promise<MakeDirResult>;
+    /** Server-side glob (`fs.glob`): enumerate by pattern without shipping the whole index. */
+    globPaths?(request: GlobPathsRequest, signal?: AbortSignal): Promise<GlobPathsResult>;
+    /** Feed a running interactive job's stdin (`proc.stdin`). */
+    jobStdin?(request: JobStdinRequest, signal?: AbortSignal): Promise<JobStdinResult>;
+    /** Write a remote file atomically from the caller's bytes. */
+    writeFile(request: WriteFileRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /** Discover remote tool availability; tolerant of missing commands. */
+    probeCapabilities(signal?: AbortSignal): Promise<RemoteCapabilities>;
+    /**
+     * Read from `offset` without reading the earlier bytes.
+     *
+     * Absent when the transport cannot seek: callers must treat "no method" as "no chunked download" rather
+     * than falling back to a whole-file read (see {@link ReadFileRangeRequest}).
+     */
+    readFileRange?(request: ReadFileRangeRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /**
+     * Write at `offset`, leaving the bytes before it untouched.
+     *
+     * Absent when the transport can only replace whole files: a chunked upload must then either use one
+     * whole-file write or refuse to resume, never pretend.
+     */
+    writeFileRange?(request: WriteFileRangeRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * Copy one remote file to another path **on the remote side**.
+     *
+     * Absent when the transport has no server-side copy: the caller must then relay the bytes itself and say
+     * that it did, rather than quietly streaming a large file through the local machine while claiming a copy.
+     */
+    copyFile?(request: CopyFileRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * Copy a whole **directory tree** on the remote host.
+     *
+     * Absent when the transport cannot do it server-side. The caller must **not** fall back to relaying a tree
+     * file by file: that is exactly the cost this method exists to remove, and a silent fallback would turn a
+     * one-round-trip operation into thousands.
+     */
+    copyTree?(request: CopyTreeRequest, signal?: AbortSignal): Promise<CopyTreeOutcome>;
+    /**
+     * Sample the remote host's environment: OS, resources, and which commands exist.
+     *
+     * Absent on transports that cannot probe; the caller then simply has no environment answer rather than a
+     * guessed one.
+     */
+    probeEnv?(refresh: boolean, signal?: AbortSignal): Promise<RemoteEnvResult>;
+    /**
+     * Move a remote path.
+     *
+     * Contract: create the destination's parents when asked, and **fail** when the move cannot be done as a
+     * rename (e.g. across devices) — a silent copy would break "move then confirm" delete semantics.
+     */
+    rename?(request: RenameRequest, signal?: AbortSignal): Promise<void>;
+    /** Remove a file, or a directory tree when `recursive` is set. */
+    remove?(request: RemoveRequest, signal?: AbortSignal): Promise<void>;
+}
+/** Encode bytes as base64 without line wrapping. */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/** Decode base64, ignoring line breaks produced by remote tooling. */
+export declare function decodeBase64(text: string): Uint8Array;
+//# sourceMappingURL=transport.d.ts.map

package/lib/types/src/host/integration/agent/agent-install-io.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The install ladder's I/O, built on the connection's **Tier 1 transport**.
+ *
+ * The agent cannot install itself, so every step of the ladder runs through the transport that already
+ * works: `exec` for the probe, `writeFile` for the upload (the Tier 1 transports already implement bounded,
+ * atomic remote writes), and one more `exec` for the digest. Nothing here opens a second authentication
+ * path, which is what keeps "upload" as trustworthy as "run a command".
+ *
+ * @module dsh-over-ssh/integration/agent-install-io
+ */
+import type { AgentInstallIo } from '../../infra/transport/agent/agent-installer.ts';
+import type { Transport } from '../../infra/transport/transport.ts';
+/** Options for {@link createAgentInstallIo}. */
+export interface AgentInstallIoOptions {
+    /** The Tier 1 transport of the connection being installed onto. */
+    readonly transport: Transport;
+    /** Refuse to upload anything larger than this (a corrupt manifest must not fill the host's disk). */
+    readonly maxUploadBytes?: number;
+    /** Local file reader, injected so tests never touch a real file. */
+    readonly readLocalFile?: (path: string) => Promise<Uint8Array>;
+    /** Local size lookup, so an oversized artifact is rejected before it is read into memory. */
+    readonly localSize?: (path: string) => Promise<number>;
+    /** Cap for exec output while probing; the ladder only needs tiny answers. */
+    readonly probeMaxBytes?: number;
+}
+/**
+ * Build the ladder's I/O from an existing transport.
+ *
+ * @param options - transport plus optional readers and caps.
+ * @returns an {@link AgentInstallIo} that never opens a second connection.
+ */
+export declare function createAgentInstallIo(options: AgentInstallIoOptions): AgentInstallIo;
+//# sourceMappingURL=agent-install-io.d.ts.map

package/lib/types/src/host/integration/agent/agent-preflight.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The bridge between the install ladder and transport selection.
+ *
+ * Selection is synchronous (it may only consult cached facts) while the ladder must talk to the host, so
+ * the two are joined by an **async preflight**: the selector's first answer is revised before any transport
+ * is built. That is what makes "agent unavailable ⇒ Tier 1" true without making the selector depend on I/O.
+ *
+ * Two rules this module exists to enforce:
+ *
+ *  1. **No host traffic unless the connection asked for the agent.** A non-agent decision returns
+ *     immediately, so an ordinary alias connection never probes or uploads anything.
+ *  2. **A failed ladder is a degradation, never an exception.** `ensureAgent` already turns every remote
+ *     problem into a `tier1` outcome; this module forwards that as a revised decision plus a hint.
+ *
+ * @module dsh-over-ssh/integration/agent-preflight
+ */
+import type { TransportPreflight } from '../../app/transport/transport-service.ts';
+import type { ConnectionProfile } from '../../domain/roots/connection.ts';
+import type { AgentInstallation } from '../../infra/transport/agent/agent-installer.ts';
+/** What the preflight learned about one connection. */
+export type AgentPreflightOutcome = {
+    readonly kind: 'agent';
+    readonly remotePath: string;
+    readonly platform: string;
+    readonly reused: boolean;
+} | {
+    readonly kind: 'tier1';
+    readonly reason: string;
+    readonly hint: string;
+};
+/** Options for {@link createAgentPreflight}. */
+export interface AgentPreflightOptions {
+    /** Run (or reuse a memoized) ladder for one connection. Injected so this module stays offline-testable. */
+    readonly ensure: (profile: ConnectionProfile, signal?: AbortSignal) => Promise<AgentInstallation>;
+    /** Optional sink so the connection UI can show what happened. */
+    readonly onOutcome?: (connectionId: string, outcome: AgentPreflightOutcome) => void;
+    /** Optional logger for the "we are not even trying" path; defaults to silence. */
+    readonly onSkipped?: (profile: ConnectionProfile) => void;
+}
+/** The preflight plus the installation facts the agent factory needs. */
+export interface AgentPreflight {
+    /** Pass this to {@link TransportServiceOptions.preflight}. */
+    readonly preflight: TransportPreflight;
+    /** The installation for a connection, once the ladder approved one. */
+    installationFor(connectionId: string): AgentPreflightOutcome | undefined;
+    /** Forget one connection (its transport was released, or the user changed the connection). */
+    forget(connectionId: string): void;
+}
+/**
+ * Build the preflight.
+ *
+ * @param options - ladder plus optional sinks.
+ * @returns the preflight, an installation lookup, and a way to forget a connection.
+ */
+export declare function createAgentPreflight(options: AgentPreflightOptions): AgentPreflight;
+//# sourceMappingURL=agent-preflight.d.ts.map