dsh-over-ssh 0.1.0 → 0.2.0

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

@@ -1,239 +0,0 @@
-/**
- * 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

@@ -1,52 +0,0 @@
-/**
- * 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

@@ -1,77 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * 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-protocol-client.d.ts

@@ -1,132 +0,0 @@
-/**
- * 代理协议的**客户端层**：请求/响应配对、在飞窗口、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

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

@@ -1,140 +0,0 @@
-/**
- * 代理协议的**编解码层**：请求参数压缩与响应结果读取。
- *
- * 从 `agent-protocol-client.ts` 拆出（审计 0079）。全部是纯函数——无 I/O、无类、无状态，
- * 因此可以脱离客户端单独测试。客户端只负责"发出去、等回来、配对"，
- * 把线上格式（ns→ms、缺省值、字符串枚举）留给这一层。
- *
- * @module dsh-over-ssh/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, AgentGitStatusResult, 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 `git.status` result.
- *
- * Unknown `status` values and empty paths are **dropped**, not coerced: the consumer draws a badge per entry,
- * and a made-up status would be a claim the agent never made (the UI rule is "unknown status → no badge").
- * A missing `changes` array reads as empty, and a non-boolean `truncated` reads as `false` — claiming
- * truncation would tell the caller to rescan for no reason.
- */
-export declare function readGitStatusResult(value: unknown): AgentGitStatusResult;
-/** 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