dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/config.d.ts

@@ -0,0 +1,312 @@
+/**
+ * The plugin's configuration schema — **the only copy**.
+ *
+ * ## Why this is its own module
+ *
+ * The 84-line `z.object({...})` used to exist twice, byte for byte: once as `export const Config` in the entry
+ * (`src/index.ts`) and once in `src/wiring/helpers.ts`. Cordis only ever reads the **entry's** `Config`, so the
+ * wiring copy was dead as a value — but it still fed `ResolvedConfig`, the type every wiring function takes.
+ *
+ * That split is the dangerous part: adding a field to one copy and not the other leaves the **type** and the
+ * **runtime** disagreeing, and `tsc` stays silent because both copies type-check on their own. The next
+ * `config.limits.<newField>` would be `undefined` at runtime while the type says otherwise.
+ *
+ * Neither file can own it directly — `helpers.ts` importing the entry would make the entry depend on wiring and
+ * wiring on the entry. A third module is the only place both can depend on without a cycle.
+ *
+ * @module dsh-over-ssh/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Validated configuration schema (defaults are the documented defaults). */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    connections: z<({
+        id?: string | null;
+        name?: string | null;
+        host?: string | null;
+        port?: number | null;
+        user?: string | null;
+        transport?: "alias" | "ssh2" | "agent" | null;
+        alias?: string | null;
+        authKind?: "agent" | "key" | "password" | null;
+        keyPath?: string | null;
+        credentialKey?: string | null;
+        proxyJump?: string[] | null;
+        hostKeyPolicy?: "strict" | "accept-new" | null;
+        remoteDefaultRoot?: string | null;
+    } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<NoInfer<{
+        id: z<string, string, "defined">;
+        name: z<string, string, "plain">;
+        host: z<string, string, "defined">;
+        port: z<number, number, "defined">;
+        user: z<string, string, "defined">;
+        transport: z<"alias" | "ssh2" | "agent", "alias" | "ssh2" | "agent", "defined">;
+        alias: z<string, string, "plain">;
+        authKind: z<"agent" | "key" | "password", "agent" | "key" | "password", "defined">;
+        keyPath: z<string, string, "plain">;
+        credentialKey: z<string, string, "plain">;
+        proxyJump: z<string[], string[], "defined">;
+        hostKeyPolicy: z<"strict" | "accept-new", "strict" | "accept-new", "defined">;
+        remoteDefaultRoot: z<string, string, "plain">;
+    }>>[], "defined">;
+    roots: z<({
+        location?: "local" | "remote" | null;
+        path?: string | null;
+        connectionId?: string | null;
+        label?: string | null;
+        writable?: boolean | null;
+        anchorPath?: string | null;
+    } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<NoInfer<{
+        location: z<"local" | "remote", "local" | "remote", "defined">;
+        path: z<string, string, "defined">;
+        connectionId: z<string, string, "plain">;
+        label: z<string, string, "plain">;
+        writable: z<boolean, boolean, "defined">;
+        anchorPath: z<string, string, "plain">;
+    }>>[], "defined">;
+    limits: z<Schemastery.ObjectS<NoInfer<{
+        maxReadBytes: z<number, number, "defined">;
+        connectTimeoutMs: z<number, number, "defined">;
+        commandTimeoutMs: z<number, number, "defined">;
+        keepAliveSeconds: z<number, number, "defined">;
+        controlDir: z<string, string, "plain">;
+        knownHostsFile: z<string, string, "plain">;
+        /** Manifest shipped with the package; defaults to `<package>/agents/agent-manifest.json`. */
+        agentManifestPath: z<string, string, "plain">;
+        /** Remote directory the agent is installed into (under the login user's `$HOME`). */
+        agentRemoteDir: z<string, string, "defined">;
+        indexTtlMs: z<number, number, "defined">;
+        indexMaxEntries: z<number, number, "defined">;
+        /**
+         * Read-path freshness window (FR-2.7: the requirement names 5 s).
+         *
+         * `0` disables retention, so every read goes to the host — the honest escape hatch for a host where
+         * the clock or the mtime granularity makes `size:seconds` a weak version token.
+         */
+        readCacheTtlMs: z<number, number, "defined">;
+        readCacheMaxEntries: z<number, number, "defined">;
+        readCacheMaxBytes: z<number, number, "defined">;
+        terminalStateDir: z<string, string, "plain">;
+        transferChunkBytes: z<number, number, "defined">;
+        /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
+        transferConcurrency: z<number, number, "defined">;
+        /** How many finished transfers the progress table retains (FR-2.6.4). */
+        transferHistoryEntries: z<number, number, "defined">;
+        binDir: z<string, string, "defined">;
+        binMaxEntries: z<number, number, "defined">;
+        binMaxBytes: z<number, number, "defined">;
+        binMaxAgeMs: z<number, number, "defined">;
+        undoDepth: z<number, number, "defined">;
+        rangeChunkBytes: z<number, number, "defined">;
+        /** Session store root; defaults to the platform's `~/.dsh/sessions`. */
+        sessionsRoot: z<string, string, "plain">;
+        /**
+         * Session recycle bin root (FR-3.5).
+         *
+         * **Must not live under {@link sessionsRoot}**: the platform lists every directory under the sessions
+         * root and fails the whole listing on a duplicate session id, so a bin there would make deleted
+         * sessions reappear. See ADR-0009.
+         */
+        sessionBinRoot: z<string, string, "plain">;
+        sessionBinMaxEntries: z<number, number, "defined">;
+        sessionBinMaxBytes: z<number, number, "defined">;
+        sessionBinMaxAgeMs: z<number, number, "defined">;
+        /** Delete the projection cache alongside the log when true (FR-3.4 step 8). */
+        sessionPurgeProjection: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        maxReadBytes: z<number, number, "defined">;
+        connectTimeoutMs: z<number, number, "defined">;
+        commandTimeoutMs: z<number, number, "defined">;
+        keepAliveSeconds: z<number, number, "defined">;
+        controlDir: z<string, string, "plain">;
+        knownHostsFile: z<string, string, "plain">;
+        /** Manifest shipped with the package; defaults to `<package>/agents/agent-manifest.json`. */
+        agentManifestPath: z<string, string, "plain">;
+        /** Remote directory the agent is installed into (under the login user's `$HOME`). */
+        agentRemoteDir: z<string, string, "defined">;
+        indexTtlMs: z<number, number, "defined">;
+        indexMaxEntries: z<number, number, "defined">;
+        /**
+         * Read-path freshness window (FR-2.7: the requirement names 5 s).
+         *
+         * `0` disables retention, so every read goes to the host — the honest escape hatch for a host where
+         * the clock or the mtime granularity makes `size:seconds` a weak version token.
+         */
+        readCacheTtlMs: z<number, number, "defined">;
+        readCacheMaxEntries: z<number, number, "defined">;
+        readCacheMaxBytes: z<number, number, "defined">;
+        terminalStateDir: z<string, string, "plain">;
+        transferChunkBytes: z<number, number, "defined">;
+        /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
+        transferConcurrency: z<number, number, "defined">;
+        /** How many finished transfers the progress table retains (FR-2.6.4). */
+        transferHistoryEntries: z<number, number, "defined">;
+        binDir: z<string, string, "defined">;
+        binMaxEntries: z<number, number, "defined">;
+        binMaxBytes: z<number, number, "defined">;
+        binMaxAgeMs: z<number, number, "defined">;
+        undoDepth: z<number, number, "defined">;
+        rangeChunkBytes: z<number, number, "defined">;
+        /** Session store root; defaults to the platform's `~/.dsh/sessions`. */
+        sessionsRoot: z<string, string, "plain">;
+        /**
+         * Session recycle bin root (FR-3.5).
+         *
+         * **Must not live under {@link sessionsRoot}**: the platform lists every directory under the sessions
+         * root and fails the whole listing on a duplicate session id, so a bin there would make deleted
+         * sessions reappear. See ADR-0009.
+         */
+        sessionBinRoot: z<string, string, "plain">;
+        sessionBinMaxEntries: z<number, number, "defined">;
+        sessionBinMaxBytes: z<number, number, "defined">;
+        sessionBinMaxAgeMs: z<number, number, "defined">;
+        /** Delete the projection cache alongside the log when true (FR-3.4 step 8). */
+        sessionPurgeProjection: z<boolean, boolean, "defined">;
+    }>>, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    connections: z<({
+        id?: string | null;
+        name?: string | null;
+        host?: string | null;
+        port?: number | null;
+        user?: string | null;
+        transport?: "alias" | "ssh2" | "agent" | null;
+        alias?: string | null;
+        authKind?: "agent" | "key" | "password" | null;
+        keyPath?: string | null;
+        credentialKey?: string | null;
+        proxyJump?: string[] | null;
+        hostKeyPolicy?: "strict" | "accept-new" | null;
+        remoteDefaultRoot?: string | null;
+    } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<NoInfer<{
+        id: z<string, string, "defined">;
+        name: z<string, string, "plain">;
+        host: z<string, string, "defined">;
+        port: z<number, number, "defined">;
+        user: z<string, string, "defined">;
+        transport: z<"alias" | "ssh2" | "agent", "alias" | "ssh2" | "agent", "defined">;
+        alias: z<string, string, "plain">;
+        authKind: z<"agent" | "key" | "password", "agent" | "key" | "password", "defined">;
+        keyPath: z<string, string, "plain">;
+        credentialKey: z<string, string, "plain">;
+        proxyJump: z<string[], string[], "defined">;
+        hostKeyPolicy: z<"strict" | "accept-new", "strict" | "accept-new", "defined">;
+        remoteDefaultRoot: z<string, string, "plain">;
+    }>>[], "defined">;
+    roots: z<({
+        location?: "local" | "remote" | null;
+        path?: string | null;
+        connectionId?: string | null;
+        label?: string | null;
+        writable?: boolean | null;
+        anchorPath?: string | null;
+    } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<NoInfer<{
+        location: z<"local" | "remote", "local" | "remote", "defined">;
+        path: z<string, string, "defined">;
+        connectionId: z<string, string, "plain">;
+        label: z<string, string, "plain">;
+        writable: z<boolean, boolean, "defined">;
+        anchorPath: z<string, string, "plain">;
+    }>>[], "defined">;
+    limits: z<Schemastery.ObjectS<NoInfer<{
+        maxReadBytes: z<number, number, "defined">;
+        connectTimeoutMs: z<number, number, "defined">;
+        commandTimeoutMs: z<number, number, "defined">;
+        keepAliveSeconds: z<number, number, "defined">;
+        controlDir: z<string, string, "plain">;
+        knownHostsFile: z<string, string, "plain">;
+        /** Manifest shipped with the package; defaults to `<package>/agents/agent-manifest.json`. */
+        agentManifestPath: z<string, string, "plain">;
+        /** Remote directory the agent is installed into (under the login user's `$HOME`). */
+        agentRemoteDir: z<string, string, "defined">;
+        indexTtlMs: z<number, number, "defined">;
+        indexMaxEntries: z<number, number, "defined">;
+        /**
+         * Read-path freshness window (FR-2.7: the requirement names 5 s).
+         *
+         * `0` disables retention, so every read goes to the host — the honest escape hatch for a host where
+         * the clock or the mtime granularity makes `size:seconds` a weak version token.
+         */
+        readCacheTtlMs: z<number, number, "defined">;
+        readCacheMaxEntries: z<number, number, "defined">;
+        readCacheMaxBytes: z<number, number, "defined">;
+        terminalStateDir: z<string, string, "plain">;
+        transferChunkBytes: z<number, number, "defined">;
+        /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
+        transferConcurrency: z<number, number, "defined">;
+        /** How many finished transfers the progress table retains (FR-2.6.4). */
+        transferHistoryEntries: z<number, number, "defined">;
+        binDir: z<string, string, "defined">;
+        binMaxEntries: z<number, number, "defined">;
+        binMaxBytes: z<number, number, "defined">;
+        binMaxAgeMs: z<number, number, "defined">;
+        undoDepth: z<number, number, "defined">;
+        rangeChunkBytes: z<number, number, "defined">;
+        /** Session store root; defaults to the platform's `~/.dsh/sessions`. */
+        sessionsRoot: z<string, string, "plain">;
+        /**
+         * Session recycle bin root (FR-3.5).
+         *
+         * **Must not live under {@link sessionsRoot}**: the platform lists every directory under the sessions
+         * root and fails the whole listing on a duplicate session id, so a bin there would make deleted
+         * sessions reappear. See ADR-0009.
+         */
+        sessionBinRoot: z<string, string, "plain">;
+        sessionBinMaxEntries: z<number, number, "defined">;
+        sessionBinMaxBytes: z<number, number, "defined">;
+        sessionBinMaxAgeMs: z<number, number, "defined">;
+        /** Delete the projection cache alongside the log when true (FR-3.4 step 8). */
+        sessionPurgeProjection: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        maxReadBytes: z<number, number, "defined">;
+        connectTimeoutMs: z<number, number, "defined">;
+        commandTimeoutMs: z<number, number, "defined">;
+        keepAliveSeconds: z<number, number, "defined">;
+        controlDir: z<string, string, "plain">;
+        knownHostsFile: z<string, string, "plain">;
+        /** Manifest shipped with the package; defaults to `<package>/agents/agent-manifest.json`. */
+        agentManifestPath: z<string, string, "plain">;
+        /** Remote directory the agent is installed into (under the login user's `$HOME`). */
+        agentRemoteDir: z<string, string, "defined">;
+        indexTtlMs: z<number, number, "defined">;
+        indexMaxEntries: z<number, number, "defined">;
+        /**
+         * Read-path freshness window (FR-2.7: the requirement names 5 s).
+         *
+         * `0` disables retention, so every read goes to the host — the honest escape hatch for a host where
+         * the clock or the mtime granularity makes `size:seconds` a weak version token.
+         */
+        readCacheTtlMs: z<number, number, "defined">;
+        readCacheMaxEntries: z<number, number, "defined">;
+        readCacheMaxBytes: z<number, number, "defined">;
+        terminalStateDir: z<string, string, "plain">;
+        transferChunkBytes: z<number, number, "defined">;
+        /** Chunks in flight at once during a transfer. 1 restores the sequential behaviour. */
+        transferConcurrency: z<number, number, "defined">;
+        /** How many finished transfers the progress table retains (FR-2.6.4). */
+        transferHistoryEntries: z<number, number, "defined">;
+        binDir: z<string, string, "defined">;
+        binMaxEntries: z<number, number, "defined">;
+        binMaxBytes: z<number, number, "defined">;
+        binMaxAgeMs: z<number, number, "defined">;
+        undoDepth: z<number, number, "defined">;
+        rangeChunkBytes: z<number, number, "defined">;
+        /** Session store root; defaults to the platform's `~/.dsh/sessions`. */
+        sessionsRoot: z<string, string, "plain">;
+        /**
+         * Session recycle bin root (FR-3.5).
+         *
+         * **Must not live under {@link sessionsRoot}**: the platform lists every directory under the sessions
+         * root and fails the whole listing on a duplicate session id, so a bin there would make deleted
+         * sessions reappear. See ADR-0009.
+         */
+        sessionBinRoot: z<string, string, "plain">;
+        sessionBinMaxEntries: z<number, number, "defined">;
+        sessionBinMaxBytes: z<number, number, "defined">;
+        sessionBinMaxAgeMs: z<number, number, "defined">;
+        /** Delete the projection cache alongside the log when true (FR-3.4 step 8). */
+        sessionPurgeProjection: z<boolean, boolean, "defined">;
+    }>>, "defined">;
+}>>, "plain">;
+/** What {@link apply} receives: the schema's resolved output, which is what the loader passes. */
+export type ResolvedConfig = Schemastery.TypeT<typeof Config>;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/src/file-references.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The `./file-references` entry: the multi-root `ctx.fileReferences` provider.
+ *
+ * Enabling this module **replaces** the core `dsh-file-reference-local` row (one local workspace) with a
+ * provider that also serves remote roots - the same shape as `./fs` replacing `fs-sandbox`. The provider
+ * answers for local roots too, so a workspace mixing both kinds stays complete.
+ *
+ * **Both rows must be switched together.** Cordis refuses a second service with the same name, so enabling
+ * this entry while `file-reference-local` is still active used to fail activation and the plugin-manager row
+ * showed "异常". A takeover is a composition decision, so this entry now **degrades instead of throwing**:
+ * when `fileReferences` is already provided it logs why and leaves the core provider in place. To really take
+ * over, disable the core row (see cordis.patch.yml, stage 2) and then enable this one.
+ *
+ * @module dsh-over-ssh/file-references
+ */
+import { Context } from '@deepseek-ai/cordis';
+/**
+ * Install the multi-root provider, unless something else already owns `fileReferences`.
+ *
+ * @param ctx - plugin context.
+ * @returns the provider's fiber, or `undefined` when the core provider keeps the service.
+ */
+export default function apply(ctx: Context): (import("@deepseek-ai/cordis").Fiber & PromiseLike<import("@deepseek-ai/cordis").Fiber>) | undefined;
+export { RemoteFileReferenceService, DEFAULT_MAX_RESULTS, LOCAL_EXCLUDED_DIRECTORIES, LOCAL_MAX_DEPTH, LOCAL_MAX_ENTRIES, type FileReferenceIndex, type LocalEntry, type RemoteFileReferenceOptions, } from './host/integration/fs/file-reference-provider.ts';
+//# sourceMappingURL=file-references.d.ts.map

package/lib/types/src/fs.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The `./fs` entry: the filesystem provider as a Cordis service package.
+ *
+ * The composition replaces the core `fs-sandbox` row with this module (see `cordis.patch.yml`), so the
+ * model's file tools follow the plugin's router without any consumer change.
+ *
+ * Two registration shapes exist, and both are exported:
+ *
+ *  - the **class** (`RoutedFsProvider`) — what `ctx.plugin(RoutedFsProvider)` installs; every read keeps the
+ *    original whole-prefix semantics;
+ *  - this module's **default function plugin** — it reads `ctx.sshDevRangeReader` when the main entry is
+ *    loaded and hands it to {@link createRoutedFsProvider}, so a large remote read becomes several bounded
+ *    offset requests instead of one `[0, end)` prefix read.
+ *
+ * @module dsh-over-ssh/fs
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { RoutedFsProvider, createRoutedFsProvider, toFsError, MAPPED_DOMAIN_CODES, type BackendRangeReader } from './host/integration/fs/fs-provider.ts';
+/** The optional capability the main entry publishes. */
+export interface RangeReaderService {
+    readonly readBytesRange: BackendRangeReader;
+    readonly rangeChunkBytes?: number;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Offset-read capability for routed backends, present when the main entry is loaded. */
+        sshDevRangeReader?: RangeReaderService;
+    }
+}
+/**
+ * Install the provider, using the chunked read when the capability is available.
+ *
+ * The capability is read through `ctx.get` instead of being declared in `inject`: the provider must still
+ * install when the main entry is absent — it then keeps the old read semantics rather than failing to load.
+ *
+ * The returned fiber **must be handed back** to the loader. Returning `undefined` here makes Cordis treat
+ * the entry as "did nothing": the plugin is installed as a child fiber, but the row never reaches the
+ * active state and every consumer waiting on `fs` stays pending forever. The early return below is the
+ * only case that legitimately answers nothing (a takeover that another provider already owns).
+ *
+ * @param ctx - plugin context.
+ * @returns the provider plugin's fiber, or `undefined` when the takeover is skipped.
+ */
+export default function apply(ctx: Context): (import("@deepseek-ai/cordis").Fiber & PromiseLike<import("@deepseek-ai/cordis").Fiber>) | undefined;
+export { RoutedFsProvider, createRoutedFsProvider, toFsError, MAPPED_DOMAIN_CODES };
+//# sourceMappingURL=fs.d.ts.map

package/lib/types/src/host/app/backend.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The backend contract: what the router needs from any one root.
+ *
+ * A "root" is served by exactly one backend: the local disk, or one remote connection's transport.
+ * The router (`routed-fs.ts`) never talks to a filesystem directly — it resolves a path to a root
+ * and hands the root-absolute path to that backend. That split is what lets one workspace mix local
+ * and remote roots (ADR-0003), and it keeps every backend testable on its own.
+ *
+ * Contract notes:
+ *
+ *  - Paths crossing this boundary are **root-absolute in the backend's own spelling** (POSIX for
+ *    remote, host paths for local). The router owns all translation.
+ *  - `version` is an opaque token that must change whenever the content changes. Tokens are only
+ *    compared **within one backend**; the router keys its cache by backend, not globally.
+ *  - `stat` never throws for a missing path: it returns `exists: false`, so "create if absent"
+ *    flows need one round trip rather than an error path.
+ *
+ * @module dsh-over-ssh/app/backend
+ */
+/** One directory entry, as reported by a backend. */
+export interface BackendEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+    readonly isSymlink: boolean;
+    /** 0 for directories and for backends that cannot cheaply report sizes. */
+    readonly size: number;
+    /** Milliseconds since the epoch; 0 when unknown. */
+    readonly mtimeMs: number;
+    /**
+     * 这一项自己的版本令牌，由后端给出。
+     *
+     * 为什么不由消费方用 `size:mtimeMs` 现算：那样算出来的令牌没有 inode，而原子写换 inode 是唯一
+     * 与 mtime 精度无关的「换过文件」信号。只有后端手里有 stat 结果，所以令牌由它给。
+     */
+    readonly version?: string;
+}
+/** Metadata for one path. */
+export interface BackendStat {
+    readonly exists: boolean;
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+    readonly isSymlink: boolean;
+    readonly size: number;
+    readonly mtimeMs: number;
+    /** Opaque change token; empty when the backend cannot provide one. */
+    readonly version: string;
+}
+/** Bytes read from a backend. */
+export interface BackendRead {
+    readonly bytes: Uint8Array;
+    /** Full size of the file when known, not the length of `bytes`. */
+    readonly size: number;
+    readonly truncated: boolean;
+    readonly version: string;
+}
+/** Text read from a backend. */
+export interface BackendText {
+    readonly text: string;
+    readonly size: number;
+    readonly truncated: boolean;
+    readonly version: string;
+}
+/** Outcome of a write. */
+export interface BackendWrite {
+    readonly bytes: number;
+    /** Version observed after the write, when the backend can report it cheaply. */
+    readonly version: string;
+}
+/** How a backend confines writes, mirroring the core's `SandboxMode`. */
+export type BackendSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** One backend serving one root. */
+export interface Backend {
+    /** Stable id, also the namespace prefix of every target key it produces. */
+    readonly id: string;
+    /** Whether the backend's own confinement applies, or `undefined` when it has none. */
+    readonly sandboxMode: BackendSandboxMode | undefined;
+    /** Whether the backend can watch for changes natively. */
+    readonly watches: boolean;
+    /**
+     * Watch one path for changes, in this backend's own absolute spelling (the backend layer has no `FsTarget`).
+     *
+     * The callback shape is the platform's own (`FsProvider.watch`): `changed()` means "re-stat this path, it
+     * may have changed"; `changed(error)` means the **watcher itself** failed and the subscription must be
+     * treated as dead. The returned function stops the watcher and must be idempotent.
+     *
+     * Optional on purpose: a backend that cannot watch (a local world without the platform seat, a Tier 1
+     * remote root) omits it and the provider keeps answering `FS_IO_ERROR` — the pre-existing refusal, never a
+     * silent no-op that would make a file panel look live while it never refreshes.
+     */
+    watch?(absolute: string, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
+    stat(absolute: string, signal?: AbortSignal): Promise<BackendStat>;
+    /**
+     * Stat the path entry itself, without following a final symlink.
+     *
+     * Optional: a backend that cannot distinguish a link from its target simply omits it, and the
+     * router falls back to {@link stat} (reporting `isSymlink: false`).
+     */
+    lstat?(absolute: string, signal?: AbortSignal): Promise<BackendStat>;
+    list(absolute: string, signal?: AbortSignal): Promise<readonly BackendEntry[]>;
+    readBytes(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendRead>;
+    readText(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendText>;
+    /**
+     * Write text, atomically where the backend can.
+     *
+     * @param expectedVersion - when non-empty the write must fail if the current version differs.
+     */
+    writeText(absolute: string, text: string, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite>;
+    /**
+     * Apply a unified diff to one file, atomically.
+     *
+     * Optional: only backends with a server-side patcher implement it. Absent means the caller must refuse
+     * rather than approximate the result with a read-modify-write it cannot make atomic on the far side.
+     */
+    patchText?(absolute: string, diff: string, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite & {
+        readonly hunks: number;
+    }>;
+    /**
+     * Atomic in-place edit (审计 0030), when the backend can do it without shipping the whole file back.
+     *
+     * Optional: a backend that omits it makes `ctx.fs` fall back to read → replace → write. When present it must
+     * apply the **same** three-state semantics as that fallback (not found / ambiguous / replaceAll) and
+     * must honour `expectedVersion` across its own read-modify-write.
+     */
+    editText?(absolute: string, oldString: string, newString: string, replaceAll: boolean, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite & {
+        readonly replaced: number;
+    }>;
+    /**
+     * Create a directory, and its parents when asked (FR-2.2.2: the file tree's 「新建目录」).
+     *
+     * Optional: a backend that cannot create directories simply omits it, and the route answers an explicit
+     * failure rather than a silent no-op. `recursive: false` must **fail** when the parent is missing or the
+     * target exists — a non-recursive mkdir that succeeds on an existing directory is indistinguishable from a
+     * successful creation, which is how a rename dialog ends up overwriting a folder.
+     */
+    mkdir?(absolute: string, options: {
+        readonly recursive: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Rename (or move) a path, creating the destination's parents when asked (FR-2.2.2: 「重命名」).
+     *
+     * Must **refuse** to clobber an existing destination: the failure has to be visible, because the caller's
+     * intent was a rename and silently replacing a directory would be data loss.
+     */
+    rename?(from: string, to: string, options: {
+        readonly createParents: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Remove a path (FR-2.2.2: 「删除」). `recursive: false` refuses a non-empty directory.
+     *
+     * The recycle-bin path (`remote_delete` with `mode: 'recycle'`) is a *rename*, not this: this is the plain
+     * removal the file tree's delete action uses after the user confirmed it.
+     */
+    remove?(absolute: string, options: {
+        readonly recursive: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Change one path's permission bits, as a 3-4 digit **octal string** (`"755"`).
+     *
+     * Optional, and deliberately one narrow operation: `remote_write` needs it so a written build or probe
+     * script can be executed, and nothing else in this plugin does. A string rather than a number because the
+     * caller's `755` is octal digits, not decimal seven hundred and fifty-five, and that confusion is silent.
+     */
+    chmod?(absolute: string, mode: string, signal?: AbortSignal): Promise<void>;
+    /** Host path a child process in this backend's world can open, if any. */
+    processPath?(absolute: string): string | undefined;
+    /** `file:` URL for this path in the backend's world. */
+    fileUrl?(absolute: string): string;
+}
+//# sourceMappingURL=backend.d.ts.map