dsh-over-ssh 0.1.0 → 0.1.1

package/lib/types/src/host/integration/tools/session-tools.d.ts

@@ -1,46 +0,0 @@
-/**
- * The session-administration tool surface: one `remote_sessions` tool whose `action` picks list / delete /
- * delete_workspace / restore. Four separate tools for a rarely-used feature was the worst size-to-value ratio
- * on the whole surface.
- *
- * These operate on the **platform's session store**, not on a remote root, so they take no connection or root:
- * a session is identified by its id, and its location is derived from its own header (`cwd` → `projectKey`).
- * That is also why they do not go through `ctx.fs` — the store is not a workspace file.
- *
- * **Irreversible calls are gated.** `mode: "permanent"` goes through the platform's pre-execute waterfall and is
- * answered with `ask`; when the composition has no approval surface the registry turns that into a denial (fail
- * closed). Recycle-mode deletion is an ordinary call: it is recoverable.
- *
- * @module dsh-over-ssh/integration/session-tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
-import type { DeleteSessionResult, SessionAdminService } from '../../app/session-admin/session-admin-service.ts';
-import type { SessionTrashEntry } from '../../domain/session/session-admin.ts';
-import type { SessionRecord } from '../../domain/session/session-admin.ts';
-/** Format one inventory record as a human-readable line. */
-export declare function formatSession(record: SessionRecord): string;
-/** Human summary of a session deletion. */
-export declare function formatSessionDelete(result: DeleteSessionResult): string;
-/** Human summary of the bin. */
-export declare function formatSessionBin(entries: readonly SessionTrashEntry[]): string;
-/**
- * Build the session-administration definitions.
- *
- * @param service - the session administration service.
- * @returns definitions ready for `ctx.tools.register`.
- */
-export declare function sessionToolDefinitions(service: SessionAdminService): ToolDefinition[];
-/**
- * Gate irreversible session operations behind the platform's approval surface.
- *
- * Denial by default is deliberate: these calls destroy conversation history that cannot be regenerated, and a
- * composition without an approval surface must refuse rather than proceed.
- *
- * @param ctx - host context with the `tools` service.
- * @returns a disposer removing the gate.
- */
-export declare function sessionDestructionGate(ctx: Context): () => void;
-/** Register the session tool and the gate. */
-export declare function registerSessionTools(ctx: Context, service: SessionAdminService): () => void;
-//# sourceMappingURL=session-tools.d.ts.map

package/lib/types/src/host/integration/tools/strict-arguments.d.ts

@@ -1,79 +0,0 @@
-/**
- * Strict root-level argument validation for this plugin's tool surface.
- *
- * **Why this exists.** `defineTool` compiles the parameter map into an object-rooted JSON Schema that
- * carries `properties` and `required` but **no `additionalProperties`**, and the core validator only
- * reports an undeclared property when that keyword is explicitly `false`
- * (`@deepseek-ai/dsh-tools` `json-schema.ts`, the `object` case). A model that writes `stdin`, `shell`,
- * `waitMs`, `mode` or `executable` therefore gets a **successful** call in which the field was silently
- * dropped — the most dangerous failure mode there is, because the caller believes the setting took effect.
- *
- * The plugin cannot close the core's implicit root, so it enforces closure itself on the documented
- * pre-dispatch extension point (`tools/pre-execute`), the same hook `permanentDeleteGate` already uses.
- *
- * **One message, everything wrong at once.** The core reports missing/typed arguments from inside
- * `execute`, but a pre-execute gate runs *before* that, so this gate can name every unknown field and every
- * missing required field in a single refusal instead of sending the caller back one field at a time.
- *
- * @module dsh-over-ssh/integration/strict-arguments
- */
-import type { Context } from '@deepseek-ai/cordis';
-/**
- * The name prefix every tool of this plugin uses.
- *
- * The gate is scoped by prefix rather than by a copied name list: a list would drift the moment a tool is
- * added, and this plugin's namespace is `remote_*`. `tests/strict-arguments.test.ts` pins that every tool
- * name this plugin registers starts with the prefix, so the assumption cannot rot silently.
- */
-export declare const STRICT_TOOL_PREFIX = "remote_";
-/** Whether a tool name belongs to this plugin's surface. */
-export declare function isStrictTool(name: string): boolean;
-/** What one argument check found. */
-export interface ArgumentViolations {
-    /** Fields the caller sent that the tool does not declare. */
-    readonly unknown: readonly string[];
-    /** Fields the tool requires that the caller did not send. */
-    readonly missing: readonly string[];
-    /** Every field the tool does declare, in declaration order. */
-    readonly declared: readonly string[];
-}
-/** The parts of one registered parameter schema this gate reads. */
-export interface StrictParameterSchema {
-    readonly properties?: Readonly<Record<string, unknown>> | undefined;
-    readonly required?: readonly string[] | undefined;
-}
-/**
- * Compare a call's arguments against the tool's own declared parameters.
- *
- * Only the **root** is checked: a nested open map (such as `remote_exec`'s `env`) keeps whatever openness it
- * declared, because closing it would reject the very keys that field exists to carry.
- *
- * A non-object argument (or a missing schema) yields no violations here: the core's own validation owns
- * those cases, and reporting them twice would produce two different messages for one mistake.
- *
- * @param schema - the registered parameter schema (`properties` / `required`).
- * @param args - the model-supplied arguments, however malformed.
- * @returns the unknown fields, the missing required fields, and the declared field list.
- */
-export declare function argumentViolations(schema: StrictParameterSchema | undefined, args: unknown): ArgumentViolations;
-/** Whether anything was found worth refusing. */
-export declare function hasViolations(violations: ArgumentViolations): boolean;
-/**
- * The model-facing refusal.
- *
- * It names what was rejected **and** what is accepted: the caller's next attempt should be a correction, not
- * a guess. "Unknown field" alone would leave the model trying spellings one at a time.
- *
- * @param toolName - the tool that was called.
- * @param violations - what the check found.
- * @returns one actionable sentence.
- */
-export declare function formatArgumentViolations(toolName: string, violations: ArgumentViolations): string;
-/**
- * Register the gate.
- *
- * @param ctx - host context with the `tools` service.
- * @returns a disposer removing the listener (idempotent).
- */
-export declare function strictArgumentsGate(ctx: Context): () => void;
-//# sourceMappingURL=strict-arguments.d.ts.map

package/lib/types/src/host/integration/tools/terminal-manifest.d.ts

@@ -1,94 +0,0 @@
-/**
- * The files a terminal wrapper reads: the root manifest and per-session state.
- *
- * The wrapper is a **separate process** launched by the platform's terminal controller, so it cannot ask the
- * host anything over IPC — it reads two small JSON files instead:
- *
- *  - `roots.json` — every remote root with its local anchor and its already-credential-resolved ssh argv;
- *  - `state/<sessionId>.json` — the remote target of one session, written when the host resolves it.
- *
- * Writes are atomic (temp file + rename) because the wrapper may read them at any moment, and a half-written
- * JSON must never decide where the user's terminal goes.
- *
- * @module dsh-over-ssh/integration/terminal-manifest
- */
-import { type ManifestRoot, type RootManifest, type SessionState, type SshInvocation } from '../../domain/session/terminal-target.ts';
-/**
- * Build the ssh invocation the terminal wrapper spawns for one connection.
- *
- * Deliberately shared with the entry **and** with the real-host verification: a hand-written copy is exactly
- * how a wrapper ends up connecting as the local user instead of the configured one (the verification script
- * hit that: `ssh host` used `yerier@…` and was refused, because the manifest lacked `-l root`).
- *
- * Difference from the alias transport: terminals are interactive, so a password connection must be allowed to
- * prompt (`BatchMode=no`) — an agent-authenticated one must not.
- *
- * @param profile - connection facts (host, alias, port, user, auth).
- * @param limits - resolved plugin limits (`knownHostsFile`, `connectTimeoutMs`).
- * @returns destination plus credential arguments.
- */
-export declare function sshInvocationFor(profile: {
-    readonly host: string;
-    readonly alias?: string;
-    readonly port?: number;
-    readonly user?: string;
-    readonly authKind: 'agent' | 'key' | 'password';
-    readonly identityFile?: string;
-    readonly connectTimeoutMs?: number;
-}, limits?: {
-    readonly knownHostsFile?: string;
-    readonly connectTimeoutMs?: number;
-}): SshInvocation;
-/** File-system surface, injected so tests never touch the developer's home directory. */
-export interface ManifestIo {
-    readFile(path: string): Promise<string>;
-    writeFile(path: string, data: string): Promise<void>;
-    mkdir(path: string): Promise<void>;
-    rename(from: string, to: string): Promise<void>;
-    remove(path: string): Promise<void>;
-    list(dir: string): Promise<readonly string[]>;
-}
-/** Real file-system binding. */
-export declare const nodeManifestIo: ManifestIo;
-/**
- * Turn a session id into a safe file name.
- *
- * Session ids are host-chosen strings and may contain separators or colons; the name is sanitized and given a
- * short hash suffix so two distinct ids can never collide onto one file.
- *
- * @param sessionId - raw session id.
- * @returns a file name (no directory part) unique to that id.
- */
-export declare function sessionFileName(sessionId: string): string;
-/** Reads and writes the wrapper's manifest files. */
-export declare class TerminalManifestStore {
-    #private;
-    /**
-     * @param options - `dir` is the plugin state directory (usually `~/.dsh/over-ssh`).
-     */
-    constructor(options: {
-        readonly dir: string;
-        readonly io?: ManifestIo;
-    });
-    /** Absolute path of the root manifest. */
-    get manifestPath(): string;
-    /** Absolute path of one session's state file. */
-    statePath(sessionId: string): string;
-    /**
-     * Replace the whole root manifest.
-     *
-     * @param roots - remote roots the terminal wrapper may target.
-     */
-    writeRoots(roots: readonly ManifestRoot[]): Promise<void>;
-    /** Read the root manifest; `undefined` when missing, malformed, or from another format version. */
-    readRoots(): Promise<RootManifest | undefined>;
-    /** Record one session's remote target. */
-    writeSession(state: SessionState): Promise<void>;
-    /** Read one session's target; `undefined` when missing or malformed. */
-    readSession(sessionId: string): Promise<SessionState | undefined>;
-    /** Remove one session's state (session closed); missing files are not an error. */
-    forgetSession(sessionId: string): Promise<void>;
-    /** Every readable session state (used by the wrapper when it has no session id). */
-    listSessions(): Promise<readonly SessionState[]>;
-}
-//# sourceMappingURL=terminal-manifest.d.ts.map

package/lib/types/src/host/integration/transfer/remote-copy.d.ts

@@ -1,66 +0,0 @@
-/**
- * Copy one remote file to another path **on the remote side**.
- *
- * Why this exists separately from the transfer service: that service models "local file ↔ remote file", and
- * its failure context is typed `upload | download`. A remote-to-remote copy has neither a local path nor a
- * direction, so folding it in would mean widening every one of those types for one caller.
- *
- * Two paths, in order of preference:
- *
- *   1. **Server-side** (`transport.copyFile`): the remote host copies the file itself. No bytes cross this
- *      process and none touch the local disk — the whole point of the operation.
- *   2. **Relay**: read a chunk from the source and write it to the destination through this process. Used when
- *      the transport has no server-side copy (Tier 1, or an agent that predates `fs.copy`). The bytes do pass
- *      through here, and the outcome says so instead of implying otherwise.
- *
- * @module dsh-over-ssh/integration/transfer/remote-copy
- */
-import type { RemoteStatResult, Transport } from '../../infra/transport/transport.ts';
-/** What one copy needs, injected so the module stays testable without a transport. */
-export interface RemoteCopyDeps {
-    readonly transportFor: (connectionId: string) => Promise<Transport>;
-    readonly statRemote: (absolute: string) => Promise<RemoteStatResult>;
-    /** Chunk ceiling for the relay path; ignored when the copy happens on the server. */
-    readonly chunkBytes: number;
-    readonly now: () => number;
-}
-/** One copy request; both paths are already root-absolute. */
-export interface RemoteCopyRequest {
-    readonly connectionId: string;
-    readonly from: string;
-    readonly to: string;
-    /** Replace an existing destination. When false the copy refuses to clobber. */
-    readonly overwrite: boolean;
-    /**
-     * Copy a whole directory tree.
-     *
-     * Only the server-side path can do this. There is deliberately **no relay fallback**: relaying a tree file
-     * by file is the exact cost this mode exists to remove, and a silent fallback would turn one round trip into
-     * thousands while still reporting success.
-     */
-    readonly recursive?: boolean;
-    readonly signal?: AbortSignal;
-    readonly onProgress?: (transferredBytes: number, totalBytes: number) => void;
-}
-/** What the copy did. */
-export interface RemoteCopyOutcome {
-    readonly bytes: number;
-    /** `server` means the remote host copied it; `relay` means the bytes came through this process. */
-    readonly via: 'server' | 'relay';
-    readonly durationMs: number;
-    /** Recursive copies only: how many of each kind were produced. */
-    readonly files?: number;
-    readonly dirs?: number;
-    readonly symlinks?: number;
-}
-/**
- * Copy `from` to `to` on the remote host, preferring the server-side path.
- *
- * @param deps - transport lookup, remote stat, chunk size and clock.
- * @param request - the two absolute paths, the overwrite policy and an optional cancel signal.
- * @returns bytes copied and which path was taken.
- * @throws SshDevError `REMOTE_NOT_FOUND` when the source is missing, `REMOTE_UNSUPPORTED` when neither path
- *   is available, `TRANSFER_CONFLICT` when the destination exists and `overwrite` is false.
- */
-export declare function copyRemoteFile(deps: RemoteCopyDeps, request: RemoteCopyRequest): Promise<RemoteCopyOutcome>;
-//# sourceMappingURL=remote-copy.d.ts.map

package/lib/types/src/host/integration/transfer/transfer-adapters.d.ts

@@ -1,48 +0,0 @@
-/**
- * Adapters that turn the plugin's routing + transports into the injected dependencies the transfer and
- * recycle-bin services expect.
- *
- * Two rules shape everything here:
- *
- *  - **Remote work uses the real primitives.** Chunked reads go through `Transport.readFileRange` (verified on
- *    a real host: exact window, no whole-file read) and positioned writes through `writeFileRange` (POSIX
- *    `pwrite` semantics, shared by all three transports). Where a transport lacks the method the fallback is
- *    written down instead of hidden.
- *  - **Local work never borrows the remote path.** `node:fs` is opened with `position` arguments so a local
- *    chunk does not read the whole file either; the recycle bin's local mutators are a separate object, so a
- *    local target can never end up being "moved" by an ssh command.
- *
- * @module dsh-over-ssh/integration/transfer-adapters
- */
-import type { RootRef } from '../../domain/roots/root.ts';
-import type { RoutedFileSystem } from '../../app/routed-fs.ts';
-import type { Transport } from '../../infra/transport/transport.ts';
-import type { RecycleBinServiceDeps } from '../../app/recycle-bin/recycle-bin-service.ts';
-import type { TransferDependencies } from './transfer-service.ts';
-/** What both adapters need from the plugin. */
-export interface WorldAdapterDeps {
-    /** Path routing: turns a path in any root's spelling into `{root, backend, absolute}`. */
-    readonly routed: RoutedFileSystem;
-    /** The transport of one connection (the caller already owns the profile lookup). */
-    readonly transportFor: (connectionId: string) => Promise<Transport>;
-    /** Bin directory **inside one root** (same device, so the move stays a rename). */
-    readonly binRootFor: (root: RootRef) => string;
-    /** Chunk ceiling passed to the transfer service. */
-    readonly chunkBytes: number;
-    /** Chunks in flight at once, passed to the transfer service. */
-    readonly concurrency: number;
-    /** Upper bound for one text read (the index file). */
-    readonly maxReadBytes: number;
-    /** Clock, injected for tests. */
-    readonly now?: () => number;
-}
-/** The transfer service's dependencies. */
-export declare function createTransferDeps(deps: WorldAdapterDeps): TransferDependencies;
-/** The recycle bin's dependencies: remote primitives plus an explicit local world. */
-export declare function createRecycleBinDeps(deps: WorldAdapterDeps & {
-    readonly knownRoots: () => readonly RootRef[];
-    readonly undoDepth: number;
-    /** Cross-process lock around the bin index read-modify-write. */
-    readonly withIndexLock?: import('../../app/recycle-bin/recycle-bin-contract.ts').WithIndexLock;
-}): RecycleBinServiceDeps;
-//# sourceMappingURL=transfer-adapters.d.ts.map

package/lib/types/src/host/integration/transfer/transfer-tracker.d.ts

@@ -1,106 +0,0 @@
-/**
- * A bounded registry of in-flight and recently finished transfers (FR-2.6.4).
- *
- * Why a registry and not a callback straight into the client: the UI asks "what is happening" whenever it
- * renders, which is a *pull*. Pushing would need a channel this plugin does not have (its client half talks
- * over one HTTP route), so the honest shape is a small table the UI polls.
- *
- * Three rules, each of which is a way a progress UI usually lies:
- *
- *  1. **A finished transfer is kept, not deleted.** A row that vanishes the instant it completes leaves the
- *     user unable to tell "done" from "failed and cleared"; the failure list FR-2.6.4 asks for is exactly
- *     the recent history.
- *  2. **The table is bounded** (`maxEntries`, oldest finished first). An unbounded map keyed by transfer id is
- *     a leak that only shows up after a long session.
- *  3. **`percent` is computed from the bytes that landed, never extrapolated.** A progress bar that jumps to
- *     the end because a chunk was *planned* is worse than no bar.
- *
- * The module imports no cordis and no `node:fs`: it is a table plus transitions, so it is testable offline.
- *
- * @module dsh-over-ssh/integration/transfer-tracker
- */
-import { type TransferProgress } from '../../domain/transfer/transfer.ts';
-/** Lifecycle of one tracked transfer. */
-export type TrackedTransferStatus = 'running' | 'done' | 'failed' | 'cancelled';
-/** One tracked transfer, as the UI sees it. */
-export interface TrackedTransfer {
-    readonly id: string;
-    readonly direction: 'upload' | 'download';
-    readonly connectionId: string;
-    /** Remote path (root-absolute). */
-    readonly remotePath: string;
-    /** Local path; for a download this is the destination, for an upload the source. */
-    readonly localPath: string;
-    readonly status: TrackedTransferStatus;
-    readonly progress: TransferProgress;
-    /** Message of the failure, when `status === 'failed'`. */
-    readonly error?: string;
-    /** Machine-readable code of the failure, when the host named one. */
-    readonly errorCode?: string;
-    readonly startedAt: number;
-    /** When it stopped running; absent while it is still running. */
-    readonly finishedAt?: number;
-}
-/** What a caller supplies to open a transfer. */
-export interface TransferStart {
-    readonly direction: 'upload' | 'download';
-    readonly connectionId: string;
-    readonly remotePath: string;
-    readonly localPath: string;
-    readonly totalBytes: number;
-}
-/** The tracker's injected facts. */
-export interface TransferTrackerOptions {
-    /** How many entries to retain, finished ones evicted oldest-first. At least 1. */
-    readonly maxEntries: number;
-    /** Injectable clock. */
-    readonly now?: () => number;
-}
-/** The table. */
-export interface TransferTracker {
-    /** Open a transfer and return its id. */
-    start(input: TransferStart): string;
-    /**
-     * Record progress; unknown ids are ignored (a late callback after eviction must not throw).
-     *
-     * `totalBytes` is carried on every report because the tracker does **not** know the size up front: the plan is
-     * computed inside the transfer service, so the first honest total arrives with the first progress callback.
-     * Guessing a total at `start` would show 100% for a transfer that has barely begun.
-     */
-    progress(id: string, transferredBytes: number, totalBytes?: number): void;
-    /** Mark it finished. */
-    done(id: string, transferredBytes?: number): void;
-    /** Mark it failed, with whatever code the host produced. */
-    fail(id: string, error: string, errorCode?: string): void;
-    /** Mark it cancelled (the user's own action, which is not a failure). */
-    cancel(id: string): void;
-    /**
-     * Close a transfer from the error it threw, choosing between `cancelled` and `failed`.
-     *
-     * The policy lives here rather than at the call site because it is a **domain** rule, not plumbing: a
-     * cancelled transfer is the user's own action, so listing it among failures would bury the real ones — and
-     * the requirement's failure list is the thing that has to stay readable. It sat in the composition root
-     * first, where no test could reach it (audit 0046).
-     *
-     * @param id - the transfer.
-     * @param failure - the thrown value and the code the host produced, if any.
-     */
-    settle(id: string, failure: {
-        readonly code?: string | undefined;
-        readonly message: string;
-    }): void;
-    /** Everything retained, newest first. */
-    list(): readonly TrackedTransfer[];
-    /** One entry, if it is still retained. */
-    get(id: string): TrackedTransfer | undefined;
-    /** Drop every finished entry (the UI's "clear" button). */
-    clearFinished(): number;
-}
-/**
- * Build a tracker.
- *
- * @param options - bounds and clock.
- * @returns the tracker.
- */
-export declare function createTransferTracker(options: TransferTrackerOptions): TransferTracker;
-//# sourceMappingURL=transfer-tracker.d.ts.map

package/lib/types/src/host/integration/transfer-adapters.d.ts

@@ -1,44 +0,0 @@
-/**
- * Adapters that turn the plugin's routing + transports into the injected dependencies the transfer and
- * recycle-bin services expect.
- *
- * Two rules shape everything here:
- *
- *  - **Remote work uses the real primitives.** Chunked reads go through `Transport.readFileRange` (verified on
- *    a real host: exact window, no whole-file read) and positioned writes through `writeFileRange` (POSIX
- *    `pwrite` semantics, shared by all three transports). Where a transport lacks the method the fallback is
- *    written down instead of hidden.
- *  - **Local work never borrows the remote path.** `node:fs` is opened with `position` arguments so a local
- *    chunk does not read the whole file either; the recycle bin's local mutators are a separate object, so a
- *    local target can never end up being "moved" by an ssh command.
- *
- * @module dsh-remote-workspace/integration/transfer-adapters
- */
-import type { RootRef } from '../domain/root.ts';
-import type { RoutedFileSystem } from '../app/routed-fs.ts';
-import type { Transport } from '../infra/transport/transport.ts';
-import type { RecycleBinServiceDeps } from '../app/recycle-bin-service.ts';
-import type { TransferDependencies } from './transfer-service.ts';
-/** What both adapters need from the plugin. */
-export interface WorldAdapterDeps {
-    /** Path routing: turns a path in any root's spelling into `{root, backend, absolute}`. */
-    readonly routed: RoutedFileSystem;
-    /** The transport of one connection (the caller already owns the profile lookup). */
-    readonly transportFor: (connectionId: string) => Promise<Transport>;
-    /** Bin directory **inside one root** (same device, so the move stays a rename). */
-    readonly binRootFor: (root: RootRef) => string;
-    /** Chunk ceiling passed to the transfer service. */
-    readonly chunkBytes: number;
-    /** Upper bound for one text read (the index file). */
-    readonly maxReadBytes: number;
-    /** Clock, injected for tests. */
-    readonly now?: () => number;
-}
-/** The transfer service's dependencies. */
-export declare function createTransferDeps(deps: WorldAdapterDeps): TransferDependencies;
-/** The recycle bin's dependencies: remote primitives plus an explicit local world. */
-export declare function createRecycleBinDeps(deps: WorldAdapterDeps & {
-    readonly knownRoots: () => readonly RootRef[];
-    readonly undoDepth: number;
-}): RecycleBinServiceDeps;
-//# sourceMappingURL=transfer-adapters.d.ts.map

package/lib/types/src/host/integration/transfer-service.d.ts

@@ -1,164 +0,0 @@
-/**
- * The remote-file transfer seam: move one file in one direction, in bounded chunks, with progress.
- *
- * This module owns the *policy* half of a transfer — offsets, resume decisions, progress callbacks,
- * cancellation and failure classification — and none of the I/O. Every side effect arrives as an
- * injected dependency (`readLocal`, `writeRemote`, `readRemote`, `writeLocal`, `statLocal`,
- * `statRemote`, optional `sha256Local`, optional clock), so the whole flow can be exercised offline
- * against substitute I/O (AGENTS.md 红线 3), and the same code runs on a real host by wiring the real
- * implementations in [`src/index.ts`] (left to the plugin entry, which this change does not touch).
- *
- * Contract notes that callers and implementers both rely on:
- *
- *  - **Memory is bounded by `chunkBytes`**: a chunk is read, written and dropped; the file is never
- *    assembled in memory. A test asserts this by recording every `readLocal` request, not by claiming it.
- *  - **`offset === undefined` means "replace the target's content with exactly these bytes"**;
- *    `offset === n` means "place these bytes at byte n, extending the target". The first write of a
- *    fresh transfer therefore carries no offset, and every later chunk carries its absolute offset.
- *  - **Progress fires once per completed write** and never decreases: each snapshot is computed from
- *    a running byte counter, and the clock is injected so rates are reproducible in tests.
- *  - **Cancellation is reported, never swallowed**: an aborted transfer fails with `CANCELLED` and
- *    details carrying the bytes that are known to have landed, how many chunks were written, and
- *    whether the chunk in flight may have landed partially.
- *  - **Failure is classified**: `details.kind` is the precise {@link TransferFailureKind}; the error
- *    code stays inside the existing `SSH_DEV_ERROR_CODES` table (see `domain/transfer.ts`).
- *
- * @module dsh-remote-workspace/integration/transfer-service
- */
-import { type TransferDegradation, type TransferProgress } from '../domain/transfer.ts';
-import type { BackendStat } from '../app/backend.ts';
-import type { RemoteWriteOutcome } from '../infra/transport/transport.ts';
-/** Default cap on one read/write step; overridable per call and per service instance. */
-export declare const DEFAULT_TRANSFER_CHUNK_BYTES: number;
-/** One bounded source read. */
-export interface SourceReadOptions {
-    /** Byte offset to start at. */
-    readonly offset: number;
-    /** Maximum bytes to return; a shorter answer means the source ended early. */
-    readonly length: number;
-    readonly signal?: AbortSignal;
-}
-/** One bounded remote read. */
-export interface RemoteReadOptions {
-    /** Byte offset to start at; omitted means 0. */
-    readonly offset?: number;
-    /** Maximum bytes to return *from `offset`*. */
-    readonly maxBytes: number;
-    readonly signal?: AbortSignal;
-}
-/** One remote write. */
-export interface RemoteWriteOptions {
-    /** `undefined` replaces the file's content; `n` places the bytes at byte `n`. */
-    readonly offset?: number;
-    /** Refuse the write unless the target's current content has this digest (optimistic guard). */
-    readonly expectedSha256?: string;
-    readonly signal?: AbortSignal;
-}
-/** One local write (the download side). */
-export interface LocalWriteOptions {
-    /** `undefined` replaces the file's content; `n` places the bytes at byte `n`. */
-    readonly offset?: number;
-}
-/** Everything a transfer needs from the outside world. */
-export interface TransferDependencies {
-    /** Bounded local read. Must not return more than `length` bytes. */
-    readonly readLocal: (path: string, options: SourceReadOptions) => Promise<Uint8Array>;
-    /**
-     * Remote write. `offset === undefined` replaces the target; `offset === n` writes at `n`.
-     * Returning {@link RemoteWriteOutcome} is how a remote digest (if any) reaches the caller.
-     */
-    readonly writeRemote: (absolute: string, bytes: Uint8Array, options: RemoteWriteOptions) => Promise<RemoteWriteOutcome>;
-    /**
-     * Remote read, bounded by `maxBytes` and optionally starting at `offset`.
-     *
-     * The sketched Tier 1 transport takes only `maxBytes`; the optional `offset` is what makes a
-     * chunked download possible, so an implementation that cannot honour it must say so rather than
-     * silently returning the head of the file (a wrong answer is worse than a refused one).
-     */
-    readonly readRemote: (absolute: string, options: RemoteReadOptions) => Promise<Uint8Array>;
-    /** Local write; same offset convention as {@link TransferDependencies.writeRemote}. */
-    readonly writeLocal: (path: string, bytes: Uint8Array, options: LocalWriteOptions) => Promise<void>;
-    /** Local metadata. Must report `exists: false` for a missing path instead of throwing. */
-    readonly statLocal: (path: string) => Promise<BackendStat>;
-    /** Remote metadata. Same `exists` rule as {@link TransferDependencies.statLocal}. */
-    readonly statRemote: (absolute: string) => Promise<BackendStat>;
-    /** Optional digest of a local file; when absent the result reports `sha256: null`. */
-    readonly sha256Local?: (path: string) => Promise<string>;
-    /**
-     * Whether `writeRemote` may continue an existing partial remote file (`resume: true` requests).
-     * Defaults to `false`: a requested resume then degrades to a full rewrite **and says so**.
-     */
-    readonly supportsResume?: boolean;
-    /** Default per-chunk cap; a request may override it. */
-    readonly chunkBytes?: number;
-    /** Clock, injected so rate/remaining estimates are reproducible in tests. */
-    readonly nowMs?: () => number;
-}
-/** Common request fields. */
-export interface TransferRequestBase {
-    /** Connection the remote path belongs to; recorded in the result and in failures. */
-    readonly connectionId: string;
-    /** Absolute POSIX root the remote path must stay inside. */
-    readonly root: string;
-    /** Remote path relative to the root; `..` is folded and can never escape. */
-    readonly remotePath: string;
-    /** Per-chunk cap for this call; defaults to the service's `chunkBytes`. */
-    readonly chunkBytes?: number;
-    /** Keep bytes already present on the target when possible; defaults to `false`. */
-    readonly resume?: boolean;
-    readonly onProgress?: (progress: TransferProgress) => void;
-    readonly signal?: AbortSignal;
-}
-/** Upload one local file to the remote root. */
-export interface UploadRequest extends TransferRequestBase {
-    /** Local source file. */
-    readonly localPath: string;
-    /**
-     * Digest the remote target must currently have, forwarded to the first `writeRemote` call as its
-     * optimistic guard. A dependency that refuses the write surfaces as `TRANSFER_CONFLICT`.
-     */
-    readonly expectedSha256?: string;
-}
-/** Download one remote file into a local path. */
-export interface DownloadRequest extends TransferRequestBase {
-    /** Local destination *file* path (its base name is validated for the host platform). */
-    readonly localPath: string;
-}
-/** What one transfer did. */
-export interface TransferResult {
-    readonly direction: 'upload' | 'download';
-    readonly connectionId: string;
-    readonly root: string;
-    readonly localPath: string;
-    /** Root-absolute remote path the transfer actually used (after `..` folding). */
-    readonly remotePath: string;
-    readonly totalBytes: number;
-    /** Bytes this transfer wrote, excluding any prefix it resumed from. */
-    readonly bytesTransferred: number;
-    /** Writes performed by this transfer (0 for a resumed transfer with nothing left; 1 for an empty file). */
-    readonly chunks: number;
-    readonly resumed: boolean;
-    /** Offset the transfer started at. */
-    readonly startOffset: number;
-    readonly durationMs: number;
-    /**
-     * Digest of the transferred content, or `null` when no digest was obtainable:
-     * the remote's own digest for a single non-resumed write, else `sha256Local`'s answer.
-     */
-    readonly sha256: string | null;
-    /** Why something was not done as asked (resume refused, digest unavailable); empty when clean. */
-    readonly degradations: readonly TransferDegradation[];
-}
-/** The two operations this seam exposes. */
-export interface TransferService {
-    upload(request: UploadRequest): Promise<TransferResult>;
-    download(request: DownloadRequest): Promise<TransferResult>;
-}
-/**
- * Build the transfer service.
- *
- * @param dependencies - all local/remote I/O plus the optional clock, digest and resume capability.
- * @returns the upload/download operations; no state is kept between calls.
- */
-export declare function createTransferService(dependencies: TransferDependencies): TransferService;
-//# sourceMappingURL=transfer-service.d.ts.map