agent-repl 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to `agent-repl` are documented here.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-09-25
+
+First public release.
+
+### Added
+- `agent-repl mcp`: an MCP server with pi-repl's `repl_start`, `repl_status` and `repl_send` tools, for Claude Code, Codex, OpenCode and other agents. pi-repl's guidance for agents is kept within Claude Code's 2,048-character limit on tool descriptions by attaching runtime notes to the `target` parameter.
+- `agent-repl <runtime>`, `status`, `attach`, `env`, `export` and `stop`: pi-repl's `/repl` commands in a terminal. Starting a runtime attaches to it when run in a terminal.
+- Clean-record entries name the agent that sent them, from the MCP client's name, or `PI_REPL_AGENT_LABEL` when set.
+- Generated from pi-repl 0.8.1, with pi-repl's own test suite run against the generated copy.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oliver Maclaren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# agent-repl
+
+Shared REPL sessions for coding agents. agent-repl starts a Python, IPython, Julia, R, Haskell (GHCi), Clojure, Ruby, Java, Octave, MATLAB, gnuplot or C++ REPL in tmux. You attach to it from a terminal and work there as normal. [Claude Code](https://docs.claude.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai) and other agents that support MCP run code in the same session, so you and the agent share one live workspace.
+
+agent-repl is [pi-repl](https://github.com/omaclaren/pi-repl) running outside [Pi](https://pi.dev). The tools, runtime support and session handling are pi-repl's own code. agent-repl adds an MCP server and a command-line interface in place of Pi's extension API.
+
+Here Claude Code defined `f` and printed two values, and Codex, started separately, then called the same `f`. This is the Python session's tmux pane, with the paths of the private files that carry each submission shortened:
+
+```text
+>>> exec(open("/tmp/pi-rc-…/c9749e010f41-….py").read(),globals())
+
+── pi-repl · input · 5 lines · id: c9749e010f41 ──
+def f(n):
+    return sum(i*i for i in range(1, n+1))
+print(f(10))
+print(f(100))
+── output ──
+385
+338350
+── done · id: c9749e010f41 ──
+
+>>> exec(open("/tmp/pi-rc-…/7dacd8658f42-….py").read(),globals())
+
+── pi-repl · input · 1 line · id: 7dacd8658f42 ──
+print(f(1000))
+── output ──
+333833500
+── done · id: 7dacd8658f42 ──
+
+>>>
+```
+
+## Features
+
+- **Shared sessions**: each runtime has one named tmux session (`pi-repl-python`, `pi-repl-julia`, ...), used by you, Pi and every connected agent. An agent sees variables you defined in the terminal, and you see what the agent ran.
+- **MCP tools**: `repl_start`, `repl_status` and `repl_send`, with pi-repl's descriptions and guidance for each runtime.
+- **Command line**: start, attach to, inspect, export and stop sessions from a terminal.
+- **Labelled submissions**: code sent by an agent appears in the pane with its output between labelled markers, as above. How much code is shown can be changed (see [Echo setting](#echo-setting)).
+- **Records**: pi-repl keeps a raw log of each session's pane and a clean record of submitted code and output, which can be exported as Markdown. Each entry in the record names the agent that sent it. A compatible [pi-studio](https://github.com/omaclaren/pi-studio) using the same session shares the clean record.
+
+## Requirements
+
+- Node.js 22 or later
+- [tmux](https://github.com/tmux/tmux)
+- The runtimes you want to use, available as commands in your login shell: `python` or `ipython`, `julia`, `R`, `ghci`, `clojure`, `irb`, `jshell`, `octave-cli`, `matlab`, `gnuplot` or `cling`
+
+agent-repl is an early release, developed and tested on macOS. pi-repl also supports Linux, and Windows through WSL.
+
+## Install
+
+```bash
+npm install -g agent-repl
+```
+
+## Setting up an agent
+
+Each agent starts `agent-repl mcp` itself when it needs the tools. Add it once:
+
+**Claude Code**
+
+```bash
+claude mcp add --scope user agent-repl -- agent-repl mcp
+```
+
+**Codex**
+
+```bash
+codex mcp add agent-repl -- agent-repl mcp
+```
+
+**OpenCode**: in `~/.config/opencode/opencode.json`, or `opencode.json` in a project:
+
+```json
+{
+  "mcp": {
+    "agent-repl": { "type": "local", "command": ["agent-repl", "mcp"], "enabled": true }
+  }
+}
+```
+
+**Other agents**: configure a stdio MCP server with the command `agent-repl` and the argument `mcp`.
+
+Then ask the agent, for example, to "start a shared Julia REPL and fit a line to these points", and run `agent-repl attach julia` in a terminal to follow along. Claude Code and Codex have both run code in a shared Python session this way; OpenCode connects to the server and lists its tools.
+
+New sessions start in the MCP server's working directory, which is wherever the agent launches it; `agent-repl mcp --cwd <dir>` sets it explicitly. An existing session keeps the directory it started in.
+
+## Command line
+
+| Command | Description |
+|---------|-------------|
+| `agent-repl <runtime>` | Start or reuse a shared REPL and attach to it in this terminal |
+| `agent-repl <runtime> -d` | Start or reuse a shared REPL without attaching |
+| `agent-repl status [runtime]` | Show running sessions |
+| `agent-repl attach [runtime]` | Attach to a session in this terminal |
+| `agent-repl env [python]` | Show the Python session's interpreter and environment |
+| `agent-repl export [runtime]` | Write the session's clean record to a Markdown file in the current directory |
+| `agent-repl stop [runtime]` | Stop a session, verifying that its processes exit |
+| `agent-repl mcp [--cwd <dir>]` | Run the MCP server on stdio |
+
+Runtimes are `python`, `ipython`, `julia`, `r`, `ghci`, `clojure` (or `clj`), `ruby`, `java`, `octave`, `matlab`, `gnuplot` and `cpp`. Python and IPython share one session. Without a runtime, `status` lists every session, and `attach`, `export` and `stop` act on the only running session.
+
+`attach` runs `tmux attach` in the current terminal, or switches the current client when you are already inside tmux. Without a terminal, for example when an agent runs the command, it prints the `tmux attach` command instead.
+
+These are pi-repl's `/repl` commands, and the output is pi-repl's. The [pi-repl README](https://github.com/omaclaren/pi-repl#readme) describes them in detail, including how `stop` checks that a runtime has exited and how each runtime handles submitted code.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `repl_start` | Start or reuse a session with an explicit runtime and wait for a normal prompt |
+| `repl_status` | Report which sessions are running, with their paths and recent output |
+| `repl_send` | Run code in a running session and return the submitted code and output |
+
+`repl_send` never starts a session, and stopping one is left to you. The tool descriptions are pi-repl's, with its guidance for agents appended. Claude Code limits an MCP tool description to 2,048 characters, so guidance about choosing a runtime, and the notes for particular runtimes, are attached to the `target` parameter instead. Arguments are checked against pi-repl's parameter schemas, as Pi checks them, before a tool runs.
+
+## Echo setting
+
+By default an agent's submissions are shown in the pane in summary form: short code in full, longer code truncated. Each MCP server has its own setting, taken from `PI_REPL_ECHO_MODE` (`off`, `summary` or `full`) when it starts:
+
+```bash
+claude mcp add --scope user -e PI_REPL_ECHO_MODE=off agent-repl -- agent-repl mcp
+```
+
+An agent can also pass `echoMode` for a single `repl_send`. Full mode keeps longer source code in the pane's history.
+
+## Agent names in the record
+
+Entries in the clean record, and in `agent-repl export`, are labelled with the name the agent gives when it connects: `Claude Code`, `Codex` or `OpenCode`, or the raw client name for other agents. To choose the label yourself, set `PI_REPL_AGENT_LABEL` in the server's environment, as for the echo setting. Submissions from Pi are labelled `Pi`.
+
+## Privacy and safety
+
+An agent's code runs in your REPL with your permissions. Whether the agent asks before calling a tool is decided by the agent's own permission settings. Anyone who can reach your tmux server can see and type into these sessions.
+
+pi-repl writes submitted code to private temporary files (mode `0600`, in a directory only you can read) and removes them after each run. The raw session log and the clean record are kept in similar private directories under your temporary directory. The log is not deleted automatically; the clean record keeps the most recent 300 submissions. `PI_REPL_CONTROL_ROOT` moves the temporary code files to another directory, which must be owned by you with mode `0700`.
+
+## Relationship to pi-repl
+
+`src/pi-repl.ts` is generated from pi-repl's `index.ts` and should not be edited by hand. The only change is where its two Pi imports come from: `src/pi-compat` holds copies of the Pi helpers it uses (output truncation, command execution and `StringEnum`, MIT licensed, © Mario Zechner) and type definitions for the parts of Pi's extension API it calls. `src/shared` is pi-repl's `shared/` directory, unchanged. `src/host.ts` provides that API, and `src/mcp.ts` and `src/cli.ts` expose the tools and the `/repl` command.
+
+With a pi-repl checkout beside this one, after running `npm install` there:
+
+```bash
+npm run sync        # regenerate src/pi-repl.ts, src/shared, src/pi-compat and test/upstream
+npm run test:all
+```
+
+pi-repl's own test suite is copied to `test/upstream` with only its import paths changed, and runs against the generated copy with `npm run test:upstream`. Tests for optional runtimes are skipped unless `PI_REPL_TEST_RUNTIMES` selects them, as in pi-repl.
+
+The echo setting behaves differently outside Pi: it belongs to each MCP server process, so `agent-repl echo` only explains how to set it.
+
+## Development
+
+```bash
+git clone https://github.com/omaclaren/agent-repl
+cd agent-repl
+npm install
+npm link               # use this checkout as the agent-repl command
+npm test               # builds, then runs the unit and end-to-end tests
+npm run test:upstream  # pi-repl's test suite against the generated copy
+npm run typecheck
+```
+
+The end-to-end tests start `agent-repl mcp` and the command line against a real Python REPL. They use a separate tmux server with its own socket, a temporary home directory and private temporary files, so they never touch your sessions. They are skipped when tmux or `python3` is not available.
+
+## License
+
+MIT. The files in `src/pi-compat` copied from Pi are MIT licensed, © 2025 Mario Zechner; see [`src/pi-compat/LICENSE`](src/pi-compat/LICENSE).

package/dist/cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// agent-repl: pi-repl's shared tmux REPLs for any coding agent.
+//
+//   agent-repl mcp            MCP server on stdio, for an agent's MCP configuration
+//   agent-repl <args>         pi-repl's /repl command in a terminal, e.g. `agent-repl python`
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { hostContext, loadPiRepl } from "./host.js";
+import { runMcpServer } from "./mcp.js";
+import { forAgentRepl } from "./text.js";
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const HELP = `agent-repl ${VERSION}: shared tmux REPLs for coding agents, from pi-repl
+
+Usage:
+  agent-repl mcp [--cwd <dir>]   Run the MCP server on stdio (add this to your agent)
+  agent-repl <runtime> [-d]      Start or reuse a shared REPL and attach to it (-d: start only)
+  agent-repl status [runtime]    Show running sessions
+  agent-repl attach [runtime]    Open a session in this terminal
+  agent-repl env [python]        Show the Python session's interpreter and environment
+  agent-repl export [runtime]    Write the session's record of submissions to a file
+  agent-repl stop [runtime]      Stop a session
+
+Runtimes: python, ipython, julia, r, ghci, clojure (clj), ruby, java, octave,
+matlab, gnuplot, cpp. Sessions are the tmux sessions pi-repl uses
+(pi-repl-python, pi-repl-julia, ...), shared by every agent and terminal.
+
+Environment:
+  PI_REPL_ECHO_MODE     off, summary (default) or full: how much submitted code
+                        the MCP server echoes into the REPL pane
+  PI_REPL_AGENT_LABEL   name recorded for submissions (default: the agent's own
+                        name, such as Claude Code or Codex)
+  PI_REPL_CONTROL_ROOT  directory for the private files used to submit code`;
+const SUBCOMMANDS = new Set(["status", "env", "stop", "attach", "export", "echo", "help"]);
+async function runReplCommand(args, cwd, print) {
+    const captured = [];
+    const notify = (message, level) => {
+        captured.push({ message, level });
+        if (!print)
+            return;
+        const text = forAgentRepl(message);
+        if (level === "info")
+            console.log(text);
+        else
+            console.error(text);
+        if (level === "error")
+            process.exitCode = 1;
+    };
+    await loadPiRepl().commands.get("repl").handler(args, hostContext(cwd, notify));
+    return captured;
+}
+/** The session named by pi-repl's attach instructions, when there is exactly one. */
+export function attachTarget(messages) {
+    const names = messages.flatMap(({ message }) => [...message.matchAll(/^tmux attach -t (\S+)$/gm)].map(match => match[1]));
+    return names.length === 1 ? names[0] : undefined;
+}
+function attachTerminal(sessionName) {
+    // Inside tmux, switch this client to the session instead of nesting tmux.
+    const args = process.env.TMUX ? ["switch-client", "-t", sessionName] : ["attach", "-t", sessionName];
+    return spawnSync("tmux", args, { stdio: "inherit" }).status ?? 1;
+}
+async function attach(runtime, cwd) {
+    const interactive = process.stdin.isTTY && process.stdout.isTTY;
+    const messages = await runReplCommand(`attach ${runtime}`.trim(), cwd, !interactive);
+    const target = attachTarget(messages);
+    if (interactive && target)
+        process.exitCode = attachTerminal(target);
+    else if (interactive)
+        for (const { message, level } of messages)
+            (level === "info" ? console.log : console.error)(forAgentRepl(message));
+}
+async function main(argv) {
+    let cwd = process.cwd();
+    const args = [];
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "--cwd")
+            cwd = resolve(argv[++index] ?? ".");
+        else if (arg.startsWith("--cwd="))
+            cwd = resolve(arg.slice("--cwd=".length));
+        else
+            args.push(arg);
+    }
+    const [first = "", ...rest] = args;
+    const command = first.toLowerCase();
+    if (!first || command === "help" || first === "--help" || first === "-h") {
+        console.log(HELP);
+        return;
+    }
+    if (first === "--version" || first === "-v") {
+        console.log(VERSION);
+        return;
+    }
+    if (command === "mcp") {
+        await runMcpServer({ cwd, version: VERSION });
+        return;
+    }
+    if (command === "echo") {
+        console.log("The echo setting belongs to each agent's agent-repl MCP server. Set PI_REPL_ECHO_MODE=off, summary or full in the server's environment, or ask the agent to pass echoMode to repl_send.");
+        return;
+    }
+    if (command === "attach") {
+        await attach(rest.join(" "), cwd);
+        return;
+    }
+    if (SUBCOMMANDS.has(command)) {
+        await runReplCommand(args.join(" "), cwd, true);
+        return;
+    }
+    // Anything else is a start request, which pi-repl parses and validates.
+    const detach = rest.some(arg => arg === "-d" || arg === "--detach");
+    const startArgs = args.filter(arg => arg !== "-d" && arg !== "--detach").join(" ");
+    const messages = await runReplCommand(startArgs, cwd, true);
+    if (process.exitCode || detach || messages.some(({ level }) => level !== "info"))
+        return;
+    if (process.stdin.isTTY && process.stdout.isTTY)
+        await attach(first, cwd);
+}
+main(process.argv.slice(2)).catch(error => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/host.js

@@ -0,0 +1,24 @@
+// Runs pi-repl outside Pi. pi-repl registers its tools and its /repl command
+// through a small part of Pi's extension API; this supplies that part, with
+// commands run by Pi's own execCommand (copied in pi-compat).
+import registerPiRepl from "./pi-repl.js";
+import { execCommand } from "./pi-compat/index.js";
+let host;
+/** pi-repl keeps its state in module variables, so it is registered once per process. */
+export function loadPiRepl() {
+    if (host)
+        return host;
+    const tools = new Map();
+    const commands = new Map();
+    const api = {
+        exec: (command, args, options) => execCommand(command, args, options?.cwd ?? process.cwd(), options),
+        registerTool: tool => { tools.set(tool.name, tool); },
+        registerCommand: (name, command) => { commands.set(name, command); },
+    };
+    registerPiRepl(api);
+    host = { tools, commands };
+    return host;
+}
+export function hostContext(cwd, notify) {
+    return { cwd, hasUI: true, ui: { notify: (message, level = "info") => notify(message, level) } };
+}

package/dist/mcp.js

@@ -0,0 +1,109 @@
+// MCP server exposing pi-repl's tools (repl_start, repl_status, repl_send).
+//
+// Pi shows a tool's description to the model and adds its prompt guidelines to
+// the system prompt. MCP has only the description, and some clients cap it
+// (Claude Code at 2,048 characters), so general guidelines are appended to the
+// description, and guidance on choosing a target and on particular runtimes
+// goes with the `target` parameter.
+// Tool results are pi-repl's text content; its `details` feed Pi's UI and are
+// not shown to the model in Pi either. pi-repl labels recorded submissions with
+// PI_REPL_AGENT_LABEL, which the server sets from the connecting client's name
+// unless it is already set.
+import { randomUUID } from "node:crypto";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { Compile } from "typebox/compile";
+import { Value } from "typebox/value";
+import { hostContext, loadPiRepl } from "./host.js";
+import { forAgentRepl } from "./text.js";
+export const INSTRUCTIONS = `agent-repl provides long-lived REPL sessions (Python/IPython, Julia, R, GHCi, Clojure, Ruby, Java, Octave, MATLAB, gnuplot and C++) running in tmux. The user can watch and type into the same session from a terminal, so treat it as shared state: inspect before changing it, and do not assume variables exist.
+
+Start or reuse a session with repl_start, choosing the runtime explicitly, then run code with repl_send. Use repl_status to check which sessions are running. Stopping or restarting a session is the user's decision; they can run \`agent-repl stop <runtime>\` in a terminal. To show the user the session, suggest \`agent-repl attach <runtime>\`.
+
+These are the same tmux sessions pi-repl uses (pi-repl-python, pi-repl-julia, ...), so other agents and Pi may be using them too. Messages from these tools can mention pi-repl's Pi commands /repl and /lab; outside Pi the same command is \`agent-repl\` in a terminal (\`/repl stop python\` is \`agent-repl stop python\`).`;
+const TARGET_GUIDANCE = /^(?:In (?:GHCi|Clojure|Ruby|Java)|For (?:Octave|MATLAB|C\+\+|gnuplot))(?!\w)|\btarget='/;
+// Claude Code and Codex send a display title; OpenCode sends only its name.
+const CLIENT_NAMES = { opencode: "OpenCode" };
+/** The name recorded for a client's submissions, e.g. "Claude Code" for claude-code. */
+export function agentLabel(client) {
+    if (!client)
+        return undefined;
+    return client.title?.trim() || CLIENT_NAMES[client.name] || client.name?.trim() || undefined;
+}
+export function describeTool(tool) {
+    const guidelines = (tool.promptGuidelines ?? []).map(forAgentRepl);
+    // A JSON copy drops TypeBox's symbol-keyed metadata and leaves plain JSON Schema.
+    const inputSchema = JSON.parse(JSON.stringify(tool.parameters));
+    for (const property of Object.values(inputSchema.properties ?? {})) {
+        if (property.description)
+            property.description = forAgentRepl(property.description);
+    }
+    const target = inputSchema.properties?.target;
+    const targetGuidance = target ? guidelines.filter(line => TARGET_GUIDANCE.test(line)) : [];
+    if (target && targetGuidance.length)
+        target.description = [target.description, "", ...targetGuidance.map(line => `- ${line}`)].join("\n");
+    const general = guidelines.filter(line => !targetGuidance.includes(line));
+    const description = [forAgentRepl(tool.description), ...(general.length ? ["", ...general.map(line => `- ${line}`)] : [])].join("\n");
+    return {
+        name: tool.name,
+        title: tool.label,
+        description,
+        inputSchema: inputSchema,
+        annotations: { title: tool.label, readOnlyHint: tool.name === "repl_status", destructiveHint: false, openWorldHint: false },
+    };
+}
+// As Pi does before calling a tool: optional nulls dropped, TypeBox conversion
+// (e.g. "5000" to 5000), then validation.
+function validateArguments(tool, input) {
+    const args = structuredClone(input ?? {});
+    const required = new Set(tool.parameters.required ?? []);
+    for (const key of Object.keys(args))
+        if (args[key] === null && !required.has(key))
+            delete args[key];
+    Value.Convert(tool.parameters, args);
+    const validator = Compile(tool.parameters);
+    if (validator.Check(args))
+        return args;
+    const errors = validator.Errors(args).map(error => {
+        const path = error.instancePath.replace(/^\//, "").replace(/\//g, ".");
+        const missing = error.keyword === "required" ? error.params.requiredProperties?.[0] : undefined;
+        return `  - ${missing ?? (path || "root")}: ${error.message}`;
+    });
+    throw new Error(`Invalid arguments for ${tool.name}:\n${errors.join("\n") || "  - unknown validation error"}`);
+}
+export function createMcpServer({ cwd, version, log = message => process.stderr.write(`${message}\n`) }) {
+    const { tools } = loadPiRepl();
+    const described = [...tools.values()].map(describeTool);
+    const server = new Server({ name: "agent-repl", title: "agent-repl", version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    const labelSetByUser = Boolean(process.env.PI_REPL_AGENT_LABEL?.trim());
+    server.oninitialized = () => {
+        const label = agentLabel(server.getClientVersion());
+        if (!labelSetByUser && label)
+            process.env.PI_REPL_AGENT_LABEL = label;
+    };
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: described }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const tool = tools.get(request.params.name);
+        if (!tool)
+            return { content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }], isError: true };
+        const notify = (message, level) => log(`[agent-repl ${level}] ${message}`);
+        try {
+            const params = validateArguments(tool, request.params.arguments);
+            const result = await tool.execute(`mcp-${randomUUID()}`, params, extra.signal, undefined, hostContext(cwd, notify));
+            return { content: result.content };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true };
+        }
+    });
+    return server;
+}
+export async function runMcpServer(options) {
+    const server = createMcpServer(options);
+    await server.connect(new StdioServerTransport());
+    const close = () => { void server.close().finally(() => process.exit(0)); };
+    process.stdin.on("end", close);
+    process.on("SIGINT", close);
+    process.on("SIGTERM", close);
+}

package/dist/pi-compat/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/pi-compat/child-process.js

@@ -0,0 +1,105 @@
+// Copied from @earendil-works/pi-coding-agent dist/utils/child-process (waitForChildProcess only) 0.85.1 (MIT License, (c) 2025 Mario Zechner; see LICENSE).
+// Regenerated by scripts/sync-from-pi-repl.mjs; do not edit by hand.
+const EXIT_STDIO_GRACE_MS = 100;
+export function spawnProcess(command, args, options) {
+    return process.platform === "win32" ? crossSpawn(command, args, options) : nodeSpawn(command, args, options);
+}
+export function spawnProcessSync(command, args, options) {
+    return process.platform === "win32"
+        ? crossSpawn.sync(command, args, options)
+        : nodeSpawnSync(command, args, options);
+}
+/**
+ * Wait for a child process to terminate without hanging on inherited stdio handles.
+ *
+ * A short-lived child can `exit` while a detached descendant keeps its stdout/stderr
+ * pipe open. We must not resolve and destroy the streams on a fixed deadline measured
+ * from `exit`, or output still being written past that deadline is silently lost
+ * (earendil-works/pi#5303). Instead, after `exit` we wait for the pipes to fall idle:
+ * the grace timer is re-armed on every chunk, so an actively writing descendant keeps
+ * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant
+ * that never lets `close` fire) still releases us after the grace elapses.
+ */
+export function waitForChildProcess(child) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let exited = false;
+        let exitCode = null;
+        let postExitTimer;
+        let stdoutEnded = child.stdout === null;
+        let stderrEnded = child.stderr === null;
+        const cleanup = () => {
+            if (postExitTimer) {
+                clearTimeout(postExitTimer);
+                postExitTimer = undefined;
+            }
+            child.removeListener("error", onError);
+            child.removeListener("exit", onExit);
+            child.removeListener("close", onClose);
+            child.stdout?.removeListener("end", onStdoutEnd);
+            child.stderr?.removeListener("end", onStderrEnd);
+            child.stdout?.removeListener("data", onData);
+            child.stderr?.removeListener("data", onData);
+        };
+        const finalize = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            resolve(code);
+        };
+        const maybeFinalizeAfterExit = () => {
+            if (!exited || settled)
+                return;
+            if (stdoutEnded && stderrEnded) {
+                finalize(exitCode);
+            }
+        };
+        const armIdleTimer = () => {
+            if (postExitTimer)
+                clearTimeout(postExitTimer);
+            postExitTimer = setTimeout(() => finalize(exitCode), EXIT_STDIO_GRACE_MS);
+        };
+        const onData = () => {
+            // Output is still arriving after exit; defer finalizing so we don't
+            // destroy the stream mid-write and truncate the tail.
+            if (exited && !settled)
+                armIdleTimer();
+        };
+        const onStdoutEnd = () => {
+            stdoutEnded = true;
+            maybeFinalizeAfterExit();
+        };
+        const onStderrEnd = () => {
+            stderrEnded = true;
+            maybeFinalizeAfterExit();
+        };
+        const onError = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(err);
+        };
+        const onExit = (code) => {
+            exited = true;
+            exitCode = code;
+            maybeFinalizeAfterExit();
+            if (!settled) {
+                armIdleTimer();
+            }
+        };
+        const onClose = (code) => {
+            finalize(code);
+        };
+        child.stdout?.once("end", onStdoutEnd);
+        child.stderr?.once("end", onStderrEnd);
+        child.stdout?.on("data", onData);
+        child.stderr?.on("data", onData);
+        child.once("error", onError);
+        child.once("exit", onExit);
+        child.once("close", onClose);
+    });
+}

package/dist/pi-compat/exec.js

@@ -0,0 +1,76 @@
+// Copied from @earendil-works/pi-coding-agent dist/core/exec 0.85.1 (MIT License, (c) 2025 Mario Zechner; see LICENSE).
+// Regenerated by scripts/sync-from-pi-repl.mjs; do not edit by hand.
+/**
+ * Shared command execution utilities for extensions and custom tools.
+ */
+import { spawn } from "node:child_process";
+import { waitForChildProcess } from "./child-process.js";
+/**
+ * Execute a shell command and return stdout/stderr/code.
+ * Supports timeout and abort signal.
+ */
+export async function execCommand(command, args, cwd, options) {
+    return new Promise((resolve) => {
+        const proc = spawn(command, args, {
+            cwd,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let killed = false;
+        let timeoutId;
+        const killProcess = () => {
+            if (!killed) {
+                killed = true;
+                proc.kill("SIGTERM");
+                // Force kill after 5 seconds if SIGTERM doesn't work
+                setTimeout(() => {
+                    if (!proc.killed) {
+                        proc.kill("SIGKILL");
+                    }
+                }, 5000);
+            }
+        };
+        // Handle abort signal
+        if (options?.signal) {
+            if (options.signal.aborted) {
+                killProcess();
+            }
+            else {
+                options.signal.addEventListener("abort", killProcess, { once: true });
+            }
+        }
+        // Handle timeout
+        if (options?.timeout && options.timeout > 0) {
+            timeoutId = setTimeout(() => {
+                killProcess();
+            }, options.timeout);
+        }
+        proc.stdout?.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        // Wait for process termination without hanging on inherited stdio handles
+        // held open by detached descendants.
+        waitForChildProcess(proc)
+            .then((code) => {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            if (options?.signal) {
+                options.signal.removeEventListener("abort", killProcess);
+            }
+            resolve({ stdout, stderr, code: code ?? 0, killed });
+        })
+            .catch((_err) => {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            if (options?.signal) {
+                options.signal.removeEventListener("abort", killProcess);
+            }
+            resolve({ stdout, stderr, code: 1, killed });
+        });
+    });
+}