dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/integration/fs-provider.d.ts

@@ -0,0 +1,226 @@
+/**
+ * The `ctx.fs` provider: the core filesystem seam served by this plugin's router.
+ *
+ * Core components (the model's `read`/`write`/`edit` tools, the workspace file panel, agent
+ * instructions) reach the filesystem only through `ctx.fs`, so registering this provider is what
+ * makes remote roots usable everywhere without touching a single consumer.
+ *
+ * Mapping rules that matter:
+ *
+ *  - `targetKey` is the router's namespaced key, wrapped in the core's branded type. Consumers treat
+ *    it as opaque; this provider is the owner that may parse it back.
+ *  - Core error codes are produced here, not leaked from the domain layer: `FS_STALE_VERSION`,
+ *    `FS_NOT_OBSERVED`, `FS_EDIT_NOT_FOUND`, `FS_AMBIGUOUS_EDIT`, `FS_NOT_TEXT`, `FS_TOO_LARGE`,
+ *    `FS_SANDBOX_DENIED`, `FS_IO_ERROR`.
+ *  - The fence is the plugin's own multi-root confinement (ADR-0003): `read-only` denies every
+ *    mutation, a root registered `writable: false` is denied, and `workspace-write` admits every
+ *    registered root — the core's single-root fence cannot express several roots.
+ *
+ * @module dsh-remote-workspace/integration/fs-provider
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { FileSystem, FsError, FsVersion } from '@deepseek-ai/dsh-fs';
+import type { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsTarget, FsWriteIntent, FsWriteOutcome } from '@deepseek-ai/dsh-fs';
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import type { Backend } from '../app/backend.ts';
+import { SshDevError, type SshDevErrorCode } from '../domain/errors.ts';
+/**
+ * One true window read: the bytes at `[offset, offset + length)`, fetched by the backend that owns
+ * the path **without** buffering the prefix before `offset` (the defect recorded in audit 0016's Lead
+ * list, item 1: `readByteRange` used to read `[0, end)` and slice).
+ */
+export interface RangeWindow {
+    readonly bytes: Uint8Array;
+    /** Full size of the file when the backend can report it cheaply; `undefined` when it cannot. */
+    readonly size?: number;
+    /**
+     * Whether `bytes` stops before the end of the file.
+     *
+     * `false` means the window reached EOF and is the **only** signal
+     * {@link RoutedFsProvider.readByteRange} needs to stop paging: without it a window that ends exactly
+     * at EOF would cost one extra empty round trip, and a window that ends past EOF would look identical
+     * to one that stopped short. Every reader must report it truthfully — a reader that keeps saying
+     * `true` makes the provider page on past the end.
+     */
+    readonly truncated: boolean;
+}
+/**
+ * Offset-read seam.
+ *
+ * This is an **injected optional function**, not a `Backend` method: `Backend` (and
+ * `RemoteBackend`, the only backend that could implement it) is deliberately outside this change's
+ * write scope, so the capability arrives as a constructor dependency instead. It is handed the
+ * resolved backend and its root-absolute path, so one injected function can serve every root.
+ *
+ * Return `null` — never throw — to say "this backend/transport has no offset read". The provider then
+ * falls back to the bounded prefix read and does **not** pretend the read was chunked.
+ */
+export type BackendRangeReader = (backend: Backend, request: {
+    readonly absolute: string;
+    readonly offset: number;
+    readonly length: number;
+}, signal?: AbortSignal) => Promise<RangeWindow | null>;
+/** Options for {@link RoutedFsProvider}. */
+export interface RoutedFsProviderOptions {
+    /**
+     * How to read a byte window where the backend can seek.
+     *
+     * Omitted (the default, and what `ctx.plugin(RoutedFsProvider)` gets) means every read keeps the
+     * old semantics. Wire it at the point the remote backend is built (`src/index.ts`
+     * `createRemoteBackend`, currently lines 355-365), where the transport — and therefore
+     * `Transport.readFileRange` — is reachable; see {@link createBackendRangeReader}.
+     */
+    readonly readBytesRange?: BackendRangeReader;
+    /** Largest window one underlying request may ask for; the memory bound for a chunked read. */
+    readonly rangeChunkBytes?: number;
+}
+/**
+ * Filesystem provider over the plugin's roots.
+ *
+ * Registers as `ctx.fs`; the composition replaces the core `fs-sandbox` row with this one so the
+ * model's file tools follow the router (see `cordis.patch.yml`).
+ */
+export declare class RoutedFsProvider extends FileSystem {
+    #private;
+    static inject: string[];
+    protected readonly rangeReader: BackendRangeReader | undefined;
+    protected readonly rangeChunkBytes: number;
+    constructor(ctx: Context, options?: RoutedFsProviderOptions);
+    /** This provider confines writes to the registered roots. */
+    get sandboxMode(): SandboxMode;
+    /** Resolve a model-facing path to the router's target and wrap it for the core. */
+    resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<FsTarget>;
+    /** Path a subprocess in the target's world can open (the remote absolute path for remote roots). */
+    processPath(target: FsTarget): string;
+    /** Map a host path onto the local world when one of the registered roots covers it. */
+    processPathFromHostPath(hostPath: string): string | undefined;
+    /** Canonical `file:` URI in the target's world. */
+    fileUrl(target: FsTarget): string;
+    /** Containment; two targets in different worlds never contain one another. */
+    contains(parent: FsTarget, child: FsTarget): boolean;
+    /** Metadata, or `undefined` for an absent target. */
+    stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
+    /** Path metadata without following a final symlink, where the backend can tell. */
+    lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
+    /** Whole-file UTF-8 text; binary and oversize files fail with typed codes. */
+    readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
+    /**
+     * Stream text in chunks.
+     *
+     * Backends currently hand back the whole bounded body, so this yields it as one chunk; a
+     * transport-level chunked read is a follow-up, and the bound keeps memory finite meanwhile.
+     */
+    streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
+    /** Whole-file bytes, refusing oversized targets instead of truncating. */
+    readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
+    /**
+     * One byte window, bounded by the caller's window rather than the file size.
+     *
+     * Two paths, and they are deliberately distinguishable:
+     *
+     *  - the backend has an offset read (the injected {@link BackendRangeReader} answers with a window):
+     *    the window is fetched as a sequence of requests of at most the configured chunk size, each
+     *    starting at the file offset it needs. Nothing before `offset` is ever transferred or held, so
+     *    the memory bound is the chunk size plus the returned window, not the file size;
+     *  - the backend has none (a local backend, a transport without `readFileRange`, or no injected
+     *    reader at all): the previous semantics are kept exactly — one bounded prefix read `[0, end)`
+     *    capped at 8 MiB, then a slice — and a window past that cap still fails with `FS_TOO_LARGE`
+     *    instead of silently buffering the file.
+     */
+    readByteRange(target: FsTarget, range: {
+        offset: number;
+        length: number;
+    }, signal?: AbortSignal): Promise<Uint8Array>;
+    /** Direct children, in stable name order, with resolved child targets. */
+    listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
+    /** Atomic write, honouring the write intent and the plugin's fence. */
+    writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsWriteOutcome>;
+    /** Literal edit with the core's three-state semantics and an optional version guard. */
+    editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: FsVersion;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsEditOutcome>;
+    /**
+     * Observation is not available yet.
+     *
+     * Tier 1 has no remote watcher, and the router deliberately reports `watches: false` instead of
+     * pretending: the caller (observation policy) falls back to revalidation on read.
+     *
+     * @param target - the target whose changes were requested.
+     * @param _changed - invalidation callback the base class would call; unused while unsupported.
+     * @param _signal - cancels watcher initialization; unused while unsupported.
+     * @returns never, because no watcher can be created yet.
+     * @throws FsError with `FS_IO_ERROR` until a watcher exists.
+     */
+    watch(target: FsTarget, _changed: (error?: Error) => void, _signal: AbortSignal): Promise<() => Promise<void>>;
+    private rootsService;
+    private router;
+    private routedTarget;
+    /** Enforce the per-call policy and the root's own writability. */
+    private assertWritable;
+    /** Previous text content, when it is readable text inside the cap; `undefined` otherwise. */
+    private readPriorText;
+    /** Run a backend call, translating domain errors into core codes. */
+    private call;
+}
+/**
+ * The plugin callback {@link createRoutedFsProvider} answers.
+ *
+ * `inject` is part of the shape because Cordis reads it off the plugin it is handed; typing it here keeps
+ * the factory's contract honest instead of relying on a cast at the call site.
+ */
+export interface FsProviderPlugin {
+    (ctx: Context): void;
+    inject: readonly string[];
+}
+/**
+ * Build the `ctx.fs` plugin with an injected offset-read seam.
+ *
+ * Cordis registers a plugin by calling it with the context, so a deployment that has the range reader
+ * available can register `createRoutedFsProvider({ readBytesRange })` instead of the bare class and
+ * get true chunked window reads; registering the class itself keeps the old semantics. Both are the
+ * same provider, so nothing else in the composition changes.
+ *
+ * Two details are load-bearing, and both were wrong before (found by loading the real `./fs` row in a
+ * packaged host — the provider never activated, so every `fs` consumer stayed pending):
+ *
+ *  - the callback must **not return the instance**. Cordis treats a function plugin's return value as
+ *    an effect to apply, and a provider instance is not one: `ctx.plugin(fn)` fails with
+ *    `Invalid effect` and the service is never provided. Constructing the instance inside the call is
+ *    what registers it (it extends `FileSystem`, which registers itself in the constructor).
+ *  - the callback must **carry the class's `inject`**. Cordis reads `inject` off the plugin it is
+ *    given, and a bare arrow function has none, so the provider would install before `sshDevRoots`
+ *    exists and silently read an undefined service.
+ *
+ * @param options - the seam plus the chunk size; see {@link RoutedFsProviderOptions}.
+ * @returns a plugin callback that constructs the provider on registration.
+ */
+export declare function createRoutedFsProvider(options: RoutedFsProviderOptions): FsProviderPlugin;
+/**
+ * Build the {@link BackendRangeReader} the provider injects.
+ *
+ * The Lead wires the pieces that live outside this change's write scope: a store that already holds a
+ * backend's bytes (tests), or — in production — the transport behind the backend, calling
+ * `Transport.readFileRange({ path, offset, maxBytes })` and returning `null` when that optional method
+ * is absent. The provider owns everything else: chunking, the memory bound, EOF short-circuiting.
+ *
+ * @param store - reads `[offset, offset + length)` from a backend, or `undefined` for a missing path.
+ * @param options - `chunkSizeHint` advertises the largest window worth asking for; it is **not** how the
+ *   provider bounds memory (the provider chunks by its own `rangeChunkBytes`).
+ * @returns a reader that answers `null` (never throws) when the store has no offset read.
+ */
+export declare function createBackendRangeReader(store: (backend: Backend, offset: number, length: number) => {
+    readonly bytes: Uint8Array;
+    readonly size: number;
+} | undefined, options?: {
+    readonly chunkSizeHint?: number;
+}): BackendRangeReader;
+/** Translate a domain failure into the core's filesystem vocabulary. */
+export declare function toFsError(error: SshDevError): FsError;
+/** Codes this provider can surface, exported for tests that assert the mapping table. */
+export declare const MAPPED_DOMAIN_CODES: readonly SshDevErrorCode[];
+//# sourceMappingURL=fs-provider.d.ts.map

package/lib/types/src/host/integration/lsp/lsp-framing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * LSP base protocol framing: `Content-Length: <bytes>\r\n\r\n<json>`.
+ *
+ * The agent is a **byte pipe** — it spawns the language server and moves bytes, but does not parse
+ * JSON-RPC ([protocol.md §lsp.*](../../../../dsh-over-ssh-agent/doc/01-product/protocol.md)). Everything in
+ * this module is therefore the plugin's job.
+ *
+ * `Content-Length` counts **bytes**, not characters. A parser that slices by string length passes every
+ * ASCII test and corrupts the first frame containing a multi-byte character — which in practice means the
+ * first diagnostic message written in Chinese. This module works on bytes throughout for that reason.
+ *
+ * @module dsh-over-ssh/host/integration/lsp/lsp-framing
+ */
+/** A cap on one frame's declared length. A corrupt header must not make us allocate without bound. */
+export declare const MAX_LSP_FRAME_BYTES: number;
+/** Encode one JSON-RPC message as an LSP frame. */
+export declare function encodeLspFrame(message: unknown): Uint8Array;
+/** What one parsed frame carried. */
+export type LspMessage = Record<string, unknown>;
+/**
+ * Incremental parser for a language server's stdout.
+ *
+ * Bytes arrive in whatever chunks the agent's ring buffer happens to hand over, so a frame routinely
+ * straddles two reads. {@link feed} returns every message that became complete and keeps the remainder.
+ */
+export declare class LspFrameParser {
+    #private;
+    /**
+     * Append bytes and return every message that is now complete.
+     *
+     * A malformed header is **not** skipped silently: the stream is no longer parseable (we cannot know
+     * where the next frame starts), so this throws and the caller must restart the session.
+     */
+    feed(chunk: Uint8Array | string): LspMessage[];
+    /** Bytes held back waiting for the rest of a frame. Diagnostics only. */
+    get pending(): number;
+}
+//# sourceMappingURL=lsp-framing.d.ts.map

package/lib/types/src/host/integration/lsp/lsp-registry.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-connection language-server sessions, shared across tool calls.
+ *
+ * A language server takes seconds to index a project, so starting one per tool call would make every query
+ * useless. This keeps one session per (connection, root, language) and reuses it.
+ *
+ * The registry also owns the **default server table**: which executable to run for a language. Nothing is
+ * probed here — if the executable is missing, `lsp.start` fails and the error says which command was tried.
+ *
+ * @module dsh-over-ssh/host/integration/lsp/lsp-registry
+ */
+import { LspSession, type LspDiagnostic, type LspTransportLike } from './lsp-session.ts';
+/** Which remote root a session belongs to. */
+export interface LspTarget {
+    readonly connectionId: string;
+    readonly root: string;
+}
+/** One server to run for a language. */
+export interface LspServerCommand {
+    readonly command: string;
+    readonly args?: readonly string[];
+}
+/** Language id for a path, matching the LSP `languageId` convention. */
+export declare function languageForPath(path: string): string;
+/** The default server for a language, or `undefined` when the table has no entry. */
+export declare function defaultServerFor(language: string): LspServerCommand | undefined;
+/** A session as reported to a caller. */
+export interface LspSessionInfo {
+    readonly connectionId: string;
+    readonly root: string;
+    readonly language: string;
+    readonly command: string;
+    readonly id: string;
+    readonly stopped: boolean;
+}
+/**
+ * A transport as seen by the registry: **possibly** LSP-capable.
+ *
+ * Tier 1 (plain `ssh host 'cmd'`) has no LSP methods at all, and the registry must say so instead of
+ * assuming. Callers get a clear "this connection cannot run a language server" rather than a TypeError on
+ * an undefined method.
+ */
+export type MaybeLspTransport = Partial<LspTransportLike>;
+export interface LspRegistryDeps {
+    /** Acquire the transport for a connection; same shape the other tools use. */
+    acquire(connectionId: string): Promise<MaybeLspTransport>;
+    /** Server log lines (`window/logMessage`), for the host log. */
+    onLog?(connectionId: string, message: string): void;
+}
+export interface LspRegistry {
+    /**
+     * The session for this target+language, started and initialized on first use.
+     *
+     * `override` replaces the default executable — the escape hatch for a language not in the table, or for a
+     * server the caller wants to run with different arguments.
+     */
+    session(target: LspTarget, language: string, override: LspServerCommand | undefined, signal: AbortSignal): Promise<LspSession>;
+    list(): readonly LspSessionInfo[];
+    /** Close one session. Returns false when there was nothing to close. */
+    stop(target: LspTarget, language: string, signal: AbortSignal): Promise<boolean>;
+    /** Close every session. Called on plugin teardown. */
+    disposeAll(): Promise<void>;
+}
+export declare function createLspRegistry(deps: LspRegistryDeps): LspRegistry;
+/** Diagnostics grouped for rendering. Re-exported so the tool does not import the session module directly. */
+export type { LspDiagnostic };
+//# sourceMappingURL=lsp-registry.d.ts.map

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

@@ -0,0 +1,130 @@
+/**
+ * One language-server session, driven over the agent's byte pipe.
+ *
+ * The agent spawns the server and moves bytes; **it does not parse JSON-RPC**
+ * ([protocol.md §lsp.*](../../../../dsh-over-ssh-agent/doc/01-product/protocol.md), ADR-0006). Everything
+ * LSP-aware lives here: the `initialize` handshake, request/response correlation, server→client requests,
+ * and diagnostics collection.
+ *
+ * The transport is poll-based (`lsp.read` with an offset), so this class owns a pump loop. It backs off
+ * while the server is quiet — a language server is idle most of the time, and polling it at full speed
+ * would spend the SSH connection on nothing.
+ *
+ * @module dsh-over-ssh/host/integration/lsp/lsp-session
+ */
+import type { AgentLspRead, AgentLspStartRequest, AgentLspStatus } from '../../infra/transport/agent/agent-protocol-types.ts';
+/** The slice of an agent transport one session needs. */
+export interface LspTransportLike {
+    /**
+     * Host capabilities, when the transport exposes them (`Transport.capabilities`).
+     *
+     * Optional because the byte pipe itself does not need them — only the registry's "is this server
+     * installed" check does.
+     */
+    readonly capabilities?: {
+        readonly lspServers?: readonly {
+            readonly command: string;
+            readonly language: string;
+            readonly path: string;
+        }[];
+    };
+    lspStart(request: AgentLspStartRequest, signal?: AbortSignal): Promise<AgentLspStatus>;
+    lspWrite(id: string, bytes: Uint8Array, signal?: AbortSignal): Promise<{
+        readonly id: string;
+        readonly written: number;
+        readonly state: string;
+    }>;
+    lspRead(id: string, offset?: number, signal?: AbortSignal): Promise<AgentLspRead>;
+    lspStop(id: string, signal?: AbortSignal): Promise<AgentLspStatus>;
+    /**
+     * Release a finished session's agent-side record and output buffer.
+     *
+     * Optional: only the agent transport has it. Absent means the agent will evict the row by itself later,
+     * which is correct — just slower to reclaim.
+     */
+    lspForget?(id: string, signal?: AbortSignal): Promise<void>;
+}
+/** One diagnostic, flattened to what a caller needs. */
+export interface LspDiagnostic {
+    readonly line: number;
+    readonly character: number;
+    readonly endLine: number;
+    readonly endCharacter: number;
+    /** `error` / `warning` / `information` / `hint`. */
+    readonly severity: string;
+    readonly message: string;
+    /** `file` / `warning` / `info` / `hint`, when the server sent one. */
+    readonly source?: string;
+}
+/** A server that failed to answer in time, or exited, must not leave callers hanging. */
+export declare class LspSessionError extends Error {
+}
+export interface LspSessionOptions {
+    /** Executable name on PATH or absolute path. */
+    readonly command: string;
+    readonly args?: readonly string[];
+    /** Working directory; language servers use it to find project config. */
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    /** Called for `window/logMessage` and similar, for diagnostics. */
+    readonly onLog?: (message: string) => void;
+}
+/**
+ * One running language server.
+ *
+ * Lifecycle: {@link start} → {@link initialize} → queries → {@link close}.
+ */
+export declare class LspSession {
+    #private;
+    constructor(transport: LspTransportLike, options: LspSessionOptions);
+    /** The agent's session id. Empty until {@link start}. */
+    get id(): string;
+    /** True once the server has exited or the session was stopped. */
+    get stopped(): boolean;
+    /** Start the server process and begin pumping its output. */
+    start(signal: AbortSignal): Promise<void>;
+    /** The `initialize` / `initialized` handshake. */
+    initialize(rootPath: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Ask for diagnostics on one document.
+     *
+     * Diagnostics are **pushed**: the server sends `textDocument/publishDiagnostics` after `didOpen` or
+     * `didChange`, with no request to correlate against. So this opens the document, then waits for a
+     * notification for that URI (or the timeout). A server that never publishes yields an empty list rather
+     * than an error — "no diagnostics" and "did not answer" look the same to a caller that only wants to
+     * know whether the file is clean.
+     */
+    diagnostics(uri: string, text: string, signal: AbortSignal, timeoutMs?: number): Promise<{
+        readonly diagnostics: readonly LspDiagnostic[];
+        readonly answered: boolean;
+    }>;
+    /**
+     * Open a document, or send the new text if it is already open.
+     *
+     * Position-based queries (`hover`, `definition`) need this first: a server answers about documents it
+     * knows, and an unopened file gets an empty result rather than an error — which reads as "no symbol here".
+     */
+    openDocument(uri: string, text: string): void;
+    /** Diagnostics already received for a URI, without asking again. */
+    cachedDiagnostics(uri: string): readonly LspDiagnostic[] | undefined;
+    /** One `textDocument/hover` query. */
+    hover(uri: string, line: number, character: number, signal: AbortSignal): Promise<unknown>;
+    /** One `textDocument/definition` query. */
+    definition(uri: string, line: number, character: number, signal: AbortSignal): Promise<unknown>;
+    /** Send one JSON-RPC request and wait for its response. */
+    request(method: string, params: unknown, signal: AbortSignal, timeoutMs?: number): Promise<unknown>;
+    /** Send one JSON-RPC notification (no response expected). */
+    notify(method: string, params: unknown): void;
+    /** Shut the server down politely, then stop it. */
+    close(signal: AbortSignal): Promise<void>;
+}
+/**
+ * Absolute path → `file://` URI.
+ *
+ * Percent-encoding matters: a path with a space or a Chinese character becomes a URI the server will not
+ * match against its own, and every subsequent `didOpen` silently does nothing.
+ */
+export declare function pathToUri(absolute: string): string;
+/** `file://` URI → absolute path. */
+export declare function uriToPath(uri: string): string;
+//# sourceMappingURL=lsp-session.d.ts.map

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

@@ -0,0 +1,64 @@
+/**
+ * The management tool surface: `remote_transfer` (upload/download) and `remote_delete` (recycle/permanent).
+ *
+ * `remote_delete` is the reason this module exists separately from `remote-tools.ts`: a **permanent** delete
+ * bypasses `ctx.fs` and cannot be undone, so it goes through the platform's pre-execute waterfall and is
+ * answered with `ask` (which the registry turns into a denial when the composition has no approval surface —
+ * fail closed). Recycle mode is an ordinary call: it is recoverable and `undo` exists.
+ *
+ * @module dsh-remote-workspace/integration/management-tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { DiscardResult } from '../app/recycle-bin-service.ts';
+import type { TransferResult } from './transfer-service.ts';
+/** Where one call lands. */
+export interface ManagementTarget {
+    readonly connectionId: string;
+    /** Backend-absolute root path. */
+    readonly root: string;
+}
+/** What the tools need, injected so the definitions stay testable without transports. */
+export interface ManagementToolBackend {
+    /** Resolve the calling agent's working directory to a remote root. */
+    resolve(cwd: string): ManagementTarget | undefined;
+    /** Run one upload or download. */
+    transfer(request: {
+        readonly target: ManagementTarget;
+        readonly direction: 'upload' | 'download';
+        readonly localPath: string;
+        readonly remotePath: string;
+        readonly signal: AbortSignal;
+    }): Promise<TransferResult>;
+    /** Discard one path, into the bin or permanently. */
+    discard(request: {
+        readonly target: ManagementTarget;
+        readonly path: string;
+        readonly mode: 'recycle' | 'permanent';
+        readonly signal: AbortSignal;
+    }): Promise<DiscardResult>;
+}
+/** Human summary of a finished transfer. */
+export declare function formatTransfer(result: TransferResult): string;
+/** Human summary of a discard. */
+export declare function formatDiscard(result: DiscardResult): string;
+/**
+ * Build the two definitions.
+ *
+ * @param backend - injected implementations.
+ * @returns definitions ready for `ctx.tools.register`.
+ */
+export declare function managementToolDefinitions(backend: ManagementToolBackend): ToolDefinition[];
+/**
+ * Gate irreversible deletions behind the platform's approval surface.
+ *
+ * A **denial by default** is deliberate: when the composition has no approval support, the registry turns
+ * `ask` into a denial, which is the right outcome for an operation that bypasses `ctx.fs` and cannot be undone.
+ *
+ * @param ctx - host context with the `tools` service.
+ * @returns a disposer removing the gate.
+ */
+export declare function permanentDeleteGate(ctx: Context): () => void;
+/** Register both tools and the gate. */
+export declare function registerManagementTools(ctx: Context, backend: ManagementToolBackend): () => void;
+//# sourceMappingURL=management-tools.d.ts.map