@nia-teams/four-tools 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nia Teams
+
+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

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# Four Tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [简体中文](./README_CN.md)
+
+The common way to extend an AI agent is to keep adding specialized tools and MCP servers: every new integration brings another set of schemas until tool definitions consume tens of thousands of tokens, crowding the context window, raising argument error rates, and still leaving the agent stuck as soon as a task falls outside its preset tool list.
+
+Large language models are already good at reading files, writing files, and running commands. Give an agent four operating-system tools—`read`, `write`, `edit`, and `shell` (under 1,000 tokens of schema in total)—and it can handle nearly any task: read documents, edit code, call APIs, run tests, or write and execute a script when no dedicated tool exists. These four tools are not just coding tools; they are the foundational toolset for a general-purpose agent operating on a computer.
+
+In production environments—local workstations, cloud sandboxes, headless containers, or chat-driven services—existing implementations of these four tools run into three limitations:
+- **Bundled inside interactive CLI products**: Community implementations (such as Pi's `coding-agent`) package the four tools inside a full terminal CLI application alongside TUI renderers and WASM image libraries rather than as a standalone, zero-dependency SDK.
+- **Coupled to specific external shell commands**: Implementations that shell out to `python3`, `setsid`, `stdbuf -oL`, `sed`, or `base64 -w0` fail on macOS (BSD userland) or minimal Alpine containers when those commands or flags are absent, and can lose `0755` executable permissions, overwrite symlinks during atomic writes, or allow parent shells on macOS to run subsequent commands during process-group teardown.
+- **No unattended background terminal management**: Interactive CLIs assume a human is watching `tmux`. Agents running in cloud services or chat channels executing 30+ second builds, test suites, or long-running tasks need timed-out commands to move into a background terminal without disconnecting, keep child log descriptors open, and wake the agent via an exit event when finished.
+
+`@nia-teams/four-tools` extracts these four tools into a standalone package with zero runtime dependencies and a two-layer structure:
+- **Core layer (`@nia-teams/four-tools`)**: Depends only on the `ExecutionEnv` interface with no `node:fs`, `node:path`, or `node:os` imports. Includes a TypeScript two-stage unique match edit engine (preserving UTF-8 BOM and existing CRLF/LF line endings), a `FileMutationQueue` serialized by environment ID and canonical path, and tool definitions compatible with `@nia-teams/agent-core` and Nia Teams.
+- **Native macOS / Linux syscall backend (`@nia-teams/four-tools/node`)**: Uses Node.js POSIX syscalls for line-paginated reads, atomic writes that preserve symlinks and target file modes, cross-kernel process-group signaling (`SIGSTOP` before `SIGKILL` on macOS), and background terminal lifecycle management (`exec` hands off after 30s by default, plus `terminal_create / list / read / signal / destroy`).
+
+```sh
+npm install @nia-teams/four-tools
+```
+
+AI coding assistants can load the bundled skill: `node_modules/@nia-teams/four-tools/skills/four-tools/SKILL.md` ([`skills/four-tools/SKILL.md`](./skills/four-tools/SKILL.md)).
+
+---
+
+## Quick Start
+
+Requires Node.js 20+ on macOS or Linux. Install the dependencies and run [`examples/quickstart.ts`](./examples/quickstart.ts):
+
+```sh
+npm install @nia-teams/agent-core @nia-teams/ai
+npm install -D tsx
+DEEPSEEK_API_KEY=sk-... npx tsx examples/quickstart.ts
+```
+
+```ts
+import { AgentRuntime, InMemoryConversationStore } from '@nia-teams/agent-core';
+import { OpenAIClient } from '@nia-teams/ai';
+import { createNodeTools } from '@nia-teams/four-tools/node';
+
+if (!process.env.DEEPSEEK_API_KEY) throw new Error('Set DEEPSEEK_API_KEY');
+const client = new OpenAIClient({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  baseURL: 'https://api.deepseek.com/v1',
+  model: 'deepseek-chat',
+});
+const tools = createNodeTools({ cwd: process.cwd(), terminals: false });
+const store = InMemoryConversationStore.fromUserMessage(
+  'Read package.json and summarize this project. Do not modify files.',
+);
+const runtime = new AgentRuntime({ store, sessionId: 'quickstart' });
+try {
+  await runtime.run({
+    client,
+    systemPrompt: 'You are a coding assistant. Inspect files before answering.',
+    tools,
+    onEvent(event) {
+      if (event.type === 'text_delta') process.stdout.write(event.delta);
+      if (event.type === 'tool_call_start') console.log(`\n[${event.name}]`, event.input);
+    },
+  });
+  console.log();
+} finally {
+  await tools.dispose();
+  await client.close();
+}
+```
+
+---
+
+## Tool Behavior
+
+- **`read`**: Paginates text by line (1-based `offset`), capped at 2,000 lines and 50 KiB by default. Configure caps via `read: { maxLines, maxBytes }` or pass `read: { truncate: false }` to let the runtime manage output budgets.
+- **`write`**: Creates missing parent directories and writes the file, returning `File written: <path> (<n> chars)` (`n` is UTF-16 code units). When targeting a resolvable symlink, preserves the symlink and existing target file mode.
+- **`edit`**: Matches one unique exact substring first, falling back to a line-mapped Unicode-normalized match (NFC, curly quotes, narrow no-break spaces). Preserves UTF-8 BOM and untouched CRLF/LF line endings, rejects files over 16 MiB by default, and returns `OK: replacement applied`.
+- **`shell`**: Runs a command and returns formatted text containing `$ <command>`, stdout, optional `[stderr]`, and `exit_code: <code>, duration: <ms>ms`.
+- **Write serialization**: `createFourTools` shares a `FileMutationQueue` between `write` and `edit` in the same group; pass a shared `mutationQueue` across groups to serialize writes by environment ID and `realpath`.
+- **Hooks**: `afterRead`, `afterMutate`, and `afterExec` (on exit code 0) can return `@nia-teams/ai/protocol` guidance; `resolveEnv` supplies per-command environment overrides.
+
+---
+
+## Managed Background Terminals
+
+`createNodeEnv()` enables background terminals by default:
+
+- **Timeout handoff**: Foreground `shell` waits 30 seconds by default (`timeout: 0` also uses 30 seconds). On timeout, the process continues running in the background and returns `Terminal ID: <id>`.
+- **Terminal actions**: Manage background processes with `terminal_create`, `terminal_list`, `terminal_read` (0-based `offset`), `terminal_signal` (`SIGINT` / `SIGTERM` / `SIGKILL` map to exit codes `130` / `143` / `137`), and `terminal_destroy`.
+- **Exit events and log retention**: Child processes inherit log file descriptors and can continue writing after the top-level shell exits. `onTerminalExit` fires once when the top-level shell exits (suppressed on `destroy`); `env.dispose()` kills managed process groups and removes logs. Full output from truncated foreground commands is written to `spillPath`.
+- **Foreground-only mode**: Passing `createNodeTools({ cwd, terminals: false })`, `createFourTools(env, { shell: { allowBackground: false, name: 'bash' } })`, or an `ExecutionEnv` without `env.terminals` exposes a foreground-only schema and kills the process group on timeout or abort.
+
+---
+
+## Local Examples
+
+### 1. Interactive CLI Agent (`examples/local-agent.ts`)
+
+Streams assistant text, reasoning, and tool calls in the terminal, and feeds background terminal exits into `host.injectMessage` to wake follow-up turns:
+
+```sh
+OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com/v1 \
+  MODEL=deepseek-chat npx tsx examples/local-agent.ts
+```
+
+Selects a client from `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY` in that order (`MODEL` overrides the default model). Press `Ctrl+C` once to cancel the active turn; press twice within 1.2s or type `/exit` to shut down and dispose terminals.
+
+### 2. Browser Workbench (`examples/web-agent.ts`)
+
+Starts a local HTTP server (`127.0.0.1:18880` by default; configurable via `HOST`, `PORT`, `WORKSPACE_DIR`, `WEB_AGENT_TOKEN`) with chat streaming, tool cards, workspace file previews, and live terminal status:
+
+```sh
+OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com/v1 \
+  MODEL=deepseek-chat npx tsx examples/web-agent.ts
+```
+
+Open the printed token URL in a browser. SSE reconnect replay is backed by `createSnapshotStream`. The token grants local command execution; place the server behind an authenticated TLS proxy before exposing it beyond loopback.
+
+---
+
+## Custom Execution Environments & Exports
+
+To run over SSH, containers, or remote sandboxes, implement `ExecutionEnv` and pass it to `createFourTools(env)`. Omit `env.terminals` when background process management is not supported.
+
+| Subpath | Exports |
+| --- | --- |
+| `@nia-teams/four-tools` | `createFourTools`, `createReadTool`, `createWriteTool`, `createEditTool`, `createShellTool`, `applyUniqueEdit`, `FileMutationQueue`, `ExecutionEnv`, and types |
+| `@nia-teams/four-tools/node` | `createNodeEnv`, `createNodeTools` (tool array with `.env` and `.dispose()`), `createNodeFourTools`, `PosixNodeExecutionEnv`, `PosixTerminalManager` |
+
+Tools run with the host process's permissions. `cwd` is the base directory for relative paths; path sandboxing, approvals, and secret redaction are enforced by the host `ExecutionEnv`.
+
+---
+
+## Build & Test
+
+```sh
+npm ci --registry=https://registry.npmjs.org
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+## License
+
+[MIT](./LICENSE)

package/README_CN.md

@@ -0,0 +1,144 @@
+# Four Tools
+
+[English](./README.md) | 简体中文
+
+过去给 AI Agent 扩展能力，主流做法是不断往上下文里添加专用工具和 MCP 服务：每接入一个系统就增加一批工具，工具定义往往占用上万 Token，不仅挤占上下文窗口、增加参数出错率，遇到预设工具之外的任务仍然无法处理。
+
+大语言模型本身就擅长读写文件和运行命令。只要给 Agent 提供操作系统的四个基础工具——`read`、`write`、`edit`、`shell`（全部工具定义不到 1,000 Token），它就能覆盖绝大多数任务：读文档、改代码、调接口、跑测试；遇到没有现成工具的场景，编写一段脚本执行即可完成扩展。这四个工具不只是写代码专用的工具，而是通用 Agent 在计算机上完成各类任务的基础工具集。
+
+但在实际生产环境（本地开发机、云端沙箱、无界面容器、聊天服务后台）中，现有的四工具实现存在三处限制：
+- **与交互式终端 CLI 捆绑**：社区现有实现（如 Pi 的 `coding-agent`）通常把这四个工具与终端 TUI 界面、WASM 图像处理等依赖打包在同一个 CLI 应用里，没有拆分为零依赖的独立 SDK。
+- **依赖特定系统的外部命令**：底层拼接 `python3`、`setsid`、`stdbuf -oL`、`sed`、`base64 -w0` 的实现，换到 macOS（BSD 工具链）或精简 Alpine 容器时会因缺少命令或参数报错；同时还会出现原子写入丢失 `0755` 可执行权限、覆盖软链接、macOS 终止进程组时父 shell 继续执行后续命令等问题。
+- **缺少无人值守的后台终端管理**：交互式 CLI 假定有人在终端前查看 `tmux`；运行在云端或聊天通道里的 Agent 执行超过 30 秒的构建、测试或长耗时任务时，需要超时后不断连转入后台终端、保留子进程日志句柄持续写入，并在退出时通过事件唤醒 Agent 汇报。
+
+`@nia-teams/four-tools` 将这四个工具拆分为零运行时依赖的独立包，采用两层结构解决上述问题：
+- **核心层（`@nia-teams/four-tools`）**：仅依赖 `ExecutionEnv` 接口，不引入 `node:fs`、`node:path` 或 `node:os`。内置 TypeScript 两级唯一文本匹配（保留 UTF-8 BOM 与原有 CRLF/LF 换行符）、按环境与真实路径串行化的 `FileMutationQueue`，以及兼容 `@nia-teams/agent-core` 与 Nia Teams 的工具定义。
+- **macOS / Linux 原生系统调用后端（`@nia-teams/four-tools/node`）**：基于 Node.js POSIX 系统调用实现按行分页读取、保留软链接与目标权限位的写入、跨内核进程组信号回收（macOS 先发 `SIGSTOP` 再发 `SIGKILL`），以及后台终端生命周期管理（`exec` 默认 30 秒转后台，支持 `terminal_create / list / read / signal / destroy`）。
+
+```sh
+npm install @nia-teams/four-tools
+```
+
+AI 编程助手可加载随包分发的 `SKILL.md`：`node_modules/@nia-teams/four-tools/skills/four-tools/SKILL.md`（[`skills/four-tools/SKILL.md`](./skills/four-tools/SKILL.md)）。
+
+---
+
+## 快速开始
+
+运行环境为 Node.js 20+（macOS 或 Linux）。安装依赖并运行 [`examples/quickstart.ts`](./examples/quickstart.ts)：
+
+```sh
+npm install @nia-teams/agent-core @nia-teams/ai
+npm install -D tsx
+DEEPSEEK_API_KEY=sk-... npx tsx examples/quickstart.ts
+```
+
+```ts
+import { AgentRuntime, InMemoryConversationStore } from '@nia-teams/agent-core';
+import { OpenAIClient } from '@nia-teams/ai';
+import { createNodeTools } from '@nia-teams/four-tools/node';
+
+if (!process.env.DEEPSEEK_API_KEY) throw new Error('Set DEEPSEEK_API_KEY');
+const client = new OpenAIClient({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  baseURL: 'https://api.deepseek.com/v1',
+  model: 'deepseek-chat',
+});
+const tools = createNodeTools({ cwd: process.cwd(), terminals: false });
+const store = InMemoryConversationStore.fromUserMessage(
+  'Read package.json and summarize this project. Do not modify files.',
+);
+const runtime = new AgentRuntime({ store, sessionId: 'quickstart' });
+try {
+  await runtime.run({
+    client,
+    systemPrompt: 'You are a coding assistant. Inspect files before answering.',
+    tools,
+    onEvent(event) {
+      if (event.type === 'text_delta') process.stdout.write(event.delta);
+      if (event.type === 'tool_call_start') console.log(`\n[${event.name}]`, event.input);
+    },
+  });
+  console.log();
+} finally {
+  await tools.dispose();
+  await client.close();
+}
+```
+
+---
+
+## 工具行为
+
+- **`read`**：按行分页读取文本（`offset` 从 1 开始），默认上限 2,000 行、50 KiB。可通过 `read: { maxLines, maxBytes }` 调整，或传 `read: { truncate: false }` 交由上层运行时裁剪。
+- **`write`**：创建缺失的父目录并写入文件，返回 `File written: <path> (<n> chars)`（`n` 为 UTF-16 字符数）。目标为可解析软链接时，保留软链接本身及目标文件原有权限位。
+- **`edit`**：先匹配唯一原文子串，未命中时尝试 Unicode 规范化（NFC、弯引号与窄空格）匹配。保留 UTF-8 BOM 与未修改行的 CRLF/LF，默认拒绝超过 16 MiB 的文件，成功返回 `OK: replacement applied`。
+- **`shell`**：执行命令并返回包含 `$ <command>`、标准输出、`[stderr]` 与 `exit_code: <code>, duration: <ms>ms` 的文本结果。
+- **并发写锁**：`createFourTools` 为同组 `write` / `edit` 共享一个 `FileMutationQueue`；多组实例可传入同一个 `mutationQueue`，按环境 ID 与真实文件路径（`realpath`）串行执行修改。
+- **钩子**：`afterRead`、`afterMutate` 与 `afterExec`（退出码为 0 时）可返回 `@nia-teams/ai/protocol` 格式的上下文提示；`resolveEnv` 为单次命令提供环境变量覆盖。
+
+---
+
+## 后台终端管理
+
+`createNodeEnv()` 默认开启后台终端：
+
+- **超时转后台**：前台 `shell` 默认等待 30 秒（`timeout: 0` 同为 30 秒）。超时后命令不中断，转为后台终端并返回 `Terminal ID: <id>`。
+- **终端操作**：通过 `terminal_create`、`terminal_list`、`terminal_read`（`offset` 从 0 开始）、`terminal_signal`（`SIGINT` / `SIGTERM` / `SIGKILL` 对应退出码 `130` / `143` / `137`）和 `terminal_destroy` 管理后台进程。
+- **退出通知与日志保留**：子进程继承日志文件描述符，顶层 shell 退出后仍可继续写入。顶层 shell 退出时触发一次 `onTerminalExit`（主动 `destroy` 不触发）；调用 `env.dispose()` 终止所有受管进程组并清理日志。前台命令超出大小上限的完整输出保存在 `spillPath`。
+- **仅前台模式**：传入 `createNodeTools({ cwd, terminals: false })`、`createFourTools(env, { shell: { allowBackground: false, name: 'bash' } })` 或省略 `env.terminals` 时，工具 Schema 隐藏后台终端操作，超时或取消时终止命令进程组。
+
+---
+
+## 本地运行示例
+
+### 1. 命令行交互（`examples/local-agent.ts`）
+
+流式输出回复、推理过程与工具调用，后台终端退出时通过 `host.injectMessage` 唤醒下一轮汇报：
+
+```sh
+OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com/v1 \
+  MODEL=deepseek-chat npx tsx examples/local-agent.ts
+```
+
+按 `ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY` 顺序选择客户端，`MODEL` 覆盖默认模型。按一次 `Ctrl+C` 取消当前轮次，1.2 秒内连按两次或输入 `/exit` 退出并清理后台终端。
+
+### 2. 浏览器工作台（`examples/web-agent.ts`）
+
+启动本地 HTTP 服务（默认 `127.0.0.1:18880`，支持 `HOST`、`PORT`、`WORKSPACE_DIR`、`WEB_AGENT_TOKEN`），提供对话流、工具卡片、工作区文件预览与后台终端列表：
+
+```sh
+OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com/v1 \
+  MODEL=deepseek-chat npx tsx examples/web-agent.ts
+```
+
+在浏览器打开终端打印的带 Token 链接即可交互；SSE 流通过 `createSnapshotStream` 支持断线重连。该 Token 具备本地命令执行权限，监听非回环地址时请通过受控代理访问。
+
+---
+
+## 自定义执行环境与子路径导出
+
+对接 SSH、容器或远程沙箱时，实现 `ExecutionEnv` 接口并传入 `createFourTools(env)`；无后台进程管理能力时省略 `env.terminals`。
+
+| 子路径 | 导出内容 |
+| --- | --- |
+| `@nia-teams/four-tools` | `createFourTools`、`createReadTool`、`createWriteTool`、`createEditTool`、`createShellTool`、`applyUniqueEdit`、`FileMutationQueue`、`ExecutionEnv` 与类型定义 |
+| `@nia-teams/four-tools/node` | `createNodeEnv`、`createNodeTools`（返回带 `.env` 与 `.dispose()` 的工具数组）、`createNodeFourTools`、`PosixNodeExecutionEnv`、`PosixTerminalManager` |
+
+工具使用宿主进程的文件系统与执行权限；`cwd` 仅作为相对路径基准，路径隔离、审批门禁与密钥脱敏由宿主 `ExecutionEnv` 负责。
+
+---
+
+## 构建与测试
+
+```sh
+npm ci --registry=https://registry.npmjs.org
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+## 开源协议
+
+[MIT](./LICENSE)

package/dist/core/contracts.d.ts

@@ -0,0 +1,118 @@
+/** Public tool surface shared with Nia Teams; the example command is generic. */
+export declare const toolContracts: {
+    readonly read: {
+        readonly description: "Read a file from the workspace. Supports optional line offset and limit for reading specific ranges.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly path: {
+                    readonly type: "string";
+                    readonly description: "Absolute or workspace-relative file path";
+                };
+                readonly offset: {
+                    readonly type: "integer";
+                    readonly description: "1-based line number to start reading from";
+                };
+                readonly limit: {
+                    readonly type: "integer";
+                    readonly description: "Maximum number of lines to read";
+                };
+            };
+            readonly required: readonly ["path"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly write: {
+        readonly description: "Write content to a file in the workspace. Creates parent directories if needed. Overwrites existing content.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly path: {
+                    readonly type: "string";
+                    readonly description: "Absolute or workspace-relative file path";
+                };
+                readonly content: {
+                    readonly type: "string";
+                    readonly description: "Content to write to the file";
+                };
+            };
+            readonly required: readonly ["path", "content"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly edit: {
+        readonly description: "Find and replace a unique string in a file. The old_string must appear exactly once in the file.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly path: {
+                    readonly type: "string";
+                    readonly description: "Absolute or workspace-relative file path";
+                };
+                readonly old_string: {
+                    readonly type: "string";
+                    readonly description: "The exact text to find (must be unique in the file)";
+                };
+                readonly new_string: {
+                    readonly type: "string";
+                    readonly description: "The replacement text";
+                };
+            };
+            readonly required: readonly ["path", "old_string", "new_string"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly shell: {
+        readonly description: "Execute shell commands or manage persistent terminals in the workspace sandbox.\n\nActions:\n- exec (default): Run a one-shot command, wait for output. For build, test, git, file ops, etc.\n- terminal_create: Create a non-interactive background process. A command is required. When it exits, success or failure is reported back to the originating session by default. Pass notifyOnExit=false only for deliberate fire-and-forget work.\n- terminal_list: List active background processes.\n- terminal_read: Read retained process output (supports offset/limit for incremental reading).\n- terminal_signal: Send signal (SIGINT/SIGTERM/SIGKILL) to a background process.\n- terminal_destroy: Destroy a terminal.\n\nFor exec and terminal_create, when the command is not already self-explanatory, begin it with one short English comment describing the purpose. The comment is valid shell syntax and is shown to the user as the activity title; the remaining lines are executed unchanged. Keep it concrete and non-sensitive.\n\nExample:\n# Inspect the project configuration\ncat package.json";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly action: {
+                    readonly type: "string";
+                    readonly enum: readonly ["exec", "terminal_create", "terminal_list", "terminal_read", "terminal_signal", "terminal_destroy"];
+                    readonly description: "Action to perform (default: exec)";
+                };
+                readonly command: {
+                    readonly type: "string";
+                    readonly description: "Shell command (required for exec / terminal_create). For a non-obvious command, optionally start with a short English `# purpose` comment; it remains valid shell syntax and the UI uses it as the activity title. Example: `# Inspect the project configuration\ncat package.json`. Never put secrets or credentials in the comment.";
+                };
+                readonly cwd: {
+                    readonly type: "string";
+                    readonly description: "Working directory (exec)";
+                };
+                readonly timeout: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly description: "Timeout in seconds (exec, default 30). No cap — the call returns as soon as the command finishes, so overestimating costs nothing while underestimating costs an extra poll round-trip. Pass your real estimate directly — a build might need 300, a long compute job 1800 or more.";
+                };
+                readonly id: {
+                    readonly type: "string";
+                    readonly description: "Terminal ID (read/write/signal/destroy)";
+                };
+                readonly name: {
+                    readonly type: "string";
+                    readonly description: "Terminal name (terminal_create)";
+                };
+                readonly notifyOnExit: {
+                    readonly type: "boolean";
+                    readonly default: true;
+                    readonly description: "Notify and wake the originating session when the terminal command exits (terminal_create, default true). Set false only for deliberate fire-and-forget work.";
+                };
+                readonly offset: {
+                    readonly type: "number";
+                    readonly description: "Read start line (terminal_read)";
+                };
+                readonly limit: {
+                    readonly type: "number";
+                    readonly description: "Max lines to read (terminal_read)";
+                };
+                readonly signal: {
+                    readonly type: "string";
+                    readonly enum: readonly ["SIGINT", "SIGTERM", "SIGKILL"];
+                    readonly description: "Signal (terminal_signal)";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+    };
+};

package/dist/core/contracts.js

@@ -0,0 +1,125 @@
+/** Public tool surface shared with Nia Teams; the example command is generic. */
+export const toolContracts = {
+    read: {
+        description: 'Read a file from the workspace. Supports optional line offset and limit for reading specific ranges.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute or workspace-relative file path',
+                },
+                offset: {
+                    type: 'integer',
+                    description: '1-based line number to start reading from',
+                },
+                limit: {
+                    type: 'integer',
+                    description: 'Maximum number of lines to read',
+                },
+            },
+            required: ['path'],
+            additionalProperties: false,
+        },
+    },
+    write: {
+        description: 'Write content to a file in the workspace. Creates parent directories if needed. Overwrites existing content.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute or workspace-relative file path',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Content to write to the file',
+                },
+            },
+            required: ['path', 'content'],
+            additionalProperties: false,
+        },
+    },
+    edit: {
+        description: 'Find and replace a unique string in a file. The old_string must appear exactly once in the file.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute or workspace-relative file path',
+                },
+                old_string: {
+                    type: 'string',
+                    description: 'The exact text to find (must be unique in the file)',
+                },
+                new_string: {
+                    type: 'string',
+                    description: 'The replacement text',
+                },
+            },
+            required: ['path', 'old_string', 'new_string'],
+            additionalProperties: false,
+        },
+    },
+    shell: {
+        description: 'Execute shell commands or manage persistent terminals in the workspace sandbox.\n\nActions:\n- exec (default): Run a one-shot command, wait for output. For build, test, git, file ops, etc.\n- terminal_create: Create a non-interactive background process. A command is required. When it exits, success or failure is reported back to the originating session by default. Pass notifyOnExit=false only for deliberate fire-and-forget work.\n- terminal_list: List active background processes.\n- terminal_read: Read retained process output (supports offset/limit for incremental reading).\n- terminal_signal: Send signal (SIGINT/SIGTERM/SIGKILL) to a background process.\n- terminal_destroy: Destroy a terminal.\n\nFor exec and terminal_create, when the command is not already self-explanatory, begin it with one short English comment describing the purpose. The comment is valid shell syntax and is shown to the user as the activity title; the remaining lines are executed unchanged. Keep it concrete and non-sensitive.\n\nExample:\n# Inspect the project configuration\ncat package.json',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: [
+                        'exec',
+                        'terminal_create',
+                        'terminal_list',
+                        'terminal_read',
+                        'terminal_signal',
+                        'terminal_destroy',
+                    ],
+                    description: 'Action to perform (default: exec)',
+                },
+                command: {
+                    type: 'string',
+                    description: 'Shell command (required for exec / terminal_create). For a non-obvious command, optionally start with a short English `# purpose` comment; it remains valid shell syntax and the UI uses it as the activity title. Example: `# Inspect the project configuration\ncat package.json`. Never put secrets or credentials in the comment.',
+                },
+                cwd: {
+                    type: 'string',
+                    description: 'Working directory (exec)',
+                },
+                timeout: {
+                    type: 'number',
+                    minimum: 0,
+                    description: 'Timeout in seconds (exec, default 30). No cap — the call returns as soon as the command finishes, so overestimating costs nothing while underestimating costs an extra poll round-trip. Pass your real estimate directly — a build might need 300, a long compute job 1800 or more.',
+                },
+                id: {
+                    type: 'string',
+                    description: 'Terminal ID (read/write/signal/destroy)',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Terminal name (terminal_create)',
+                },
+                notifyOnExit: {
+                    type: 'boolean',
+                    default: true,
+                    description: 'Notify and wake the originating session when the terminal command exits (terminal_create, default true). Set false only for deliberate fire-and-forget work.',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Read start line (terminal_read)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max lines to read (terminal_read)',
+                },
+                signal: {
+                    type: 'string',
+                    enum: ['SIGINT', 'SIGTERM', 'SIGKILL'],
+                    description: 'Signal (terminal_signal)',
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+};

package/dist/core/edit-engine.d.ts

@@ -0,0 +1,11 @@
+export type EditResult = {
+    ok: true;
+    content: string;
+    matchedBy: 'exact' | 'normalized';
+    line: number;
+} | {
+    ok: false;
+    reason: 'empty_old_string' | 'unchanged' | 'not_found' | 'not_unique' | 'ambiguous_normalized';
+    count?: number;
+};
+export declare function applyUniqueEdit(original: string, oldString: string, newString: string): EditResult;