dsh-wsl-tool 1.8.0

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# This bundle layer registers the wsl tool plugin in an agent preset.
+# Presets can also add the row manually instead of relying on this patch.
+
+# The entry name is PATH-RELATIVE on purpose. DSH anchors a relative `name:` to
+# the directory of the patch file that declared it (`anchorInsertedPluginNames`),
+# so this row always loads this bundle's own `index.js` — whatever the package
+# folder happens to be called. A bare package name would instead have to match
+# the installed folder name, which couples this file to the npm package name:
+# the registry refuses `dsh-wsl` as too similar to `is-wsl`, so the published
+# name is `dsh-wsl-tool` while a local `file:` install may sit in
+# `node_modules/dsh-wsl`. Keep this relative.
+
+- insert:
+    - id: tool-wsl
+      name: './index.js'

package/index.js

@@ -0,0 +1,39 @@
+// dsh-wsl: model-facing WSL tools for DeepSeek Harness (DSH).
+//
+// Registers three tools:
+//   - `wsl`      : run a Linux command through wsl.exe, returning stdout/stderr
+//                  with exit-code / signal / timeout / truncation markers.
+//   - `wsl-path` : convert between Windows and WSL paths via `wslpath`.
+//   - `wsl-env`  : summarize the WSL environment (distros, kernel, cpu, mem,
+//                  disk) so an agent knows what it is running on.
+//
+// Each call runs in a fresh shell, so no state persists between calls. This
+// plugin publishes nothing and only consumes the host-plane `subprocess` and
+// `tools` registries, so it sits loose in an agent preset without a realm.
+//
+// The implementation lives in `lib/`: `config` (defaults and environment
+// overrides), `paths` (path translation and shell quoting), `guard` (the
+// destructive-command rules), `result` (markers and truncation), `runner` (the
+// one spawn path) and `tools/` (the three tool definitions).
+
+import { resolveConfig } from './lib/config.js'
+import { createRunner } from './lib/runner.js'
+import { createWslTool } from './lib/tools/wsl.js'
+import { createWslPathTool } from './lib/tools/wsl-path.js'
+import { createWslEnvTool } from './lib/tools/wsl-env.js'
+
+export const name = 'tool-wsl'
+export const inject = ['tools', 'subprocess']
+
+export function apply(ctx) {
+  // Read the environment once per mount: a configuration change is a mount
+  // (i.e. a DSH restart), not something a running session re-reads.
+  const config = resolveConfig()
+  const runner = createRunner(ctx, config)
+  // `ctx` is passed for the optional `jobs` service only (background commands);
+  // it is read with ctx.get at call time, never injected, so a preset without
+  // tool-jobs still mounts this plugin.
+  ctx.tools.register(createWslTool({ ctx, config, runner }))
+  ctx.tools.register(createWslPathTool({ config, runner }))
+  ctx.tools.register(createWslEnvTool({ config, runner }))
+}

package/lib/config.js

@@ -0,0 +1,130 @@
+// Resolved settings for one mounted plugin instance.
+//
+// Everything tunable lives here. The numeric knobs are environment-overridable
+// so a deployment can tune them without editing this package; an unparsable or
+// out-of-range value falls back to the default instead of failing the mount,
+// because one bad environment variable must not take all three tools down.
+
+import { windowsPathToWsl } from './paths.js'
+
+export const DEFAULTS = {
+  /** Linux-side directory used when the caller passes no `workdir`. */
+  workdir: '~',
+  /** Deadline for a model-issued command; `timeoutMs` overrides it per call. */
+  commandTimeoutMs: 10 * 60 * 1000,
+  /** Ceiling for a per-call `timeoutMs`, mirroring the platform shell tools'
+   *  `maxTimeoutMs`: a slip of the keyboard must not mean "never time out". */
+  maxCommandTimeoutMs: 24 * 60 * 60 * 1000,
+  /** Hard ceiling for the plugin's OWN probes (`wsl -l -v`, `wslpath`, `wsl-env`). */
+  internalTimeoutMs: 30 * 1000,
+  /** Grace period handed to the provider's termination procedure. */
+  graceMs: 3000,
+  /** Per-stream in-memory output window; overflow keeps the tail. */
+  maxOutputBytes: 64 * 1024,
+  /** Per-stream spill-file cap; a larger stream loses its complete-stream file. */
+  maxSpillBytes: 64 * 1024 * 1024,
+  /** Windows caps a whole command line at 32767 chars; above this the script
+   *  is fed to `bash -ls` on stdin instead. */
+  maxCommandChars: 30_000,
+  /** `setTimeout` stores its delay in a signed 32-bit int; larger fires at once. */
+  maxTimerDelayMs: 2 ** 31 - 1,
+}
+
+/**
+ * Host shell facts forwarded into the Linux side.
+ *
+ * WSL does not pass Windows environment variables into a distribution (that is
+ * what `WSLENV` is for), so without this the Linux side sees none of the facts
+ * the platform's own shell tools inject, and a script reading `$DSH_SESSION_ID`
+ * silently gets nothing.
+ *
+ * Only the KEYS live here; the values are per-execution — `DSH_SESSION_ID` cannot
+ * be a host constant, since one host serves many sessions — so they are collected
+ * by `runner.collectForwardEnv` from the platform's own `ctx.shellEnv` registry,
+ * the same source the model's other shell tools use.
+ *
+ * `DSH_WEB_URL` is deliberately NOT in this list: it is a `127.0.0.1` URL for the
+ * Windows-side server, and in the default NAT networking mode WSL cannot reach
+ * Windows loopback (measured: HTTP 000 both on `127.0.0.1` and on the host IP,
+ * which the server does not bind either). Forwarding it would hand out a URL
+ * that cannot be opened. `DSH_HOME` is a Windows path, so it is translated to
+ * the same directory's `/mnt/...` view.
+ */
+export const FORWARDED_ENV_KEYS = ['DSH_SESSION_ID', 'DSH_SHELL', 'DSH_HOME']
+
+// Bounds for the environment-overridable knobs, so a typo cannot silently
+// produce an absurd window or a deadline that fires instantly.
+const OUTPUT_BYTES_MIN = 1024
+const OUTPUT_BYTES_MAX = 8 * 1024 * 1024
+const TIMEOUT_MS_MIN = 100
+
+const ENV_INT_RE = /^\d+$/
+
+function envInt(env, name, fallback, min, max) {
+  const raw = env[name]
+  if (typeof raw !== 'string') return fallback
+  const trimmed = raw.trim()
+  if (!ENV_INT_RE.test(trimmed)) return fallback
+  const value = Number(trimmed)
+  return value >= min && value <= max ? value : fallback
+}
+
+/** @returns a distribution name to pin, or null to use the system default. */
+function envDistro(env) {
+  const raw = env.DSH_WSL_DISTRO
+  return typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : null
+}
+
+/**
+ * Where a call starts when the caller passes no `workdir`.
+ *
+ * `home` (the default) keeps the documented `~`. `session` starts in the
+ * session's working directory — the plugin's own process cwd, the same source
+ * `dsh-pwsh-local` uses by default — which is what an agent working on a
+ * Windows checkout usually wants, since its files live at `/mnt/<drive>/...`
+ * rather than in the Linux home. Anything else is an explicit default path.
+ *
+ * @returns a path, or null meaning "the process working directory".
+ */
+function envWorkdir(env) {
+  const raw = env.DSH_WSL_WORKDIR
+  if (typeof raw !== 'string' || raw.trim() === '') return DEFAULTS.workdir
+  const value = raw.trim()
+  if (value === 'home') return DEFAULTS.workdir
+  if (value === 'session') return null
+  return value
+}
+
+/**
+ * Resolve the effective configuration for one mount.
+ *
+ * `DSH_WSL_MAX_OUTPUT_BYTES` also raises the spill ceiling when needed, since a
+ * spill file smaller than the in-memory window could never hold the complete
+ * stream and would be discarded exactly when it is most useful.
+ *
+ * @param env - environment to read (injectable for tests).
+ */
+export function resolveConfig(env = process.env) {
+  const maxOutputBytes = envInt(
+    env, 'DSH_WSL_MAX_OUTPUT_BYTES', DEFAULTS.maxOutputBytes, OUTPUT_BYTES_MIN, OUTPUT_BYTES_MAX,
+  )
+  const maxCommandTimeoutMs = envInt(
+    env, 'DSH_WSL_MAX_TIMEOUT_MS', DEFAULTS.maxCommandTimeoutMs, TIMEOUT_MS_MIN, DEFAULTS.maxTimerDelayMs,
+  )
+  return {
+    ...DEFAULTS,
+    // null means "whatever wsl.exe uses by default", which is what makes the
+    // package portable: `Ubuntu-22.04` exists on the author's machine, not
+    // necessarily on a storefront user's.
+    distro: envDistro(env),
+    defaultWorkdir: envWorkdir(env),
+    maxOutputBytes,
+    maxSpillBytes: Math.max(DEFAULTS.maxSpillBytes, maxOutputBytes),
+    maxCommandTimeoutMs,
+    // The default deadline obeys the cap too, so the two knobs cannot disagree.
+    commandTimeoutMs: Math.min(
+      envInt(env, 'DSH_WSL_TIMEOUT_MS', DEFAULTS.commandTimeoutMs, TIMEOUT_MS_MIN, DEFAULTS.maxTimerDelayMs),
+      maxCommandTimeoutMs,
+    ),
+  }
+}

package/lib/diagnostics.js

@@ -0,0 +1,150 @@
+// Capability diagnostics for `wsl-env`: one probe script, its parser, and the
+// compact lines composed from it.
+//
+// The question this answers is "can this machine run X?" — WSL1 or 2, systemd,
+// cgroup version, GPU passthrough, docker, which drives are mounted, and how WSL
+// itself is configured. Every fact is optional: a missing tool or a disabled
+// interop must degrade to a label, never fail the whole summary.
+
+import { windowsPathToWsl } from './paths.js'
+
+const WINDOWS_MOUNT_RE = /^\/mnt\/([a-z])(?:\/|$)/
+
+/**
+ * Describe where the session's own working directory lands inside WSL.
+ *
+ * This is the one fact that changes what the model should DO rather than what it
+ * can do: a checkout under `/mnt/<drive>` goes through the Windows filesystem
+ * bridge, where metadata-heavy work (builds, installs, git) is dramatically
+ * slower than on the Linux filesystem — measured on the author's machine at ~8x
+ * for a 128 MB sequential write and far worse for many small files. Saying so
+ * here is cheap; discovering it as a mystery slowdown is not.
+ *
+ * @param hostCwd - the plugin's own working directory (a Windows path here).
+ * @returns a summary line, or null when the directory cannot be expressed.
+ */
+export function workspaceLine(hostCwd) {
+  const path = windowsPathToWsl(String(hostCwd ?? ''))
+  if (!path.startsWith('/')) return null
+  const mount = WINDOWS_MOUNT_RE.exec(path)
+  const where = mount === null
+    ? 'Linux filesystem'
+    : `Windows drive mount /mnt/${mount[1]} — builds, installs and git are much slower here; prefer a path under /home when it matters`
+  return `workspace: ${path} (${where})`
+}
+
+/**
+ * One shell round trip collecting every fact that does not need its own
+ * `wsl.exe` launch. Each line is `key=value`; a fact that cannot be read prints
+ * an explicit marker (`absent`, `none`, empty) rather than disappearing.
+ *
+ * `cmd.exe` is reached through interop to read the WINDOWS-side `.wslconfig`
+ * (networking mode, memory and processor limits live there, not in the distro).
+ * It runs from `/mnt/c` so cmd.exe does not inherit a `\\wsl.localhost\...`
+ * working directory and complain about a UNC path.
+ */
+export const CAPABILITY_PROBE = [
+  String.raw`echo "os=$(. /etc/os-release 2>/dev/null && printf '%s' "$PRETTY_NAME")"`,
+  String.raw`echo "wsl=$(uname -r | grep -q WSL2 && echo 2 || echo 1)"`,
+  String.raw`echo "init=$(ps -p 1 -o comm= 2>/dev/null | tr -d ' ')"`,
+  String.raw`echo "cgroup=$(stat -fc %T /sys/fs/cgroup 2>/dev/null)"`,
+  String.raw`[ -e /dev/dxg ] && echo "gpu=dxg" || echo "gpu=none"`,
+  String.raw`if command -v nvidia-smi >/dev/null 2>&1; then echo "nvidia=$(nvidia-smi -L 2>/dev/null | head -1)"; else echo "nvidia=absent"; fi`,
+  String.raw`if command -v docker >/dev/null 2>&1; then echo "docker=$(timeout 3 docker info --format '{{.ServerVersion}}' 2>/dev/null || echo cli-only)"; else echo "docker=absent"; fi`,
+  String.raw`echo "drives=$(ls /mnt 2>/dev/null | grep -E '^[a-z]$' | tr '\n' ',')"`,
+  String.raw`echo "wslconf=$(grep -vE '^[[:space:]]*(#|$)' /etc/wsl.conf 2>/dev/null | tr '\n' ';')"`,
+  String.raw`echo "winconf=$(cd /mnt/c 2>/dev/null && cmd.exe /c 'type "%USERPROFILE%\.wslconfig"' 2>/dev/null | tr -d '\r' | grep -vE '^[[:space:]]*(#|$)' | tr '\n' ';')"`,
+].join('\n')
+
+/**
+ * Parse `key=value` probe output into a fact map.
+ * Lines without `=`, and keys repeated later, are ignored/overwritten; values
+ * keep their internal spaces and lose only the trailing newline.
+ */
+export function parseFacts(text) {
+  const facts = {}
+  for (const line of String(text ?? '').split(/\r?\n/)) {
+    const separator = line.indexOf('=')
+    if (separator <= 0) continue
+    const key = line.slice(0, separator).trim()
+    if (key === '' || /\s/.test(key)) continue
+    facts[key] = line.slice(separator + 1).trim()
+  }
+  return facts
+}
+
+function cgroupLabel(value) {
+  if (value === 'cgroup2fs') return 'cgroup v2'
+  if (value === 'tmpfs') return 'cgroup v1'
+  return value === undefined || value === '' ? null : `cgroup ${value}`
+}
+
+/**
+ * Compose the compact capability lines from a parsed probe.
+ * @returns lines for the facts that were readable; unreadable ones are omitted
+ *   rather than guessed at, so an absent line means "could not tell".
+ */
+export function capabilityLines(facts) {
+  const lines = []
+
+  // Identity and kernel-level facts.
+  const identity = []
+  if (facts.os) identity.push(facts.os)
+  if (facts.wsl === '2') identity.push('WSL2')
+  else if (facts.wsl === '1') identity.push('WSL1 (no systemd, no docker, slow /mnt)')
+  const cgroup = cgroupLabel(facts.cgroup)
+  if (cgroup !== null) identity.push(cgroup)
+  if (identity.length > 0) lines.push(identity.join(' · '))
+
+  // Init system and containers.
+  const runtime = []
+  if (facts.init) {
+    runtime.push(facts.init === 'systemd' ? 'systemd: yes' : `systemd: no (PID 1 is ${facts.init})`)
+  }
+  if (facts.docker === 'absent') runtime.push('docker: not installed')
+  else if (facts.docker === 'cli-only') runtime.push('docker: cli only, daemon unreachable')
+  else if (facts.docker) runtime.push(`docker: daemon ${facts.docker}`)
+  if (runtime.length > 0) lines.push(runtime.join(' · '))
+
+  // GPU passthrough. The adapter UUID adds length without answering
+  // "can this machine do GPU work", so it is dropped.
+  const gpu = []
+  if (facts.gpu === 'dxg') gpu.push('/dev/dxg present (GPU passthrough enabled)')
+  else if (facts.gpu === 'none') gpu.push('no /dev/dxg (no GPU passthrough)')
+  if (facts.nvidia && facts.nvidia !== 'absent') {
+    gpu.push(`nvidia-smi: ${facts.nvidia.replace(/\s*\(UUID:[^)]*\)/, '')}`)
+  } else if (facts.nvidia === 'absent') gpu.push('nvidia-smi: not installed')
+  if (gpu.length > 0) lines.push(`GPU: ${gpu.join(' · ')}`)
+
+  // Mounted Windows drives.
+  const drives = (facts.drives ?? '').split(',').filter((drive) => drive !== '')
+  if (drives.length > 0) lines.push(`drives: ${drives.map((drive) => `/mnt/${drive}`).join(' ')}`)
+
+  // Configuration, from both sides of the boundary.
+  const config = []
+  if (facts.wslconf) config.push(`/etc/wsl.conf: ${facts.wslconf}`)
+  if (facts.winconf) config.push(`.wslconfig: ${facts.winconf}`)
+  else if (facts.winconf === '') config.push('.wslconfig: not set')
+  if (config.length > 0) lines.push(config.join(' · '))
+
+  return lines
+}
+
+/**
+ * Summarize `wsl --version`, whose labels are LOCALIZED, so nothing is parsed
+ * by name: the first three lines are WSL/kernel/WSLg in a fixed order, and the
+ * Windows build line is the one naming Windows. The Direct3D/MSRDC/DXCore
+ * versions are dropped as noise.
+ * @returns one line, or null when the output was not the expected table.
+ */
+export function launcherSummary(text) {
+  const lines = String(text ?? '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.includes(':') && line.length > 0)
+  if (lines.length === 0) return null
+  const keep = lines.slice(0, 3)
+  const windows = lines.find((line) => /windows/i.test(line))
+  if (windows !== undefined && !keep.includes(windows)) keep.push(windows)
+  return keep.join(' · ')
+}

package/lib/guard.js

@@ -0,0 +1,107 @@
+// Destructive-command guard.
+//
+// The guard is a safety net for a model that is about to do something
+// irreversible — not a security boundary (the caller may always pass
+// `allowDangerous: true`). It is therefore tuned to be deterministic and to
+// err toward refusing, while still letting a read-only INVESTIGATION of the
+// same tools run: `man fdisk` and `grep reboot /var/log/syslog` must work.
+
+// `rm` is the one command whose flag spelling is genuinely open-ended:
+// `rm -rf`, `rm -fr`, `rm -r -f`, `rm -R --force`, `rm --recursive --force`.
+// A regex over the whole command missed the separated and long forms, so scan
+// each `rm` invocation and collect its flags individually. The prefix and the
+// trailing lookahead tolerate everything that can wrap a command word: quotes,
+// backticks, `$(`/`)` command substitution, and a `\rm` escape.
+const RM_INVOCATION = /(?:^|[\s;&|"'`(\\])(?:\S*\/)?rm(?=[\s"'`)}]|$)/g
+const QUOTE_STRIP_RE = /^["'`]+|["'`]+$/g
+
+// `$IFS` (and `${IFS}`) expands to whitespace, so `rm$IFS-rf` is the same
+// command as `rm -rf`. Normalize it for MATCHING only; the command that runs is
+// untouched, so the worst case is refusing an exotic but harmless literal.
+const IFS_ESCAPE_RE = /\$\{?IFS\}?/g
+
+// A RECURSIVE delete is refused whether or not `-f` is present: with stdin on
+// /dev/null nothing prompts, so `rm -r tree` deletes a whole tree silently —
+// exactly what this guard exists to prevent. Requiring `-f` as well let
+// `rm a -f; rm b -r` through, and `-f` only suppresses prompts anyway.
+export function rmIsDestructive(segment) {
+  RM_INVOCATION.lastIndex = 0
+  let match
+  while ((match = RM_INVOCATION.exec(segment)) !== null) {
+    for (const rawToken of segment.slice(match.index + match[0].length).split(/\s+/)) {
+      const token = rawToken.replace(QUOTE_STRIP_RE, '')
+      if (token === '--') break
+      if (token === '--recursive') return true
+      else if (/^-[A-Za-z]+$/.test(token) && (token.includes('r') || token.includes('R'))) return true
+    }
+  }
+  return false
+}
+
+// A command line is a sequence of segments separated by `;`, `&`, `|` or a
+// newline. Scanning the WHOLE line for dangerous keywords refused `man fdisk`
+// and `grep reboot /var/log/syslog`, so each segment is evaluated separately
+// and the device/power tools are matched at COMMAND POSITION — the first word,
+// past the wrappers and `VAR=value` assignments that can precede it.
+const SEGMENT_SPLIT_RE = /[;&|\n]+/
+const COMMAND_WRAPPERS = new Set([
+  'sudo', 'doas', 'command', 'exec', 'nohup', 'nice', 'ionice', 'time', 'stdbuf', 'setsid', 'env',
+])
+const ENV_ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/
+
+/** The command word a segment invokes, with wrappers skipped and the path removed. */
+export function commandWord(segment) {
+  const tokens = segment.trim().split(/\s+/).filter((token) => token.length > 0)
+  let index = 0
+  while (index < tokens.length) {
+    const bare = tokens[index].replace(QUOTE_STRIP_RE, '')
+    if (COMMAND_WRAPPERS.has(bare) || ENV_ASSIGNMENT_RE.test(bare) || bare.startsWith('-')) {
+      index += 1
+      continue
+    }
+    break
+  }
+  const word = tokens[index]
+  if (word === undefined) return null
+  const bare = word.replace(QUOTE_STRIP_RE, '')
+  return bare.slice(bare.lastIndexOf('/') + 1)
+}
+
+const POWER_TOOLS = new Set(['shutdown', 'poweroff', 'reboot', 'halt'])
+const DISK_TOOLS = new Set(['mkswap', 'wipefs', 'fdisk', 'sfdisk', 'gdisk', 'sgdisk', 'parted', 'blkdiscard', 'shred'])
+
+// Patterns that are dangerous wherever they appear, because they WRITE to a
+// block device or fork-bomb the machine regardless of the command word.
+const DESTRUCTIVE_PATTERNS = [
+  [/[^>]\s*>>?\s*\/dev\/(sd|hd|nvme|mmcblk|vd|xvd|disk)/, 'redirect onto a block device'],
+  [/:\s*\(\s*\)\s*\{[^\n]*\|[^\n]*&[^\n]*\}\s*;\s*:/, 'fork bomb'],
+]
+
+function segmentReason(segment) {
+  if (rmIsDestructive(segment)) return 'recursive delete (`rm -r`)'
+
+  const word = commandWord(segment)
+  if (word === null) return null
+  if (POWER_TOOLS.has(word)) return `power control (\`${word}\`)`
+  if (/^mkfs(\.\w+)?$/.test(word)) return 'mkfs (format a filesystem)'
+  if (DISK_TOOLS.has(word)) return `disk tool (\`${word}\`)`
+  if (word === 'dd' && /\bof=\s*\/dev\//.test(segment)) return 'dd onto a block device'
+  if (word === 'systemctl' && /\b(poweroff|reboot|halt)\b/.test(segment)) return 'power control (systemctl)'
+  return null
+}
+
+/**
+ * @param command - the final (post-translation) command string.
+ * @returns a human-readable reason when the command is destructive, else null.
+ */
+export function destructiveReason(command) {
+  const scanned = command.replace(IFS_ESCAPE_RE, ' ')
+  for (const [pattern, reason] of DESTRUCTIVE_PATTERNS) {
+    if (pattern.test(scanned)) return reason
+  }
+  for (const segment of scanned.split(SEGMENT_SPLIT_RE)) {
+    const reason = segmentReason(segment)
+    if (reason !== null) return reason
+  }
+  return null
+}

package/lib/paths.js

@@ -0,0 +1,85 @@
+// Shell quoting and Windows -> WSL path translation.
+//
+// Both concerns are "turn caller text into something bash and wsl.exe read the
+// same way", and every rule here exists because the naive version was wrong:
+// see the comments on each pattern.
+
+// Shell-quote a value for a single-quoted `export KEY='value'` fragment.
+export function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+// `~` must stay OUTSIDE the quotes or bash never expands it, so a `~`-rooted
+// path is split: the tilde stays bare and only the remainder is quoted.
+// `~/my dir` -> `~/'my dir'`; anything else is quoted whole. A path that is
+// literally named `~foo` therefore cannot be expressed — acceptable, and the
+// safe direction: an unexpanded tilde fails loudly instead of silently.
+const TILDE_PATH_RE = /^(~[A-Za-z0-9._-]*)((?:\/.*)?)$/
+
+export function quotePath(path) {
+  const match = TILDE_PATH_RE.exec(path)
+  if (match === null) return shellQuote(path)
+  const [, tilde, rest] = match
+  return rest.length <= 1 ? tilde : `${tilde}/${shellQuote(rest.slice(1))}`
+}
+
+export function buildCdCommand(workdir) {
+  return `cd ${quotePath(workdir)}`
+}
+
+// Characters that may appear inside a Windows path segment but cannot be part
+// of one: whitespace ends the segment, and a shell operator ends the token.
+// Parentheses are deliberately ALLOWED — `C:\Program Files (x86)\Steam` is an
+// ordinary Windows path, and a trailing `$(...)` is harmless because a
+// continuation chunk only ever changes if it contains a backslash.
+const PATH_CHAR = `[^\\s"'` + '`' + `|&;<>]`
+
+// One Windows drive-absolute path: `C:\foo`, `C:/foo`, and — the case the
+// first version got wrong — a path whose LATER segments contain spaces, e.g.
+// `C:\Program Files\Git` or `C:\Program Files (x86)\Steam`.
+//
+// A space continues the match only when the next chunk does NOT itself start a
+// new drive path, so `cp C:\a.txt D:\b.txt` translates BOTH paths instead of
+// letting ` D:\b.txt` be absorbed into the first. An unconsumed chunk is left
+// verbatim, so `C:\Program Files` (no backslash after the space) still becomes
+// `/mnt/c/Program Files`, and `echo C:\x && ls` still stops at the `&&`.
+//
+// The lookbehind replaces the first version's `\b`: a drive letter preceded by
+// `/`, `\` or `:` is not a drive path but path-like TEXT inside another
+// expression — `sed "s/C:\x/y/"` and `http://x/C:/y` must be left alone.
+const DRIVE_PATH_RE = new RegExp(
+  `(?<![\\w/\\\\:])([A-Za-z]):([\\\\/])(${PATH_CHAR}*(?:[ \\t]+(?![A-Za-z]:[\\\\/])${PATH_CHAR}*)*)`,
+  'g',
+)
+
+// Windows reaches a WSL filesystem as a UNC path: `\\wsl.localhost\<distro>\home\x`
+// or the legacy `\\wsl$\<distro>\home\x`. Inside a Linux command both mean the
+// Linux path, so translate them too.
+const WSL_UNC_RE = new RegExp(
+  `\\\\\\\\wsl(?:\\.localhost|\\$)(?:\\\\+([^\\\\/\\s"'` + '`' + `|&;<>()]+))?((?:[\\\\/]${PATH_CHAR}*)*)`,
+  'g',
+)
+
+/**
+ * Translate literal Windows paths into their WSL/Linux form.
+ *   C:\Users\me\a.txt            -> /mnt/c/Users/me/a.txt
+ *   C:\Program Files\Git\cmd     -> /mnt/c/Program Files/Git/cmd
+ *   \\wsl.localhost\Ubuntu\home  -> /home
+ * A single lowercase letter followed by `/` is NOT rewritten: `a:/b` is
+ * ordinary text far more often than it is a drive path, and the backslash form
+ * (`a:\b`, or an uppercase `C:/...`) still is.
+ */
+export function windowsPathToWsl(text) {
+  if (typeof text !== 'string' || text.length === 0) return text
+
+  const withDrives = text.replace(DRIVE_PATH_RE, (match, letter, separator, rest) => {
+    if (separator === '/' && letter !== letter.toUpperCase()) return match
+    const tail = rest.replace(/\\/g, '/')
+    return `/mnt/${letter.toLowerCase()}/${tail}`.replace(/\/{2,}/g, '/')
+  })
+
+  return withDrives.replace(WSL_UNC_RE, (_match, _distro, tail) => {
+    const path = String(tail ?? '').replace(/\\/g, '/').replace(/\/{2,}/g, '/')
+    return path.startsWith('/') ? path : `/${path}`
+  })
+}

package/lib/result.js

@@ -0,0 +1,104 @@
+// Turning one settled subprocess into the value the model sees, plus the
+// launcher noise filters and the truncation arithmetic.
+
+// wsl.exe emits this locale-dependent launcher warning to stderr whenever
+// Windows has a localhost proxy configured and WSL runs in NAT mode. It
+// repeats on every call, so drop it; the tokens "localhost" and "proxy"
+// ("代理") stay stable across locales.
+const LOCALHOST_PROXY_WARNING = /^\s*wsl:\s.*(localhost|127\.0\.0\.1).*(proxy|代理)/i
+
+// procps (`ps`, `top`, `free`, `w`) probes the console for a window size; a
+// redirected wsl.exe stream has no real terminal, so it reports a bogus
+// 131072x1 and warns on stderr. Pure noise for every call, so drop it.
+const BOGUS_SCREEN_SIZE_WARNING = /^\s*your \d+x\d+ screen size is bogus\.?\s*expect trouble\.?\s*$/i
+
+/** Strip wsl.exe launcher / procps noise lines from stderr. */
+export function cleanStderr(text) {
+  return text
+    .split(/\r?\n/)
+    .filter((line) => !LOCALHOST_PROXY_WARNING.test(line) && !BOGUS_SCREEN_SIZE_WARNING.test(line))
+    .join('\n')
+}
+
+// Windows exit codes are unsigned 32-bit; wsl.exe reports its own failures as
+// -1, which reaches us as 4294967295. Show the signed value a human expects.
+export function normalizeExitCode(exitCode) {
+  if (exitCode === 0xFFFFFFFF) return -1
+  return exitCode
+}
+
+export function byteLength(text) {
+  return Buffer.byteLength(text, 'utf8')
+}
+
+/**
+ * One collected stream -> text plus the truncation facts needed to recover
+ * whatever the in-memory tail window dropped.
+ *
+ * `droppedBytes` is derived from the decoded text and can be off by a byte or
+ * two when the byte-trimmed window starts inside a multi-byte character, so the
+ * model-facing marker quotes the window SIZE instead of this number.
+ */
+export function streamFacts(read) {
+  if (read === undefined || read === null) {
+    return { text: '', totalBytes: 0, droppedBytes: 0, lossy: false, spillPath: null }
+  }
+  const text = read.text ?? ''
+  const totalBytes = typeof read.nextOffset === 'number' ? read.nextOffset : byteLength(text)
+  return {
+    text,
+    totalBytes,
+    droppedBytes: read.lossy ? Math.max(0, totalBytes - byteLength(text)) : 0,
+    lossy: read.lossy === true,
+    spillPath: read.spillPath ?? null,
+  }
+}
+
+export function truncationMarkers(value, maxOutputBytes) {
+  const markers = []
+  for (const stream of ['stdout', 'stderr']) {
+    const dropped = value[`${stream}DroppedBytes`] ?? 0
+    if (dropped <= 0) continue
+    const total = value[`${stream}TotalBytes`] ?? 0
+    const spill = value[`${stream}SpillPath`]
+    const recovery = spill === null || spill === undefined
+      ? 'earlier bytes were dropped'
+      : `full stream: ${spill}`
+    markers.push(`[${stream} truncated: at most the last ${maxOutputBytes} of ${total} bytes were kept; ${recovery}]`)
+  }
+  return markers.length > 0 ? markers : ['[output truncated]']
+}
+
+/**
+ * Format one result value as the model-facing text: body first, then one marker
+ * per line. An aborted call reports the timeout rather than the exit code the
+ * kill produced, since that code is an artifact and not the command's answer.
+ */
+export function formatResult(value, maxOutputBytes) {
+  // A background start has no output yet: the whole answer is the job handle,
+  // which the model then drives with the generic job tools.
+  if (value.jobId !== null && value.jobId !== undefined) {
+    return `[started in the background as job ${value.jobId}; read it with job_output, stop it with job_kill]`
+  }
+
+  let body = value.stdout || ''
+  if (value.stderr && value.stderr.length > 0) {
+    if (body.length > 0 && !body.endsWith('\n')) body += '\n'
+    body += `[stderr]\n${value.stderr}`
+  }
+  if (body.length === 0) body = '(no output)'
+
+  const markers = []
+  if (value.truncated) markers.push(...truncationMarkers(value, maxOutputBytes))
+  if (value.timedOut) {
+    const after = typeof value.timeoutMs === 'number' ? `${value.timeoutMs}ms` : 'the configured timeout'
+    markers.push(`[timed out after ${after}; the command was killed]`)
+  } else if (value.signal !== null && value.signal !== undefined) {
+    markers.push(`[killed by signal: ${value.signal}]`)
+  } else if (value.exitCode !== 0 && value.exitCode !== null) {
+    markers.push(`[exit code: ${value.exitCode}]`)
+  }
+  if (markers.length === 0) return body
+  if (!body.endsWith('\n')) body += '\n'
+  return body + markers.join('\n')
+}