dsh-wsl-tool 1.8.0

package/lib/runner.js

@@ -0,0 +1,273 @@
+// The single spawn path. Every call in this plugin goes through it, so the
+// stdio shape, grace period, deadline classification and truncation facts are
+// identical for the model-facing tool and the plugin's own probes.
+//
+// Launching is split from settling on purpose: a background job must hand the
+// jobs registry a synchronous `cancel`/`done` pair, while a foreground call just
+// awaits the same settle step. `launch()` is that shared synchronous half.
+
+import { FORWARDED_ENV_KEYS } from './config.js'
+import { buildCdCommand, shellQuote, windowsPathToWsl } from './paths.js'
+import { cleanStderr, normalizeExitCode, streamFacts } from './result.js'
+
+// Only allow distribution names that cannot inject shell syntax into argv.
+const DISTRO_RE = /^[A-Za-z0-9._-]+$/
+
+/**
+ * Resolve the distribution to use for one call.
+ *
+ * The caller's argument wins, then `DSH_WSL_DISTRO`, then the system default —
+ * signalled by `null`, which drops `-d` entirely. That last case is what makes
+ * the package portable: a hardcoded `Ubuntu-22.04` is a distro the author has
+ * and a storefront user may not.
+ *
+ * @returns a distro name, or null to let wsl.exe pick its default.
+ */
+export function resolveDistro(arg, config) {
+  const distro = arg ?? config.distro
+  if (distro === undefined || distro === null) return null
+  if (typeof distro !== 'string' || !DISTRO_RE.test(distro) || distro.trim() === '') {
+    throw new Error('wsl: distro must be a simple name (letters, digits, dot, dash, underscore)')
+  }
+  return distro
+}
+
+/**
+ * The calling session's workspace, taken from the execution the host hands us.
+ *
+ * This is `dsh-tool-fs`'s own source (`exec.agent.session.header.cwd`), and the
+ * distinction matters: `process.cwd()` is the directory the DSH *host* was
+ * launched from, which for a web deployment is the installation directory rather
+ * than the session's project. Anything keyed off the launch directory points a
+ * session at the wrong tree.
+ *
+ * @returns the session workspace, or undefined for a caller that has none.
+ */
+export function sessionCwdOf(exec) {
+  const cwd = exec?.agent?.session?.header?.cwd
+  return typeof cwd === 'string' && cwd !== '' ? cwd : undefined
+}
+
+/**
+ * Per-execution `DSH_*` facts, resolved the way the platform's shell tools
+ * resolve them.
+ *
+ * `process.env` is the WRONG source: these values are per-session, and the
+ * `ctx.shellEnv` registry builds them for each execution — a host-level read
+ * finds nothing and forwards nothing, silently. `process.env` remains only as a
+ * fallback for a deployment where the registry is absent.
+ */
+export function collectForwardEnv(ctx, exec) {
+  let facts
+  try {
+    facts = ctx?.get?.('shellEnv')?.collect?.(exec)
+  } catch {
+    facts = undefined
+  }
+  const source = facts !== null && typeof facts === 'object' ? facts : process.env
+
+  const forwarded = {}
+  for (const key of FORWARDED_ENV_KEYS) {
+    const value = source[key]
+    if (typeof value === 'string' && value !== '') forwarded[key] = value
+  }
+  if (forwarded.DSH_HOME !== undefined) forwarded.DSH_HOME = windowsPathToWsl(forwarded.DSH_HOME)
+  return forwarded
+}
+
+// A launcher-level failure means bash never ran, so surface it as a tool error
+// instead of handing the model a meaningless exit code. The Wsl/Service/WSL_E_*
+// code is locale-independent, unlike the message around it.
+const LAUNCHER_ERROR_RE = /Wsl\/Service\/(WSL_E_[A-Z0-9_]+)/
+
+export function assertLauncherReachable(distro, result) {
+  if (result.exitCode === 0) return
+  const match = LAUNCHER_ERROR_RE.exec(`${result.stderr}\n${result.stdout}`)
+  if (match === null) return
+
+  const detail = result.stderr.trim().split(/\r?\n/)[0]
+  if (match[1] === 'WSL_E_DISTRO_NOT_FOUND') {
+    throw new Error(
+      `wsl: distribution ${distro === null ? '(system default)' : `"${distro}"`} is not registered. ` +
+      'Run the wsl-env tool (or `wsl -l -v`) to list the available distributions.',
+    )
+  }
+  throw new Error(
+    `wsl: the WSL launcher failed (${match[1]})${detail === '' ? '' : `: ${detail}`}. ` +
+    'Check that WSL and its service are healthy (`wsl --status`).',
+  )
+}
+
+/**
+ * Build the runner bound to one mount's context and configuration.
+ * @param ctx - plugin context providing the host `subprocess` service.
+ * @param config - resolved configuration (see `resolveConfig`).
+ */
+export function createRunner(ctx, config) {
+  const { maxOutputBytes, maxSpillBytes, graceMs, maxTimerDelayMs, maxCommandChars, maxCommandTimeoutMs } = config
+
+  /**
+   * Spawn immediately and return the handle plus a `settle()` that awaits it and
+   * builds the model-facing value. Synchronous, so background jobs can attach
+   * their hooks without waiting a tick.
+   */
+  function launch(argv, timeoutMs, stdinData) {
+    const controller = new AbortController()
+    const state = { timedOut: false, cancelled: false }
+    // A per-call deadline is capped like the platform shell tools cap theirs,
+    // and by the same value the default obeys, so the `timeoutMs` reported back
+    // is always the deadline that was actually armed.
+    const effectiveTimeoutMs = typeof timeoutMs === 'number' && timeoutMs > 0
+      ? Math.min(timeoutMs, maxCommandTimeoutMs, maxTimerDelayMs)
+      : null
+
+    let handle
+    try {
+      handle = ctx.subprocess.spawn({
+        argv,
+        // Required by the dsh 0.1.5 subprocess seam: every spawn spec states its
+        // own working directory. The Linux-side directory is set by the `cd`
+        // prefix the caller builds, so the Windows-side cwd only has to be a
+        // real directory (it also becomes the initial WSL cwd).
+        cwd: process.cwd(),
+        env: { WSL_UTF8: '1' },
+        stdio: {
+          stdin: typeof stdinData === 'string' ? { data: stdinData } : 'ignore',
+          stdout: { maxBytes: maxOutputBytes, spill: { maxBytes: maxSpillBytes } },
+          stderr: { maxBytes: maxOutputBytes, spill: { maxBytes: maxSpillBytes } },
+        },
+        graceMs,
+        signal: controller.signal,
+      })
+    } catch (error) {
+      throw new Error(`wsl: could not launch ${argv[0]}: ${error?.message ?? String(error)}`)
+    }
+
+    // Armed AFTER the child exists: the deadline measures the child's lifetime,
+    // and an already-aborted signal can never reach the provider (which throws
+    // "aborted before spawn" instead of starting anything).
+    let timer = null
+    if (effectiveTimeoutMs !== null) {
+      timer = setTimeout(() => {
+        state.timedOut = true
+        controller.abort()
+      }, effectiveTimeoutMs)
+    }
+
+    async function settle() {
+      try {
+        let outcome
+        try {
+          outcome = await handle.done
+        } catch (error) {
+          throw new Error(`wsl: ${argv[0]} failed to run: ${error?.message ?? String(error)}`)
+        }
+
+        const stdout = streamFacts(handle.collected?.stdout?.readFrom(0))
+        const stderr = streamFacts(handle.collected?.stderr?.readFrom(0))
+
+        return {
+          exitCode: normalizeExitCode(outcome.exitCode ?? null),
+          signal: outcome.signal ?? null,
+          timedOut: state.timedOut,
+          timeoutMs: effectiveTimeoutMs,
+          stdout: stdout.text,
+          stderr: cleanStderr(stderr.text),
+          truncated: stdout.lossy || stderr.lossy,
+          stdoutTotalBytes: stdout.totalBytes,
+          stdoutDroppedBytes: stdout.droppedBytes,
+          stderrTotalBytes: stderr.totalBytes,
+          stderrDroppedBytes: stderr.droppedBytes,
+          stdoutSpillPath: stdout.spillPath,
+          stderrSpillPath: stderr.spillPath,
+          // Present for every call so the declared output schema holds: only a
+          // background START carries an id.
+          jobId: null,
+        }
+      } finally {
+        if (timer !== null) clearTimeout(timer)
+      }
+    }
+
+    return {
+      handle,
+      state,
+      settle,
+      effectiveTimeoutMs,
+      /** Idempotent, like the seam's own `terminate()`. */
+      cancel() {
+        state.cancelled = true
+        handle.terminate()
+      },
+    }
+  }
+
+  async function spawnWsl(argv, timeoutMs, stdinData) {
+    return await launch(argv, timeoutMs, stdinData).settle()
+  }
+
+  /** Build the argv (and stdin form) for one `wsl` command. */
+  function planCommand(command, opts = {}) {
+    const distro = resolveDistro(opts.distro, config)
+    const requested = opts.workdir !== undefined && opts.workdir !== '' ? opts.workdir : null
+    // "session" mode means the CALLING SESSION's workspace, not the directory the
+    // host process happened to be launched from.
+    const sessionCwd = sessionCwdOf(opts.exec)
+    const workdir = requested !== null
+      ? windowsPathToWsl(requested)
+      : config.defaultWorkdir === null
+        ? windowsPathToWsl(sessionCwd ?? process.cwd())
+        : config.defaultWorkdir
+
+    let full = `${buildCdCommand(workdir)} && ${command}`
+    // Forwarded host facts first, then the caller's own entries: an explicit
+    // `env` value always wins over an inherited one.
+    const env = { ...collectForwardEnv(ctx, opts.exec), ...(opts.env && typeof opts.env === 'object' ? opts.env : {}) }
+    const exports = Object.entries(env)
+      .map(([k, v]) => (v === undefined ? `unset ${k}` : `export ${k}=${shellQuote(v)}`))
+    if (exports.length > 0) full = exports.join('; ') + '; ' + full
+
+    // The script travels as an argv string, except past the Windows
+    // command-line limit where it is fed to `bash -ls` on stdin instead. That
+    // fallback owns stdin, so it cannot coexist with caller-supplied stdin.
+    const viaStdin = full.length > maxCommandChars
+    if (viaStdin && typeof opts.stdin === 'string') {
+      throw new Error(
+        `wsl: this command is over the ${maxCommandChars}-character command-line limit, so the script itself must travel on stdin — ` +
+        'it cannot also carry `stdin` data. Write the script to a file and run that, or split the command.',
+      )
+    }
+
+    const distroArgs = distro === null ? [] : ['-d', distro]
+    return {
+      distro,
+      argv: viaStdin
+        ? ['wsl.exe', ...distroArgs, '-e', 'bash', '-ls']
+        : ['wsl.exe', ...distroArgs, '-e', 'bash', '-lc', full],
+      stdinData: viaStdin ? full : opts.stdin,
+    }
+  }
+
+  /** Run a Linux command to completion. */
+  async function runWsl(command, opts = {}) {
+    const plan = planCommand(command, opts)
+    const result = await spawnWsl(plan.argv, opts.timeoutMs, plan.stdinData)
+    assertLauncherReachable(plan.distro, result)
+    return result
+  }
+
+  /** Launch a Linux command without awaiting it (background jobs). */
+  function startWsl(command, opts = {}) {
+    const plan = planCommand(command, opts)
+    return { plan, launched: launch(plan.argv, opts.timeoutMs, plan.stdinData) }
+  }
+
+  return {
+    spawnWsl,
+    runWsl,
+    startWsl,
+    planCommand,
+    /** Bound to this mount's config, so callers never re-resolve env vars. */
+    resolveDistro: (arg) => resolveDistro(arg, config),
+  }
+}

package/lib/tools/wsl-env.js

@@ -0,0 +1,113 @@
+// The `wsl-env` tool: summarize the WSL environment so an agent knows what it
+// is running on before it starts issuing commands.
+
+import { CAPABILITY_PROBE, capabilityLines, launcherSummary, parseFacts, workspaceLine } from '../diagnostics.js'
+import { sessionCwdOf } from '../runner.js'
+
+/** The `*`-marked row of `wsl -l -v` is the default distribution. */
+export function parseDefaultDistro(listOutput) {
+  for (const line of String(listOutput).split(/\r?\n/)) {
+    const match = /^\s*\*\s*(\S+)/.exec(line)
+    if (match !== null) return match[1]
+  }
+  return null
+}
+
+export function createWslEnvTool({ config, runner }) {
+  return {
+    name: 'wsl-env',
+    description:
+      'Summarize the WSL environment: registered distributions, kernel and architecture, CPU count, ' +
+      'memory and disk usage, and what the machine can actually do — WSL1 or WSL2, systemd, cgroup ' +
+      'version, GPU passthrough, docker, mounted drives, and the /etc/wsl.conf + .wslconfig settings. ' +
+      'Use it to decide what is available before running commands.',
+    parameters: {
+      type: 'object',
+      properties: {
+        distro: {
+          type: 'string',
+          description: 'WSL distribution to probe. Defaults to the system default distribution.',
+        },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          summary: { type: 'string' },
+        },
+        required: ['summary'],
+      },
+      render: (_args, value) => [{ type: 'text', text: value.summary }],
+    },
+    async execute(args, exec) {
+      const resolved = runner.resolveDistro(args.distro)
+      const label = resolved === null ? 'the default WSL distribution' : `distro "${resolved}"`
+      const opts = { distro: args.distro, timeoutMs: config.internalTimeoutMs, exec }
+
+      // The probes are independent, so run them concurrently: each wsl.exe
+      // launch costs a WSL round trip, and sequential ones would dominate this
+      // tool's latency. Measured: 5 parallel spawns cost the same as one.
+      const [uname, caps, launcher, mem, disk, list] = await Promise.all([
+        runner.runWsl('uname -srm && echo "nproc: $(nproc)"', opts),
+        // Every capability fact that needs no separate launch travels in one
+        // script, so the diagnostics stay free rather than costing 8 spawns.
+        runner.runWsl(CAPABILITY_PROBE, opts),
+        runner.spawnWsl(['wsl.exe', '--version'], config.internalTimeoutMs),
+        runner.runWsl("free -h | awk 'NR==1 || NR==2'", opts),
+        runner.runWsl('df -h / /home 2>/dev/null || df -h /', opts),
+        runner.spawnWsl(['wsl.exe', '-l', '-v'], config.internalTimeoutMs),
+      ])
+
+      const failure = (name, result) => {
+        const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`
+        return `[${name} unavailable: ${detail.split(/\r?\n/)[0]}]`
+      }
+
+      // Nothing worked: report it instead of returning a summary that silently
+      // omits the kernel, memory and disk the caller asked for.
+      if (uname.exitCode !== 0) {
+        const detail = uname.stderr.trim() || uname.stdout.trim() || `exit code ${uname.exitCode}`
+        throw new Error(`wsl-env: could not probe ${label}: ${detail}`)
+      }
+
+      // Name the distribution actually used, so "system default" is never a
+      // mystery the caller has to resolve with a second call.
+      const name = resolved ?? parseDefaultDistro(list.stdout)
+      const header = [
+        name === null ? 'distro: (system default)' : `distro: ${name}${resolved === null ? ' (system default)' : ''}`,
+        uname.stdout.trim(),
+      ]
+      // Capabilities degrade one line at a time: a probe that failed leaves its
+      // line out instead of failing the whole summary.
+      if (caps.exitCode === 0) header.push(...capabilityLines(parseFacts(caps.stdout)))
+      else header.push(failure('capabilities', caps))
+      const launcherLine = launcher.exitCode === 0 ? launcherSummary(launcher.stdout) : null
+      if (launcherLine !== null) header.push(`launcher: ${launcherLine}`)
+      // Where the session's own files live is the one fact here that changes what
+      // the caller should choose to DO, so it is stated rather than implied — and
+      // it is the CALLING SESSION's workspace, never the host's launch directory.
+      const workspace = workspaceLine(sessionCwdOf(exec) ?? process.cwd())
+      if (workspace !== null) header.push(workspace)
+
+      const lines = [header.join('\n')]
+      lines.push(mem.exitCode === 0 ? mem.stdout.trimEnd() : failure('memory', mem))
+      lines.push(disk.exitCode === 0 ? disk.stdout.trimEnd() : failure('disk', disk))
+      // `wsl -l -v` can exit 0 with nothing on stdout; a bare header would be
+      // the only thing this section contributes, so report it as a failure.
+      if (list.exitCode === 0 && list.stdout.trim() !== '') {
+        lines.push('--- distributions ---\n' + list.stdout.trimEnd())
+      } else if (list.exitCode === 0) {
+        lines.push('[distribution list unavailable: wsl -l -v produced no output]')
+      } else {
+        lines.push(failure('distribution list', list))
+      }
+
+      return { summary: lines.filter((line) => line.length > 0).join('\n\n') }
+    },
+    // See wsl-path: only generic/terminal/diff exist, and `description` is a
+    // terminal-card field rather than a generic one.
+    presentCall: () => ({ card: 'generic', title: 'Inspect the WSL environment' }),
+  }
+}

package/lib/tools/wsl-path.js

@@ -0,0 +1,77 @@
+// The `wsl-path` tool: convert a path with `wslpath` in either direction.
+
+import { quotePath } from '../paths.js'
+
+const WINDOWS_PATH_RE = /^[a-zA-Z]:[\\/]/
+const UNC_PATH_RE = /^\\\\/
+
+export function createWslPathTool({ config, runner }) {
+  return {
+    name: 'wsl-path',
+    description:
+      'Convert between Windows and WSL/Linux paths using `wslpath`. ' +
+      'Pass a Windows path (e.g. `C:\\Users\\me\\a.txt`) to get its `/mnt/c/...` form, or a Linux path ' +
+      '(e.g. `/home/me/a.txt`) to get its `\\\\wsl.localhost\\...` form. ' +
+      'Use `direction` to force `win` or `linux`; leave it unset for auto-detection.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'The path to convert.',
+        },
+        direction: {
+          type: 'string',
+          enum: ['auto', 'win', 'linux'],
+          description: "Conversion direction: 'win' (Linux->Windows result) or 'linux' (Windows->WSL result). Default auto.",
+        },
+        distro: {
+          type: 'string',
+          description: 'WSL distribution to use. Defaults to the system default distribution.',
+        },
+      },
+      required: ['path'],
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          input: { type: 'string' },
+          converted: { type: 'string' },
+        },
+        required: ['input', 'converted'],
+      },
+      render: (_args, value) => [{ type: 'text', text: `${value.input} -> ${value.converted}` }],
+    },
+    async execute(args, exec) {
+      if (typeof args.path !== 'string' || args.path.trim() === '') {
+        throw new Error('wsl-path: path must be a non-empty string')
+      }
+      const looksWindows = WINDOWS_PATH_RE.test(args.path) || UNC_PATH_RE.test(args.path)
+      const direction = args.direction === 'win' || args.direction === 'linux'
+        ? args.direction
+        : (looksWindows ? 'linux' : 'win')
+      // wslpath -u <windows>  -> WSL path;  wslpath -w <linux>  -> Windows path
+      const flag = direction === 'win' ? '-w' : '-u'
+      const res = await runner.runWsl(`wslpath ${flag} ${quotePath(args.path)}`, {
+        distro: args.distro,
+        timeoutMs: config.internalTimeoutMs,
+        exec,
+      })
+      if (res.exitCode !== 0) {
+        const detail = (res.stderr || res.stdout).trim() || `exit code ${res.exitCode}`
+        throw new Error(`wsl-path: wslpath failed: ${detail}`)
+      }
+      const converted = res.stdout.trim()
+      if (converted === '') {
+        throw new Error(`wsl-path: wslpath returned no path for ${JSON.stringify(args.path)}`)
+      }
+      return { input: args.path, converted }
+    },
+    // `ToolCallView` knows exactly three cards: generic, terminal, diff. A card
+    // outside that set has no renderer, and a generic card has no `description`
+    // slot — both of those were wrong here until the platform type was read.
+    presentCall: (args) => ({ card: 'generic', title: `Convert path ${args.path}` }),
+  }
+}