dsh-remote-vs 0.0.0-stage → 0.8.3

package/src/timeouts.ts

@@ -0,0 +1,122 @@
+/**
+ * One timeout policy for every remote round trip.
+ *
+ * Why this module exists
+ * ----------------------
+ * Large remote repositories made the explorer look broken: `git status` on a
+ * cold tree takes minutes, while the client gave up at a fixed 45 s and showed
+ * "读取超时（远端无响应）" with git still working. The number therefore has to be
+ * (a) bigger by default, (b) the same on both halves, and (c) editable, because
+ * how large "large" is differs per host.
+ *
+ * The Host owns the setting (`gitTimeoutMs` / `readTimeoutMs` in the plugin
+ * config, editable in the settings form) and serves the effective pair through
+ * `/api/dsh-remote/workspaces`; the client applies it and falls back to these
+ * defaults when an older Host answers without them. Nothing here may throw on a
+ * malformed value — a bad config must degrade to the default, not break the
+ * explorer.
+ */
+import type { RemoteTimeouts } from './protocol.ts'
+
+/** Smallest accepted timeout: below this, local work would start failing. */
+export const MIN_TIMEOUT_MS = 1_000
+
+/** Largest accepted timeout — the exec route clamps to the same ceiling. */
+export const MAX_TIMEOUT_MS = 600_000
+
+/**
+ * Default for one git command (status/log/branches/diff over exec).
+ *
+ * 120 s was the old internal value and 45 s the old client deadline; both were
+ * routinely exceeded by a cold `git status` on a large monorepo. Five minutes
+ * still fails eventually (a wedged host must not spin forever) but outlasts any
+ * plausible cold index walk.
+ */
+export const DEFAULT_GIT_TIMEOUT_MS = 300_000
+
+/** Default for one SFTP file read (editor, diff sides, document preview). */
+export const DEFAULT_READ_TIMEOUT_MS = 120_000
+
+/** The pair every half starts from before any Host answer arrives. */
+export const DEFAULT_TIMEOUTS: RemoteTimeouts = {
+  gitMs: DEFAULT_GIT_TIMEOUT_MS,
+  readMs: DEFAULT_READ_TIMEOUT_MS,
+}
+
+/**
+ * Clamp one untrusted timeout into the accepted range.
+ *
+ * @param value - raw value (plugin config, JSON body, anything).
+ * @param fallback - used when the value is not a usable number.
+ * @returns a whole number of milliseconds within [MIN, MAX].
+ */
+export function clampTimeout(value: unknown, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  const whole = Math.floor(value)
+  if (whole < MIN_TIMEOUT_MS) return MIN_TIMEOUT_MS
+  if (whole > MAX_TIMEOUT_MS) return MAX_TIMEOUT_MS
+  return whole
+}
+
+/**
+ * Clamp an optional request timeout: absent/invalid stays absent, which is what
+ * the exec route forwards as "use the pool default".
+ *
+ * @param value - raw `timeoutMs` from a request body.
+ * @returns the clamped timeout, or undefined when the caller named none.
+ */
+export function clampExecTimeout(value: unknown): number | undefined {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return undefined
+  return clampTimeout(value, DEFAULT_GIT_TIMEOUT_MS)
+}
+
+/** Resolve the effective pair from raw config values. */
+export function resolveTimeouts(config: {
+  gitTimeoutMs?: unknown
+  readTimeoutMs?: unknown
+} | undefined): RemoteTimeouts {
+  return {
+    gitMs: clampTimeout(config?.gitTimeoutMs, DEFAULT_GIT_TIMEOUT_MS),
+    readMs: clampTimeout(config?.readTimeoutMs, DEFAULT_READ_TIMEOUT_MS),
+  }
+}
+
+/**
+ * Normalize a pair that arrived over the wire (an older Host sends nothing).
+ *
+ * @param value - the `timeouts` field of a workspaces answer.
+ * @returns the pair to use, always complete and clamped.
+ */
+export function normalizeTimeouts(value: unknown): RemoteTimeouts {
+  const record = (typeof value === 'object' && value !== null ? value : {}) as {
+    gitMs?: unknown
+    readMs?: unknown
+  }
+  return resolveTimeouts({ gitTimeoutMs: record.gitMs, readTimeoutMs: record.readMs })
+}
+
+/** Human-facing seconds for one timeout ("300s"), used in status and errors. */
+export function timeoutSeconds(ms: number): string {
+  return `${Math.round(ms / 1000)}s`
+}
+
+/**
+ * Extra wait the CLIENT allows beyond the server-side budget.
+ *
+ * Both halves enforce a limit, so without a margin they race and the loser is
+ * effectively random — and the loser's message is much worse: the generic
+ * client deadline ("读取超时（远端无响应）") instead of git's own "timed out after
+ * Ns" plus the hint to raise the setting. The client therefore always waits a
+ * little longer than the command it is watching.
+ */
+export const CLIENT_DEADLINE_MARGIN_MS = 15_000
+
+/**
+ * The client's watchdog for one operation whose server-side budget is `ms`.
+ *
+ * @param ms - the command's own budget (git or SFTP).
+ * @returns a deadline strictly greater than `ms`, so the server-side error wins.
+ */
+export function clientDeadlineFor(ms: number): number {
+  return ms + CLIENT_DEADLINE_MARGIN_MS
+}

package/src/tools.ts

@@ -0,0 +1,320 @@
+/**
+ * Agent tools: the model-facing counterpart of the remote GUI. Every tool
+ * talks to the same pool/files the web UI uses. Hosts must be configured in
+ * the GUI first (agents cannot create hosts).
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { RemotePool } from './pool.ts'
+import { RemoteFiles } from './sftp.ts'
+import type { RemoteStore } from './store.ts'
+import type { RemoteExecResult, RemoteHostSummary } from './protocol.ts'
+
+function text(value: string): ContentBlock[] {
+  return [{ type: 'text', text: value }]
+}
+
+/** Agent-facing host row (schema-strict projection of RemoteHostSummary). */
+export interface AgentHostRow {
+  alias: string
+  host: string
+  port: number
+  user: string
+  auth: 'key' | 'password'
+  keyReady: boolean
+  managedKey: boolean
+  description?: string
+  tags: string[]
+  createdAt: number
+  updatedAt: number
+}
+
+function toAgentHostRow(host: RemoteHostSummary): AgentHostRow {
+  return {
+    alias: host.alias,
+    host: host.host,
+    port: host.port,
+    user: host.user,
+    auth: host.auth,
+    keyReady: host.keyReady,
+    managedKey: host.managedKey,
+    ...(host.description !== undefined ? { description: host.description } : {}),
+    tags: [...host.tags],
+    createdAt: host.createdAt,
+    updatedAt: host.updatedAt,
+  }
+}
+
+/**
+ * Render the host table.
+ *
+ * An empty list has TWO very different causes and they used to share one
+ * message: nothing is configured, or a query filtered everything out. The
+ * second one claimed "no remote hosts configured" while five were sitting
+ * there, which reads as "stop looking" to a caller that just searched.
+ */
+function renderHosts(hosts: RemoteHostSummary[], query?: string): string {
+  if (hosts.length === 0) {
+    return query === undefined || query.trim() === ''
+      ? 'no remote hosts configured (add one in the Remote sidebar tab first)'
+      : `no remote host matches "${query}" — hosts are configured, the query just filtered them all out`
+  }
+  const rows = hosts.map(h => [
+    h.alias, h.host, String(h.port), h.user, h.auth,
+    h.auth === 'key' ? (h.keyReady ? 'key-ok' : 'key-missing') : 'password',
+    h.tags.length > 0 ? h.tags.join(',') : '-',
+    h.description ?? '',
+  ].join(' | '))
+  return ['alias | host | port | user | auth | key | tags | description', '--- | --- | --- | --- | --- | --- | --- | ---', ...rows].join('\n')
+}
+
+/**
+ * `ls -l`-style type letter for one entry.
+ *
+ * A symlink is NOT a regular file, and rendering it as one made the two
+ * indistinguishable: `/bin`, `/lib`, `/lib64` and `/sbin` on an ordinary host
+ * are symlinks to directories, and they came out as `- 7 bin`, which reads as a
+ * seven-byte file. `isSymlink` is already in the entry, so the render simply has
+ * to use it. `.spike/tool-schema-check.mjs` now renders every tool and fails if
+ * these three kinds stop being distinguishable.
+ */
+function entryKind(entry: { isDir: boolean; isSymlink: boolean }): string {
+  if (entry.isDir) return 'd'
+  if (entry.isSymlink) return 'l'
+  return '-'
+}
+
+function renderExec(result: RemoteExecResult): string {
+  const marker = result.timedOut ? '[timed out]' : `[exit code: ${result.exitCode ?? 'null'}]`
+  const parts = [marker]
+  if (result.stdout !== '') parts.push('stdout:\n' + result.stdout)
+  if (result.stderr !== '') parts.push('stderr:\n' + result.stderr)
+  if (result.error !== undefined) parts.push('error: ' + result.error)
+  parts.push(`duration: ${result.durationMs} ms`)
+  return parts.join('\n')
+}
+
+/** Schema-strict exec outcome (exitCode null folds to undefined). */
+export interface AgentExecOut {
+  success: boolean
+  exitCode?: number
+  timedOut: boolean
+  stdout: string
+  stderr: string
+  durationMs: number
+  error?: string
+}
+
+export interface RemoteToolsDeps {
+  store: RemoteStore
+  pool: RemotePool
+}
+
+export function remoteHostsTool(deps: RemoteToolsDeps): ReturnType<typeof defineTool> {
+  return defineTool({
+    name: 'remote_hosts',
+    description: 'List configured remote SSH hosts (alias, host, user, auth). Use remote_exec/remote_read/remote_write/remote_ls with the alias.',
+    parameters: {
+      query: { type: 'string', description: 'Optional fuzzy match against alias, host, and description.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          hosts: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                alias: { type: 'string', required: true },
+                host: { type: 'string', required: true },
+                port: { type: 'integer', required: true },
+                user: { type: 'string', required: true },
+                auth: { type: 'string', enum: ['key', 'password'], required: true },
+                keyReady: { type: 'boolean', required: true },
+                managedKey: { type: 'boolean', required: true },
+                description: { type: 'string' },
+                tags: { type: 'array', items: { type: 'string' }, required: true },
+                createdAt: { type: 'integer', required: true },
+                updatedAt: { type: 'integer', required: true },
+              },
+            },
+          },
+        },
+      },
+      render: (args, value: { hosts?: AgentHostRow[] }) => text(renderHosts(value.hosts ?? [], args.query)),
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      const query = typeof args.query === 'string' && args.query !== '' ? args.query.toLowerCase() : undefined
+      const hosts = deps.store.list()
+        .map(h => deps.store.summarize(h))
+        .filter(h => query === undefined
+          || h.alias.toLowerCase().includes(query)
+          || h.host.toLowerCase().includes(query)
+          || (h.description ?? '').toLowerCase().includes(query))
+        .map(toAgentHostRow)
+      return { hosts }
+    },
+  })
+}
+
+export function remoteExecTool(deps: RemoteToolsDeps): ReturnType<typeof defineTool> {
+  return defineTool({
+    name: 'remote_exec',
+    description: 'Run a non-interactive shell command on a remote SSH host. stdout/stderr are returned verbatim (may carry secrets).',
+    parameters: {
+      alias: { type: 'string', description: 'Host alias from remote_hosts.' },
+      command: { type: 'string', description: 'Shell command to run on the remote host.' },
+      timeoutMs: { type: 'number', description: 'Timeout in ms (default 60000, max 600000).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          success: { type: 'boolean', required: true },
+          exitCode: { type: 'integer' },
+          timedOut: { type: 'boolean', required: true },
+          stdout: { type: 'string', required: true },
+          stderr: { type: 'string', required: true },
+          durationMs: { type: 'number', required: true },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value: AgentExecOut) => text(renderExec({ ...value, exitCode: value.exitCode ?? null })),
+    },
+    async execute(args) {
+      const timeoutMs = typeof args.timeoutMs === 'number' && Number.isFinite(args.timeoutMs)
+        ? Math.min(Math.max(Math.floor(args.timeoutMs), 1000), 600_000)
+        : undefined
+      const result = await deps.pool.exec(
+        args.alias as string,
+        args.command as string,
+        timeoutMs === undefined ? {} : { timeoutMs },
+      )
+      const out: AgentExecOut = {
+        success: result.success,
+        timedOut: result.timedOut,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        durationMs: result.durationMs,
+        ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
+        ...(result.error !== undefined ? { error: result.error } : {}),
+      }
+      return out
+    },
+  })
+}
+
+export function remoteLsTool(deps: RemoteToolsDeps): ReturnType<typeof defineTool> {
+  return defineTool({
+    name: 'remote_ls',
+    description: 'List one remote directory over SFTP (absolute POSIX path).',
+    parameters: {
+      alias: { type: 'string', description: 'Host alias from remote_hosts.' },
+      path: { type: 'string', description: 'Absolute remote directory path.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          entries: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                name: { type: 'string', required: true },
+                path: { type: 'string', required: true },
+                isDir: { type: 'boolean', required: true },
+                size: { type: 'integer', required: true },
+                mtime: { type: 'integer', required: true },
+                // `mode` is part of `RemoteFileEntry` and the implementation has
+                // always returned it, but this schema did not declare it — and
+                // the schema sets `additionalProperties: false`, so the tool
+                // failed validation on EVERY call since the first release:
+                //   "value.entries[0].mode" is not a declared property
+                // A declared output schema has to describe what the tool really
+                // returns; `.spike/tool-schema-check.mjs` now enforces that.
+                mode: { type: 'integer', required: true },
+                isSymlink: { type: 'boolean', required: true },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value: { entries?: { name: string; isDir: boolean; isSymlink: boolean; size: number }[] }) => text(
+        (value.entries ?? [])
+          .map(e => `${entryKind(e)} ${e.size} ${e.name}`)
+          .join('\n') || '(empty directory)',
+      ),
+    },
+    async execute(args) {
+      const files = new RemoteFiles(deps.pool)
+      return { entries: await files.list(args.alias as string, args.path as string) }
+    },
+  })
+}
+
+export function remoteReadTool(deps: RemoteToolsDeps): ReturnType<typeof defineTool> {
+  return defineTool({
+    name: 'remote_read',
+    description: 'Read a remote text file over SFTP (absolute POSIX path, first 8 MiB window). Refuses binary files.',
+    parameters: {
+      alias: { type: 'string', description: 'Host alias from remote_hosts.' },
+      path: { type: 'string', description: 'Absolute remote file path.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          size: { type: 'integer', required: true },
+          truncated: { type: 'boolean', required: true },
+          text: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value: { text?: string; truncated?: boolean }) => text(
+        (value.text ?? '') + (value.truncated === true ? '\n[... truncated: file exceeds 8 MiB ...]' : ''),
+      ),
+    },
+    async execute(args) {
+      const files = new RemoteFiles(deps.pool)
+      const result = await files.read(args.alias as string, args.path as string)
+      if (result.binary) throw new Error('binary file: remote_read serves text only')
+      return { size: result.size, truncated: result.truncated, text: result.text ?? '' }
+    },
+  })
+}
+
+export function remoteWriteTool(deps: RemoteToolsDeps): ReturnType<typeof defineTool> {
+  return defineTool({
+    name: 'remote_write',
+    description: 'Write a remote text file over SFTP (absolute POSIX path, creates parent dirs). Overwrites without confirmation.',
+    parameters: {
+      alias: { type: 'string', description: 'Host alias from remote_hosts.' },
+      path: { type: 'string', description: 'Absolute remote file path.' },
+      content: { type: 'string', description: 'UTF-8 text content to write.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          size: { type: 'integer', required: true },
+        },
+      },
+      render: (_args, value: { size?: number }) => text(`wrote ${value.size ?? 0} bytes`),
+    },
+    async execute(args) {
+      const files = new RemoteFiles(deps.pool)
+      return files.write(args.alias as string, args.path as string, args.content as string, 'utf8')
+    },
+  })
+}

package/vendor/dsh-remote-helpers/dsh-ssh-helper-0.2.1-alpha.2-linux-x64.helper.json

@@ -0,0 +1,16 @@
+{
+  "kind": "executable",
+  "version": "0.2.1-alpha.2",
+  "platform": "linux-x64",
+  "target": "node24-linux-x64",
+  "tarball": "dsh-ssh-helper-0.2.1-alpha.2-linux-x64.tar.gz",
+  "tarballSha256": "241c1e96e4fec14808440ac767bce5df64d566164f9fb3f338f2474aa2c50421",
+  "binarySha256": "a19a508d4e0659713f88ea32307a2cec4b4c16afa62e92c0a9fb8e41bdf7c3da",
+  "protocol": 2,
+  "nodeVersion": "v24.21.0",
+  "glibcCeiling": "2.35",
+  "builtAt": "2026-10-12T14:27:00+08:00",
+  "builtOn": "WSL2 Ubuntu-22.04 (glibc 2.35), node v24.21.0, pnpm 11.28.5, tag dsh-v0.2.1-alpha.2 (d7432673)",
+  "sourcePatch": "glibc-ceiling.patch",
+  "notes": "Upstream gate (2.28) relaxed to 2.35 via DSH_GLIBC_CEILING: no docker for the manylinux pty recompile; fleet glibc is 2.35. Official 8-check suite passed (verify-ssh-helper-artifact --sandbox=required)."
+}

package/vendor/dsh-remote-helpers/dsh-ssh-helper-0.2.1-alpha.2-linux-x64.tar.gz

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/vendor/dsh-remote-helpers/dsh-ssh-helper-0.2.1-alpha.2-linux-x64.tar.gz
+size: 46734323 bytes
+sha256: 241c1e96e4fec14808440ac767bce5df64d566164f9fb3f338f2474aa2c50421

package/vendor/dsh-remote-helpers/dsh-ssh-helper-0.2.1-alpha.2-linux-x64.tar.gz.sha256

@@ -0,0 +1 @@
+241c1e96e4fec14808440ac767bce5df64d566164f9fb3f338f2474aa2c50421  dsh-ssh-helper-0.2.1-alpha.2-linux-x64.tar.gz

package/vendor/dsh-remote-helpers/glibc-ceiling.patch

@@ -0,0 +1,31 @@
+diff --git a/scripts/ssh-helper/native.ts b/scripts/ssh-helper/native.ts
+index a6f4db14..e6a7ccee 100644
+--- a/scripts/ssh-helper/native.ts
++++ b/scripts/ssh-helper/native.ts
+@@ -4,6 +4,15 @@ import { open } from 'node:fs/promises'
+ import { join } from 'node:path'
+ import { payloadFiles, type SshHelperTarget } from './artifact.ts'
+ 
++/** Local-build override: DSH_GLIBC_CEILING (default 2.28) relaxes the payload baseline for fleets newer than 2.28. Upstream behavior unchanged when unset. */
++function glibcCeiling(): number[] {
++  const raw = (process.env.DSH_GLIBC_CEILING ?? "").trim();
++  if (raw === "") return [2, 28];
++  const parts = raw.split(".").map(Number);
++  if (parts.length === 0 || parts.some((n) => !Number.isInteger(n) || n < 0)) throw new Error(`Invalid DSH_GLIBC_CEILING: ${raw}`);
++  return parts;
++}
++
+ function newer(version: string, ceiling: number[]): boolean {
+   const components = version.split('.').map(Number)
+   for (let index = 0; index < Math.max(components.length, ceiling.length); index += 1) {
+@@ -58,8 +67,9 @@ export async function verifyNativePayload(directory: string, target: SshHelperTa
+       const expected = arch === 'arm64' ? /Machine:\s+AArch64/ : /Machine:\s+Advanced Micro Devices X86-64/
+       if (!expected.test(elfHeader)) throw new Error(`ELF architecture differs from ${target}: ${path}`)
+       const versions = execFileSync('readelf', ['--version-info', filename], { encoding: 'utf8' })
++      const ceiling = glibcCeiling();
+       for (const match of versions.matchAll(/\bGLIBC_(\d+(?:\.\d+)+)/g)) {
+-        if (newer(match[1] as string, [2, 28])) throw new Error(`${path} requires GLIBC_${match[1]}, exceeding 2.28`)
++        if (newer(match[1] as string, ceiling)) throw new Error(`${path} requires GLIBC_${match[1]}, exceeding ${ceiling.join(".")}`)
+       }
+     } else {
+       execFileSync('lipo', [filename, '-verify_arch', arch === 'arm64' ? 'arm64' : 'x86_64'], { stdio: 'pipe' })