dsh-over-ssh 0.1.0 → 0.2.0

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

@@ -1,509 +0,0 @@
-/**
- * 代理协议的**类型层**：会话/启动器抽象、协议方法请求与响应 DTO、各类默认上限、能力映射。
- *
- * 从 `agent-transport.ts` 拆出（审计 0077）。放在帧层之上、客户端之下：客户端与传输适配器
- * 都需要这些类型，若留在任一侧都会形成环。
- *
- * @module dsh-remote-workspace/infra/transport/agent-protocol-types
- */
-import { type RemoteCapabilities } from '../../domain/capability.ts';
-import { type ExecRequest, type ExecResult } from './transport.ts';
-export interface AgentSession {
-    /** Send bytes to the agent's stdin. */
-    write(bytes: Uint8Array): void;
-    /** Observe stdout bytes. Called once at most; the session keeps ownership of its own handlers. */
-    onData(callback: (chunk: Uint8Array) => void): void;
-    /** Observe the remote process's exit. Called once at most. */
-    onExit(callback: (code: number | null) => void): void;
-    /** Terminate the session; safe to call more than once. */
-    close(): void;
-}
-/** Options handed to a launcher. Kept inert so tests can assert on the launch shape. */
-export interface AgentSessionOptions {
-    /** ssh alias (or `user@host`) that carries the user's own ssh configuration. */
-    readonly alias: string;
-    /** Remote command line for the agent; defaults to `<agentPath> --stdio`. */
-    readonly remoteCommand: string;
-    /** `ssh` argv *without* the remote command, e.g. `['ssh','-T','-o','BatchMode=yes','gpu01']`. */
-    readonly sshArgv: readonly string[];
-    /**
-     * Extra environment for the `ssh` child, merged over the parent's.
-     *
-     * Carries the askpass wiring for password connections (`askpass.ts`): the agent session must authenticate
-     * exactly like the ladder that installed it, so a password connection needs the helper here too.
-     */
-    readonly env?: Record<string, string>;
-    /** Cancellation for the launch itself. */
-    readonly signal?: AbortSignal;
-}
-/** Opens one agent session; injected so tests never start a process. */
-export type AgentLauncher = (options: AgentSessionOptions) => Promise<AgentSession>;
-/** Run one remote command through the agent. Injected: protocol v1 has no command-execution method. */
-export type AgentExecCommand = (request: ExecRequest, signal?: AbortSignal) => Promise<ExecResult>;
-/** Construction options for {@link AgentTransport}. */
-export interface AgentTransportOptions {
-    /** Connection id (also the pool key). */
-    readonly connectionId: string;
-    /** Session factory; defaults to {@link defaultLauncher} (real `ssh` over `node:child_process`). */
-    readonly launch?: AgentLauncher;
-    /** `ssh` argv *without* the remote command. Used by the default launcher. */
-    readonly sshArgv?: readonly string[];
-    /** Extra environment for the `ssh` child that carries the session; see {@link AgentSessionOptions.env}. */
-    readonly env?: Record<string, string>;
-    /** Remote path of the agent binary; used by the default launcher. */
-    readonly agentPath?: string;
-    /** Extra argv inserted after the agent path (before the mode flag). */
-    readonly agentArgs?: readonly string[];
-    /**
-     * Mode flag handed to the agent: {@link DEFAULT_AGENT_MODE} (`--shared`, prefer a resident daemon)
-     * or {@link STDIO_AGENT_MODE} (`--stdio`, one process per connection).
-     *
-     * `--shared` is the default because it is what makes "one agent process serving many sessions" real:
-     * jobs, LSP sessions and index snapshots are shared instead of duplicated per connection. The agent
-     * falls back to `--stdio` on its own when no daemon can run, so this does not remove the Tier 2
-     * capability on hosts where the daemon is unavailable.
-     */
-    readonly agentMode?: string;
-    /** Command runner for {@link AgentTransport.exec}; see the module note about protocol v1. */
-    readonly execCommand?: AgentExecCommand;
-    /** Method name used by the default {@link AgentTransport.exec}; defaults to `proc.exec`. */
-    readonly execMethod?: string;
-    /** Deadline applied to one request when the caller names none. Default 15 s. */
-    readonly requestTimeoutMs?: number;
-    /**
-     * How many requests may be in flight on this connection. Defaults to
-     * {@link DEFAULT_AGENT_MAX_IN_FLIGHT} (8), which mirrors the agent's own limit; set `1` to restore the
-     * old strictly serial behaviour.
-     */
-    readonly maxInFlight?: number;
-    /** Client identifier sent in `hello`; defaults to {@link AGENT_CLIENT_ID}. */
-    readonly clientId?: string;
-    /**
-     * Default session for every request on this connection (`hello.params.sessionId`).
-     *
-     * Omitted means the field is not sent at all, so the agent uses its own `"default"` and this connection
-     * behaves exactly as it did before sessions existed. Set it when several logical sessions share one
-     * connection: the agent then gives each its own share of the in-flight window, which is what stops one
-     * session's long request from queueing another's short one (audit 0021: 3502 ms → 0.7 ms).
-     */
-    readonly sessionId?: string;
-    /** Injectable clock (diagnostics and duration measurement). */
-    readonly now?: () => number;
-}
-/** One decoded frame. */
-export declare const DEFAULT_INDEX_MAX_ENTRIES = 20000;
-/** Client-side default for `index.scan` `maxDepth`; mirrors the agent's `index.DefaultMaxDepth`. */
-export declare const DEFAULT_INDEX_MAX_DEPTH = 12;
-/** Client-side default for `index.scan` / `search.grep` `timeoutMs` (agent: 5000 ms). */
-export declare const DEFAULT_INDEX_TIMEOUT_MS = 5000;
-/** Client-side default for `search.grep` `maxResults`; mirrors the agent's `search.DefaultMaxResults`. */
-export declare const DEFAULT_SEARCH_MAX_RESULTS = 1000;
-/** Client-side default for `search.grep` `maxFileBytes` (agent: 8 MiB). */
-export declare const DEFAULT_SEARCH_MAX_FILE_BYTES: number;
-/** Client-side default for `search.grep` `maxBytesScanned` (agent: 512 MiB). */
-export declare const DEFAULT_SEARCH_MAX_BYTES_SCANNED: number;
-/** Client-side default for `search.grep` `maxLineBytes` (agent: 1 MiB). */
-export declare const DEFAULT_SEARCH_MAX_LINE_BYTES: number;
-/** Client-side default for `watch.start` `maxWatches`; mirrors the agent's `watch.DefaultMaxWatches`. */
-export declare const DEFAULT_WATCH_MAX_WATCHES = 4096;
-/** Client-side default for `watch.start` `debounceMs`; mirrors the agent's `watch.DefaultDebounceMs`. */
-export declare const DEFAULT_WATCH_DEBOUNCE_MS = 150;
-/** Client-side default for `watch.poll` `timeoutMs`; mirrors the agent's `watch.DefaultPollTimeoutMs`. */
-export declare const DEFAULT_WATCH_POLL_TIMEOUT_MS = 1000;
-/** Client-side default for `watch.poll` `maxEvents`; mirrors the agent's `watch.DefaultMaxEvents`. */
-export declare const DEFAULT_WATCH_MAX_EVENTS = 256;
-/** One indexed file (`index.scan` `entries[i]`). */
-export interface AgentIndexEntry {
-    /** Absolute remote path. */
-    readonly path: string;
-    /** File size in bytes as reported by the agent (`size`). */
-    readonly size: number;
-    /**
-     * Modification time in **milliseconds** since the epoch, converted from the agent's `mtimeNs`.
-     * `null` when the agent sent no usable `mtimeNs`.
-     */
-    readonly mtimeMs: number | null;
-    /**
-     * Whether the entry is a directory. v1's `index.scan` enumerates **files only** and sends no `isDir`,
-     * so this is `false` unless a future agent adds the field.
-     */
-    readonly isDir: boolean;
-}
-/** Result of {@link AgentTransport.scanIndex} (`index.scan`). */
-export interface AgentIndexScanResult {
-    /** Entries in the order the agent returned them (the agent sorts by path). */
-    readonly entries: readonly AgentIndexEntry[];
-    /** `"git-ls-files"` / `"find-bounded"` as reported; `"unknown"` when the agent sent nothing usable. */
-    readonly strategy: string;
-    /** True when any of the four bounds (entries / depth / excludes / deadline) fired. */
-    readonly truncated: boolean;
-    /** Files enumerated (`scanned` on the wire); `0` when absent. */
-    readonly filesScanned: number;
-    /** Per-root problems the agent chose not to fail on (`warnings`); empty when absent. */
-    readonly warnings: readonly string[];
-    /** Agent-side duration in ms, or `null` when absent. */
-    readonly durationMs: number | null;
-}
-/** {@link AgentTransport.procStart} request. Mirrors the agent's `proc.exec` fields plus an output cap. */
-export interface AgentProcStartRequest {
-    /** A command line; exactly one of `argv`/`script` must be given (the agent refuses both). */
-    readonly argv?: readonly string[];
-    /** A shell script, run via `/bin/sh -c` (POSIX) or `cmd /c` (Windows). */
-    readonly script?: string;
-    readonly cwd?: string;
-    readonly env?: Readonly<Record<string, string>>;
-    /** Text written to stdin, then closed. Mutually exclusive with `stdinBytes`. */
-    readonly stdin?: string;
-    /** Bytes written to stdin, then closed (base64 on the wire). Mutually exclusive with `stdin`. */
-    readonly stdinBytes?: Uint8Array;
-    /** Keep the stdin pipe open so `proc.stdin` can append input later (审计 0030). */
-    readonly interactive?: boolean;
-    /**
-     * Kill the job after this long. **0 or absent means no limit** - unlike `proc.exec`, where a missing
-     * timeout means the agent's default.
-     */
-    readonly timeoutMs?: number;
-    /** Retained output cap (the agent's ring buffer drops the oldest bytes past it). */
-    readonly maxOutputBytes?: number;
-    /**
-     * Landlock write fence: when non-empty the job may only write under these roots.
-     * The agent refuses with `REMOTE_UNSUPPORTED` when it cannot build the fence rather than running unfenced.
-     */
-    readonly writeRoots?: readonly string[];
-}
-/** One background job (`proc.start` / `proc.status` / `proc.list`). */
-export interface AgentJobStatus {
-    readonly id: string;
-    /** `running` / `exited` / `killed` / `failed`. */
-    readonly state: string;
-    readonly command: string;
-    readonly pid?: number;
-    readonly exitCode: number;
-    readonly signal?: string;
-    readonly timedOut: boolean;
-    readonly startedMs: number;
-    readonly durationMs: number;
-    readonly outputBytes: number;
-    /** Bytes dropped from the **oldest** end of the ring buffer; non-zero means the output has a hole. */
-    readonly droppedBytes: number;
-}
-/** {@link AgentTransport.procKill} result. `killed: false` for a job that had already finished. */
-export interface AgentJobKill {
-    readonly id: string;
-    readonly killed: boolean;
-    readonly state: string;
-}
-/** {@link AgentTransport.procOutput} result. */
-export interface AgentJobOutput {
-    readonly id: string;
-    readonly state: string;
-    readonly data: string;
-    /** Pass this as the next `offset` to get only what is new. */
-    readonly nextOffset: number;
-    readonly droppedBytes: number;
-    readonly totalBytes: number;
-    /** True when the requested span was already dropped: `data` is not continuous output. */
-    readonly lost: boolean;
-    readonly exitCode: number;
-    readonly signal?: string;
-    readonly timedOut: boolean;
-}
-/** {@link AgentTransport.lspStart} request. */
-export interface AgentLspStartRequest {
-    /** The language server executable (a name on PATH or an absolute path). */
-    readonly command: string;
-    readonly args?: readonly string[];
-    /** Working directory - language servers use it to find project config, so it matters. */
-    readonly cwd?: string;
-    readonly env?: Readonly<Record<string, string>>;
-    readonly maxOutputBytes?: number;
-}
-/** One language-server session (`lsp.start` / `lsp.status` / `lsp.stop`). */
-export interface AgentLspStatus {
-    readonly id: string;
-    readonly command: string;
-    /** `running` / `exited`. */
-    readonly state: string;
-    readonly pid?: number;
-    readonly exitCode: number;
-    readonly startedMs: number;
-    readonly durationMs: number;
-    readonly outputBytes: number;
-    readonly droppedBytes: number;
-    readonly wroteBytes: number;
-    /**
-     * Session that owns this language server (ADR-0011).
-     *
-     * With `--shared` the agent's LSP session table is **one global table per daemon** - deliberately,
-     * because language servers are memory-heavy and one process per connection fights the "low memory"
-     * goal. Sharing is why `lsp.list`/`lsp.read` can see another session's server, and ownership is why
-     * `lsp.stop`/`lsp.forget` cannot touch it: an ownerless kill would leave the victim unable to tell
-     * what happened (it only sees `exited`). Absent on agents that predate ADR-0011.
-     */
-    readonly session?: string;
-}
-/** {@link AgentTransport.lspRead} result. */
-export interface AgentLspRead {
-    readonly id: string;
-    /** Raw LSP bytes (a `Content-Length`-framed JSON-RPC stream) - the agent does not parse them. */
-    readonly data: string;
-    readonly nextOffset: number;
-    readonly state: string;
-    readonly droppedBytes: number;
-    readonly totalBytes: number;
-    readonly lost: boolean;
-}
-/** {@link AgentTransport.scanIndex} request. Untyped fields are omitted from the frame, not defaulted. */
-export interface AgentIndexScanRequest {
-    /** Absolute remote roots. Empty is a local `REMOTE_COMMAND_FAILED` (`E_PARAMS` on the wire). */
-    readonly roots: readonly string[];
-    /** Entry ceiling; the agent applies {@link DEFAULT_INDEX_MAX_ENTRIES} when omitted or non-positive. */
-    readonly maxEntries?: number;
-    /** Depth ceiling; the agent applies {@link DEFAULT_INDEX_MAX_DEPTH} when omitted or non-positive. */
-    readonly maxDepth?: number;
-    /** Directory names to skip; omitted means the agent's built-in noise table. */
-    readonly exclude?: readonly string[];
-    /** Agent-side deadline; the agent applies {@link DEFAULT_INDEX_TIMEOUT_MS} when omitted or non-positive. */
-    readonly timeoutMs?: number;
-    /** `false` forces the standard-library walk (the agent's `preferGit`, diagnostic escape hatch). */
-    readonly preferGit?: boolean;
-}
-/** One content match (`search.grep` `matches[i]`). */
-export interface AgentSearchMatch {
-    /** Absolute remote path. */
-    readonly path: string;
-    /** 1-based line number as reported. */
-    readonly line: number;
-    /** 1-based column as reported; `0` when the agent sent no column (it does send one today). */
-    readonly column: number;
-    /** The matched line's text, exactly as the agent sent it. */
-    readonly text: string;
-    /** Context lines before the match (`before`); empty when absent. */
-    readonly before: readonly string[];
-    /** Context lines after the match (`after`); empty when absent. */
-    readonly after: readonly string[];
-}
-/** Result of {@link AgentTransport.searchGrep} (`search.grep`). */
-export interface AgentSearchResult {
-    /** Matches, in the agent's order (path → line → column). */
-    readonly matches: readonly AgentSearchMatch[];
-    /** `"in-process"` / `"ripgrep"` as reported; `"unknown"` when the agent sent nothing usable. */
-    readonly strategy: string;
-    /** True when any workload bound (results / bytes / deadline / file size) cut the scan short. */
-    readonly truncated: boolean;
-    /**
-     * **Cumulative** events dropped since `watch.start` (`dropped` on the wire). On `search.grep` the
-     * agent reports no such field, so it is `0`; it exists here only for wire-shape symmetry with
-     * {@link AgentWatchPollResult} — do not read it as "matches lost".
-     */
-    readonly dropped: number;
-    /** Files actually opened (`filesScanned`); `0` when absent. */
-    readonly filesScanned: number;
-    /** Bytes actually read (`bytesScanned`); `0` when absent. */
-    readonly bytesScanned: number;
-    /** Non-fatal problems (`warnings`); empty when absent. */
-    readonly warnings: readonly string[];
-    /** Agent-side duration in ms, or `null` when absent. */
-    readonly durationMs: number | null;
-    /**
-     * Which workload bounds cut the scan short (`truncatedReasons`), de-duplicated by the agent.
-     *
-     * Values are `maxResults` / `bytesScanned` / `maxFileBytes` / `timeout` / `maxEntries`. The list is kept
-     * **verbatim**: a newer agent may name a bound this client does not know, and dropping it would report a
-     * truncated scan as an untruncated one. Empty when the agent sent nothing.
-     */
-    readonly truncatedReasons: readonly string[];
-    /**
-     * Candidate files the request's `include` filters removed, or `undefined` when the agent did not say.
-     *
-     * `undefined` and `0` are different facts: `0` means "the filters removed nothing", `undefined` means "this
-     * agent cannot tell you". Reading a missing field as `0` would invent the first from the second.
-     */
-    readonly filesFiltered: number | undefined;
-}
-/**
- * {@link AgentTransport.searchGrep} request.
- *
- * Note the one place this API deliberately does **not** mirror the wire: the agent's field is
- * `caseSensitive` (default `false` = case-insensitive), and this option is its inverse
- * (`ignoreCase`, default `true`). The mapping is explicit in {@link AgentTransport.searchGrep}, so
- * callers never have to remember which way the flag points.
- */
-export interface AgentSearchGrepRequest {
-    /** Absolute remote roots (files or directories). Empty is refused locally with `REMOTE_COMMAND_FAILED`. */
-    readonly paths: readonly string[];
-    /** Literal or Go regular expression, depending on `literal`. Empty is a local `REMOTE_COMMAND_FAILED`. */
-    readonly query: string;
-    /** `true` (default on the wire) means literal substring matching; `false` means Go regexp. */
-    readonly literal?: boolean;
-    /** Case-insensitive matching; **default `true`**, inverted onto the wire's `caseSensitive`. */
-    readonly ignoreCase?: boolean;
-    /** Result ceiling; the agent applies {@link DEFAULT_SEARCH_MAX_RESULTS} when omitted or non-positive. */
-    readonly maxResults?: number;
-    /** Whole-request byte ceiling; agent default {@link DEFAULT_SEARCH_MAX_BYTES_SCANNED}. */
-    readonly maxBytesScanned?: number;
-    /** Per-file byte ceiling; agent default {@link DEFAULT_SEARCH_MAX_FILE_BYTES}. */
-    readonly maxFileBytes?: number;
-    /** Per-line byte ceiling; agent default {@link DEFAULT_SEARCH_MAX_LINE_BYTES}. */
-    readonly maxLineBytes?: number;
-    /** Agent-side deadline; agent default {@link DEFAULT_INDEX_TIMEOUT_MS}. */
-    readonly timeoutMs?: number;
-    /** Context lines around a match; `>0` forces the in-process path (no `rg` delegation). */
-    readonly contextLines?: number;
-    /**
-     * Filename patterns to keep (e.g. `*.cpp`), forwarded as the agent's `include`.
-     *
-     * Distinct from {@link paths}: `paths` decides what is **walked**, `include` decides which walked **files**
-     * are read, and it does not prune directories. Omitted means "no filename filtering" — the agent applies
-     * none, rather than this layer inventing an empty filter list.
-     */
-    readonly include?: readonly string[];
-    /**
-     * Drop the ignore rules the agent would otherwise apply: VCS ignores (`.gitignore` / `.ignore` /
-     * `.rgignore`) and its built-in `index.DefaultExcludes` noise directories.
-     *
-     * Omitted means the agent's own default (ignore rules applied), so an older agent that does not know the
-     * field still behaves exactly as before. The two search paths inside the agent both honour it — see
-     * `dsh-ssh-agent/internal/search/search.go`.
-     */
-    readonly noIgnore?: boolean;
-}
-/** One filesystem event (`watch.poll` `events[i]`). */
-export interface AgentWatchEvent {
-    /** Absolute remote path. */
-    readonly path: string;
-    /** `create` / `write` / `remove` / `rename`; `"unknown"` for a kind this client does not recognise. */
-    readonly kind: string;
-    /**
-     * When the **agent read** the event, in milliseconds since the epoch, converted from `atNs`.
-     * inotify carries no kernel timestamp, so this is not the moment the change happened; `null` when absent.
-     */
-    readonly atMs: number | null;
-}
-/** Result of {@link AgentTransport.startWatch} (`watch.start`). */
-export interface AgentWatchStartResult {
-    /**
-     * The watcher this result belongs to, as the agent normalised it (`"default"` when the caller omitted
-     * `watcherId`). Echoed so a caller sharing one connection can confirm which watcher it touched.
-     */
-    readonly watcherId: string;
-    /** The **roots** actually registered (absolute, deduplicated, ascending) — not every subdirectory. */
-    readonly watched: readonly string[];
-    /** True when `maxWatches` (or the kernel's `max_user_watches`) cut registration short. */
-    readonly truncated: boolean;
-    /** `"inotify"` today (Linux only); `"unknown"` when the agent sent nothing usable. */
-    readonly strategy: string;
-}
-/**
- * {@link AgentTransport.startWatch} request.
- *
- * Calling `start` with the **same** `watcherId` while that watcher runs **replaces** it (the agent stops
- * the old one first); if the new start fails, the old watcher is already gone. Different ids are
- * independent — that is what lets several sessions share one agent process without one session's
- * `watch.start` silently killing another's listener.
- */
-export interface AgentWatchStartRequest {
-    /**
-     * Which watcher to start or replace; omitted means the agent's `"default"` watcher, which is what a
-     * caller that never sets this has always used. The agent caps a connection at 16 watchers and answers
-     * `E_TOO_LARGE` beyond that (it never evicts someone else's watcher).
-     */
-    readonly watcherId?: string;
-    /** Absolute remote roots. Empty is a local `REMOTE_COMMAND_FAILED`. Non-absolute roots are `E_PARAMS`. */
-    readonly roots: readonly string[];
-    /** Recursively registered **directory** ceiling; agent default {@link DEFAULT_WATCH_MAX_WATCHES}. */
-    readonly maxWatches?: number;
-    /** Debounce window for merging same-`(path, kind)` events; agent default {@link DEFAULT_WATCH_DEBOUNCE_MS}. */
-    readonly debounceMs?: number;
-}
-/** Result of {@link AgentTransport.pollWatch} (`watch.poll`). */
-export interface AgentWatchPollResult {
-    /** The watcher this poll read from, as the agent normalised it (`"default"` when omitted). */
-    readonly watcherId: string;
-    /** Events returned by this poll (possibly empty, and empty is not an error). */
-    readonly events: readonly AgentWatchEvent[];
-    /** True when `maxEvents` was hit (more events remain queued) or the kernel queue overflowed. */
-    readonly truncated: boolean;
-    /** True when this poll returned because its deadline expired, not because it had events. */
-    readonly timeout: boolean;
-    /**
-     * Events dropped because the agent's queue limit was reached, **cumulative since `watch.start`** —
-     * never subtract two polls to get a delta, and do not read it as the total number of lost events
-     * (debounce merging also removes duplicates, which are not counted here).
-     */
-    readonly dropped: number;
-}
-/** {@link AgentTransport.pollWatch} request. */
-export interface AgentWatchPollRequest {
-    /** Which watcher to poll; omitted means the agent's `"default"` watcher. */
-    readonly watcherId?: string;
-    /**
-     * How long the agent may block waiting for events; agent default
-     * {@link DEFAULT_WATCH_POLL_TIMEOUT_MS}. See {@link AgentTransport.pollWatch}: this occupies the
-     * connection, and it must stay below the transport's `requestTimeoutMs` or the client deadline fires
-     * first.
-     */
-    readonly timeoutMs?: number;
-    /** Events per poll; agent default {@link DEFAULT_WATCH_MAX_EVENTS}. The rest stay queued. */
-    readonly maxEvents?: number;
-}
-/** Result of {@link AgentTransport.stopWatch} (`watch.stop`). */
-export interface AgentWatchStopResult {
-    /** The watcher this stop targeted, as the agent normalised it (`"default"` when omitted). */
-    readonly watcherId: string;
-    /** `true` when a watcher was running, `false` when there was nothing to stop (not an error). */
-    readonly stopped: boolean;
-}
-/** The agent's capability record, as the plugin cares about it. */
-export interface AgentCapabilities {
-    /** `"native"` / `"poll"` / `"none"`: only `native` may use `watch.*`. */
-    readonly watch?: string;
-    readonly index?: boolean;
-    readonly atomicWrite?: boolean;
-    readonly landlock?: string;
-    readonly git?: boolean;
-    readonly ripgrep?: boolean;
-    readonly grep?: boolean;
-    /** `proc.exec` support. Only `true` may call the command-execution path. */
-    readonly exec?: boolean;
-}
-/** Optional metadata a `hello` result may carry beyond the capability bits. */
-export interface AgentHelloExtras {
-    /** `hello.result.agent.os` (`linux`, `darwin`, …). */
-    readonly os?: string;
-    /** `hello.result.agent.arch`. */
-    readonly arch?: string;
-    /** `hello.result.agent.version`. */
-    readonly version?: string;
-    /** Explicit `uname` if a future agent sends one; preferred over the derivation from `os`. */
-    readonly uname?: string;
-}
-/**
- * Map agent capability bits onto this plugin's {@link RemoteCapabilities}.
- *
- * Honesty rules followed here, because each one would otherwise be an invented capability:
- *
- *  - a bit the agent did not send is **false**, never assumed;
- *  - `sha256` stays `null`: the agent computes versions itself and never advertises a digest tool;
- *  - `base64` / `findMaxDepth` stay `false`: those are Tier 1 shell-tool facts, and the agent does not
- *    use either command;
- *  - `posix` is true only for a POSIX `os`;
- *  - `uname` is derived from `os` (linux→Linux) when the agent sends no explicit `uname`. **That
- *    derivation is unverified against the wire** (v1 `hello` carries `os`, not `uname`) and is listed as
- *    an unverified assumption in the module documentation.
- */
-export declare function capabilitiesFromAgent(caps: AgentCapabilities | undefined, extras?: AgentHelloExtras): RemoteCapabilities;
-/**
- * The protocol v1 client: framing, request/response correlation and the `hello` handshake.
- *
- * Scope: **one session, up to {@link maxInFlight} requests in flight**. Requests are pipelined because the
- * agent dispatches them concurrently (ADR-0009) and answers by id, so the only thing that must stay
- * ordered is the blob stream — and the agent writes a response and its blob inside one critical section,
- * which makes blob arrival order equal declaration order. {@link readBlob} therefore binds to the blob
- * channel of *its own* control response rather than to a single global slot.
- *
- * A request that times out or is aborted is not simply forgotten — its response (and its blob) is still on
- * the wire, so the client drains it before reporting the failure, and it declares the connection lost when
- * it cannot.
- */
-//# sourceMappingURL=agent-protocol-types.d.ts.map