deepseek-harness/packages/util/native-command/README.md

description, kind

description	kind
Host-native command and path-opening utilities with shell-free execution, cancellation, desktop detection, and WSL path handoff.	package-library

@deepseek-ai/dsh-native-command

English | 中文

Summary

dsh-native-command runs host executables without a shell and opens Host filesystem paths through the desktop. The command runner captures utf8 output, propagates cancellation, and hides transient Windows consoles. The path opener supports default-application and text-editor intents, browser-renderable documents, WSL translation, and desktop availability checks. It is a library, not a plugin: no ctx, no state, no events.

Table of Contents

• Use this package
• Understand the implementation
• Further Exploration
• Model Experience
• Known Limitations and Deferred Work
• Dev Note

---

Use this package

Use this runner when a host-side integration must execute one native command and needs its output, its failure, or both — and must never involve a shell.

Running a command

import { runNativeCommand } from '@deepseek-ai/dsh-native-command'

declare const script: string
declare const signal: AbortSignal
const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], signal)

On exit 0 the call resolves with captured stdout and stderr. On any failure it rejects with the exit code and both captured streams attached, so a caller can tell a missing tool (ENOENT), a cancellation (ABORT_ERR), and a real command failure apart without re-running the command.

Injecting the command boundary

The NativeCommandRunner type is the injectable command boundary for host integrations: pass the function (or a wrapper) where the integration needs a testable seam, so tests can substitute a fake runner.

Opening a Host path

openNativePath(path, signal) hands a path to the default application and prefers the named default browser for HTML and SVG where the platform can identify one. openNativeTextFile(path, signal) selects text-editor intent; on macOS it uses open -t. WSL paths are translated with wslpath -w before the Windows desktop receives them. canOpenNativePath() reports whether the current Host plausibly has a desktop target.

---

Understand the implementation

Implementation internals — click to expand

The command runner is a thin wrapper over Node's execFile. The path opener selects one shell-free command from platform and environment facts, while callers retain authority over which path may be opened.

Source map

File	Role
src/index.ts	Public command-runner and path-opener exports
src/runner.ts	Shell-free execFile adapter
src/path-opener.ts	Desktop detection, open intents, browser preference, and WSL translation
src/invariant.ts	Invariant companion (no runtime invariant; each run is one stateless child-process round trip)

What execFile gives the runner

execFile spawns the executable directly with an argv array — no shell string, no shell interpretation of the arguments. The signal option terminates the child when the caller's abort fires; windowsHide suppresses the transient console window on Windows. On a non-zero exit or spawn error, the callback attaches code, stdout, and stderr to the rejected error and keeps the original error as cause.

---

Further Exploration

Read these pages when you need the consumers or the general subprocess capability this utility deliberately is not.

• Native directory picker — the OS chooser commands this runner executes.
• Session Controller — resolves Session-relative workspace paths before opening them.
• Settings Controller — selects settings documents and agent-preset directories.
• Subprocess capability — the general subprocess seam, of which this package is not a part.

---

Model Experience

None, as the host-side utilities register nothing model-facing.

KV Cache effect

Nothing here enters a request prefix; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

These limits define when this runner is not the right tool. They are current package constraints, not a task backlog.

• No output bounding — both streams buffer unbounded in memory; every current caller invokes small native tools whose output is a path or an error line. Adopt dsh-output-retention bounding before pointing this at commands with meaningful output volume.

Dev Note

Working context for maintainers — click to expand

None.