dsh-node-repl

Readme

# dsh-node-repl

[![npm version](https://img.shields.io/npm/v/dsh-node-repl?logo=npm)](https://www.npmjs.com/package/dsh-node-repl)

Per-session **Node REPL terminal** for the DSH web UI. Open a real Node.js REPL
inside any conversation — with the live agent context (`ctx`, `agent`) in scope.

## Features

- A **REPL** button in every session header opens a floating terminal window,
  local to that session (no global overlay, no conversation space taken).
- A real `node:repl` prompt — Tab completion, up/down history, top-level `await`,
  ANSI colors, `.help` / `.editor`.
- The live agent context is in scope: `ctx` (= `agent.ctx`) and `agent`, so
  `ctx.plugin`, `ctx.effect`, `ctx.get`, `ctx.on`, `ctx.provide` all work — plus
  the usual Node globals (`require`, `process`, `console`, `fetch`, …).
- Draggable and resizable window; collapse keeps the REPL alive, close kills it.

## Install

```sh
dsh plugin --profile web add dsh-node-repl
```

Restart `dsh web`, and the **REPL** button appears in each session header.

## Usage

Open a session, click **REPL**, and type JavaScript. Top-level `await` works:

```js
> 1 + 1
2
> await Promise.resolve(42)
42
> ctx.get("webServer")   // any service the agent can reach
> agent.id               // the session id
```

### Window controls

| Control                      | Effect                         |
| ---------------------------- | ------------------------------ |
| Header `REPL` button         | open / restore / collapse      |
| Title bar `–`                | collapse (keep the REPL alive) |
| Title bar `✕`                | close (kill the REPL)          |
| Drag the title bar           | move the window                |
| Drag the bottom-right corner | resize                         |

The REPL belongs to its session: refreshing the page, dropping the WebSocket, or
disposing the agent kills it (reopen to start fresh).

## Notes

The REPL runs **inside the DSH host process** (not in a child), which is how it
reaches the live `agent.ctx`. That also makes it a fully-trusted local tool: code
runs unsandboxed and can hang the process — treat it like a shell on that process.

## Development

Requires [pnpm](https://pnpm.io/) and Node ≥ 22. Build outputs (`lib/`) are
generated, not committed.

```sh
pnpm install   # installs deps and builds (prepare)
pnpm build     # rebuild host (tsc) + client bundle (esbuild)
pnpm test      # PTY/REPL bridge smoke test
pnpm lint      # eslint
pnpm format    # prettier --write
```