3 +Opt-in Nushell tools for Pi.
5 +Loaded through the root pi-ext package; requires `nu` on `PATH`.
7 +`pi --nushell` enables both tools at session start and hides active `bash` and `powershell` from the model.
8 +`/nushell` toggles the same tools during a session.
9 +`/nushell on`, `/nushell off`, and `/nushell reset` are explicit alternatives.
10 +`/nushell reset` discards the persistent worker's state without changing active tools.
11 +Turning the tools off restores only the shell tools displaced by this toggle.
12 +Pi's `!` and `!!` remain owned by `nu-bang`.
14 +- `nu`: fresh `nu --no-config-file --no-history --error-style fancy --table-mode markdown -c` process per call, streaming output and optional timeout.
15 +- `nu_session`: persistent native Nu MCP worker, serialized calls, state scoped to the active Pi session, reset on session navigation, toggle-off, or shutdown.
17 +Use `nu` unless a later call requires variables, functions, imports, environment changes, or cwd set by an earlier `nu_session` call.
18 +Both tools use Nushell syntax, not Bash or PowerShell.
19 +Nu's native commands handle structured data; `^name` explicitly runs an external executable.
20 +Use `help <command>` for installed Nu guidance.
22 +MCP evaluates expressions and returns NUON with `output` and `history_index`.
23 +`print` writes to the worker's stderr, which also carries verbose Nu protocol diagnostics and is discarded; return an expression instead.
24 +MCP does not treat a nonzero external exit code as an evaluation error: use `^command | complete` and inspect `exit_code`.
25 +MCP collects output rather than streaming it, and replaces responses over its default 10 KB limit with a history reference.
26 +Each persistent request has a 110-second client deadline; interruption resets worker state, but detached external processes may continue running.
27 +Reset does not roll back filesystem changes.
29 +Set `nushell.enable` in Pi's `settings.json` to activate both tools at session start:
33 + "nushell": {
"enable":
true }
37 +Disabled by default; project settings override user settings, and `--nushell` enables the tools regardless of settings.
38 +`/nushell off` still disables them for the current session.
40 +Set `PI_NUSHELL_DEBUG` to an existing directory's log-file path for opt-in JSONL diagnostics.
41 +The log records startup, tool selection, process/worker lifecycle, request duration, exit codes, output byte counts, and safe error classifications; it never records command text, output content, or environment values.
42 +`fresh.start`/`fresh.finish` and `session.request.start`/`session.request.finish`/`session.request.error` carry matching opaque `callId` values, including overlapping fresh calls.
43 +Terminal events carry `durationMs`; `fresh.finish` also records `outcome` and `exitCode`; session errors may carry an MCP `code` or allowlisted Nu `nuCode`.
44 +The envelope `pid` identifies the Pi logger process; `childPid` and `workerPid` identify Nu processes.
45 +New log files use owner-only permissions; preexisting group/world-readable files and symlinks are refused on Unix.
46 +Logging failures warn without writing to Pi's terminal output stream.
48 +`mise run //extensions/nushell:e2e-json` runs five isolated module exercises plus a persistent-state probe via Pi print JSON mode with `--no-session`; it retains prompts, JSON events, debug logs, outputs, and analyses under `.pi/tmp/nushell-json/`.
49 +`mise run //extensions/nushell:bench` reports fresh, cold persistent, and warm persistent end-to-end tool latency in benchstat format.
50 +It uses the real Pi extension harness and Nu binary, warms each path, and alternates fresh and warm call order each round.
51 +MCP schemas load with the first persistent worker rather than at inert extension startup.
52 +On Linux (Node 26.9.0, Pi 0.87.1, Nu 0.115.1), `//:extension-startup-bench` measured RPC readiness falling from 478 ms ±7% to 449 ms ±7% (25 runs each; benchstat p=0.003).
53 +The Nu call benchmark showed no significant fresh, cold-worker, or warm-worker latency changes (20 runs each); this preserves the warm-call advantage without eagerly loading MCP at startup.