dsh-over-ssh 0.1.0 → 0.1.1

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

@@ -1,131 +0,0 @@
-/**
- * 代理协议的**编解码层**：请求参数压缩与响应结果读取。
- *
- * 从 `agent-protocol-client.ts` 拆出（审计 0079）。全部是纯函数——无 I/O、无类、无状态，
- * 因此可以脱离客户端单独测试。客户端只负责"发出去、等回来、配对"，
- * 把线上格式（ns→ms、缺省值、字符串枚举）留给这一层。
- *
- * @module dsh-remote-workspace/infra/transport/agent-protocol-codec
- */
-import { type ExecRequest } from './transport.ts';
-import type { AgentIndexEntry, AgentIndexScanResult, AgentProcStartRequest, AgentJobStatus, AgentJobOutput, AgentLspStartRequest, AgentLspStatus, AgentLspRead, AgentIndexScanRequest, AgentSearchMatch, AgentSearchResult, AgentWatchEvent, AgentWatchStartResult, AgentWatchPollResult, AgentWatchStopResult, AgentCapabilities, AgentHelloExtras } from './agent-protocol-types.ts';
-export declare const AGENT_MAX_JOB_WAIT_MS = 30000;
-/**
- * Add `waitMs` to a `proc.*` request only when it is positive.
- *
- * Omitted means "answer immediately", which is what an agent that predates the field does anyway —
- * so a client that never passes a wait is byte-for-byte the pre-long-poll request.
- *
- * @param params - the method's own parameters.
- * @param waitMs - requested server-side wait, or `undefined` for none.
- * @returns the parameters to send.
- */
-export declare function waitParams(params: Record<string, unknown>, waitMs: number | undefined): Record<string, unknown>;
-/**
- * Client deadline for a long-polled request.
- *
- * The server may legitimately block for `waitMs`, so the request budget must outlive it: a per-request
- * deadline here is **fatal** to the whole connection (see `isFatalAgentFailure`), so an under-sized
- * budget would turn a normal wait into a reconnect.
- *
- * @param waitMs - requested server-side wait, or `undefined` for none.
- * @returns the request budget, or `undefined` to keep the transport default.
- */
-export declare function waitBudget(waitMs: number | undefined): number | undefined;
-export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
-/** Read the `capabilities` object out of a `hello`/`capabilities` result, dropping wrong-typed fields. */
-export declare function readAgentCaps(result: Record<string, unknown> | undefined): AgentCapabilities | undefined;
-/** Read the `agent` object of a `hello` result. */
-export declare function readAgentExtras(result: Record<string, unknown> | undefined): AgentHelloExtras;
-/** Drop `undefined` request fields so a control frame stays minimal (and deterministic in tests). */
-export declare function compactParams(request: ExecRequest): Readonly<Record<string, unknown>>;
-/** Read a finite number field, or `null` when the agent sent nothing usable. */
-export declare function readOptionalNumber(source: Record<string, unknown>, key: string): number | null;
-/**
- * A boolean field, falling back only when the field is **absent**.
- *
- * `??`-style semantics rather than `||`: an explicit `false` from the agent is a real answer ("this stream
- * was not cut") and must not be replaced by the fallback. Using `||` here would silently convert every
- * `false` into the legacy value, which is exactly how a complete stderr gets reported as truncated.
- */
-export declare function booleanOr(value: unknown, fallback: boolean): boolean;
-/** A non-empty string field, else `undefined` (an empty spill path is not a readable path). */
-export declare function nonEmptyString(value: unknown): string | undefined;
-/**
- * Convert Unix nanoseconds from the wire into epoch milliseconds.
- *
- * @returns `null` when the agent sent nothing usable, so a caller can tell "no timestamp" apart from
- *   "the epoch". A negative value is passed through as a negative time rather than clamped.
- */
-export declare function nsToMs(value: number | null): number | null;
-/** Narrow a `proc.*` job status; unknown fields are dropped, missing numbers become 0. */
-export declare function readJobStatus(raw: unknown): AgentJobStatus;
-/** Narrow a `proc.output` result. */
-export declare function readJobOutput(raw: unknown): AgentJobOutput;
-/** Narrow an `lsp.*` session status. */
-export declare function readLspStatus(raw: unknown): AgentLspStatus;
-/** Narrow an `lsp.read` result. */
-export declare function readLspRead(raw: unknown): AgentLspRead;
-/**
- * Build the `proc.start` frame.
- *
- * Everything the caller omits is **omitted**, not defaulted: the agent's own defaults apply. The one
- * conversion is `stdinBytes` → base64, because the wire has no byte type.
- */
-export declare function compactProcParams(request: AgentProcStartRequest): Record<string, unknown>;
-/** Build the `lsp.start` frame, omitting what the caller did not set. */
-export declare function compactLspParams(request: AgentLspStartRequest): Record<string, unknown>;
-/** Narrow one `index.scan` entry (`{path,size,mtimeNs,isDir?}`); unknown fields are dropped. */
-export declare function readIndexEntry(value: unknown): AgentIndexEntry;
-/**
- * Narrow one `index.scan` result.
- *
- * Defaults follow the protocol: `strategy` `"unknown"` when the agent sent nothing usable (an unknown
- * strategy is *not* silently mapped onto a known one), `filesScanned` `0`, `warnings` empty, and
- * `truncated` `false` — the last one is the only optimistic default in this block, and it means
- * "the agent did not report truncation", not "the result is complete".
- */
-export declare function readIndexScanResult(value: unknown): AgentIndexScanResult;
-/** Narrow one `search.grep` match; `column` defaults to `0` and the context arrays to empty. */
-export declare function readSearchMatch(value: unknown): AgentSearchMatch;
-/**
- * Narrow one `search.grep` result.
- *
- * `dropped` is not a `search.grep` field in protocol v1; it is left at `0` and documented as
- * meaningless here rather than being invented from `truncated`.
- */
-export declare function readSearchResult(value: unknown): AgentSearchResult;
-/** Narrow one `watch.start` result; `watched` lists the **roots** the agent really registered. */
-export declare function readWatchStartResult(value: unknown): AgentWatchStartResult;
-/** Narrow one `watch.poll` event; `atNs` is converted to `atMs`. */
-export declare function readWatchEvent(value: unknown): AgentWatchEvent;
-/**
- * Narrow one `watch.poll` result.
- *
- * `dropped` is passed through untouched because it is **cumulative**; the client never derives a delta
- * from it (doing so would under-report drops exactly when the stream is already incomplete).
- */
-export declare function readWatchPollResult(value: unknown): AgentWatchPollResult;
-/** Narrow one `watch.stop` result; a missing `stopped` counts as `false`, which is not a failure. */
-export declare function readWatchStopResult(value: unknown): AgentWatchStopResult;
-/**
- * Drop `undefined` request fields so a control frame stays minimal (and deterministic in tests).
- *
- * The same rule is applied inline by `search.grep` / `watch.*`: an omitted option means "let the agent
- * use its own default", never "send this client's idea of the default". Only `index.scan` needs a helper
- * because it has more optional fields than the others put together.
- */
-export declare function compactIndexParams(request: AgentIndexScanRequest): Readonly<Record<string, unknown>>;
-/**
- * The agent transport: one stdio session, serialised requests, explicit degradation.
- *
- * Lifecycle matches the other two implementations (`idle` → `connecting` → `ready`, `lost` on an
- * unexpected death) so callers cannot tell them apart except through `id` and `capabilities`.
- */
-/**
- * Whether a plugin error means the frame stream can no longer be trusted.
- *
- * Only these close the connection: everything else (a missing file, a stale version, an unsupported
- * method) is a normal answered request and leaves the session healthy.
- */
-//# sourceMappingURL=agent-protocol-codec.d.ts.map

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

@@ -1,41 +0,0 @@
-/**
- * 代理协议的**错误与截止层**：错误归一、请求取消/超时、致命失败判定。
- *
- * 从 `agent-protocol-client.ts` 拆出（审计 0079）。客户端与传输层都需要"这个失败还要不要继续"，
- * 判定放在这里，避免两边各写一份。
- *
- * @module dsh-remote-workspace/infra/transport/agent-protocol-errors
- */
-import { SshDevError } from '../../domain/errors.ts';
-export declare function toSshDev(error: unknown, method: string): SshDevError;
-/** Internal marker: the caller's signal aborted while waiting. */
-export declare class RequestAbortedError extends Error {
-}
-/** Internal marker: the per-request deadline expired. */
-export declare class RequestTimeoutError extends Error {
-    readonly timeoutMs: number;
-    constructor(timeoutMs: number);
-}
-/**
- * Await `promise` under a deadline and an abort signal.
- *
- * The timer is always cleared and the abort listener always removed, so no path leaves a dangling
- * handle behind; the first settlement wins. `onTimeout` / `onAbort` let a caller name the error that
- * fits its context (a request deadline versus a missing blob frame).
- */
-export declare function withDeadlineAndAbort<T>(promise: Promise<T>, options: {
-    readonly signal?: AbortSignal;
-    readonly timeoutMs: number;
-    readonly method: string;
-    readonly onTimeout?: (timeoutMs: number) => Error;
-    readonly onAbort?: () => Error;
-}): {
-    readonly promise: Promise<T>;
-    readonly cancel: () => void;
-};
-/** Largest server-side wait the agent accepts for `proc.status` / `proc.output` (`waitMs`).
- *
- * Distinct from `MAX_JOB_WAIT_MS` in `remote-job-tools.ts`: that one is the **client's** overall wait budget
- * (10 min); this one is the **server's** single-request cap (30 s). */
-export declare function isFatalAgentFailure(error: SshDevError): boolean;
-//# sourceMappingURL=agent-protocol-errors.d.ts.map

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

@@ -1,197 +0,0 @@
-/**
- * 代理协议的**帧层**：常量、错误类型、JSON/Blob 帧编解码、流式解析器与错误映射。
- *
- * 从 `agent-transport.ts` 拆出（审计 0077）：这一层只关心字节与帧，不知道连接、会话或传输。
- * 边界由用户要求先定：**协议层（帧/类型/客户端）与传输适配层分开**。
- *
- * @module dsh-remote-workspace/infra/transport/agent-protocol-frames
- */
-import { SshDevError } from '../../domain/errors.ts';
-/**
- * The `agent` transport (Tier 2): the plugin side of the self-hosted Go remote agent.
- *
- * Why a third implementation exists at all: the zero-install floor (Tier 1: plain POSIX commands over
- * `ssh`) cannot provide native file watching, server-side indexing, or long tasks. The optional agent
- * binary adds them *without* becoming a requirement — when it is missing, outdated, or refuses the
- * handshake, the caller falls back to Tier 1 instead of degrading silently.
- *
- * Deployment constraints this module is written against:
- *
- *  - the agent is an **optional** single static binary (`doc/02-platform/zero-install-boundaries.md`);
- *  - it speaks only over the **stdio channel** of an `ssh` command (`ssh <alias> <agent> --stdio`),
- *    listening on no port (`doc/02-platform/remote-footprint.md`);
- *  - the wire protocol is a **single evolving spec** (`dsh-ssh-agent/doc/01-product/protocol.md`); there is no
- *    frozen/next split, so the frame codec below follows that file field by field instead of inventing a
- *    friendlier one — and when that file changes, this codec changes with it in the same round.
- *
- * Three consequences of the current wire shape are visible in this file and are **not** temporary
- * workarounds to be "cleaned up" later:
- *
- *  1. **there is no arbitrary command execution in the protocol's core surface.** The agent's method
- *     dispatch serves `proc.exec` only when the capability bit says so (verified by reading
- *     `internal/agent/server.go`), so {@link AgentTransport.exec} needs
- *     an injected {@link AgentExecCommand}; without one it asks `proc.exec` and turns `E_METHOD` into
- *     `REMOTE_UNSUPPORTED` with a message saying this agent version cannot run commands.
- *  2. **`fs.write` has `expectedVersion` but no digest.** The `Transport` contract's
- *     `expectedSha256` is therefore honoured as a *version* guard (stat, compare, then write with the
- *     same version as `expectedVersion`) — never as a digest guard — and that distinction is reported.
- *  3. **a control frame is paired with its blob by *order*, not by id.** ADR-0009 made the agent dispatch
- *     requests concurrently, so responses may arrive out of order; what the agent still guarantees is
- *     that a response and the blob it declared are written back-to-back inside one critical section. Blob
- *     frames therefore arrive in the same order as the responses that declared them, which is what lets
- *     this client pipeline up to {@link DEFAULT_AGENT_MAX_IN_FLIGHT} requests while pairing each blob with
- *     its own request (see {@link AgentProtocolClient}).
- *
- * No third-party dependency is involved: the session is injected (`AgentLauncher`), so every unit test
- * runs against an in-memory fake and `node:child_process` is only reached by {@link defaultLauncher}.
- *
- * @module dsh-remote-workspace/infra/transport/agent-transport
- */
-/** Protocol version this client speaks; must equal the agent's `protocol.ProtocolVersion`. */
-export declare const AGENT_PROTOCOL_VERSION = 1;
-/** Client identifier sent in `hello.params.client`; diagnostic only, the agent never branches on it. */
-export declare const AGENT_CLIENT_ID = "dsh-remote-workspace/0.1.0";
-/** Single-frame payload ceiling, mirrored from the agent's `protocol.MaxFrameBytes` (16 MiB). */
-export declare const MAX_AGENT_FRAME_BYTES: number;
-/** Frame kind byte: control frame carrying one JSON request or one JSON response. */
-export declare const AGENT_KIND_JSON = 74;
-/** Frame kind byte: binary data frame (file content), sent only after a blob-declaring control frame. */
-export declare const AGENT_KIND_BLOB = 66;
-/**
- * The watcher name the agent uses when a caller omits `watcherId`.
- *
- * Mirrors the agent's `watch.DefaultWatcherID`. Kept client-side so a result from an agent that predates
- * the `watcherId` echo still reports which watcher it actually touched (that agent had exactly one).
- */
-export declare const DEFAULT_AGENT_WATCHER_ID = "default";
-/** Default per-request deadline used when the caller names none. */
-export declare const DEFAULT_AGENT_REQUEST_TIMEOUT_MS = 15000;
-/**
- * How many requests the client may keep in flight on one connection.
- *
- * Mirrors the agent's own `MaxInFlightRequests` (8): the agent acquires one slot per request *in its read
- * goroutine*, so sending more than that would stall its reads instead of buying throughput. Staying at the
- * agent's limit keeps the pipeline full without ever blocking the peer's reader.
- */
-export declare const DEFAULT_AGENT_MAX_IN_FLIGHT = 8;
-/**
- * Default agent mode flag.
- *
- * `--shared` lets one resident agent process serve many sessions (shared jobs / LSP / index snapshots)
- * and falls back to the in-process loop when a daemon is unavailable. `--stdio` pins the old
- * one-process-per-connection behaviour, which tests and diagnostics still use.
- */
-export declare const DEFAULT_AGENT_MODE = "--shared";
-/** The pinned in-process mode (one agent process per connection). */
-export declare const STDIO_AGENT_MODE = "--stdio";
-/** A structured failure reported by the agent (or synthesised by this client). */
-export declare class AgentProtocolError extends Error {
-    readonly code: string;
-    readonly details: Readonly<Record<string, unknown>>;
-    constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>);
-}
-/**
- * The narrow view of one agent session this module needs.
- *
- * Deliberately tiny so a fake is trivial and so the module never touches `node:child_process` itself:
- * `onData` delivers stdout bytes **in arrival order** (frame boundaries are not preserved), `onExit`
- * fires once when the remote process is gone.
- */
-export interface AgentFrame {
-    /** Kind byte: {@link AGENT_KIND_JSON} or {@link AGENT_KIND_BLOB}. */
-    readonly kind: number;
-    /** Payload bytes, copied out of the transport buffer. */
-    readonly payload: Uint8Array;
-}
-/** One encoded frame, split into its two written halves. */
-export interface EncodedFrame {
-    /** The 5-byte `[kind][uint32 BE length]` header. */
-    readonly header: Uint8Array;
-    /** The payload (`header[4]` is its length). */
-    readonly payload: Uint8Array;
-}
-/**
- * Encode one frame: `[1B kind][4B BE length][payload]`.
- *
- * @throws AgentProtocolError `E_PROTOCOL` for an unknown kind byte.
- * @throws AgentProtocolError `E_TOO_LARGE` when the payload exceeds {@link MAX_AGENT_FRAME_BYTES}.
- */
-export declare function encodeFrame(kind: number, payload: Uint8Array): EncodedFrame;
-/** Encode one complete frame (header immediately followed by payload). */
-export declare function encodeFrameBytes(kind: number, payload: Uint8Array): Uint8Array;
-/**
- * Decode exactly one frame from the head of `bytes`.
- *
- * @returns the frame plus `consumed` (header + payload) bytes, or `null` when the buffer holds only
- *   part of a frame — callers keep the remainder and retry, which is how a chunked stream is framed.
- * @throws AgentProtocolError `E_PROTOCOL` for an illegal kind byte; `E_TOO_LARGE` when the declared
- *   length exceeds the ceiling (rejected before allocating, exactly like the agent's own reader).
- */
-export declare function decodeFrame(bytes: Uint8Array): {
-    readonly frame: AgentFrame;
-    readonly consumed: number;
-} | null;
-/**
- * Incremental frame decoder over a byte stream that arrives in arbitrary chunks.
- *
- * **Why it keeps a read cursor instead of trimming the buffer on every frame.** The obvious implementation
- * (`buffer = concat(buffer, chunk)` then `buffer = buffer.slice(consumed)` per frame) re-copies the whole
- * remaining payload once per chunk *and* once per frame, so a body that arrives in many small pieces costs
- * O(bytes x pieces). Measured on this repository: an 8 MiB blob delivered in 64 KiB chunks spent **142 ms**
- * of synchronous main-thread time versus **5.1 ms** when it arrived in one piece (audit 0043) — and doubling
- * the number of chunks doubled the cost, which is the signature of the quadratic term. Every one of those
- * milliseconds is a stalled event loop, i.e. a stalled GUI.
- *
- * Two changes were needed, and the measurement is what proved the first one alone was **not** enough:
- *
- *  1. the frame loop reads through a window (`#start`/`#end` over one store) instead of copying the remainder
- *     per frame;
- *  2. the store grows **geometrically** (doubling) instead of being reallocated at exactly `pending + chunk`
- *     on every chunk.
- *
- * (1) alone still measured 126 ms: an exactly-sized `Uint8Array` per 64 KiB chunk copies the whole body every
- * time, so the cost stays O(bytes x chunks). With both, the same 8 MiB body measured **9.3 ms** and the cost
- * became flat in the chunk size (9.3 / 10.3 / 7.3 / 5.5 ms for 64 KiB … 8 MiB chunks) — linear, where before
- * doubling the chunk count doubled the time. Both changes matter; neither is sufficient alone.
- */
-export declare class AgentFrameParser {
-    #private;
-    /**
-     * Feed one chunk; returns every frame that became complete, in arrival order.
-     *
-     * @param chunk - the bytes that just arrived; any split point is legal.
-     * @returns the complete frames, in arrival order.
-     */
-    push(chunk: Uint8Array): readonly AgentFrame[];
-    /** Bytes retained for an incomplete frame (0 when the stream is aligned). */
-    get pendingBytes(): number;
-}
-/**
- * Map an agent error code onto a plugin error code.
- *
- * Centralised on purpose: this table is part of the contract with the agent, and every entry is
- * asserted by `tests/agent-transport.test.ts`.
- *
- * Two entries deserve their reasoning stated:
- *
- *  - `E_HANDSHAKE` / `E_PROTOCOL` mean "this stream cannot be trusted" (wrong protocol version, frames
- *    out of order), so they surface as `CONNECTION_LOST`: the connection is unusable, not the request.
- *  - `E_TOO_LARGE` is **one code with two meanings**, so it is mapped by `details.scope`:
- *    a **size** limit (`scope: "size"`, or absent on an older agent) becomes `REMOTE_UNSUPPORTED`
- *    because v1 has no chunked read to fall back on — the request itself is too big;
- *    a **capacity** limit (`scope: "session" | "job" | "lsp" | "watcher"`) becomes
- *    `REMOTE_COMMAND_FAILED`, because nothing is wrong with the request — the remote is momentarily
- *    full and retrying later is the right move.
- *
- *    Why the split matters: mapping capacity exhaustion to `REMOTE_UNSUPPORTED` used to make it reach
- *    the filesystem layer as `FS_NOT_REGULAR_FILE` ("this is not a regular file"), which points a
- *    caller at the wrong thing entirely. Measured end to end (`.verify/stage8-too-large-conflation.mjs`):
- *    200 slow requests on one session ⇒ 128 rejected with `E_TOO_LARGE` + `scope: "session"` ⇒
- *    surfaced as `FS_NOT_REGULAR_FILE`.
- *
- * An unrecognised code (a newer agent) is reported as `REMOTE_COMMAND_FAILED` with the original code
- * kept in `details.agentCode`, so a new agent error is never silently mistranslated into a known one.
- */
-export declare function agentErrorToSshDev(error: AgentProtocolError, connectionId: string): SshDevError;
-/** Client-side default for `index.scan` `maxEntries`; mirrors the agent's `index.DefaultMaxEntries`. */
-//# sourceMappingURL=agent-protocol-frames.d.ts.map