dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,418 @@
+/**
+ * 代理传输：把协议客户端适配成 {@link Transport}。
+ *
+ * 从原 3,388 行文件拆出（审计 0077）：协议层（帧 / 类型 / 客户端）已移到
+ * `agent-protocol-{frames,types,client}.ts`，本文件只剩**传输适配**——连接状态机、
+ * 能力探测、各方法的 RPC 调用、以及真实启动器。
+ *
+ * 兼容性：下面 re-export 三个协议模块，既有调用方（integration / wiring / tests）
+ * 从 `agent-transport.ts` 取符号的路径不变。
+ *
+ * @module dsh-over-ssh/infra/transport/agent-transport
+ */
+export * from './agent-protocol-frames.ts';
+export * from './agent-protocol-types.ts';
+export * from './agent-protocol-codec.ts';
+export * from './agent-protocol-errors.ts';
+export * from './agent-protocol-client.ts';
+import { type RemoteCapabilities } from '../../../domain/capability.ts';
+import { type ExecRequest, type ExecResult, type CopyFileRequest, type CopyTreeRequest, type CopyTreeOutcome, type PatchFileRequest, type PatchFileResult, type RemoteEnvResult, type ReadFileRangeRequest, type ReadFileRequest, type RemoteFileChunk, type RemoteStatResult, type RemoteWriteOutcome, type RemoveRequest, type RenameRequest, type Transport, type WriteFileRangeRequest, type WriteFileRequest } from '../transport.ts';
+import type { EditFileRequest, EditFileResult, HashFileRequest, HashFileResult, JobStdinRequest, JobStdinResult, MakeDirRequest, MakeDirResult, GlobPathsRequest, GlobPathsResult, RemovePathRequest, RenamePathRequest } from '../transport.ts';
+import { TransportBase } from '../transport-base.ts';
+import type { AgentLauncher, AgentTransportOptions, AgentIndexScanResult, AgentProcStartRequest, AgentJobStatus, AgentJobKill, AgentJobOutput, AgentLspStartRequest, AgentLspStatus, AgentLspRead, AgentIndexScanRequest, AgentSearchResult, AgentSearchGrepRequest, AgentWatchStartResult, AgentWatchStartRequest, AgentWatchPollResult, AgentWatchPollRequest, AgentWatchStopResult, AgentGitStatusResult, AgentCapabilities } from './agent-protocol-types.ts';
+export declare class AgentTransport extends TransportBase implements Transport {
+    #private;
+    readonly id: string;
+    constructor(options: AgentTransportOptions);
+    /**
+     * Session the agent echoed at handshake (`hello.result.sessionId`), or `undefined` when it sent none.
+     *
+     * `undefined` is the honest answer for an agent that predates sessions, and callers must not treat it as
+     * `"default"`: doing so would claim per-session isolation the agent never agreed to.
+     */
+    get negotiatedSessionId(): string | undefined;
+    /**
+     * Whether the agent said jobs outlive this connection (`hello.result.daemon`).
+     *
+     * `false` until a handshake says otherwise, because today's agent does tie job lifetime to the
+     * connection; assuming `true` would make callers skip the cleanup that is still required.
+     */
+    get daemon(): boolean;
+    /**
+     * The agent's own capability record (Tier 2 facts).
+     *
+     * `capabilities` is deliberately the Tier 1 shape, so the agent's extra bits (`watch`, `index`,
+     * `atomicWrite`, `landlock`, `exec`) would otherwise be dropped on the floor. Tier 2 callers must gate
+     * on **this** record: `watch !== 'native'` means no `watch.*`, and `exec !== true` means no `proc.exec`.
+     * Empty until the first handshake.
+     */
+    get agentCapabilities(): AgentCapabilities;
+    /** `uname` derived from the agent's `os`, or `undefined` when the agent reported nothing usable. */
+    get agentUname(): string | undefined;
+    /**
+     * Open the session and handshake. Idempotent and single-flight: concurrent callers share one attempt.
+     *
+     * @throws SshDevError `CONNECTION_LOST` when the handshake fails or the protocol version mismatches
+     *   (the only correct reaction is falling back to Tier 1), `CONNECTION_UNREACHABLE` when the session
+     *   cannot be started at all.
+     */
+    connect(signal?: AbortSignal): Promise<void>;
+    /**
+     * Close the session. Idempotent, and safe to call while connecting (the attempt is abandoned).
+     *
+     * A later `connect` opens a fresh session, so the transport is reusable after a disconnect.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Run one command through the agent.
+     *
+     * Protocol v1 has no arbitrary-command method, so there are exactly two paths:
+     *
+     *  - an injected {@link AgentExecCommand} (a deployment whose agent build does add one);
+     *  - otherwise the client asks `proc.exec` and maps `E_METHOD` onto `REMOTE_UNSUPPORTED` — an honest
+     *    "this agent version cannot run commands", never a silent fallback to the Tier 1 transport.
+     */
+    exec(request: ExecRequest, signal?: AbortSignal): Promise<ExecResult>;
+    /**
+     * Stat a path with the agent's own `fs.stat`, so the token is the **same one `fs.read` reports**.
+     *
+     * This is the member that closes the read→write token gap on Tier 2. `fs.stat` returns the agent's
+     * `Version{Size, MtimeNs}.String()` (`size:mtimeNs`), which is exactly what `fs.read` returns and exactly
+     * what `fs.write`'s `expectedVersion` guard compares against. Deriving a token here instead — or letting
+     * the caller fall back to a shell `stat -c '%Y'` — would produce seconds and make every guard mismatch.
+     *
+     * The agent's `version` string is passed through **untouched** rather than re-formatted locally: there is
+     * one token producer (the agent) and this is not a second one.
+     */
+    statPath(path: string, signal?: AbortSignal): Promise<RemoteStatResult>;
+    /**
+     * Read a remote file: `fs.read` (control frame) followed by its blob frame.
+     *
+     * The version token is the string the **agent** returned (`size:mtimeNs`), passed through untouched:
+     * re-deriving it locally would produce a token that no longer matches the guard the agent applies on
+     * the next write. Note this is *not* byte-identical to the Tier 1 `size:mtimeSeconds` token, because
+     * the agent reports nanoseconds (verified in its `Version.String()`); {@link statPath} exists so a caller
+     * can obtain the *same* Tier 2 token from a stat instead of comparing the two shapes.
+     */
+    readFile(request: ReadFileRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /**
+     * Write a remote file: `fs.write` (control frame, then one blob frame with the content).
+     *
+     * **The guard here is a version comparison, not a digest comparison.** Protocol v1's `fs.write` accepts
+     * `expectedVersion` and nothing else, so the guard is implemented as: `fs.stat` the target, refuse when the
+     * observed version differs from the caller's token, and otherwise pass that same version to the agent as
+     * `expectedVersion` so the agent re-checks it at write time (that is the compare-and-swap closing the race
+     * between our stat and our write). When the target does not exist, no version token can match, so the write
+     * is refused with `TRANSFER_CONFLICT` rather than overwriting blind.
+     *
+     * **Which field carries the token.** {@link WriteFileRequest.expectedVersion} is the explicit channel and
+     * wins when present. {@link WriteFileRequest.expectedSha256} is still accepted as a *version* token for
+     * callers written before the explicit field existed, and that legacy overloading is exactly what this
+     * transport used to do implicitly; the error details say `guard: 'version'` in both cases so a caller is
+     * never told a digest was verified when a version was.
+     *
+     * The alternative — refusing every guarded write with `REMOTE_UNSUPPORTED` — was rejected because the
+     * version round trip is available, cheap, and strictly safer than an unguarded overwrite.
+     */
+    writeFile(request: WriteFileRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * Offset read: the agent's own `fs.read` with `offset`.
+     *
+     * This used to borrow `proc.exec` (`tail -c +N | head -c M | base64`) because protocol v1's `fs.read` had no
+     * offset. The agent now serves `offset` natively (audit 0006), so the shell hop is gone: no `tail`/`head`/
+     * `base64` on the remote, no shell quoting, and the bytes are framed instead of base64-inflated (the old path
+     * asked for `2 * cap + 4096` bytes of headroom precisely because of that inflation).
+     *
+     * The agent's `truncated` already means "there is more after this window", so it is passed through rather
+     * than recomputed from `size - offset`.
+     */
+    readFileRange(request: ReadFileRangeRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /**
+     * Positioned write: `fs.write` with `offset` (the agent's `WriteAt`).
+     *
+     * This used to shell out (`dd of=… seek=… conv=notrunc`) because protocol v1's `fs.write` only replaced a
+     * whole file. The agent serves `offset` natively now (audit 0006), so the payload travels as a real blob
+     * frame instead of base64-on-stdin: no `dd`, no shell quoting, and no 4/3 size inflation. The agent owns the
+     * POSIX rules (offset 0 may create and keeps the tail, offset > 0 refuses a missing file) — see
+     * `WriteAt` in the agent, which is the single place those rules are written down.
+     */
+    writeFileRange(request: WriteFileRangeRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * {@inheritDoc Transport.copyFile}
+     *
+     * Throws `REMOTE_UNSUPPORTED` on an agent that predates `fs.copy`; the caller is expected to fall back to a
+     * relay it reports honestly, not to pretend the bytes stayed on the remote host.
+     */
+    copyFile(request: CopyFileRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * {@inheritDoc Transport.copyTree}
+     *
+     * One round trip for a whole tree. An agent that predates `recursive` answers E_PARAMS, which
+     * `#optionalRequest` surfaces as REMOTE_UNSUPPORTED so the caller can say "this agent is too old" instead
+     * of relaying the tree.
+     */
+    copyTree(request: CopyTreeRequest, signal?: AbortSignal): Promise<CopyTreeOutcome>;
+    /**
+     * `proc.forget`: drop a settled job from the connection's job list.
+     *
+     * The list otherwise only grows — a long session that starts dozens of jobs keeps every one of them
+     * forever, and `remote_job { action: "list" }` becomes noise. The agent refuses to forget a job that is
+     * still running, so this cannot lose track of live work.
+     */
+    procForget(id: string, signal?: AbortSignal): Promise<void>;
+    /** {@inheritDoc Transport.patchFile} — one round trip for every hunk, all-or-nothing. */
+    patchFile(request: PatchFileRequest, signal?: AbortSignal): Promise<PatchFileResult>;
+    /** {@inheritDoc Transport.probeEnv} — one round trip, cached on the agent side until `refresh`. */
+    probeEnv(refresh: boolean, signal?: AbortSignal): Promise<RemoteEnvResult>;
+    /** Move a path; a cross-device move fails instead of silently copying. */
+    /** {@inheritDoc Transport.editFile} — atomic in-place edit: one round trip, no file transfer. */
+    editFile(request: EditFileRequest, signal?: AbortSignal): Promise<EditFileResult>;
+    /** {@inheritDoc Transport.removePath} */
+    removePath(request: RemovePathRequest, signal?: AbortSignal): Promise<void>;
+    /** {@inheritDoc Transport.renamePath} */
+    renamePath(request: RenamePathRequest, signal?: AbortSignal): Promise<void>;
+    /** {@inheritDoc Transport.hashFile} */
+    hashFile(request: HashFileRequest, signal?: AbortSignal): Promise<HashFileResult>;
+    /** {@inheritDoc Transport.makeDir} */
+    makeDir(request: MakeDirRequest, signal?: AbortSignal): Promise<MakeDirResult>;
+    /** {@inheritDoc Transport.globPaths} */
+    globPaths(request: GlobPathsRequest, signal?: AbortSignal): Promise<GlobPathsResult>;
+    /** `proc.stdin` for the job layer: same call, job-shaped arguments (审计 0030). */
+    procStdin(id: string, data: string, close: boolean, signal?: AbortSignal): Promise<JobStdinResult>;
+    /** {@inheritDoc Transport.jobStdin} */
+    jobStdin(request: JobStdinRequest, signal?: AbortSignal): Promise<JobStdinResult>;
+    rename(request: RenameRequest, signal?: AbortSignal): Promise<void>;
+    /** Remove a file or (with `recursive`) a directory tree. */
+    remove(request: RemoveRequest, signal?: AbortSignal): Promise<void>;
+    /**
+     * Enumerate remote files for `@` completion: `index.scan`.
+     *
+     * Gated on `agentCapabilities.index === true` **before** anything is written; when the agent did not
+     * advertise indexing this throws `REMOTE_UNSUPPORTED` and leaves `agent.methods()` untouched, so a
+     * caller can fall back to Tier 1 without a wasted round trip.
+     *
+     * The returned numbers are **the agent's own report** (entry count, strategy, truncation); this client
+     * does not re-validate them, and an unrecognised `strategy` stays unrecognised (`"unknown"`).
+     *
+     * This is the **full** scan. When the agent has a snapshot from a previous scan it can refresh
+     * incrementally instead — see {@link scanIndexRefresh}, which is what a caller polling for `@` completion
+     * should use after the first scan.
+     *
+     * The agent's per-scan deadline is the request's `timeoutMs` (it has its own 5 s default); the *client's*
+     * deadline is the transport's `requestTimeoutMs`.
+     *
+     * @throws SshDevError `REMOTE_UNSUPPORTED` when the capability is absent, `REMOTE_COMMAND_FAILED`
+     *   (`E_PARAMS`) for an empty `roots`, `CANCELLED`/`CONNECTION_LOST` per the shared request rules.
+     */
+    scanIndex(request: AgentIndexScanRequest, signal?: AbortSignal): Promise<AgentIndexScanResult>;
+    /**
+     * Refresh the remote index **incrementally**: `index.refresh`.
+     *
+     * The agent keeps a bounded snapshot per (roots, caps) identity from the last scan and reuses the file
+     * listing of every directory whose mtime did not move, so a poll after the first scan costs
+     * `O(directories)` instead of `O(files)`. Measured on a synthetic 13-directory / 52-file tree:
+     * 65 syscalls → 13.
+     *
+     * **The agent's own report is what the caller gets.** When it cannot refresh safely (no snapshot yet,
+     * different roots, expired entry) it answers with a full scan and says so in `strategy`/`warnings` — this
+     * method never pretends an incremental answer was incremental.
+     *
+     * ## The boundary a caller must know
+     *
+     * A reused directory keeps the `size`/`mtimeNs` recorded at the last scan: a directory's mtime does not
+     * change when a file's **content** changes, only when its set of entries does. So this is right for
+     * `@` completion (which needs paths and kinds, and where added/removed/renamed files *are* picked up), and
+     * wrong for anything that needs current file sizes. Use {@link scanIndex} for that.
+     *
+     * @throws SshDevError same vocabulary as {@link scanIndex}. An agent predating `index.refresh` answers
+     *   `E_METHOD`, which maps to `REMOTE_UNSUPPORTED` — callers should treat that as "fall back to scanIndex".
+     */
+    scanIndexRefresh(request: AgentIndexScanRequest, signal?: AbortSignal): Promise<AgentIndexScanResult>;
+    /**
+     * Start a background command and return immediately: `proc.start`.
+     *
+     * The agent runs it in a job table and answers with an id; progress and output come from
+     * {@link procStatus} / {@link procOutput}. **Nothing is pushed** - v1's frame discipline (a control
+     * frame plus an optional blob frame, strictly paired, written by one goroutine) has no room for
+     * server-initiated frames, so the caller polls.
+     *
+     * Jobs die with the connection: the agent kills them all when the ssh channel closes. This is
+     * "reconnectable within one connection", not a durable task queue.
+     *
+     * @throws SshDevError `REMOTE_UNSUPPORTED` when the agent predates `proc.start` (`E_METHOD`).
+     */
+    procStart(request: AgentProcStartRequest, signal?: AbortSignal): Promise<AgentJobStatus>;
+    /**
+     * One job's state: `proc.status`.
+     *
+     * @throws SshDevError `REMOTE_NOT_FOUND` for an unknown (or already forgotten) id.
+     */
+    procStatus(id: string, signal?: AbortSignal, waitMs?: number): Promise<AgentJobStatus>;
+    /**
+     * Incremental output read: `proc.output`.
+     *
+     * `offset` is a **position, not a cursor**: pass `nextOffset` from the previous call to get only what is
+     * new. Re-reading an older offset re-sends that span (nothing is remembered as already read).
+     *
+     * The agent keeps a bounded ring buffer that drops the **oldest** bytes (errors tend to be at the end),
+     * so a result with `lost: true` means the requested span was already discarded - the caller must not
+     * treat it as continuous output.
+     */
+    procOutput(id: string, offset?: number, signal?: AbortSignal, waitMs?: number): Promise<AgentJobOutput>;
+    /** Terminate a job: `proc.kill`. Idempotent - an already-finished job answers `killed: false`. */
+    procKill(id: string, signal?: AbortSignal): Promise<AgentJobKill>;
+    /**
+     * End one session explicitly: kill its running jobs and drop its finished ones (`session.end`).
+     *
+     * With `--shared` (the default) a daemon keeps jobs alive across connections, so a session that
+     * simply goes away leaves its long-running commands behind — "survives reconnects" would silently
+     * become "leaks forever" (protocol.md §9.4). Callers end the session when it is genuinely over.
+     *
+     * Idempotent: an unknown or already-clean session reports `killed: 0, forgotten: 0`.
+     */
+    endSession(session?: string, signal?: AbortSignal): Promise<{
+        readonly session: string;
+        readonly killed: number;
+        readonly forgotten: number;
+        readonly lspStopped: number;
+    }>;
+    /** Every job this connection has started: `proc.list`. */
+    procList(signal?: AbortSignal): Promise<readonly AgentJobStatus[]>;
+    /**
+     * Host a language server: `lsp.start`.
+     *
+     * The agent is a **stdio pipe**, not an LSP implementation: it starts the process and moves bytes.
+     * `lspWrite` takes bytes (base64 on the wire) and `lspRead` pages the server's output by offset - the
+     * caller owns all JSON-RPC framing and semantics.
+     *
+     * @throws SshDevError `REMOTE_UNSUPPORTED` when the agent predates `lsp.start`.
+     */
+    lspStart(request: AgentLspStartRequest, signal?: AbortSignal): Promise<AgentLspStatus>;
+    /**
+     * Send bytes to a language server's stdin: `lsp.write`.
+     *
+     * 走**原生 blob 帧**（`blob: true`），不再把 LSP 帧 base64 塞进 `params.data`：base64 会让负载
+     * 膨胀 4/3，还要在两端各做一次编解码，而 didOpen/didChange 每次都要走这条路。代理侧
+     * `expectsBlob` 早就支持这个可选形态了，只是插件一直没发。
+     */
+    lspWrite(id: string, bytes: Uint8Array, signal?: AbortSignal): Promise<{
+        readonly id: string;
+        readonly written: number;
+        readonly state: string;
+    }>;
+    /** Read a language server's output from `offset`: `lsp.read`. Same offset semantics as {@link procOutput}. */
+    lspRead(id: string, offset?: number, signal?: AbortSignal): Promise<AgentLspRead>;
+    /** One language-server session's state: `lsp.status`. */
+    lspStatus(id: string, signal?: AbortSignal): Promise<AgentLspStatus>;
+    /** Terminate a language-server session: `lsp.stop` (closes stdin, then kills if it will not exit). */
+    lspStop(id: string, signal?: AbortSignal): Promise<AgentLspStatus>;
+    /**
+     * Release a **finished** language-server session's record and output buffer: `lsp.forget`.
+     *
+     * `lsp.stop` only ends the process; the agent keeps the session row and its output ring (up to 4 MiB) so a
+     * caller can still read the tail. Without this call that memory lives until the agent's own finish-cap
+     * evicts it (`MaxFinishedSessions` = 16 / 32 MiB), which on a long-lived connection is a lot of resident
+     * memory for sessions nobody will read again (audit 2026-11-01: `lsp.forget` had zero callers).
+     *
+     * @param id - the session id `lsp.start` returned.
+     * @throws SshDevError `REMOTE_UNSUPPORTED` when the agent predates the method (`E_METHOD`).
+     */
+    lspForget(id: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Enumerate the language-server sessions **the agent** is holding: `lsp.list`.
+     *
+     * Distinct from the registry's list, which answers "which servers do we have a client for". This one answers
+     * "what processes exist on the remote right now", including ones left by an earlier connection.
+     */
+    lspList(signal?: AbortSignal): Promise<readonly Record<string, unknown>[]>;
+    /**
+     * Bounded content search: `search.grep`, always available in protocol v1 (no capability bit gates it).
+     *
+     * `literal` defaults to the wire default (`true`); `ignoreCase` defaults to `true` and is written as
+     * the agent's inverted `caseSensitive` flag. Everything the caller omits is omitted from the frame, so
+     * the agent's own default applies — this client does not pre-fill values it cannot see the effect of.
+     *
+     * A regex that the *agent* cannot compile comes back as `E_PARAMS` → `REMOTE_COMMAND_FAILED`; v1 has no
+     * cancel frame, so a long search is bounded only by `timeoutMs` and the workload caps.
+     *
+     * @throws SshDevError `REMOTE_COMMAND_FAILED` for an empty `paths`/`query` (refused locally),
+     *   `REMOTE_UNSUPPORTED` when the agent answers `E_METHOD` (plugin/agent version mismatch).
+     */
+    searchGrep(request: AgentSearchGrepRequest, signal?: AbortSignal): Promise<AgentSearchResult>;
+    /**
+     * Start (or replace) the remote native watcher: `watch.start`.
+     *
+     * Requires `agentCapabilities.watch === 'native'`. `'poll'` (darwin/windows builds) and `'none'` are
+     * **not** enough: on those platforms the protocol answers `E_UNSUPPORTED`, and the intended Tier 1
+     * behaviour is polling by the plugin — so this method refuses locally with `REMOTE_UNSUPPORTED`.
+     *
+     * `watched` is the list of **roots** that were really registered — not every subdirectory — and
+     * `truncated` (not a thrown error) is how `maxWatches` / the kernel's `max_user_watches` report that
+     * only part of a tree is covered. Calling `start` while a watcher runs replaces it; a failed
+     * replacement leaves no watcher behind, because the old one is stopped first.
+     */
+    startWatch(request: AgentWatchStartRequest, signal?: AbortSignal): Promise<AgentWatchStartResult>;
+    /**
+     * Collect queued watch events: `watch.poll`.
+     *
+     * Since ADR-0009 the agent dispatches requests concurrently, so a poll no longer blocks the connection:
+     * a concurrent `fs.read`/`search.grep` proceeds and is answered as soon as the agent gets to it. The poll
+     * still *occupies one in-flight slot* for up to `timeoutMs`, so a loop of long polls can crowd the
+     * {@link DEFAULT_AGENT_MAX_IN_FLIGHT}-slot window; keep `timeoutMs` small and poll in a loop, or use a
+     * second connection when you need a dedicated watcher.
+     *
+     * Keep `timeoutMs` below the transport's `requestTimeoutMs` (default 15 s): the client deadline is a
+     * separate clock, and when it fires first the poll fails with `CONNECTION_LOST` even though the agent
+     * is healthy. `timeout: true` with few or no events is the normal "nothing happened" outcome, not an
+     * error; when `truncated` is true the remaining events are still queued, so poll again.
+     *
+     * `dropped` is **cumulative since `watch.start`**; a growing value (or `truncated`) means the event
+     * stream is incomplete and the honest reaction is a full `scanIndex` rescan.
+     */
+    pollWatch(request?: AgentWatchPollRequest, signal?: AbortSignal): Promise<AgentWatchPollResult>;
+    /**
+     * Stop one remote watcher: `watch.stop`. Idempotent, and stopping an absent watcher is **not** an
+     * error — the agent answers `{ "stopped": false }`, which is returned as-is.
+     *
+     * `watcherId` selects which watcher to stop; omit it for the agent's `"default"` watcher, which is what
+     * a caller that never sets one has always stopped. Stopping one id never touches another, so two
+     * sessions sharing a connection cannot stop each other's listener.
+     *
+     * The first parameter also still accepts an `AbortSignal` (the pre-`watcherId` signature), so a caller
+     * written against the old positional form keeps working instead of having its signal silently read as a
+     * watcher name. Prefer the explicit two-argument form.
+     *
+     * Unpolled events are discarded by the agent, so a caller that needs a consistent view must rescan
+     * rather than assume the queue survives the stop.
+     */
+    stopWatch(watcherId?: string | AbortSignal, signal?: AbortSignal): Promise<AgentWatchStopResult>;
+    /**
+     * Read one remote work tree's status: `git.status { root }` (task-20).
+     *
+     * Read-only and bounded on the agent side (5000 entries / 1 MiB of paths / 4 MiB of output / 10 s);
+     * `truncated` travels with the result instead of being a failure. An agent that predates this method answers
+     * `E_METHOD`, which {@link #rpc} translates to `REMOTE_UNSUPPORTED` — callers treat that as "no badges", not
+     * as an error.
+     *
+     * @param root - absolute remote path (a work tree root, or any path inside it).
+     * @param signal - caller cancellation (the agent kills the git child with the request context).
+     * @returns the normalized status.
+     */
+    gitStatus(root: string, signal?: AbortSignal): Promise<AgentGitStatusResult>;
+    /**
+     * Discover capabilities from the agent, cached like the other transports.
+     *
+     * The handshake already carries the capability record, so a fresh connection answers from cache;
+     * `maxAgeMs` (default 5 minutes) decides when to re-ask.
+     */
+    probeCapabilities(signal?: AbortSignal, maxAgeMs?: number): Promise<RemoteCapabilities>;
+}
+/**
+ * The real launcher: `ssh <alias> <agent> --stdio` through `node:child_process`.
+ *
+ * Only this function touches the process API; every test injects its own launcher. stdout carries
+ * protocol frames only (the agent writes diagnostics to stderr), so stderr is inherited for the
+ * operator and stdin is the pipe this client owns.
+ */
+export declare const defaultLauncher: AgentLauncher;
+//# sourceMappingURL=agent-transport.d.ts.map

package/lib/types/src/host/infra/transport/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-remote-workspace/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-protocol-client.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 代理协议的**客户端层**：请求/响应配对、在飞窗口、blob 通道与关闭时清场。
+ *
+ * 线上格式的读写移到 `agent-protocol-codec.ts`，错误与截止移到 `agent-protocol-errors.ts`
+ * （审计 0079）。本文件只剩状态机本身：发请求、配对响应、管理 blob 通道、关闭时清场。
+ *
+ * @module dsh-remote-workspace/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-remote-workspace/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 {@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