dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,66 @@
+/**
+ * Per-connection store of `SSH_ASKPASS` helpers.
+ *
+ * Why this exists as a module: preparing a helper is **async** (it reads the secret from the credential
+ * service and writes two files), but transport factories are **synchronous** and are also reached from
+ * `createAlias` during the install ladder. The two are joined here: something async calls
+ * {@link AskpassRegistry.prepare} first, and the factory then reads {@link AskpassRegistry.envFor}
+ * without awaiting.
+ *
+ * Three rules:
+ *
+ *  1. **One helper per connection.** Preparing twice returns the same handle, so a reconnect does not
+ *     accumulate temp directories (and the secret is read once).
+ *  2. **Only password connections get one.** Key and agent connections never prompt; handing them
+ *     `BatchMode=no` would let a misconfigured host block on an interactive prompt forever.
+ *  3. **A failure is a degradation, not a throw.** If the secret cannot be resolved the connection still
+ *     works through the transports that do not need it; {@link AskpassRegistry.prepare} reports `undefined`
+ *     and the caller keeps its previous behaviour.
+ *
+ * @module dsh-over-ssh/integration/askpass-registry
+ */
+import { type AskpassHandle } from '../../infra/transport/ssh/askpass.ts';
+import type { ConnectionProfile } from '../../domain/roots/connection.ts';
+/** Options for {@link createAskpassRegistry}. */
+export interface AskpassRegistryOptions {
+    /** Resolve the connection's password. Throws when it is missing or the credential service is absent. */
+    readonly readSecret: (profile: ConnectionProfile) => Promise<string>;
+    /** Materialise one helper for a secret. */
+    readonly create: (secret: string) => Promise<AskpassHandle>;
+    /** Optional sink for "we could not prepare one" so the reason is not swallowed. */
+    readonly onUnavailable?: (connectionId: string, reason: string) => void;
+}
+/** The registry surface the composition root needs. */
+export interface AskpassRegistry {
+    /**
+     * Ensure a helper exists for this connection.
+     *
+     * @param profile - the connection.
+     * @returns the environment to hand `ssh`, or `undefined` when this connection needs none or preparation
+     *          failed (in which case the caller must keep its non-prompting behaviour).
+     */
+    prepare(profile: ConnectionProfile): Promise<Record<string, string> | undefined>;
+    /** The environment prepared for this connection, if any. Synchronous, for transport factories. */
+    envFor(profile: ConnectionProfile): Record<string, string> | undefined;
+    /** Whether a connection is currently using a password helper. */
+    has(connectionId: string): boolean;
+    /** Drop one connection's helper (its transport was released, or the connection changed). */
+    forget(connectionId: string): Promise<void>;
+    /**
+     * Allow a retired connection id to prepare a helper again.
+     *
+     * Call this only when the connection is deliberately re-established. Without it, a re-saved connection
+     * could never get a password helper, because `forget` leaves a tombstone that `prepare` honours.
+     */
+    revive(connectionId: string): void;
+    /** Drop every helper (plugin unload). */
+    disposeAll(): Promise<void>;
+}
+/**
+ * Build the registry.
+ *
+ * @param options - injected secret reader, helper factory and optional sink.
+ * @returns the registry.
+ */
+export declare function createAskpassRegistry(options: AskpassRegistryOptions): AskpassRegistry;
+//# sourceMappingURL=askpass-registry.d.ts.map

package/lib/types/src/host/integration/agent-install-io.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The install ladder's I/O, built on the connection's **Tier 1 transport**.
+ *
+ * The agent cannot install itself, so every step of the ladder runs through the transport that already
+ * works: `exec` for the probe, `writeFile` for the upload (the Tier 1 transports already implement bounded,
+ * atomic remote writes), and one more `exec` for the digest. Nothing here opens a second authentication
+ * path, which is what keeps "upload" as trustworthy as "run a command".
+ *
+ * @module dsh-remote-workspace/integration/agent-install-io
+ */
+import type { AgentInstallIo } from '../infra/transport/agent-installer.ts';
+import type { Transport } from '../infra/transport/transport.ts';
+/** Options for {@link createAgentInstallIo}. */
+export interface AgentInstallIoOptions {
+    /** The Tier 1 transport of the connection being installed onto. */
+    readonly transport: Transport;
+    /** Refuse to upload anything larger than this (a corrupt manifest must not fill the host's disk). */
+    readonly maxUploadBytes?: number;
+    /** Local file reader, injected so tests never touch a real file. */
+    readonly readLocalFile?: (path: string) => Promise<Uint8Array>;
+    /** Local size lookup, so an oversized artifact is rejected before it is read into memory. */
+    readonly localSize?: (path: string) => Promise<number>;
+    /** Cap for exec output while probing; the ladder only needs tiny answers. */
+    readonly probeMaxBytes?: number;
+}
+/**
+ * Build the ladder's I/O from an existing transport.
+ *
+ * @param options - transport plus optional readers and caps.
+ * @returns an {@link AgentInstallIo} that never opens a second connection.
+ */
+export declare function createAgentInstallIo(options: AgentInstallIoOptions): AgentInstallIo;
+//# sourceMappingURL=agent-install-io.d.ts.map

package/lib/types/src/host/integration/agent-preflight.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The bridge between the install ladder and transport selection.
+ *
+ * Selection is synchronous (it may only consult cached facts) while the ladder must talk to the host, so
+ * the two are joined by an **async preflight**: the selector's first answer is revised before any transport
+ * is built. That is what makes "agent unavailable ⇒ Tier 1" true without making the selector depend on I/O.
+ *
+ * Two rules this module exists to enforce:
+ *
+ *  1. **No host traffic unless the connection asked for the agent.** A non-agent decision returns
+ *     immediately, so an ordinary alias connection never probes or uploads anything.
+ *  2. **A failed ladder is a degradation, never an exception.** `ensureAgent` already turns every remote
+ *     problem into a `tier1` outcome; this module forwards that as a revised decision plus a hint.
+ *
+ * @module dsh-remote-workspace/integration/agent-preflight
+ */
+import type { TransportPreflight } from '../app/transport-service.ts';
+import type { ConnectionProfile } from '../domain/connection.ts';
+import type { AgentInstallation } from '../infra/transport/agent-installer.ts';
+/** What the preflight learned about one connection. */
+export type AgentPreflightOutcome = {
+    readonly kind: 'agent';
+    readonly remotePath: string;
+    readonly platform: string;
+    readonly reused: boolean;
+} | {
+    readonly kind: 'tier1';
+    readonly reason: string;
+    readonly hint: string;
+};
+/** Options for {@link createAgentPreflight}. */
+export interface AgentPreflightOptions {
+    /** Run (or reuse a memoized) ladder for one connection. Injected so this module stays offline-testable. */
+    readonly ensure: (profile: ConnectionProfile, signal?: AbortSignal) => Promise<AgentInstallation>;
+    /** Optional sink so the connection UI can show what happened. */
+    readonly onOutcome?: (connectionId: string, outcome: AgentPreflightOutcome) => void;
+    /** Optional logger for the "we are not even trying" path; defaults to silence. */
+    readonly onSkipped?: (profile: ConnectionProfile) => void;
+}
+/** The preflight plus the installation facts the agent factory needs. */
+export interface AgentPreflight {
+    /** Pass this to {@link TransportServiceOptions.preflight}. */
+    readonly preflight: TransportPreflight;
+    /** The installation for a connection, once the ladder approved one. */
+    installationFor(connectionId: string): AgentPreflightOutcome | undefined;
+    /** Forget one connection (its transport was released, or the user changed the connection). */
+    forget(connectionId: string): void;
+}
+/**
+ * Build the preflight.
+ *
+ * @param options - ladder plus optional sinks.
+ * @returns the preflight, an installation lookup, and a way to forget a connection.
+ */
+export declare function createAgentPreflight(options: AgentPreflightOptions): AgentPreflight;
+//# sourceMappingURL=agent-preflight.d.ts.map

package/lib/types/src/host/integration/anchor-directory.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The local anchor directory of a remote root.
+ *
+ * A remote root needs a **local** path to stand in for it, because a workspace path must exist on this machine
+ * (`root.ts` keeps that anchor on the `RootRef`). The platform then resolves that path with `realpath` when it
+ * opens a workspace on it, so the directory has to be **created**, not just computed:
+ *
+ *     workspace create failed: workspace/invalid-path: cannot create a Workspace at
+ *     "C:\\Users\\…\\.dsh\\ssh-dev\\roots\\腾讯云\\39d1e90c": ENOENT …
+ *
+ * That failure is what this module exists to prevent. It lives in its own file so the rule ("a remote root's
+ * anchor must exist") is in one place and testable without a real home directory (红线 3: 外部依赖走注入).
+ *
+ * @module dsh-remote-workspace/integration/anchor-directory
+ */
+import type { RootRef } from '../domain/root.ts';
+/** The one filesystem call this module needs. */
+export interface AnchorDirectoryIo {
+    /**
+     * Create a directory and its parents; a no-op when it already exists.
+     *
+     * The return value is ignored on purpose (`node:fs` answers with the first created path): this module only
+     * cares that the directory exists afterwards, so the seam stays as narrow as that fact.
+     */
+    mkdir(path: string, options: {
+        readonly recursive: true;
+    }): Promise<unknown> | unknown;
+}
+/**
+ * Make one root's local anchor exist.
+ *
+ * Local roots are their own anchor (the directory is the user's own path, which the platform checks itself), and
+ * a remote root without an anchor simply has nothing to create  - both cases return without touching the disk.
+ *
+ * @param root - the root that is about to become live.
+ * @param io - the injected filesystem.
+ * @returns nothing; a failure propagates so the caller decides whether it is fatal.
+ */
+export declare function ensureAnchorDirectory(root: Pick<RootRef, 'location' | 'anchorPath'>, io: AnchorDirectoryIo): Promise<void>;
+/**
+ * The last path segment of a remote root's anchor: **the remote folder's own name**.
+ *
+ * Why it matters: the platform titles a new workspace with `defaultWorkspaceTitle(path)` =
+ * `basename(path)` (`dsh-workspace/lib/types/paths.js:26-29`), and the directory-flow contract only carries a
+ * `path`  - there is no title parameter to pass (`DirectoryFlowOwnerProps`). So the segment this function
+ * returns **is** the name the user sees in the sidebar. A digest-only anchor made every remote workspace show
+ * up as `daf8c293`; this is what turns it into `stress_10`.
+ *
+ * Identity is *not* this function's job: the caller keeps a digest directory above it, so two remote paths with
+ * the same folder name still get two anchors (one canonical path per workspace).
+ *
+ * @param remotePath - absolute POSIX path on the remote host.
+ * @returns a segment that is safe to create on this machine and readable as a workspace name.
+ */
+export declare function anchorLeafName(remotePath: string): string;
+//# sourceMappingURL=anchor-directory.d.ts.map

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

@@ -0,0 +1,59 @@
+/**
+ * Per-connection store of `SSH_ASKPASS` helpers.
+ *
+ * Why this exists as a module: preparing a helper is **async** (it reads the secret from the credential
+ * service and writes two files), but transport factories are **synchronous** and are also reached from
+ * `createAlias` during the install ladder. The two are joined here: something async calls
+ * {@link AskpassRegistry.prepare} first, and the factory then reads {@link AskpassRegistry.envFor}
+ * without awaiting.
+ *
+ * Three rules:
+ *
+ *  1. **One helper per connection.** Preparing twice returns the same handle, so a reconnect does not
+ *     accumulate temp directories (and the secret is read once).
+ *  2. **Only password connections get one.** Key and agent connections never prompt; handing them
+ *     `BatchMode=no` would let a misconfigured host block on an interactive prompt forever.
+ *  3. **A failure is a degradation, not a throw.** If the secret cannot be resolved the connection still
+ *     works through the transports that do not need it; {@link AskpassRegistry.prepare} reports `undefined`
+ *     and the caller keeps its previous behaviour.
+ *
+ * @module dsh-remote-workspace/integration/askpass-registry
+ */
+import { type AskpassHandle } from '../infra/transport/askpass.ts';
+import type { ConnectionProfile } from '../domain/connection.ts';
+/** Options for {@link createAskpassRegistry}. */
+export interface AskpassRegistryOptions {
+    /** Resolve the connection's password. Throws when it is missing or the credential service is absent. */
+    readonly readSecret: (profile: ConnectionProfile) => Promise<string>;
+    /** Materialise one helper for a secret. */
+    readonly create: (secret: string) => Promise<AskpassHandle>;
+    /** Optional sink for "we could not prepare one" so the reason is not swallowed. */
+    readonly onUnavailable?: (connectionId: string, reason: string) => void;
+}
+/** The registry surface the composition root needs. */
+export interface AskpassRegistry {
+    /**
+     * Ensure a helper exists for this connection.
+     *
+     * @param profile - the connection.
+     * @returns the environment to hand `ssh`, or `undefined` when this connection needs none or preparation
+     *          failed (in which case the caller must keep its non-prompting behaviour).
+     */
+    prepare(profile: ConnectionProfile): Promise<Record<string, string> | undefined>;
+    /** The environment prepared for this connection, if any. Synchronous, for transport factories. */
+    envFor(profile: ConnectionProfile): Record<string, string> | undefined;
+    /** Whether a connection is currently using a password helper. */
+    has(connectionId: string): boolean;
+    /** Drop one connection's helper (its transport was released, or the connection changed). */
+    forget(connectionId: string): Promise<void>;
+    /** Drop every helper (plugin unload). */
+    disposeAll(): Promise<void>;
+}
+/**
+ * Build the registry.
+ *
+ * @param options - injected secret reader, helper factory and optional sink.
+ * @returns the registry.
+ */
+export declare function createAskpassRegistry(options: AskpassRegistryOptions): AskpassRegistry;
+//# sourceMappingURL=askpass-registry.d.ts.map

package/lib/types/src/host/integration/bin-root-resolver.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Decide, per root, where its file-level recycle bin lives — and make that place resolvable.
+ *
+ * The bin must sit **outside** the caller's repository (a "safe delete" that pollutes `git status` is not safe),
+ * yet it must be reachable by the router, which only resolves paths inside a registered root (ADR-0011). So the
+ * bin directory is registered as a **hidden root**: routable, but absent from `RootRegistry.records` and
+ * therefore from every user-facing list.
+ *
+ * This module owns the one decision that cannot be pure — *is the chosen directory usable?* — and it answers by
+ * measuring rather than assuming: the bin's parent must exist and must be on the **same device** as the root,
+ * because a cross-device `rename` is refused outright and the file-level bin has no copy fallback
+ * (`fs-commands.ts`, `recycle-bin-service.ts`). If a measurement fails, the bin stays inside the root — the old
+ * behaviour — and the reason is recorded, so a fallback is **visible** rather than silent.
+ *
+ * @module dsh-remote-workspace/integration/bin-root-resolver
+ */
+import { type RootRef } from '../domain/root.ts';
+import type { RootRecord } from './root-registry.ts';
+/** Where one root's bin ended up, and why. */
+export interface BinRootChoice {
+    /** Absolute bin directory. */
+    readonly binRoot: string;
+    /** `beside` = outside the repository (the goal); `inside` = the documented fallback. */
+    readonly placement: 'beside' | 'inside';
+    /** Whether a hidden root was registered for it (only for `beside`). */
+    readonly hidden: boolean;
+    /** Human-readable reason for a fallback, or for an inconclusive measurement. */
+    note?: string;
+}
+/** What the resolver needs from its owner. */
+export interface BinRootResolverDeps {
+    /** Register a hidden root; returns the record. */
+    readonly addHiddenRoot: (root: RootRef) => RootRecord;
+    /** Drop a hidden root by key; used when a migration fails and the new location is abandoned. */
+    readonly removeHiddenRoot?: (key: string) => void;
+    /** The configured bin directory name (`limits.binDir`). */
+    readonly binDir: string;
+    /**
+     * Whether two paths are on the same device.
+     *
+     * `undefined` means **unknown**, and unknown is treated as *usable*: refusing to move a file into the bin is
+     * worse than putting the bin in an untidy place, and a transport without a working `stat` cannot answer.
+     */
+    readonly sameDevice: (root: RootRef, left: string, right: string) => Promise<boolean | undefined>;
+    /** Whether a directory exists. */
+    readonly exists: (root: RootRef, path: string) => Promise<boolean>;
+    /**
+     * Move a directory, creating the destination's parents.
+     *
+     * Only ever called for the **old bin → new bin** migration, where the two are on one device (already
+     * measured), so a plain `rename` is the whole implementation.
+     */
+    readonly moveDirectory: (root: RootRef, from: string, to: string) => Promise<void>;
+}
+/** The resolver handed to the recycle-bin wiring. */
+export interface BinRootResolver {
+    /**
+     * The bin directory for one root, registering a hidden root on first use.
+     *
+     * Synchronous by contract: the bin service asks repeatedly and cannot await (`binRootFor`). The measurement
+     * therefore happens in {@link BinRootResolver.prepare}, which the composition calls when a root is registered.
+     *
+     * @param root - the root being served.
+     * @returns its bin directory.
+     */
+    binRootFor: (root: RootRef) => string;
+    /** Measure and register a root's bin placement; call this when the root is added. */
+    prepare: (root: RootRef) => Promise<BinRootChoice>;
+    /** The choice made for one root, if any (for diagnostics). */
+    choiceFor: (root: RootRef) => BinRootChoice | undefined;
+    /** Drop one root's cached choice (its root was removed, or its connection changed). */
+    forget: (key: string) => void;
+}
+/**
+ * Build the resolver.
+ *
+ * @param deps - injected registration, configuration and measurement seams.
+ * @returns the resolver.
+ */
+export declare function createBinRootResolver(deps: BinRootResolverDeps): BinRootResolver;
+//# sourceMappingURL=bin-root-resolver.d.ts.map

package/lib/types/src/host/integration/connection-test.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The connectivity probe behind the panel's 「测试」 button.
+ *
+ * What "testing a connection" means here, and why it is a real connection rather than a TCP ping:
+ *
+ *  - it goes through the **same transport service** the rest of the plugin uses, so it answers the only question
+ *    that matters to the user  - "would a remote operation work right now"  - including the transport the
+ *    selector picked and whether that pick was a degradation;
+ *  - the last step is an actual command round-trip (`printf`), so a host that accepts TCP but has no usable
+ *    shell (or a transport that cannot execute) is reported as a failure, not as a success;
+ *  - the probe **warms the connection** the caller will use next, because `acquire` is memoized per connection.
+ *
+ * Everything it needs is injected (红线 3: 外部依赖走注入), so the whole classification is testable without a
+ * server, and the entry is the only place that knows about profiles.
+ *
+ * @module dsh-remote-workspace/integration/connection-test
+ */
+/** The slice of `Transport` the probe uses. Narrow on purpose: the probe must not be able to do more. */
+export interface ProbeTransport {
+    readonly id: string;
+    connect(signal?: AbortSignal): Promise<void>;
+    exec(request: {
+        readonly argv: readonly string[];
+        readonly maxBytes?: number;
+    }, signal?: AbortSignal): Promise<{
+        readonly exitCode: number;
+        readonly stdout: string;
+    }>;
+}
+/** One acquisition: the transport plus the decision that produced it. */
+export interface ProbeAcquisition {
+    readonly transport: ProbeTransport;
+    readonly decision: {
+        readonly kind: string;
+        readonly degradations?: readonly {
+            readonly code: string;
+        }[];
+    };
+}
+/** What the probe needs. */
+export interface ConnectionProbeDeps {
+    /** Acquire (and, on first use, connect) the connection's transport. Rejects with `CONNECTION_NOT_FOUND` for an unknown id. */
+    readonly acquire: (connectionId: string) => Promise<ProbeAcquisition>;
+    /** Budget for the whole probe; each transport keeps its own timeouts on top of it. */
+    readonly timeoutMs?: number;
+    /** Clock, injected so a test can assert the reported milliseconds. */
+    readonly now?: () => number;
+}
+/** The wire answer: success carries the facts the row shows, failure carries a reason it can print. */
+export type ConnectionProbeResult = {
+    readonly ok: true;
+    readonly transport: string;
+    readonly degraded: boolean;
+    readonly degradation?: string;
+    readonly ms: number;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+    readonly ms: number;
+};
+/**
+ * Probe one connection.
+ *
+ * Never throws: a refused or broken connection is a **result** the panel prints, because a button that rejects
+ * leaves the user with nothing to read.
+ *
+ * @param connectionId - the connection to test.
+ * @param deps - the injected acquisition, clock and budget.
+ * @returns the outcome, with the elapsed milliseconds either way.
+ */
+export declare function probeConnection(connectionId: string, deps: ConnectionProbeDeps): Promise<ConnectionProbeResult>;
+//# sourceMappingURL=connection-test.d.ts.map

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

@@ -0,0 +1,115 @@
+/**
+ * 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-remote-workspace/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';
+/** 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-remote-workspace/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.
+     *
+     * @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 the cwd is outside every registered root.
+     */
+    list(agent: Agent, query: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
+}
+export default RemoteFileReferenceService;
+//# sourceMappingURL=file-reference-provider.d.ts.map