dsh-over-ssh 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,141 @@
+/**
+ * Multi-root implementation of the core `ctx.fileReferences` seam.
+ *
+ * The core ships [`@deepseek-ai/dsh-file-reference-local`] for **one** local workspace. This plugin's whole
+ * point is several roots of two kinds, so this provider answers the same contract for both:
+ *
+ *  - a **remote** root is enumerated by {@link RemoteIndex} (Tier 2 `index.scan` when the connection has an
+ *    agent, else one bounded `find`/`git ls-files`), cached per root;
+ *  - a **local** root is enumerated here with a bounded walk, because installing this provider **replaces**
+ *    the core's local one — returning nothing for local agents would be a regression, not a feature.
+ *
+ * Candidate paths use the router's display spelling (`ssh://<connection>/abs` for remote roots) so a token
+ * stays unambiguous in a multi-root workspace; the local case keeps ordinary host paths.
+ *
+ * @module dsh-over-ssh/integration/file-reference-provider
+ */
+import { Context } from '@deepseek-ai/cordis';
+import FileReferenceService, { type FileReferenceCandidate } from '@deepseek-ai/dsh-file-reference';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { SessionIdentity, SessionRootOutcome } from '../../domain/roots/session-roots.ts';
+/** The ADR-0013 session-root rule, published as `ctx.sshDevSessionRoots` by the main entry. */
+export interface FileReferenceSessionRoots {
+    /** Which remote root this session added with 「添加目录」, when its cwd names none. */
+    outcomeFor(workspacePath: string | undefined, identity?: SessionIdentity): SessionRootOutcome;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Session-added remote roots, shared with the tool surfaces (ADR-0013). */
+        sshDevSessionRoots?: FileReferenceSessionRoots;
+    }
+}
+/** What the provider needs from the index layer (provided as `ctx.sshDevIndex`). */
+export interface FileReferenceIndex {
+    /**
+     * Rank candidates for a partially typed `@` query inside one remote root.
+     *
+     * @param connectionId - connection that owns the root.
+     * @param root - backend-absolute remote root path.
+     * @param query - text after `@`.
+     * @param signal - caller cancellation.
+     * @returns ranked candidates whose `path` is a router-resolvable spelling
+     *   (`ssh://<connection>/abs`), so a token stays unambiguous across roots.
+     */
+    complete(connectionId: string, root: string, query: string, signal: AbortSignal): Promise<readonly FileReferenceCandidate[]>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Remote index used by the file-reference provider. */
+        sshDevIndex: FileReferenceIndex;
+    }
+}
+/** Directory names never traversed by the local walk (same intent as the core's exclusion list). */
+export declare const LOCAL_EXCLUDED_DIRECTORIES: readonly string[];
+/** Default cap for the local walk; the core uses a comparable bound for its own index. */
+export declare const LOCAL_MAX_ENTRIES = 20000;
+/** How deep the local walk may go before it gives up (protects against pathological trees). */
+export declare const LOCAL_MAX_DEPTH = 12;
+/**
+ * How long a local enumeration may be reused before the tree is walked again.
+ *
+ * **Short on purpose, and much shorter than the remote branch's 30 s** (`RemoteIndex` `ttlMs`). That cache
+ * exists to avoid a *network round trip*; this one exists only to collapse **one typing burst** into a single
+ * walk. A burst is a few keystrokes a couple of hundred milliseconds apart, so a quarter second folds the
+ * whole burst while keeping staleness below the threshold where a user could notice — creating a file and
+ * typing `@` again within 250 ms is not something a person does.
+ *
+ * The failure mode is deliberately the cheap one: a miss costs a walk, i.e. exactly today's behaviour, so
+ * this can never be *slower* than not caching, only less fresh for at most this long.
+ *
+ * Measured (`.verify/probe-local-fref-cache.ts`, 10 000-entry tree): typing `@module` walked the whole tree
+ * **6 times** and cost 413 ms; the walk is ~68 ms each, and it is paid per keystroke, on the host's event loop.
+ */
+export declare const LOCAL_CACHE_TTL_MS = 250;
+/**
+ * Cap for the local enumeration cache.
+ *
+ * Keys are registry root paths, so the set is bounded by how many roots the user registered — but it is
+ * capped anyway, for the same reason `RemoteIndex` bounds its own caches: a bound that depends on "the
+ * caller will not do that" is not a bound.
+ */
+export declare const LOCAL_MAX_CACHED_ROOTS = 8;
+/** How many candidates one query returns (the core's local provider uses the same order of magnitude). */
+export declare const DEFAULT_MAX_RESULTS = 50;
+/** One locally enumerated entry, with the kind completion needs. */
+export interface LocalEntry {
+    readonly path: string;
+    readonly kind: 'file' | 'directory';
+}
+/** Construction options; `walk` is injected so tests never touch a real filesystem. */
+export interface RemoteFileReferenceOptions {
+    /** Maximum entries collected in one local walk. Default {@link LOCAL_MAX_ENTRIES}. */
+    readonly maxEntries?: number;
+    /** Maximum depth of the local walk. Default {@link LOCAL_MAX_DEPTH}. */
+    readonly maxDepth?: number;
+    /** Maximum candidates returned per query. Default {@link DEFAULT_MAX_RESULTS}. */
+    readonly maxResults?: number;
+    /** Local enumerator, injected for tests. Defaults to a real bounded `readdir` walk. */
+    readonly walk?: (root: string, signal: AbortSignal) => Promise<readonly LocalEntry[]>;
+    /** How long a local enumeration stays reusable. Default {@link LOCAL_CACHE_TTL_MS}. */
+    readonly localTtlMs?: number;
+    /** Cap for the local enumeration cache. Default {@link LOCAL_MAX_CACHED_ROOTS}. */
+    readonly maxCachedRoots?: number;
+    /** Injectable clock, so the TTL is testable without sleeping. */
+    readonly now?: () => number;
+}
+/**
+ * The provider.
+ *
+ * Lifecycle note: it is registered as a **separate module** (`dsh-over-ssh/file-references`) so the
+ * composition decides whether to replace the core's local service — enabling it is an explicit choice.
+ */
+export declare class RemoteFileReferenceService extends FileReferenceService {
+    #private;
+    static inject: string[];
+    constructor(ctx: Context, options?: RemoteFileReferenceOptions);
+    /**
+     * List candidates for one agent's working directory.
+     *
+     * **The session cwd always answers, even when no registered root covers it** (FR-1.9 / ADR-0012).
+     * Stage 2 mounts this provider as `ctx.fs`, and the workspace a session was opened on need not be a
+     * registered root — the shape that broke it is a root registered *underneath* the cwd (session
+     * `D:\project\x`, the plugin's own root `D:\project\x\dsh-over-ssh`), where no root contains
+     * the cwd and the router answers `ROOT_OUTSIDE`. `@` completion must not go dark in that workspace,
+     * so the cwd itself is used as an **implicit local root** — the same rule `routed-fs` applies to the
+     * filesystem: local only, only the cwd subtree, remote roots unchanged.
+     *
+     * The implicit root is **this session's own directory**, so session isolation (ADR-0012) is not
+     * weakened: the walk starts at the cwd and cannot reach a sibling root, and a path outside the cwd is
+     * still not offered. Containment comes from the walk's root argument rather than a per-entry filter —
+     * a filter would re-normalize up to {@link LOCAL_MAX_ENTRIES} paths on **every keystroke**, which is
+     * exactly the cost audit 0057 removed.
+     *
+     * @param agent - target agent; its session cwd decides which root answers.
+     * @param query - text after `@` (may be empty: "show the shallowest entries").
+     * @param signal - caller cancellation.
+     * @returns ranked candidates, best first; empty when nothing can answer — no registry, a remote cwd
+     *   without an index, or a cwd that is not an absolute host path.
+     */
+    list(agent: Agent, query: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
+}
+export default RemoteFileReferenceService;

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

@@ -0,0 +1,366 @@
+/**
+ * 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.
+ *  - A failed resolution first **syncs the live sessions' working directories** into session-scoped local
+ *    roots and retries once. The platform reads the workspace by absolute path *without* a cwd while a turn
+ *    starts (`agent-instructions`), so a session whose cwd no root covered used to lose the whole turn; the
+ *    sync is what makes its own directory resolvable. It costs nothing on the happy path.
+ *
+ * @module dsh-over-ssh/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;
+    /**
+     * Reads the working directories of the live sessions, for the session-root sync.
+     *
+     * Defaults to the platform's session service (`ctx.get('sessions')`, see {@link readSessionCwds}); injected
+     * here so a test can drive the sync without a Cordis host. Returning `[]` is always safe: it disables the
+     * sync and leaves every existing behaviour untouched.
+     */
+    readonly sessionWorkspaceCwds?: () => readonly string[];
+    /**
+     * The fork lineage of one session, nearest first (ADR-0013).
+     *
+     * Defaults to the platform's session service (`ctx.get('sessions')`, see {@link readSessionAncestors});
+     * injected here so a test can drive the rule without a Cordis host. Returning `[]` is always safe: a fork
+     * then simply does not inherit, which is the pre-ADR-0013 behaviour.
+     */
+    readonly sessionAncestors?: (sessionId: string) => readonly string[];
+}
+/**
+ * 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 {
+    static inject: string[];
+    protected readonly rangeReader: BackendRangeReader | undefined;
+    protected readonly rangeChunkBytes: number;
+    /** Reads the live sessions' working directories; see {@link RoutedFsProviderOptions.sessionWorkspaceCwds}. */
+    protected readonly sessionWorkspaceCwds: () => readonly string[];
+    /** Reads one session's fork lineage; see {@link RoutedFsProviderOptions.sessionAncestors}. */
+    protected readonly sessionAncestors: (sessionId: string) => readonly string[];
+    /**
+     * Change detector for {@link syncSessionRoots}: the state the last sync produced.
+     *
+     * A small mutable holder rather than a `string` field: every method here may run with the Cordis service Proxy
+     * as `this`, and mutating a property through that Proxy is the one thing this class must not rely on — mutating
+     * a property of an object it *read* through the Proxy is fine.
+     */
+    protected readonly sessionSync: {
+        lastSignature: string;
+    };
+    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 into the process world: for a local root the two are the same string.
+     *
+     * **This is a mapping, not an access check.** It used to answer `undefined` for any path outside the
+     * registered local roots, which broke the platform's own machinery: the PTC worker maps its runtime into the
+     * subprocess world through this method, so every `run_code` call died with
+     * `PTC runtime bootstrap is unavailable in the subprocess execution world:
+     * …/@deepseek-ai/dsh-ptc-runtime-node/lib/process.js` — a file that exists and that the harness has every
+     * right to read (2026-10-31, reported by the user as "the session cannot read the workspace").
+     *
+     * The core's own `dsh-fs-local` answers `resolve(hostPath)` unconditionally for exactly this reason: the
+     * question is "what is this host path called in the process world", not "may this caller open it". Access
+     * control lives in {@link resolve}/{@link readFile}/{@link writeText}, where the roots are enforced.
+     */
+    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.
+     *
+     * Reads **bytes** rather than calling `backend.readText`, so the binary sniff happens before decoding: the
+     * previous shape asked the backend for the decoded text and then re-encoded the whole string
+     * (`Buffer.from(text, 'utf8')`) only to look at its first {@link BINARY_SNIFF_BYTES} bytes. Measured on a
+     * 9 MiB file (audit 2026-11-01b follow-up): `open`+`stat`+`read` 2.65 ms, `+` decode 3.95 ms, `+` the
+     * redundant re-encode **5.66 ms** — 1.71 ms, ~75% of the plugin's overhead, spent to encode bytes the caller
+     * had just decoded. `TextDecoder` then decodes straight off the read buffer without the extra copy.
+     */
+    readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
+    /**
+     * Stream text in chunks, paging through the offset reader when the composition injected one.
+     *
+     * The platform calls this for every file at or above **its own** streaming threshold —
+     * `@deepseek-ai/dsh-tool-fs/lib/index.js:217` (`STREAM_MIN_SIZE = 10 * 1024 * 1024`) feeding `:338` — and
+     * `@deepseek-ai/dsh-fs/lib/types/index.d.ts:164-172` makes the backend own both the chunking and the
+     * cross-chunk UTF-8 decoding. Answering by reading the whole file first, which is what this did, made that
+     * contract a lie twice over: it buffered the entire file *and* it refused anything past the whole-file cap
+     * with `FS_TOO_LARGE`, so the `read` tool could not open a large remote log at all even when the caller had
+     * asked for one window of it.
+     *
+     * Without the offset seam the previous semantics are kept exactly: one bounded whole read, one chunk, and
+     * `FS_TOO_LARGE` past the cap. Nothing pretends to be chunked when it is not.
+     */
+    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 window
+     *    itself is capped at {@link MAX_RANGE_WINDOW_BYTES} — it is returned whole, so it is allocated
+     *    whole, and an unbounded `length` would be an unbounded allocation;
+     *  - 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>;
+    /**
+     * Watch one target through its backend.
+     *
+     * The route decides the world, then the backend owns the mechanism:
+     *
+     *  - **local roots** delegate to the platform's own `FileSystem.watch` (chokidar) via `PlatformLocalBackend`.
+     *    Before this method was wired, taking over `ctx.fs` made **local** files stop reporting changes: the
+     *    platform's `dsh-api-workspace-files` got `workspace-file/watch-unsupported` for every target, because
+     *    `RoutedFsProvider` replaced the sandboxed provider (a `LocalFileSystem` subclass) and this method only
+     *    ever threw. Delegating restores the pre-takeover behaviour without a second chokidar implementation.
+     *  - **remote roots** with a native agent watcher use `watch.start/poll/stop`; Tier 1 remains unsupported
+     *    and keeps failing honestly (the caller falls back to revalidation on read).
+     *
+     * A backend that has **no** `watch` method keeps the historical `FS_IO_ERROR` refusal — never a silent
+     * no-op, which would leave a consumer believing it is subscribed.
+     *
+     * @param target - the target whose changes were requested.
+     * @param changed - platform callback: re-stat on no argument, subscription-failure on an error.
+     * @param signal - cancels watcher initialization and subscription.
+     * @returns the disposer (`() => Promise<void>`), idempotent.
+     * @throws FsError `FS_IO_ERROR` when the backend cannot watch, plus the mapped backend failures
+     *   (`FS_NOT_FOUND`, `AbortError` for cancellation, …).
+     */
+    watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
+    private rootsService;
+    private router;
+    /**
+     * Resolve a path, syncing the live sessions' working directories once if it fails.
+     *
+     * Why on failure rather than before every call: the sync costs a walk of the live-session list plus a
+     * containment scan over the roots, and the overwhelming majority of resolutions succeed against a registered
+     * root. Why it must exist at all: the platform reads the workspace through `ctx.fs` by **absolute path without
+     * a cwd** while a turn starts, so a session whose own directory no root covers lost the entire turn before the
+     * model was called — there was no cwd to key a fallback on.
+     *
+     * One sync, then one retry: a session that appeared a moment ago is therefore picked up on its **first** read
+     * rather than failing once and working on the next call, and a second failure means the sync genuinely had
+     * nothing to add (the path is outside every root), so the caller gets the original error.
+     *
+     * @param path - model-facing path.
+     * @param cwd - the caller's session cwd, when it has one.
+     * @returns the resolution; when nothing changed the caller keeps the **original** failure.
+     */
+    private resolveWithSessionSync;
+    /**
+     * The route options for one call: the cwd the platform supplied, plus the session identity this call runs
+     * under when the tool dispatcher carried one down (`integration/session-scope.ts`, ADR-0013).
+     *
+     * Both are kept because they answer different questions. The cwd is what the platform's contract provides
+     * (relative spellings, the workspace-level rule, the anchor rule); the session is the only thing that can
+     * separate two conversations opened on the same directory. A call with neither is an agentless one and keeps
+     * the plugin-wide view, exactly as before.
+     *
+     * @param cwd - the caller's session cwd, when it has one.
+     * @returns the options to hand the route table.
+     */
+    private sessionRouteOptions;
+    /**
+     * The working directory of one live session, or `undefined` when it is not listed.
+     *
+     * @param sessionId - the asking session.
+     * @returns its cwd, when the platform reports one.
+     */
+    private sessionWorkspaceCwdOf;
+    /**
+     * Re-read the live sessions and register their working directories as session roots.
+     *
+     * Guarded by **change detection**, not by a time window: reading the session list and comparing it with the
+     * state the last sync produced costs microseconds, while a time throttle would have a window in which a session
+     * created a moment ago is not registered yet — and that session's very first read is exactly the one that used
+     * to kill the turn. The signature includes the session roots that currently exist, so a registry reset (which
+     * drops them) is noticed and repaired too.
+     */
+    private syncSessionRoots;
+    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.
+     *
+     * `undefined` here means **"no previous text to report"**, never "the target is absent" — the caller
+     * already decided existence from {@link BackendStat.exists}. Keeping those two apart is what stops a
+     * directory / oversized / binary file from slipping past a `createIfAbsent` guard.
+     */
+    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.
+ *
+ * Two mappings are deliberately *not* the tempting ones:
+ *
+ *  - **`CANCELLED` becomes an `AbortError`, not `FS_IO_ERROR`.** A cancelled tool call is not an I/O failure,
+ *    and the platform already recognises the abort shape (the same one {@link assertNotAborted} produces), so
+ *    reporting it as `FS_IO_ERROR` told the UI "the filesystem broke" (audit 2026-10-31 P2).
+ *  - **`REMOTE_UNSUPPORTED` becomes `FS_IO_ERROR`, not `FS_NOT_REGULAR_FILE`.** It means "this host/agent
+ *    cannot do that", never "this path is not a regular file"; the old mapping sent the caller to inspect the
+ *    path instead of the capability.
+ */
+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[];