@codebam/dsh-tool-nu

A model-facing nu (Nushell) tool for the DeepSeek Harness.

Each call runs nu --no-config-file --no-history -c <source> in a fresh process and returns stdout/stderr with the same [exit code: N], [stderr], truncation, timeout, and sandbox markers as the stock bash tool. The plugin is a consumer of the existing ctx.shell seam, not a new shell provider: the stock bash tool, its executor, and its sandbox world stay mounted and untouched, and nu simply joins the tool catalog beside bash.

Why a trampoline

dsh composes exactly one provider of ctx.shell; a second registration fails loud. A nu executor package mirroring dsh-bash-sandbox would therefore replace bash, not accompany it. This plugin instead:

1. sends the Nu source as the ordinary NU_TOOL_SOURCE environment entry on an existing shell request, and
2. runs <executable> --no-config-file --no-history -c "$NU_TOOL_SOURCE".

Bash expands the quoted variable and does not re-scan the result, so quotes, backticks, $(…), and newlines in the source stay data. The request travels through the mounted executor, so sandbox policy, approval/escalation, timeouts, output caps, spill files, and ctx.jobs background handles are inherited from the world dsh already uses — including the @codebam/dsh-opensandbox profile world.

Install

Add a row to the profile patch (~/.dsh/profiles/<profile>/cordis.patch.yml):

- insert:
    - id: tool-nu
      name: '@codebam/dsh-tool-nu' # or an absolute path to index.mjs
      config:
        executable: nu # prefer an absolute path in deployment
        enableRunInBackground: true

Node resolves this plugin's @deepseek-ai/* peers from the profile's node_modules. dsh populates $DSH_HOME/profiles/node_modules for its own install closure; when loading by file path instead, provide that resolution next to index.mjs (the NixOS route below symlinks it). No bash-sandbox, tool-bash, or terminal row needs disabling.

Configuration

| Field | Default | Meaning | |---|---|---| | executable | nu | Nu executable. Deployments should pin an absolute path such as ${pkgs.nushell}/bin/nu so it resolves inside the execution world. | | enableRunInBackground | true | Expose run_in_background; when false, the field is removed and forced background calls are rejected. |

Tool arguments

The schema mirrors the bash tool call-for-call, so model habits and presenter cards transfer:

| Argument | Required | Meaning | |---|---|---| | command | yes | The Nu source to execute (Nushell pipeline syntax, not bash). | | description | yes | Active-voice UI label, 5–10 words. | | timeoutMs | no | Overrides the executor default; the executor caps it and kills on expiry. | | workdir | no | Per-call working directory; relative paths resolve against the session workspace. | | run_in_background | no | When enabled: return a nu-… job id immediately; collect with job_output, stop with job_kill. | | sandbox_permissions + justification | no | Advertised only when the mounted executor confines; identical one-shot, approval-backed escalation path as the bash tool. |

Model-facing behavior

• The system-prompt section says: check [exit code: N] on every nu result.
• The description teaches Nu's structured-data workflow: end data pipelines with | to nuon or | to json -r, and prefix externals with ^.
• Non-zero exits are results, not tool errors; only infrastructure failures (spawn errors, aborts) are errors. result.aborted throws AbortError.
• Background jobs are registered with kind nu; their outcome/detail and incremental output go through the generic ctx.jobs runtime and job_output.
• Managed harness facts are available to Nu as $env.DSH_*.

Deployment (NixOS profile)

This repository carries a staged module for the NixOS profile that pins this plugin and copies it into $DSH_HOME:

• packaging/nixos/dsh-tool-nu.nix — the fetchFromGitHub derivation (replace lib.fakeHash with the hash Nix reports on the first build).
• packaging/nixos/default.nix.snippet — the pkgs/default.nix callPackage line.
• packaging/nixos/agents.nix.snippet — the home/agents.nix copy block and profile-patch row, modeled on the existing dshOpenSandbox block.
• packaging/README.md — placement and build steps.

Development

npm run peers      # link node_modules/@deepseek-ai to the installed dsh closure
npm test           # node --test (mock-ctx + renderer suites)
npm run test:local # peers + test in one shot
npm run check      # syntax-check every ESM source
npm run pack:check # npm pack --dry-run

npm test uses the real @deepseek-ai/* packages from the installed dsh closure (not mocks of dsh), so it runs the same defineTool schema validation, approveEscalation logic, and shell renderer contract dsh will use at runtime.

Verified

Against dsh 0.1.6-alpha.1 and Nushell 0.115.1:

• loaded into a real acp composition through the profile patch and a probe tool; apply completed with tools, shell, systemPrompt, and shellEnv injected;
• 40 + 2 | to nuon returned 42 through the real bash-sandbox executor (exitCode: 0, sandbox workspace-write/full, no denial);
• background sleep 300ms; 7 | to nuon registered as nu-1, completed with exit code: 0, and read back 7;
• source containing shell command substitution and backticks executed as literal Nu data, and did not touch the files those substitutions named.

Known limitations

• Windows: the pwsh executor does not expand $NU_TOOL_SOURCE the way bash does. Disable the row on win32 (disabled: !!js process.platform === 'win32', as the snippets do) until a PowerShell-flavored invocation exists.
• Source travels in the environment: model commands are small, but multi-megabyte scripts can exceed the OS per-entry limit. A later iteration can stage the script through ctx.fs or nu … /dev/stdin.
• Structured output is a convention: the tool does not auto-append | to nuon, because a trailing comment or multi-statement script would break. The description instructs the model instead.
• Fresh process per call: cwd, variables, functions, and history never persist; pass workdir instead of cd.
• Executor-owned output semantics: truncation tail, spill paths, timeout caps, and background lifetime match the mounted executor (shared with bash).
• Replay exit pills parse from result text exactly like the bash tool, with the same known residual for output whose final line is itself a marker.

License

MIT. Portions are adapted from @deepseek-ai/dsh-tool-bash (Copyright (c) 2026 DeepSeek, MIT); see LICENSE.