dsh-remote-local-plugin 0.0.0-stage → 0.8.0

package/lib/types/config.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Local plugin configuration and path resolution.
+ *
+ * @module dsh-remote-local/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Raw plugin config. */
+export interface Config {
+    /** Empty means `$DSH_HOME/remote`. */
+    readonly stateDir?: string;
+    /** SSH executable. */
+    readonly sshBinary?: string;
+    /** Remote discovery document path; empty derives from `remoteDshHome`. */
+    readonly remoteStateFile?: string;
+    readonly probeTimeoutMs?: number;
+    readonly connectTimeoutMs?: number;
+    readonly healthIntervalMs?: number;
+    readonly reconnect?: boolean;
+    readonly maxReconnectDelayMs?: number;
+    /** `yes`, `no`, `ask`, or `accept-new`. */
+    readonly strictHostKeyChecking?: string;
+    /** Provision DSH + dsh-remote-agent when discovery finds no agent. */
+    readonly autoProvision?: boolean;
+    readonly remoteDshHome?: string;
+    readonly remoteInstallDir?: string;
+    readonly remoteDshVersion?: string;
+    readonly remotePnpmVersion?: string;
+    /** Node.js version installed into the remote install dir when none is usable. */
+    readonly remoteNodeVersion?: string;
+    /** Download Node.js into the remote install dir when it is missing or too old. */
+    readonly autoInstallNode?: boolean;
+    /** `systemd`, `nohup`, or `none`. */
+    readonly remoteStart?: string;
+    readonly provisionTimeoutMs?: number;
+    /** Keep the model key local and proxy it through a reverse SSH tunnel. Default false. */
+    readonly credentialProxy?: boolean;
+    /** Copy the resolved local model key into the remote service environment. */
+    readonly copyModelKey?: boolean;
+    /** Provider base URL used when the key is copied to the remote host. */
+    readonly remoteModelBaseUrl?: string;
+    readonly credentialProxyUpstream?: string;
+    /** Remote loopback port that receives the reverse-forwarded proxy. */
+    readonly credentialProxyRemotePort?: number;
+    /** Credential reference resolved in the local DSH process. */
+    readonly modelCredentialRef?: string;
+    /** Mirror remote sessions into the local conversation UI. */
+    readonly mirrorSessions?: boolean;
+    /** Poll interval for mirrored remote event logs. */
+    readonly mirrorPollMs?: number;
+    /** Maximum remote events replayed when a mirror is created. */
+    readonly mirrorMaxEvents?: number;
+}
+/** Loader-validated schema. */
+export declare const Config: z<Config>;
+/** How the remote DSH web host is supervised after provisioning. */
+export type RemoteStartMode = 'systemd' | 'nohup' | 'none';
+/** Resolved config. */
+export interface ResolvedConfig {
+    readonly stateDir: string;
+    readonly sshBinary: string;
+    readonly remoteStateFile: string;
+    readonly probeTimeoutMs: number;
+    readonly connectTimeoutMs: number;
+    readonly healthIntervalMs: number;
+    readonly reconnect: boolean;
+    readonly maxReconnectDelayMs: number;
+    readonly strictHostKeyChecking: 'yes' | 'no' | 'ask' | 'accept-new';
+    readonly autoProvision: boolean;
+    readonly remoteDshHome: string;
+    readonly remoteInstallDir: string;
+    readonly remoteDshVersion: string;
+    readonly remotePnpmVersion: string;
+    readonly remoteNodeVersion: string;
+    readonly autoInstallNode: boolean;
+    readonly remoteStart: RemoteStartMode;
+    readonly provisionTimeoutMs: number;
+    readonly credentialProxy: boolean;
+    readonly copyModelKey: boolean;
+    readonly remoteModelBaseUrl: string;
+    readonly credentialProxyUpstream: string;
+    readonly credentialProxyRemotePort: number;
+    readonly modelCredentialRef: string;
+    readonly mirrorSessions: boolean;
+    readonly mirrorPollMs: number;
+    readonly mirrorMaxEvents: number;
+}
+/** DSH home. */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv): string;
+/** Expand `~` and resolve relative paths. */
+export declare function resolveLocalPath(path: string, home?: string): string;
+/** Join a remote path expression without resolving it locally. */
+export declare function joinRemotePath(base: string, suffix: string): string;
+/** Materialize defaults. */
+export declare function resolveConfig(config?: Config, env?: NodeJS.ProcessEnv): ResolvedConfig;

package/lib/types/credentials/proxy.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Local model credential proxy.
+ *
+ * The remote DSH process is configured with a per-host proxy token and a base
+ * URL that points at a reverse SSH tunnel. Requests arrive here over the
+ * tunnel after token validation; the proxy then injects the real local API
+ * key and forwards to the provider. The key never leaves the local machine.
+ *
+ * The proxy binds loopback only. The reverse tunnel exposes it only on the
+ * remote host's loopback interface while the SSH connection is up.
+ *
+ * @module dsh-remote-local/credentials/proxy
+ */
+/** Options for one proxy instance. */
+export interface CredentialProxyOptions {
+    /** Real provider key. Never logged or returned. */
+    readonly apiKey: string;
+    /** Provider origin, for example `https://api.deepseek.com`. */
+    readonly upstreamBaseUrl: string;
+    /** Loopback bind address; defaults to 127.0.0.1. */
+    readonly host?: string;
+    /** Per-request upstream idle timeout. */
+    readonly timeoutMs?: number;
+    /** Whether a caller-supplied placeholder is one of this profile's proxy tokens. */
+    readonly isTokenValid: (token: string) => boolean;
+}
+/** Started proxy. */
+export interface CredentialProxyAddress {
+    readonly port: number;
+    readonly baseUrl: string;
+}
+/** Loopback credential proxy. */
+export declare class ModelCredentialProxy {
+    #private;
+    constructor(options: CredentialProxyOptions);
+    /** Start on an ephemeral loopback port. */
+    start(): Promise<CredentialProxyAddress>;
+    /** Stop and release active sockets. */
+    stop(): Promise<void>;
+}

package/lib/types/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Local plugin error taxonomy.
+ *
+ * These codes are surfaced to the Settings UI and to agent tools; they are
+ * never sent to a remote host as-is.
+ *
+ * @module dsh-remote-local/errors
+ */
+/** Stable local error codes. */
+export type LocalErrorCode = 'request/invalid' | 'host/invalid' | 'host/duplicate' | 'host/not-found' | 'host/not-connected' | 'host/connect-failed' | 'ssh/probe-failed' | 'ssh/tunnel-failed' | 'agent/unavailable' | 'agent/error' | 'directory/unreadable' | 'internal';
+/** Error carrying a stable code and JSON-safe details. */
+export declare class LocalError extends Error {
+    readonly code: LocalErrorCode;
+    readonly details: Record<string, unknown>;
+    readonly retryable: boolean;
+    constructor(code: LocalErrorCode, message: string, options?: {
+        readonly details?: Record<string, unknown>;
+        readonly retryable?: boolean;
+        readonly cause?: unknown;
+    });
+}
+/** Normalize unknown failures without leaking stack traces to the browser. */
+export declare function asLocalError(error: unknown, fallback?: LocalErrorCode): LocalError;

package/lib/types/host-api/contract.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Host API contract shared by the host handler and the browser Settings page.
+ *
+ * The route is registered inside DSH Connection's authenticated `/api` fence,
+ * so it works through the web HTTP carrier and the desktop IPC carrier without
+ * a second authentication scheme.
+ *
+ * @module dsh-remote-local/host-api/contract
+ */
+import type { HostView } from '../hosts/types.ts';
+import type { AcceptedResult, CreateSessionResult, HostInfo, PromptDeliveryMode, RemoteSessionSummary, RemoteWorkspace, SessionSnapshot } from '@dsh-remote/protocol';
+/** Exact authenticated Fetch route owned by the local plugin. */
+export declare const HOST_API_PATH = "/api/dsh-remote";
+/** Endpoint names. */
+export type HostApiEndpoint = 'state' | 'target/validate' | 'host/add' | 'host/remove' | 'host/connect' | 'host/disconnect' | 'host/refresh' | 'host/provision' | 'host/workspaces' | 'host/workspace/create' | 'host/directory/list' | 'local/directory/list' | 'local/workspace/create' | 'host/sessions' | 'host/session' | 'host/session/create' | 'host/session/prompt' | 'host/session/cancel' | 'host/web-url' | 'host/files/list' | 'host/files/read' | 'host/files/stat' | 'host/files/bytes';
+/** Browser-safe state snapshot. */
+export interface RemoteHostsState {
+    readonly protocolVersion: number;
+    readonly hosts: readonly HostView[];
+}
+/** Result of parsing a destination. */
+export interface ValidatedTarget {
+    readonly canonical: string;
+    readonly host: string;
+    readonly user: string | null;
+    readonly port: number | null;
+}
+/** Result of listing workspaces. */
+export interface HostWorkspace extends RemoteWorkspace {
+    /** Local mirror workspace id, when it has been synced. */
+    readonly localWorkspaceId?: string;
+}
+export interface WorkspacesResult {
+    readonly workspaces: readonly HostWorkspace[];
+}
+/** Result of listing sessions. */
+export interface SessionsResult {
+    readonly sessions: readonly RemoteSessionSummary[];
+}
+export interface HostCreateSessionResult extends CreateSessionResult {
+    /** Local mirror session that opens in the ordinary Conversation UI. */
+    readonly localSessionId?: string;
+}
+export interface MirrorFileResult {
+    readonly mirrored: boolean;
+    readonly value?: unknown;
+}
+/** Result of resolving the remote Web UI. */
+export interface WebUrlResult {
+    readonly url: string;
+}
+/** One request body. */
+export interface HostApiRequest {
+    readonly endpoint: HostApiEndpoint;
+    readonly payload?: unknown;
+}
+/** Success/failure result returned by the route. */
+export type HostApiResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly details: Record<string, unknown>;
+    };
+};
+/** Payloads accepted by each endpoint. */
+export interface HostApiPayloads {
+    state: undefined;
+    'target/validate': {
+        sshTarget: string;
+    };
+    'host/add': {
+        sshTarget: string;
+        label?: string;
+        token?: string;
+        remoteAgentPort?: number;
+        autoConnect?: boolean;
+    };
+    'host/remove': {
+        hostId: string;
+    };
+    'host/connect': {
+        hostId: string;
+    };
+    'host/disconnect': {
+        hostId: string;
+    };
+    'host/refresh': {
+        hostId: string;
+    };
+    'host/provision': {
+        hostId: string;
+    };
+    'host/workspaces': {
+        hostId: string;
+    };
+    'host/workspace/create': {
+        hostId: string;
+        path: string;
+        title?: string;
+    };
+    'host/directory/list': {
+        hostId: string;
+        path?: string;
+    };
+    'local/directory/list': {
+        path?: string;
+    };
+    'local/workspace/create': {
+        path: string;
+        title?: string;
+    };
+    'host/sessions': {
+        hostId: string;
+        workspaceId?: string;
+    };
+    'host/session': {
+        hostId: string;
+        sessionId: string;
+        limit?: number;
+    };
+    'host/session/create': {
+        hostId: string;
+        workspaceId?: string;
+        cwd?: string;
+        agentPreset?: string;
+    };
+    'host/session/prompt': {
+        hostId: string;
+        sessionId: string;
+        text: string;
+        mode?: PromptDeliveryMode;
+        provider?: string;
+        model?: string;
+        reasoningEffort?: string;
+    };
+    'host/session/cancel': {
+        hostId: string;
+        sessionId: string;
+    };
+    'host/web-url': {
+        hostId: string;
+    };
+    'host/files/list': {
+        sessionId: string;
+        path: string;
+    };
+    'host/files/read': {
+        sessionId: string;
+        path: string;
+        offset?: number;
+        limit?: number;
+    };
+    'host/files/stat': {
+        sessionId: string;
+        path: string;
+    };
+    'host/files/bytes': {
+        sessionId: string;
+        path: string;
+        offset?: number;
+        length?: number;
+    };
+}
+/** Values returned by each endpoint. */
+export interface HostApiValues {
+    state: RemoteHostsState;
+    'target/validate': ValidatedTarget;
+    'host/add': HostView;
+    'host/remove': {
+        removed: true;
+    };
+    'host/connect': HostView;
+    'host/disconnect': HostView;
+    'host/refresh': HostView;
+    'host/provision': HostView;
+    'host/workspaces': WorkspacesResult;
+    'host/workspace/create': RemoteWorkspace;
+    'host/directory/list': {
+        path: string;
+        parent: string;
+        entries: readonly {
+            name: string;
+            path: string;
+        }[];
+        truncated: boolean;
+    };
+    'local/directory/list': {
+        path: string;
+        parent: string;
+        entries: readonly {
+            name: string;
+            path: string;
+        }[];
+        truncated: boolean;
+    };
+    'local/workspace/create': {
+        workspaceId: string;
+    };
+    'host/sessions': SessionsResult;
+    'host/session': SessionSnapshot;
+    'host/session/create': HostCreateSessionResult;
+    'host/session/prompt': AcceptedResult;
+    'host/session/cancel': AcceptedResult;
+    'host/web-url': WebUrlResult;
+    'host/files/list': MirrorFileResult;
+    'host/files/read': MirrorFileResult;
+    'host/files/stat': MirrorFileResult;
+    'host/files/bytes': MirrorFileResult;
+}
+/** Informational type for the Settings page. */
+export interface HostSummary extends Pick<HostView, 'id' | 'label' | 'sshTarget' | 'phase'> {
+    readonly hostInfo: HostInfo | null;
+}

package/lib/types/host-api/handler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Authenticated host API over Connection's exact Fetch route.
+ *
+ * The route is mounted under `/api`, so Connection owns the Host/Origin fence,
+ * browser authentication, owner-Peer check, and body limits. This module only
+ * validates the endpoint/payload, dispatches to the service, and shapes the
+ * JSON result.
+ *
+ * @module dsh-remote-local/host-api/handler
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RemoteHostsService } from '../service.ts';
+import type { RemoteMirrorService } from '../mirror/service.ts';
+/** Register the route; returns its asynchronous disposer. */
+export declare function registerHostApi(ctx: Context, service: RemoteHostsService, mirrors?: RemoteMirrorService): () => Promise<void>;

package/lib/types/host-api/terminal.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Authenticated streaming route for mirrored remote terminals.
+ *
+ * The stock terminal Remote service is bound before an instance adapter can
+ * replace it, so the client terminal proxy talks to this exact Fetch route
+ * instead. Unary actions return JSON; attach returns SSE frames already in the
+ * shape the normal terminal UI consumes.
+ *
+ * @module dsh-remote-local/host-api/terminal
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RemoteTerminals } from '../remote/terminal.ts';
+export declare const TERMINAL_API_PATH = "/api/dsh-remote-terminal";
+/** Register the terminal route. */
+export declare function registerTerminalApi(ctx: Context, terminals: RemoteTerminals): () => Promise<void>;

package/lib/types/hosts/id.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stable host ids.
+ *
+ * An id is a human-readable slug plus a short hash of the canonical SSH
+ * destination. Re-adding the same destination is therefore a duplicate, while
+ * two aliases for the same machine remain distinct hosts (the user decides
+ * whether to merge them).
+ *
+ * @module dsh-remote-local/hosts/id
+ */
+/** Whether a value is a valid host id. */
+export declare function isHostId(value: string): boolean;
+/** Slugify a label or destination. */
+export declare function slugify(value: string): string;
+/** Derive a stable id from one canonical destination. */
+export declare function hostIdFor(canonicalDestination: string, label?: string): string;

package/lib/types/hosts/store.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Durable host registry.
+ *
+ * One JSON document, mode 0600, serialized through an in-process mutation
+ * queue. The token lives here and is never returned to the browser.
+ *
+ * @module dsh-remote-local/hosts/store
+ */
+import type { HostRecord } from './types.ts';
+/** Current on-disk schema version. */
+export declare const HOST_STORE_VERSION = 1;
+/** Load result, including non-fatal malformed-record warnings. */
+export interface HostStoreLoad {
+    readonly hosts: HostRecord[];
+    readonly warnings: string[];
+}
+/** Whether a value is a complete host record. */
+export declare function isHostRecord(value: unknown): value is HostRecord;
+/** Serialized host registry. */
+export declare class HostStore {
+    #private;
+    readonly file: string;
+    constructor(file: string);
+    /** Load valid records; malformed entries are skipped with a warning. */
+    load(): Promise<HostStoreLoad>;
+    /** Current records. */
+    list(): Promise<HostRecord[]>;
+    /** Add one record, rejecting a duplicate id or destination. */
+    add(record: HostRecord): Promise<HostRecord>;
+    /** Merge a patch into one record. */
+    update(id: string, patch: Partial<HostRecord>): Promise<HostRecord>;
+    /** Remove one record. */
+    remove(id: string): Promise<boolean>;
+}

package/lib/types/hosts/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Host records, runtime state, and browser-safe projections.
+ *
+ * The token is part of the durable record because the local plugin must
+ * reconnect after a restart without prompting. It never crosses the RPC
+ * boundary: {@link HostView} carries only `hasToken`.
+ *
+ * @module dsh-remote-local/hosts/types
+ */
+import type { HostInfo } from '@dsh-remote/protocol';
+/** Lifecycle phase shown by the Settings page. */
+export type HostPhase = 'idle' | 'discovering' | 'installing' | 'connecting' | 'connected' | 'disconnected' | 'error';
+/** Durable host record (mode 0600 state file). */
+export interface HostRecord {
+    readonly id: string;
+    readonly label: string;
+    /** Canonical SSH destination exactly as typed by the user. */
+    readonly sshTarget: string;
+    /** Explicit SSH port, or null when the destination uses SSH config/default 22. */
+    readonly sshPort: number | null;
+    /** Cached remote agent port discovered over SSH. */
+    readonly remoteAgentPort: number | null;
+    /** Bearer token issued by the remote agent. Secret. */
+    readonly token: string | null;
+    /** Per-host placeholder accepted by the local credential proxy. Secret. */
+    readonly proxyToken?: string | null;
+    readonly autoConnect: boolean;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/** Ephemeral runtime state for one host. */
+export interface HostRuntime {
+    readonly phase: HostPhase;
+    readonly localPort: number | null;
+    readonly localUrl: string | null;
+    readonly hostInfo: HostInfo | null;
+    readonly workspaceCount: number | null;
+    readonly error: string | null;
+    readonly errorCode: string | null;
+    readonly connectedAt: string | null;
+    /** Human-readable progress detail for discovery/provisioning. */
+    readonly detail: string | null;
+    /** Whether the local model credential proxy is active for this host. */
+    readonly modelProxy: boolean;
+    /** Whether the resolved local model key was copied into the remote environment. */
+    readonly modelDirect: boolean;
+}
+/** Browser/tool-safe host projection. */
+export interface HostView {
+    readonly id: string;
+    readonly label: string;
+    readonly sshTarget: string;
+    readonly sshPort: number | null;
+    readonly remoteAgentPort: number | null;
+    readonly autoConnect: boolean;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly hasToken: boolean;
+    readonly phase: HostPhase;
+    readonly localPort: number | null;
+    readonly localUrl: string | null;
+    readonly hostInfo: HostInfo | null;
+    readonly workspaceCount: number | null;
+    readonly error: string | null;
+    readonly errorCode: string | null;
+    readonly connectedAt: string | null;
+    /** Human-readable progress detail for discovery/provisioning. */
+    readonly detail: string | null;
+    /** Whether the local model credential proxy is active for this host. */
+    readonly modelProxy: boolean;
+    /** Whether the resolved local model key was copied into the remote environment. */
+    readonly modelDirect: boolean;
+}
+/** Input accepted by `host/add`. */
+export interface AddHostInput {
+    readonly label?: string;
+    readonly sshTarget: string;
+    readonly token?: string;
+    readonly remoteAgentPort?: number;
+    readonly autoConnect?: boolean;
+}
+/** Create an idle runtime state. */
+export declare function idleRuntime(): HostRuntime;
+/** Project one record + runtime into the browser-safe view. */
+export declare function toHostView(record: HostRecord, runtime: HostRuntime): HostView;

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * dsh-remote-local-plugin host entry.
+ *
+ * Owns the host registry, SSH tunnels, the authenticated Connection RPC
+ * channel used by the Settings page, and the model-facing remote tools.
+ *
+ * @module dsh-remote-local
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, type Config as LocalConfig } from './config.ts';
+export declare const name = "dsh-remote-local";
+/** Connection owns the authenticated `/api` carrier; credentials stay local. */
+export declare const inject: string[];
+export { Config };
+export type { LocalConfig };
+export { RemoteHostsService } from './service.ts';
+export { HOST_API_PATH } from './host-api/contract.ts';
+/** Mount the host registry and its extension points. */
+export declare function apply(ctx: Context, config?: LocalConfig): Promise<void>;

package/lib/types/mirror/service.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Native remote-session mirror.
+ *
+ * A remote DSH session is replayed into a local Session and registered with a
+ * custom Agent. The existing local client therefore lists it beside local
+ * workspaces and renders it with the ordinary Conversation UI, while prompts
+ * and cancellation are routed back to the remote agent.
+ *
+ * This is a mirror, not a second agent loop: the local Session is a durable
+ * projection of the remote log, and the remote DSH remains the execution owner.
+ *
+ * @module dsh-remote-local/mirror
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import type { PromptDeliveryMode } from '@dsh-remote/protocol';
+import type { ResolvedConfig } from '../config.ts';
+import type { RemoteHostsService } from '../service.ts';
+interface MirrorRecord {
+    readonly hostId: string;
+    readonly remoteSessionId: string;
+    localSessionId: string;
+    readonly remoteWorkspaceId: string | null;
+    readonly anchor: string;
+    lastSeq: number;
+    updatedAt: string;
+}
+interface MirrorRuntime {
+    readonly record: MirrorRecord;
+    readonly agent: MirrorAgent;
+    readonly session: Session;
+    timer: NodeJS.Timeout | undefined;
+    running: boolean;
+    stopped: boolean;
+    lastError: string | null;
+    pendingUsers: unknown[];
+    waiters: Array<() => void>;
+}
+interface MirrorAgent {
+    readonly id: SessionId;
+    readonly session: Session;
+    readonly options: {
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+    };
+    readonly ctx: Context;
+    readonly inbox: Record<string, unknown[]>;
+    readonly status: 'idle' | 'running';
+    cancel(cause?: unknown): void;
+    whenIdle(): Promise<void>;
+    runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    send(message: unknown, target?: unknown, wakeup?: boolean): void;
+    followup(message: unknown): void;
+    steer(message: unknown): void;
+    inject(message: unknown): void;
+}
+/** Mirror remote sessions into local Sessions and custom Agents. */
+export declare class RemoteMirrorService {
+    #private;
+    constructor(ctx: Context, hosts: RemoteHostsService, config: ResolvedConfig);
+    /** Load mappings and begin periodic discovery. */
+    start(): Promise<void>;
+    /** Stop mirrors and timers. */
+    dispose(): Promise<void>;
+    /** Reconcile connected hosts with the local workspace/session catalog. */
+    sync(): Promise<void>;
+    /** Resolve a local workspace anchor to its remote filesystem context. */
+    remoteFileContext(workspaceRoot: string): {
+        hostId: string;
+        remoteRoot: string;
+        anchor: string;
+    } | undefined;
+    /** Whether the test-only manifest excludes this remote workspace from UI listings. */
+    isTestHidden(remoteWorkspaceId: string, remotePath: string): boolean;
+    /** Find the local mirror workspace for one remote workspace. */
+    localWorkspaceId(hostId: string, remoteWorkspaceId: string): string | undefined;
+    /** Find the local mirror for one remote session. */
+    localSessionId(hostId: string, remoteSessionId: string): string | undefined;
+    /** Create a mirror on demand and return its local session id. */
+    ensureRemoteSession(hostId: string, remoteSessionId: string): Promise<string | undefined>;
+    /** Route one prompt from the local Agent façade to the remote session. */
+    prompt(runtime: MirrorRuntime, message: unknown, mode: PromptDeliveryMode): void;
+    /** Route cancellation to the remote session. */
+    cancel(runtime: MirrorRuntime): void;
+}
+export {};

package/lib/types/mirror/test-visibility.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Test-only visibility manifest.
+ *
+ * This file lives only in a test DSH_HOME. It is intentionally not a Settings
+ * option and not an agent tool: a test harness writes it before/after a run.
+ *
+ *   $DSH_HOME/remote/test-visibility.json
+ *   { "hiddenPaths": ["/tmp/dsh-remote-tests"], "hiddenWorkspaceIds": ["..."] }
+ *
+ * Hidden paths/ids are not registered into the local workspace registry. Hiding
+ * an already-mirrored workspace archives its local mirror Sessions and removes
+ * the local row; removing the entry restores it from the remote log later.
+ *
+ * @module dsh-remote-local/mirror/test-visibility
+ */
+export interface TestVisibility {
+    readonly hiddenPaths: readonly string[];
+    readonly hiddenWorkspaceIds: readonly string[];
+}
+/** Read the manifest; absent or malformed files disable test visibility. */
+export declare function loadTestVisibility(stateDir: string): Promise<TestVisibility>;
+/** Whether one remote workspace/path is hidden from local registration. */
+export declare function isTestHidden(remotePath: string, remoteWorkspaceId: string, visibility: TestVisibility): boolean;