dsh-over-ssh 0.1.0 → 0.2.0

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

@@ -1,41 +0,0 @@
-/**
- * 代理协议的**错误与截止层**：错误归一、请求取消/超时、致命失败判定。
- *
- * 从 `agent-protocol-client.ts` 拆出（审计 0079）。客户端与传输层都需要"这个失败还要不要继续"，
- * 判定放在这里，避免两边各写一份。
- *
- * @module dsh-over-ssh/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/agent-protocol-frames.d.ts

@@ -1,197 +0,0 @@
-/**
- * 代理协议的**帧层**：常量、错误类型、JSON/Blob 帧编解码、流式解析器与错误映射。
- *
- * 从 `agent-transport.ts` 拆出（审计 0077）：这一层只关心字节与帧，不知道连接、会话或传输。
- * 边界由用户要求先定：**协议层（帧/类型/客户端）与传输适配层分开**。
- *
- * @module dsh-over-ssh/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-over-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-over-ssh/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-over-ssh/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