dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,239 @@
+/**
+ * The remote backend: one remote directory served over a {@link Transport}.
+ *
+ * This is the Tier 1 shape — no agent on the remote host, only POSIX tools the server already has
+ * (`sh`, `wc`, `stat`, `base64`). Directory listing is therefore one bounded shell script rather
+ * than a protocol method, and the script is built from a fixed template with a single quoted path,
+ * so there is no injection surface.
+ *
+ * Version tokens are whatever **one** transport reports for the same file state, and this backend never
+ * mixes two sources. On Tier 1 that is the shell `size:mtimeSeconds` shape (comparable with the ssh2
+ * transport); on Tier 2 it is the agent's `size:mtimeNs`, obtained from {@link Transport.statPath} so that a
+ * token read by `readText` and a token compared by `writeText` come from the same producer. Deriving one
+ * from the other is what made every read→write guard fail on Tier 2 (audit 0055).
+ *
+ * @module dsh-over-ssh/infra/backend/remote-backend
+ */
+import type { Backend, BackendEntry, BackendRead, BackendSandboxMode, BackendStat, BackendText, BackendWrite } from '../../app/backend.ts';
+import type { RemoteCapabilities } from '../../domain/capability.ts';
+import { type VersionedCacheStats } from '../cache/versioned.ts';
+import type { Transport } from '../transport/transport.ts';
+/** Options for {@link RemoteBackend}. */
+export interface RemoteBackendOptions {
+    /** Backend id; the router namespaces target keys with it (equals the root key). */
+    readonly id: string;
+    /** A ready transport. Mutually exclusive with {@link getTransport}. */
+    readonly transport?: Transport;
+    /**
+     * Lazy transport resolver, called once on first use.
+     *
+     * The root registry's backend factory is synchronous while acquiring a transport is not, so the
+     * connection is established when the first operation needs it and reused afterwards.
+     */
+    readonly getTransport?: () => Promise<Transport>;
+    /** Read cap applied by the backend itself; the router passes a smaller one when it wants to. */
+    readonly maxReadBytes?: number;
+    /**
+     * Freshness cache policy for the read path (FR-2.7). Omitted means {@link DEFAULT_CACHE}.
+     *
+     * This is the switch that makes "re-opening the same file within the TTL costs **zero** round trips"
+     * true. Before it existed, `VersionedCache` was written, benchmarked and then never constructed by
+     * any production code: every read went to the host, and the numbers in `baseline.md` measured a
+     * component nobody called (audit 0044).
+     */
+    readonly cache?: RemoteBackendCacheOptions;
+}
+/** Cache policy for one remote backend. */
+export interface RemoteBackendCacheOptions {
+    /** Freshness window; the FR-2.7 budget is 5 s. `0` disables retention (every read goes remote). */
+    readonly ttlMs?: number;
+    /** Bound on retained entries. */
+    readonly maxEntries?: number;
+    /** Bound on retained payload bytes. */
+    readonly maxBytes?: number;
+    /** Injectable clock, so a TTL can be tested without sleeping. */
+    readonly now?: () => number;
+}
+/** Filesystem access for one remote root over a transport. */
+export declare class RemoteBackend implements Backend {
+    #private;
+    readonly id: string;
+    readonly sandboxMode: BackendSandboxMode | undefined;
+    /**
+     * Whether this root has a **native** watcher: the transport is one that speaks `watch.*` *and* its handshake
+     * advertised `watch === "native"`. It reads `false` until the transport is known — the capability is a fact
+     * about the connected agent, and claiming it early would advertise a watcher for a Tier 1 host that can
+     * never serve one.
+     */
+    get watches(): boolean;
+    constructor(options: RemoteBackendOptions);
+    /**
+     * Read-path cache counters, for diagnostics and the performance baseline.
+     *
+     * Reported rather than inferred: the FR-2.7 claims ("0 round trips inside the TTL", "≈5× on
+     * revalidation") are only checkable if the counters behind them are reachable from outside.
+     */
+    get cacheStats(): {
+        readonly reads: VersionedCacheStats;
+        readonly listings: VersionedCacheStats;
+    };
+    /** Remote capabilities discovered so far (probe results live on the transport). */
+    capabilities(): Promise<RemoteCapabilities>;
+    /**
+     * Stat a path, preferring the transport's **own** token source when it has one.
+     *
+     * This is where the two tiers are reconciled, and it is the *only* place that decides. A transport that
+     * exposes {@link Transport.statPath} (Tier 2: the agent's `fs.stat`) reports the very same token its
+     * `readFile` reports (`size:mtimeNs`), so a version read by one and compared by the other is comparing
+     * like with like. Tier 1 has no native stat, so the shell script below runs exactly as it always has and
+     * its long-standing `size:mtimeSeconds` tokens are untouched.
+     *
+     * Before this, `stat` always ran the shell script: on Tier 2 it produced seconds while every read produced
+     * nanoseconds, so the `remote_read` → `remote_write`/`remote_edit` version guard could never pass and the
+     * FR-2.7 stale-revalidation branch never matched either.
+     */
+    stat(absolute: string, signal?: AbortSignal): Promise<BackendStat>;
+    list(absolute: string, signal?: AbortSignal): Promise<readonly BackendEntry[]>;
+    /**
+     * Read a file, going through the FR-2.7 freshness cache.
+     *
+     * The three states the budget is written in terms of:
+     *  - **fresh** (inside the TTL): returned from memory, **zero** round trips;
+     *  - **stale**: one cheap `stat` decides. If the version still matches, the retained body is reused and
+     *    only the timestamp is refreshed — this is the ≈5× revalidation path;
+     *  - **gone or changed**: re-read and replace.
+     *
+     * A read with a different cap is a different cache entry (see the field notes), so a capped probe can
+     * never satisfy a full read.
+     */
+    readBytes(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendRead>;
+    /**
+     * Atomic in-place edit through the agent's `fs.edit` (审计 0030).
+     *
+     * The caller passes the version it just read; the agent re-checks it, so a concurrent modification
+     * between our read and this call is refused rather than clobbered. Throws `REMOTE_UNSUPPORTED` when the
+     * agent predates the method, which is what makes `ctx.fs` fall back to read → replace → write.
+     */
+    editText(absolute: string, oldString: string, newString: string, replaceAll: boolean, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite & {
+        readonly replaced: number;
+    }>;
+    /**
+     * Apply a unified diff server-side: every hunk in one round trip, all-or-nothing.
+     *
+     * No client-side fallback on purpose. Reading the file, patching it here and writing it back would cost
+     * three round trips for two hunks — more than the `remote_edit` calls it is meant to replace — and would
+     * need a second implementation of the hunk-matching rules.
+     */
+    patchText(absolute: string, diff: string, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite & {
+        readonly hunks: number;
+    }>;
+    readText(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendText>;
+    /**
+     * Cache-aware wrapper around {@link readManyUncached}, so a batch sweep leaves the cache warm.
+     *
+     * Satisfying the whole batch from cache is deliberately **not** attempted: the batch exists to collapse
+     * N round trips into one, and splitting it into cached and uncached halves would give back the round trips
+     * it was built to save. Cached entries are therefore refreshed from the batch's answer, and files already
+     * fresh are still fetched (one shared round trip) rather than removed from the batch.
+     */
+    readMany(absolutePaths: readonly string[], options: {
+        readonly maxBytesEach: number;
+        readonly totalBytesCap?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly chunks: readonly (BackendText | undefined)[];
+        readonly missing: readonly string[];
+    }>;
+    /**
+     * Write text remotely.
+     *
+     * **The version guard is tier-aware, and that is the point.** The token a caller passes back is one this
+     * backend just handed out, so the guard must be verified by the *same* token source:
+     *
+     *  - a transport with a native version token (Tier 2) verifies the token itself through
+     *    {@link WriteFileRequest.expectedVersion}, which is what its own `fs.write` guard compares — no digest
+     *    is involved and none could be, because the agent advertises no sha256 tool;
+     *  - a Tier 1 transport verifies a content digest, so the current content is hashed and handed over as
+     *    `expectedSha256`. That path is unchanged.
+     *
+     * A plain write is one round trip plus one `stat` for the new version.
+     */
+    writeText(absolute: string, text: string, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite>;
+    /**
+     * Watch one remote path (directory, or one file) through the agent's native watcher.
+     *
+     * The agent watches **directories**: `watch.start` registers recursively from the given roots, and each
+     * reported event carries the path of the changed entry. A file target therefore watches its parent directory
+     * and filters events by exact path — the same shape the platform's own local watcher uses, and the only way
+     * inotify can report changes to one file.
+     *
+     * Degradation is **not** silent:
+     *  - `watch.start` reporting `truncated` (maxWatches / `max_user_watches` cut registration short) means the
+     *    tree is only partially covered; the watcher is stopped and this call fails rather than promising
+     *    notifications it cannot deliver;
+     *  - a poll whose cumulative `dropped` grew means events were lost (queue limit / kernel overflow); the
+     *    owner is told through `changed(error)` and the watcher stops, so the caller rescans instead of trusting
+     *    an incomplete stream.
+     *
+     * `changed()` also covers "nothing to re-stat but something happened" — the platform's contract is
+     * "re-stat this path", so events are coalesced per poll.
+     *
+     * @param absolute - root-absolute remote path (directory or file).
+     * @param changed - platform callback: no argument = re-stat; an error = the subscription is dead.
+     * @param signal - cancels the subscription; stopping is immediate and idempotent.
+     * @returns the disposer (stops the watcher; idempotent).
+     * @throws SshDevError `REMOTE_UNSUPPORTED` when this connection has no native watcher, `REMOTE_NOT_FOUND`
+     *   when a file target's parent directory does not exist, `CANCELLED` when aborted during setup.
+     */
+    watch(absolute: string, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
+    /**
+     * Stop every watcher this backend started.
+     *
+     * Not part of {@link Backend}: the wiring owns backend teardown and is outside this change's scope. It is
+     * public so whoever retires the backend can end the poll loops, and so tests can prove they stop.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Create a directory (FR-2.2.2).
+     *
+     * Prefers the agent's `fs.mkdir` (Tier 2) and falls back to one bounded shell script. The shell path is not
+     * dead weight: Tier 1 has no agent, and an older agent answers `E_METHOD`, which
+     * {@link Transport.makeDir} reports as `REMOTE_UNSUPPORTED`.
+     *
+     * **Why the protocol path is worth preferring**: the shell version depends on the remote having a POSIX
+     * `mkdir`, and its refusals have to be parsed back out of the script's own `DSH_ERROR=` line. Windows
+     * targets have neither. The product rule — `recursive: false` refuses a name that is already taken, so a
+     * 「新建目录」 dialog cannot silently "succeed" into someone else's folder — is applied **here**, once, for
+     * both paths.
+     */
+    mkdir(absolute: string, options: {
+        readonly recursive: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Rename/move a path (FR-2.2.2), refusing to clobber.
+     *
+     * The no-clobber rule lives in {@link renameCommand}'s script (see its notes): `mv` would either replace a
+     * file or move the source *inside* an existing directory, and both are silent.
+     */
+    rename(from: string, to: string, options: {
+        readonly createParents: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /** Remove a path (FR-2.2.2); `recursive: false` refuses a directory. */
+    remove(absolute: string, options: {
+        readonly recursive: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Change one path's permission bits.
+     *
+     * Runs through `exec` rather than a transport primitive because the agent has no `fs.chmod`; the same
+     * script therefore works on both tiers, which is what keeps `remote_write`'s `mode` from meaning two
+     * different things depending on the host (audit 0064 P4). `chmodCommand` re-validates the octal digits, so
+     * this is not a place where model-supplied text reaches a shell unchecked.
+     */
+    chmod(absolute: string, mode: string, signal?: AbortSignal): Promise<void>;
+    /** Whether this backend's root contains a path (used by the router's `contains`). */
+    contains(parent: string, candidate: string): boolean;
+}
+/** Parse `KEY=value` header lines into a map. */
+export declare function parseHeaders(stdout: string): Map<string, string>;
+//# sourceMappingURL=remote-backend.d.ts.map

package/lib/types/src/host/infra/cache/lru.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A bounded LRU cache: at most `maxEntries` entries and at most `maxBytes` of payload.
+ *
+ * Both bounds are enforced because "number of open files" and "memory held by cached file
+ * bodies" fail differently: a repository of tiny files hits the entry bound, a few large
+ * generated files hit the byte bound.
+ *
+ * @module dsh-over-ssh/infra/cache/lru
+ */
+/** Bounds for one cache. */
+export interface LruCacheOptions {
+    /** Maximum number of retained entries; at least 1. */
+    readonly maxEntries: number;
+    /** Maximum total payload bytes; at least 1. */
+    readonly maxBytes: number;
+}
+/** Observable cache counters. */
+export interface LruStats {
+    readonly entries: number;
+    readonly bytes: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly evictions: number;
+    /** Values rejected because a single value exceeded `maxBytes`. */
+    readonly rejectedOversize: number;
+}
+/** A size-bounded, recency-ordered map. */
+export declare class LruCache<V> {
+    #private;
+    constructor(options: LruCacheOptions, sizeOf: (value: V) => number);
+    /** Look up a value and mark it most-recently used. */
+    get(key: string): V | undefined;
+    /** Look up a value without changing recency or counters. */
+    peek(key: string): V | undefined;
+    /** Whether the key is retained. */
+    has(key: string): boolean;
+    /**
+     * Insert or replace a value.
+     *
+     * @returns `false` when the value alone exceeds `maxBytes` and was therefore not stored.
+     */
+    set(key: string, value: V): boolean;
+    /** Remove a key, returning whether it was present. */
+    delete(key: string): boolean;
+    /** Remove everything. */
+    clear(): void;
+    /** Keys from least to most recently used. */
+    keys(): readonly string[];
+    /** Current counters. */
+    get stats(): LruStats;
+}
+//# sourceMappingURL=lru.d.ts.map

package/lib/types/src/host/infra/cache/versioned.d.ts

@@ -0,0 +1,77 @@
+/**
+ * TTL + version cache used by the remote read path.
+ *
+ * The performance budget depends on this three-state behaviour:
+ *  - within TTL: a hit with zero remote round trips;
+ *  - past TTL: a *stale* hit whose body may still be reused if a cheap version check matches
+ *    (this is what makes revalidation ≈5× cheaper than a first open);
+ *  - invalidated: no usable body.
+ *
+ * @module dsh-over-ssh/infra/cache/versioned
+ */
+/** Cache policy for one cache instance. */
+export interface VersionedCacheOptions {
+    /** Freshness window in milliseconds. */
+    readonly ttlMs: number;
+    readonly maxEntries: number;
+    readonly maxBytes: number;
+    /** Monotonic-or-wall clock; injectable so tests are deterministic. */
+    readonly now?: () => number;
+}
+/** One lookup result. */
+export interface VersionedHit<V> {
+    readonly value: V;
+    /** The version token recorded when the body was cached. */
+    readonly version: string;
+    /** Whether the entry is still inside its freshness window. */
+    readonly fresh: boolean;
+    readonly ageMs: number;
+}
+/** Counters reported for diagnostics and the performance baseline. */
+export interface VersionedCacheStats {
+    readonly entries: number;
+    readonly bytes: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly freshHits: number;
+    readonly staleHits: number;
+    /** Version checks that reused an existing body. */
+    readonly revalidations: number;
+    readonly evictions: number;
+}
+/** Freshness-aware cache keyed by route key. */
+export declare class VersionedCache<V> {
+    #private;
+    constructor(options: VersionedCacheOptions, sizeOf: (value: V) => number);
+    /**
+     * Look up an entry.
+     *
+     * @param key - route key.
+     * @returns the entry with its freshness, or `undefined` when nothing is retained.
+     */
+    get(key: string): VersionedHit<V> | undefined;
+    /** Insert or replace an entry, stamping it as just-read. */
+    set(key: string, value: V, version: string): boolean;
+    /**
+     * Refresh an entry's timestamp after a cheap remote version check matched.
+     *
+     * @param key - route key.
+     * @param version - the version observed by the check; a mismatch refuses the touch.
+     * @returns whether the entry was refreshed.
+     */
+    touch(key: string, version: string): boolean;
+    /** Drop one entry. */
+    invalidate(key: string): boolean;
+    /**
+     * Drop every entry whose key starts with the prefix, used when a directory epoch changes.
+     *
+     * @param prefix - key prefix.
+     * @returns the number of removed entries.
+     */
+    invalidatePrefix(prefix: string): number;
+    /** Remove everything. */
+    clear(): void;
+    /** Current counters. */
+    get stats(): VersionedCacheStats;
+}
+//# sourceMappingURL=versioned.d.ts.map

package/lib/types/src/host/infra/temp-name.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A temporary file name that is unique per **write**, not just per process.
+ *
+ * The pid alone is not enough: two concurrent writes to the same target from one process picked the same
+ * temp name, so A's rename could publish B's bytes while reporting A's byte count, and B's rename then
+ * failed because the file was already gone (audit 0097). A per-process sequence closes that window, and the
+ * pid keeps the name distinct from another host process writing the same file.
+ *
+ * @module dsh-over-ssh/infra/temp-name
+ */
+/**
+ * Build a temp path next to `path` that no other in-flight write in this process will reuse.
+ *
+ * @param path - the target the temp file is later renamed onto.
+ * @returns `path` plus a `.dsh-tmp-<pid>-<n>` suffix, keeping the file in the same directory so the rename
+ *   stays a rename and not a cross-device copy.
+ */
+export declare function temporaryNameFor(path: string): string;
+//# sourceMappingURL=temp-name.d.ts.map

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

@@ -0,0 +1,121 @@
+/**
+ * The Tier 2 install ladder: probe → reuse-or-upload → verify → execute-or-fall-back.
+ *
+ * Tier 1 is the floor, so **nothing in here throws for a remote-side problem**: every failure becomes a
+ * {@link AgentInstallation} with `kind: 'tier1'` plus a reason and an actionable hint. Callers then keep
+ * using the zero-install transport, and the diagnostic survives to the UI.
+ *
+ * The whole ladder runs through injected I/O ({@link AgentInstallIo}) because it must be testable without a
+ * server and, more importantly, because it has to run over the **Tier 1 transport** — the agent cannot be
+ * used to install itself.
+ *
+ * Integrity rules taken from ADR-0005:
+ *
+ *  - the artifact's SHA-256 comes from the plugin's shipped manifest, never from the remote host;
+ *  - the digest is verified **after** the upload and again after it lands at its final path;
+ *  - a file that is group- or world-writable is never executed;
+ *  - the last step is an actual execution (`--version`), because `noexec` cannot be detected reliably by
+ *    reading mount options; "it ran" is the only honest proof.
+ *
+ * @module dsh-over-ssh/infra/transport/agent-installer
+ */
+/** One binary shipped with the plugin, as listed in the SHA-256 manifest. */
+export interface AgentArtifact {
+    /** Manifest key: `linux-amd64`, `linux-arm64`, … */
+    readonly platform: string;
+    /** Absolute path inside the plugin package. */
+    readonly path: string;
+    /** Lowercase hex SHA-256 from the manifest (trusted, local). */
+    readonly sha256: string;
+    readonly bytes: number;
+}
+/** Where the agent should end up, and where it is staged first. */
+export interface AgentInstallTarget {
+    /** Final remote path of the binary. */
+    readonly remotePath: string;
+    /**
+     * Remote directory used for staging. Must share a filesystem with {@link remotePath} so the final
+     * `mv` is an atomic rename rather than a copy.
+     */
+    readonly stagingDir: string;
+}
+/** Every effect the ladder needs; all of it must work **before** Tier 2 exists. */
+export interface AgentInstallIo {
+    /** Run one shell command over the Tier 1 transport. */
+    exec(command: string, signal?: AbortSignal): Promise<{
+        readonly exitCode: number;
+        readonly stdout: string;
+        readonly stderr: string;
+    }>;
+    /** Upload the local artifact, then verify; the caller decides sftp vs base64. */
+    upload(localPath: string, remotePath: string, signal?: AbortSignal): Promise<void>;
+    /** Remote `sha256sum`-equivalent, or `undefined` when the host has no usable digest tool. */
+    digestTool(signal?: AbortSignal): Promise<'sha256sum' | 'shasum' | undefined>;
+    /** Hex digest of a remote file using the tool reported by {@link digestTool}. */
+    remoteSha256(path: string, tool: string, signal?: AbortSignal): Promise<string | undefined>;
+}
+/** Why the plugin stayed on Tier 1. One value per distinct operator action. */
+export type AgentFallbackReason = 'probe-failed' | 'platform-unsupported' | 'no-digest-tool' | 'staging-unwritable' | 'upload-failed' | 'upload-mismatch' | 'not-executable' | 'too-large';
+/** Outcome of the ladder. */
+export type AgentInstallation = {
+    readonly kind: 'installed' | 'reused';
+    readonly platform: string;
+    readonly remotePath: string;
+    readonly sha256: string;
+} | {
+    readonly kind: 'tier1';
+    readonly reason: AgentFallbackReason;
+    readonly hint: string;
+    readonly details: Readonly<Record<string, unknown>>;
+};
+/** Options for {@link ensureAgent}. */
+export interface EnsureAgentOptions {
+    /** Every shipped artifact, normally read from the manifest. */
+    readonly artifacts: readonly AgentArtifact[];
+    /** Missing artifacts are the caller's problem, not the remote host's. */
+    readonly target: AgentInstallTarget;
+    readonly io: AgentInstallIo;
+    readonly signal?: AbortSignal;
+    /** Refuse to upload anything larger than this (guards against a corrupt manifest). */
+    readonly maxBytes?: number;
+}
+/**
+ * Map `uname` output onto a manifest platform key.
+ *
+ * @param system - `uname -s` (e.g. `Linux`, `Darwin`).
+ * @param machine - `uname -m` (e.g. `x86_64`, `aarch64`).
+ * @returns the manifest key, or `undefined` when nothing is shipped for that pair.
+ */
+export declare function platformKey(system: string, machine: string): string | undefined;
+/**
+ * Run the ladder: reuse an already-correct binary, otherwise install one, otherwise stay on Tier 1.
+ *
+ * @param options - artifacts, target, injected I/O and cancellation.
+ * @returns the installation, or a Tier 1 fallback carrying a reason and a hint. Never throws for a
+ *   remote-side problem; a cancelled/aborted call propagates instead.
+ */
+export declare function ensureAgent(options: EnsureAgentOptions): Promise<AgentInstallation>;
+/** Manifest schema this loader understands (written by `tools/agent-manifest.mjs`). */
+export declare const AGENT_MANIFEST_VERSION = 1;
+/**
+ * Read the shipped manifest into install artifacts.
+ *
+ * Every field is validated rather than trusted: a manifest with a bad digest, a missing path or an unknown
+ * schema version must fail **before** anything is uploaded, because this file is the root of the trust
+ * chain (ADR-0005). `agentVersion`/`sourceCommit` are optional provenance (written by
+ * `tools/agent-manifest.mjs generate` from the binaries themselves); a manifest without them still loads. Artifact paths are resolved relative to the manifest's own directory, so the packaged
+ * tree can be moved as a unit.
+ *
+ * @param manifestPath - path to `agent-manifest.json` inside the plugin package.
+ * @returns the parsed manifest with absolute artifact paths.
+ * @throws Error describing the first structural problem (unreadable, unknown version, empty, malformed).
+ */
+export declare function loadAgentManifest(manifestPath: string): Promise<{
+    readonly version: number;
+    readonly artifacts: readonly AgentArtifact[];
+    /** Version the artifacts report (`hello.result.agent.version`), when the manifest records it. */
+    readonly agentVersion?: string;
+    /** Commit the artifacts were built from, when the manifest records it. */
+    readonly sourceCommit?: string;
+}>;
+//# sourceMappingURL=agent-installer.d.ts.map

package/lib/types/src/host/infra/transport/agent/agent-protocol-client.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 代理协议的**客户端层**：请求/响应配对、在飞窗口、blob 通道与关闭时清场。
+ *
+ * 线上格式的读写移到 `agent-protocol-codec.ts`，错误与截止移到 `agent-protocol-errors.ts`
+ * （审计 0079）。本文件只剩状态机本身：发请求、配对响应、管理 blob 通道、关闭时清场。
+ *
+ * @module dsh-over-ssh/infra/transport/agent-protocol-client
+ */
+import { SshDevError } from '../../../domain/errors.ts';
+import type { AgentSession } from './agent-protocol-types.ts';
+/**
+ * 代理协议的**客户端层**：请求/响应配对、在飞窗口、blob 通道、截止与取消、参数压缩与结果读取。
+ *
+ * 从 `agent-transport.ts` 拆出（审计 0077）。它只依赖帧层与类型层，**不依赖**任何 Transport 实现，
+ * 因此可以脱离传输单独测试（既有测试正是这么用的）。
+ *
+ * @module dsh-over-ssh/infra/transport/agent-protocol-client
+ */
+export declare class AgentProtocolClient {
+    #private;
+    constructor(session: AgentSession, options?: {
+        readonly requestTimeoutMs?: number;
+        readonly maxInFlight?: number;
+        readonly now?: () => number;
+        readonly epoch?: number;
+        readonly epochNow?: () => number;
+        /**
+         * Called once when the connection is declared dead.
+         *
+         * Without it a client-side death is invisible to the owner: a per-request deadline that expires
+         * poisons this client permanently (`#lost` is never cleared), yet the transport still reports
+         * `state === 'ready'`, so the transport service keeps handing the same dead client to every later
+         * call. Every one of them then fails instantly with the *first* timeout's message and numbers.
+         */
+        readonly onFatal?: () => void;
+        /**
+         * Default session for every request on this connection, sent as `hello.params.sessionId`.
+         *
+         * Omitted (the default) means the field is not sent at all — byte-for-byte the pre-session
+         * handshake, which the agent answers with `sessionId: "default"`.
+         */
+        readonly sessionId?: string;
+    });
+    /** Whether the `hello` handshake already succeeded. */
+    get handshaked(): boolean;
+    /** Whether the connection has been declared dead. */
+    get lost(): boolean;
+    /** Whether the agent accepted request-level cancellation (`capabilities.cancel === true`). */
+    get cancelSupported(): boolean;
+    /**
+     * Record the cancellation capability the handshake reported.
+     *
+     * Called by the owning transport after it adopts `hello`/`capabilities`; a client that is never told keeps
+     * the old behaviour. `true` only when the agent literally sent `true` — a missing bit is not a maybe.
+     */
+    setCancelSupport(supported: boolean): void;
+    /** Whether {@link close} already ran. */
+    get closed(): boolean;
+    /** Feed stdout bytes; called by the transport's data handler. */
+    handleData(chunk: Uint8Array): void;
+    /**
+     * Handshake. The first method on a fresh session must be `hello`; a version mismatch is fatal and is
+     * **not** retried with a guessed version.
+     */
+    handshake(signal?: AbortSignal, clientId?: string): Promise<unknown>;
+    /**
+     * Session the agent echoed for this connection, or `undefined` when it did not send one.
+     *
+     * `undefined` is meaningful: it means the agent predates session support, so this client must not claim
+     * the requests are isolated from one another.
+     */
+    get negotiatedSessionId(): string | undefined;
+    /**
+     * Whether the agent reported that jobs outlive this connection (`hello.result.daemon`).
+     *
+     * Defaults to `false`, which is the honest reading of "the agent said nothing": today's agent does tie
+     * job lifetime to the connection, so assuming otherwise would make callers skip cleanup that is still
+     * required.
+     */
+    get daemon(): boolean;
+    /** `capabilities`. Requires a completed handshake. */
+    capabilities(signal?: AbortSignal): Promise<unknown>;
+    /**
+     * Send one control-frame request (plus an optional blob frame) and await its response.
+     *
+     * @throws SshDevError `CONNECTION_LOST` when the session is gone, the deadline expired mid-request, or
+     *   the stream desynchronised; `CANCELLED` when the caller's signal aborted.
+     * @throws AgentProtocolError when the agent answered with a structured error.
+     */
+    request(method: string, params: Readonly<Record<string, unknown>>, options?: RequestOptions): Promise<unknown>;
+    /**
+     * The blob payload belonging to `control`.
+     *
+     * v1 semantics: a response with `result.blob === true` is followed by exactly one blob frame, so the
+     * blob cannot be awaited *before* the control response arrives; it is persisted on arrival instead
+     * (a fast agent may deliver it before this call is even entered).
+     *
+     * Under pipelining several requests may have declared a blob at once, so the channel is resolved by the
+     * identity of the control promise instead of from one global "current blob" slot.
+     *
+     * Bounded on purpose: the blob shares the request deadline, so an agent that declares a blob and then
+     * goes silent produces one failed request instead of a promise that never settles.
+     *
+     * @throws AgentProtocolError `E_PROTOCOL` when the response carried no blob within the deadline.
+     */
+    readBlob(control: Promise<unknown>, options?: {
+        readonly signal?: AbortSignal;
+        readonly timeoutMs?: number;
+    }): Promise<Uint8Array>;
+    /** Declare the connection dead: reject everything outstanding and stop accepting work. */
+    failConnection(error: SshDevError): void;
+    /** Stop the client; idempotent. */
+    close(): void;
+}
+interface RequestOptions {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    /** Blob payload to send immediately after the control frame (`fs.write`). */
+    readonly blob?: Uint8Array;
+    /**
+     * Session this request belongs to; overrides the client's {@link AgentProtocolClientOptions.sessionId}
+     * default for this one request.
+     *
+     * The agent gives each session its own share of the per-connection in-flight window, so naming the
+     * session is what keeps one session's long request from queueing another's short one behind it.
+     * Measured on a real host before the agent grew sessions (audit 0021): a `fs.stat` on session B waited
+     * **3502 ms** behind eight long requests on session A, and **0.6 ms** when the window was not full.
+     */
+    readonly session?: string;
+}
+export {};
+//# sourceMappingURL=agent-protocol-client.d.ts.map