---
id: SMH-SPEC-ZVMD_XYT
type: spec
title: "Embedded Nushell"
---

# Embedded Nushell

## Intent

Provide structured, cross-platform scripting without launching an interpreter for each tool call.
Keep tool definitions in plugins; expose Nushell as a reusable in-process SDK facility.
Native evaluation does not create a privileged tool path or require an installed shell.

## Scope

- Embedded Nushell evaluation on supported Linux, macOS, and Windows targets.
- Typed pipeline input and results, explicit execution context, bounded diagnostics.
- Controlled filesystem, network, clock, randomness, and external-process effects.
- Bundled Nushell documentation retrievable through `smith docs`.

General tool, durable-effect, secret, and documentation contracts remain in [SMH-SPEC-SPEC0001](../SMH-SPEC-SPEC0001-smith-specification/index.md).
Plugin registration, grants, and parity remain in [SMH-SPEC-PLUG0001](../SMH-SPEC-PLUG0001-plugin-system/index.md).
Nushell does not replace the wasm plugin sandbox.

## Evaluation

Bundled and user plugins invoke the same granted Nushell facility.
A bundled plugin contributes the default Nushell tool; core has no Nushell-specific tool registration or dispatch.
Evaluation executes inside Smith, not through a Nushell, Bash, or PowerShell subprocess.
The supported language and command surface is explicit and discoverable.
Unsupported syntax or commands fail with actionable diagnostics; no installed-shell fallback.

Requests carry explicit working directory, input, authorized environment, and invocation limits.
Pipeline results retain structured values or bytes without mandatory terminal-table rendering or lossy text conversion.
Syntax, type, command, cancellation, and limit failures produce explicit outcomes with useful source locations where available.
Only Smith contracts cross the SDK boundary; Nushell engine types are not public Smith contracts.
Evaluation never blocks input rendering or core event processing.

In-process evaluation reaches external programs only through supervised process effects.

```mermaid
flowchart TB
  plugin["Wasm tool plugin"] --> sdk["Granted Nu evaluation"]
  sdk --> nu["In-process Nushell"]
  nu -->|"explicit external command"| process["Supervised process effect"]
```

Pure pipelines and native SDK operations require no interpreter or helper-process launch.
External executables still require process creation; embedding does not claim otherwise.
Smith provides no built-in Bash or PowerShell evaluator.
Explicitly requested external programs may include project-owned shell scripts; they receive no special path or privileges.

## Effect safety

Every effect reachable from Nushell obeys the same grants, scopes, recording, secret handling, and supervision as the equivalent SDK operation.
Nushell cannot turn a read-only grant into write, network, or process authority.
Native commands cannot bypass the durable effect boundary.
Replay consumes recorded effect outcomes without automatically re-executing processes or mutations.
Failure after a possible mutation preserves the observed mutation evidence rather than reporting clean success.

Execution context is invocation-local; variables, definitions, cwd, and environment changes do not leak across invocations, plugins, or sessions.
User shell startup files, history, and ambient Nushell plugins are not loaded.
Nushell commands cannot change Smith's process-global cwd or environment, exit Smith, or install uncontrolled signal handlers.
Clock and randomness are controlled, recorded inputs rather than ambient native shortcuts.

## Bounds and cancellation

Execution, parsing, intermediate data, retained state, output, and diagnostics have named bounds and follow the invoking SDK budget.
Native engine allocations remain visible to Smith's lifetime accounting.
Nushell work cannot multiply the parent budget by starting jobs or parallel pipelines.
Cancellation and deadlines cover supported loops, streams, native commands, and external processes.
Cancelled or timed-out invocations settle with explicit outcomes and leave no unsupervised jobs.
Native evaluation does not inherit wasm fuel metering; its limits must hold independently.
A supported command cannot rely on forcibly killing a Rust thread to satisfy its deadline.
Oversized input and results fail explicitly without silently dropping mutation evidence.

## Documentation

Nushell documentation ships within the offline `smith docs` corpus.
It includes language guides, tutorials, and reference matching Smith's embedded Nu version and exposed command set.
Unsupported upstream functionality and Smith-specific execution constraints are identified explicitly.
Command reference derives from authoritative Nu command declarations; upstream material retains pinned provenance and required license notices.
Agents retrieve selected Nu documentation through the same bounded search, filtering, and retrieval interfaces as other Smith documentation.
Documentation retrieval requires neither an installed `nu` executable nor interpreter initialization.
Documented examples are checked against Smith's exposed evaluator, not only a standalone Nushell binary.

## Acceptance

- [ ] A plugin evaluates a structured pipeline in process with no interpreter subprocess and no installed shell.
- [ ] Bundled and user plugins receive identical SDK semantics and grant enforcement.
- [ ] File, network, and external-process effects cannot bypass recording or granted scopes.
- [ ] Native loops, streams, and commands settle on cancellation and limits; external descendants remain supervised.
- [ ] Successive invocations cannot observe leaked state or alter Smith's process-global execution context.
- [ ] Regular replay produces recorded outcomes without repeating external effects.
- [ ] Supported platforms use Nushell syntax without Bash or PowerShell fallback.
- [ ] Installed Smith serves matching Nu guides, tutorials, reference, and checked examples through bounded offline retrieval.