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

package/lib/types/remote/directory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Read-only remote directory browser used by the workspace creation UI.
+ * It reuses the host's SSH transport and runs a tiny Python lister remotely.
+ *
+ * @module dsh-remote-local/remote/directory
+ */
+import type { RemoteHostsService } from '../service.ts';
+export interface RemoteDirectoryEntry {
+    readonly name: string;
+    readonly path: string;
+}
+export interface RemoteDirectoryListing {
+    readonly path: string;
+    readonly parent: string;
+    readonly entries: readonly RemoteDirectoryEntry[];
+    readonly truncated: boolean;
+}
+/** List child directories of one remote path. */
+export declare function listRemoteDirectories(hosts: RemoteHostsService, hostId: string, path?: string): Promise<RemoteDirectoryListing>;

package/lib/types/remote/files.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Remote-backed `workspaceFiles` for native workspace trees and file previews.
+ *
+ * Mirrored workspaces have a local anchor path. The stock workspace-files
+ * service would read that empty anchor; this adapter maps the anchor prefix to
+ * the remote workspace root and runs a small read-only helper over SSH.
+ *
+ * @module dsh-remote-local/remote/files
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RemoteHostsService } from '../service.ts';
+import type { RemoteMirrorService } from '../mirror/service.ts';
+/** Install the adapter over the host's workspace-files service. */
+export declare function installRemoteWorkspaceFiles(ctx: Context, mirrors: RemoteMirrorService, hosts: RemoteHostsService): void;

package/lib/types/remote/local-directory.d.ts

@@ -0,0 +1,11 @@
+export interface LocalDirectoryListing {
+    readonly path: string;
+    readonly parent: string;
+    readonly entries: readonly {
+        readonly name: string;
+        readonly path: string;
+    }[];
+    readonly truncated: boolean;
+}
+/** List child directories of one local path. */
+export declare function listLocalDirectories(path?: string): Promise<LocalDirectoryListing>;

package/lib/types/remote/provisioner.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Plugin-owned remote provisioning.
+ *
+ * On first connect the plugin uploads its bundled agent tarball, runs the
+ * installer bootstrap script over SSH, then waits for the remote state file.
+ * No separate installer command is required.
+ *
+ * @module dsh-remote-local/remote/provisioner
+ */
+import type { ResolvedConfig } from '../config.ts';
+import type { ParsedSshTarget } from '../ssh/target.ts';
+/** Progress callback shown in the host card. */
+export type ProvisionProgress = (message: string) => void;
+/** Provisioner bound to one plugin config. */
+export declare class RemoteProvisioner {
+    #private;
+    constructor(config: ResolvedConfig);
+    /**
+     * Install/start the remote agent when discovery finds no live agent.
+     *
+     * @param target - validated SSH target.
+     * @param options - optional local proxy endpoint and progress callback.
+     */
+    ensureInstalled(target: ParsedSshTarget, options?: {
+        readonly modelBaseUrl?: string;
+        readonly modelApiKey?: string;
+        readonly onProgress?: ProvisionProgress;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** Locate the packed agent shipped in this plugin's assets directory. */
+export declare function findAgentTarball(): string;

package/lib/types/remote/terminal.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Remote PTY terminals for mirrored Sessions.
+ *
+ * The stock terminal controller spawns processes in the local execution
+ * environment. For a mirror, this manager spawns an SSH PTY in the remote
+ * workspace instead and exposes the browser protocol the normal terminal UI
+ * already consumes.
+ *
+ * @module dsh-remote-local/remote/terminal
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { TerminalFrame, TerminalInput, TerminalShell, WebTerminalInfo } from '@deepseek-ai/dsh-api-terminal-controller';
+import type { RemoteHostsService } from '../service.ts';
+import type { RemoteMirrorService } from '../mirror/service.ts';
+/** One host-side terminal manager. */
+export declare class RemoteTerminals {
+    #private;
+    constructor(ctx: Context, hosts: RemoteHostsService, mirrors: RemoteMirrorService);
+    /** Whether this Session owns a mirrored workspace. */
+    isMirrored(sessionId: string): boolean;
+    /** Return the remote cwd/limits for one Session. */
+    environment(sessionId: string): {
+        cwd: string;
+        maxInputBytes: number;
+        maxBufferedBytes: number;
+        maxCols: number;
+        maxRows: number;
+        scrollback: number;
+    };
+    /** One remote shell candidate. */
+    shells(): TerminalShell[];
+    /** Terminals retained for one Session. */
+    list(sessionId: string): WebTerminalInfo[];
+    /** Allocate an SSH PTY in the mirrored workspace. */
+    create(sessionId: string, request: {
+        id?: string;
+        shellPath?: string;
+        cols?: number;
+        rows?: number;
+    }): WebTerminalInfo;
+    /** Feed input/resize into one remote PTY. */
+    input(id: string, input: TerminalInput): void;
+    /** Rename a retained terminal. */
+    rename(id: string, title: string): void;
+    /** Close one terminal. */
+    close(id: string): void;
+    /** Stream frames for one attachment. */
+    attach(id: string, signal: AbortSignal): AsyncGenerator<TerminalFrame>;
+    /** Retain acknowledgement used by reconnecting windows. */
+    retain(): AsyncGenerator<{
+        type: 'retained';
+    }>;
+    /** Dispose every process. */
+    dispose(): void;
+}

package/lib/types/service.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Host registry + tunnel lifecycle service.
+ *
+ * One instance owns every configured remote host, at most one SSH tunnel per
+ * host, the remote agent client, health checks, and bounded reconnection with
+ * exponential backoff. The browser and agent tools only ever see
+ * {@link HostView}; tokens stay in this process.
+ *
+ * @module dsh-remote-local/service
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type AcceptedResult, type ApprovalOutcome, type RemoteApprovalFrame, type CreateSessionRequest, type CreateSessionResult, type CreateWorkspaceRequest, type ListSessionsResult, type PromptDeliveryMode, type RemoteWorkspace, type SessionSnapshot } from '@dsh-remote/protocol';
+import type { ResolvedConfig } from './config.ts';
+import { type AddHostInput, type HostView } from './hosts/types.ts';
+/** Snapshot returned to the Settings page. */
+export interface HostsState {
+    readonly protocolVersion: number;
+    readonly hosts: readonly HostView[];
+}
+/** Constructor inputs beyond config. */
+export interface RemoteHostsServiceOptions {
+    /** Resolve the local provider key at connect time; never cached in the view. */
+    readonly resolveModelKey?: () => Promise<string | undefined>;
+}
+/** One host registry service. */
+export declare class RemoteHostsService {
+    #private;
+    readonly ctx: Context;
+    readonly config: ResolvedConfig;
+    constructor(ctx: Context, config: ResolvedConfig, options?: RemoteHostsServiceOptions);
+    /** Load the registry and auto-connect opted-in hosts. */
+    start(): Promise<void>;
+    /** Browser/tool snapshot. */
+    state(): HostsState;
+    /** All hosts in creation order. */
+    list(): HostView[];
+    /** One host view. */
+    view(id: string): HostView;
+    /** Parse a destination without touching SSH. */
+    validateTarget(raw: string): {
+        canonical: string;
+        host: string;
+        user: string | null;
+        port: number | null;
+    };
+    /** Register a host and (by default) start connecting in the background. */
+    add(input: AddHostInput): Promise<HostView>;
+    /** Remove a host and tear down its tunnel. */
+    remove(id: string): Promise<void>;
+    /** Connect one host, waiting for discovery, tunnel, and health. */
+    connect(id: string): Promise<HostView>;
+    /** Disconnect one host and suppress automatic reconnection. */
+    disconnect(id: string): Promise<HostView>;
+    /** Re-discover the remote agent; reconnect when its port or token changed. */
+    refresh(id: string): Promise<HostView>;
+    /** Force a fresh remote install/restart, then reconnect. */
+    provision(id: string): Promise<HostView>;
+    /** List remote workspaces. */
+    workspaces(id: string): Promise<readonly RemoteWorkspace[]>;
+    /** List remote sessions, optionally within one workspace. */
+    sessions(id: string, workspaceId?: string): Promise<ListSessionsResult>;
+    /** Read one session snapshot. */
+    snapshot(id: string, sessionId: string, limit?: number): Promise<SessionSnapshot>;
+    /** Register a remote workspace. */
+    createWorkspace(id: string, request: CreateWorkspaceRequest): Promise<RemoteWorkspace>;
+    /** Create a remote session. */
+    createSession(id: string, request: CreateSessionRequest): Promise<CreateSessionResult>;
+    /** Send a prompt to a remote session. */
+    promptSession(id: string, sessionId: string, text: string, mode?: PromptDeliveryMode, selection?: {
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+    }): Promise<AcceptedResult>;
+    /** Cancel a remote session's active turn. */
+    cancelSession(id: string, sessionId: string): Promise<AcceptedResult>;
+    /** SSH invocation facts for auxiliary remote file/terminal adapters. */
+    sshFor(id: string): {
+        binary: string;
+        target: string;
+        port: number | null;
+    };
+    /** Follow remote approval questions for one host. */
+    followApprovals(id: string, signal: AbortSignal): AsyncGenerator<RemoteApprovalFrame>;
+    /** Send one approval answer to the remote agent. */
+    answerApproval(id: string, approvalId: string, outcome: ApprovalOutcome): Promise<AcceptedResult>;
+    /** Resolve the remote Web UI behind this host's tunnel. */
+    webUrl(id: string): Promise<{
+        url: string;
+    }>;
+    /** Stop every tunnel and timer. */
+    dispose(): Promise<void>;
+}

package/lib/types/ssh/probe.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SSH discovery of the remote agent's private state file.
+ *
+ * This is the only command the local plugin runs before a tunnel exists. It
+ * is fixed, bounded, and never interpolates user input into shell syntax.
+ *
+ * @module dsh-remote-local/ssh/probe
+ */
+import { type AgentDiscoveryState } from '@dsh-remote/protocol';
+import type { ParsedSshTarget } from './target.ts';
+/** Probe options. */
+export interface AgentProbeOptions {
+    readonly sshBinary: string;
+    readonly timeoutMs: number;
+    readonly strictHostKeyChecking: 'yes' | 'no' | 'ask' | 'accept-new';
+    readonly remoteStateFile: string;
+}
+/** Successful discovery. */
+export interface DiscoveryResult {
+    readonly state: AgentDiscoveryState;
+    readonly latencyMs: number;
+}
+/** Shell-quote one literal for the fixed remote command. */
+export declare function shellQuote(value: string): string;
+/** Build the fixed `cat` command for a remote state path. */
+export declare function discoveryCommand(remoteStateFile: string): string;
+/** SSH argv shared by discovery and tunnel startup. */
+export declare function baseSshArgs(target: ParsedSshTarget, options: {
+    timeoutMs: number;
+    strictHostKeyChecking: 'yes' | 'no' | 'ask' | 'accept-new';
+}): string[];
+/** Discover one host's running agent. */
+export declare function discoverAgent(target: ParsedSshTarget, options: AgentProbeOptions): Promise<DiscoveryResult>;

package/lib/types/ssh/target.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Strict SSH destination parser.
+ *
+ * The plugin spawns `ssh` with an argv array, never a shell, so the parser's
+ * job is to reject strings that could be mistaken for options or that carry
+ * shell metacharacters before they reach the process boundary.
+ *
+ * @module dsh-remote-local/ssh/target
+ */
+/** One validated SSH destination. */
+export interface ParsedSshTarget {
+    readonly raw: string;
+    readonly user: string | null;
+    readonly host: string;
+    readonly port: number | null;
+    /** `user@host` for argv. */
+    readonly destination: string;
+    /** Canonical user/host/port spelling used for ids and duplicate checks. */
+    readonly canonical: string;
+}
+/** Parse and validate a destination such as `user@host`, `host:2222`, or `ssh://user@host:22`. */
+export declare function parseSshTarget(raw: string): ParsedSshTarget;
+/** Validate a display label. */
+export declare function validateHostLabel(label: string): string;

package/lib/types/ssh/tunnel.d.ts

@@ -0,0 +1,50 @@
+/**
+ * One SSH local-forward tunnel to a remote agent.
+ *
+ * The tunnel binds `127.0.0.1` only and forwards to the remote agent's
+ * loopback port. It never exposes a public interface and never starts a
+ * shell on the remote side (`-N`).
+ *
+ * @module dsh-remote-local/ssh/tunnel
+ */
+import type { ParsedSshTarget } from './target.ts';
+/** Tunnel options. */
+export interface TunnelOptions {
+    readonly sshBinary: string;
+    readonly target: ParsedSshTarget;
+    readonly remotePort: number;
+    readonly connectTimeoutMs: number;
+    readonly strictHostKeyChecking: 'yes' | 'no' | 'ask' | 'accept-new';
+    /** Reverse forward used by the local model credential proxy. */
+    readonly reverseForward?: {
+        readonly remotePort: number;
+        readonly localPort: number;
+    };
+    /** Called once when an unexpected exit happens. */
+    readonly onExit?: (info: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+        stderr: string;
+    }) => void;
+}
+/** Build the tunnel argv (exported for tests). */
+export declare function tunnelArgs(options: TunnelOptions, localPort: number): string[];
+/** Ask the OS for one free loopback port. */
+export declare function allocateLocalPort(): Promise<number>;
+/** Wait until a loopback port accepts a TCP connection. */
+export declare function waitForPort(port: number, timeoutMs: number): Promise<void>;
+/** A started SSH tunnel. */
+export declare class Tunnel {
+    #private;
+    readonly localPort: number;
+    readonly localUrl: string;
+    private constructor();
+    /** Start a tunnel, retrying port allocation if the first bind races. */
+    static start(options: TunnelOptions, attempts?: number): Promise<Tunnel>;
+    /** Child process id. */
+    get pid(): number | undefined;
+    /** Captured stderr tail. */
+    get stderr(): string;
+    /** Stop the tunnel; idempotent. */
+    stop(): Promise<void>;
+}

package/lib/types/tools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Model-facing tools for remote development.
+ *
+ * These are deliberately thin wrappers over the same service the Settings
+ * page uses. They let an agent add a host, inspect its status, and read remote
+ * workspaces/sessions without a UI detour; secrets are never returned.
+ *
+ * @module dsh-remote-local/tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RemoteHostsService } from './service.ts';
+/**
+ * Require an explicit approval before model-facing host writes. These tools can
+ * start SSH connections and, in direct-key mode, copy the local model key into
+ * the remote service environment.
+ */
+export declare function installRemoteToolGuards(ctx: Context): void;
+/** Register the remote-development tool family. */
+export declare function registerRemoteTools(ctx: Context, service: RemoteHostsService): void;

package/node_modules/dsh-remote-terminal-controller/README.md

@@ -0,0 +1,9 @@
+# dsh-remote-terminal-controller
+
+Profile-level fork of `@deepseek-ai/dsh-api-terminal-controller`.
+
+- Host half re-exports the stock `TerminalController`.
+- Client half constructs `ClientTerminals` with a Session-routing remote face:
+  - local Sessions keep the stock local PTY controller;
+  - mirrored remote Sessions use `/api/dsh-remote-terminal` (SSH PTY).
+- The bundle patch replaces the stock `terminal-controller` row in the selected DSH profile.

package/node_modules/dsh-remote-terminal-controller/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Disable the stock terminal-controller row and insert this fork in its place.
+# `name` in a non-insert patch only asserts an existing name, so replacement is
+# expressed as disable + insert.
+- id: terminal-controller
+  disabled: true
+- insert:
+    - id: terminal-controller-remote
+      name: dsh-remote-terminal-controller