orbitx 0.2.9 → 0.3.0

package/Readme.md

@@ -1,457 +1,479 @@
-[![OrbitX Logo](https://raw.githubusercontent.com/ali39af/orbitx/refs/heads/main/orbitx.svg)](#)
-
-📖 **[Full documentation](./docs/index.md)** — a deeper, page-by-page guide (providers, agents, tools, skills, MCP transport, streaming, full API reference), written to be useful both to humans learning the library and to AI agents coding against it.
-
-## Installation
-
-```bash
-npm install orbitx
-```
-
-## Demo
-
-<table>
-  <tr>
-    <td align="center">
-      <a href="https://www.youtube.com/watch?v=nuIhIBdBjTI">
-        <img src="https://img.youtube.com/vi/nuIhIBdBjTI/maxresdefault.jpg" width="400" alt="Demo 1">
-      </a>
-      <br>
-      <b>Demo 1</b>
-    </td>
-    <td align="center">
-      <a href="https://www.youtube.com/watch?v=Go1PIYo0sFw">
-        <img src="https://img.youtube.com/vi/Go1PIYo0sFw/maxresdefault.jpg" width="400" alt="Demo 2">
-      </a>
-      <br>
-      <b>Demo 2</b>
-    </td>
-  </tr>
-</table>
-
-
-## Quick Start
-
-The fastest way to get an agent running is `SimpleAgent` — give it a provider, an instruction, and a list of tools/skills.
-
-```ts
-import { OllamaProvider, SimpleAgent, GetCurrentTimeTool } from "orbitx";
-
-const ollamaProvider = new OllamaProvider("gemma4:e4b");
-
-const agent = new SimpleAgent({
-  aiProvider: ollamaProvider,
-  instruction: "You are a helpful assistant.",
-  tools: [GetCurrentTimeTool()],
-});
-
-let oldRole: "assistant" | "tool" | "user" | undefined;
-
-agent.run("what is current time?", (chunk) => {
-  if (oldRole !== chunk.role) {
-    process.stdout.write(`\n${chunk.role}: `);
-    oldRole = chunk.role;
-  }
-  process.stdout.write(chunk.content);
-
-  if (chunk.done && chunk.role === "assistant" && chunk.toolCalls?.length) {
-    console.log(chunk.toolCalls);
-  }
-  if (chunk.role === "tool") {
-    console.log({ toolCallId: chunk.toolCallId, toolName: chunk.toolName });
-  }
-
-  if (chunk.done) {
-    process.stdout.write("\n\n");
-    oldRole = undefined;
-  }
-});
-```
-
-All tools and skills passed in are baked into the system prompt once, up front — there's no separate routing/selection step deciding what the model can see turn to turn.
-
-### Recovering an agent's state
-
-`getCurrentAgentStates()` returns a plain JSON-serializable snapshot (messages, memory, token counters). Save it wherever you like, and pass it back in as `initData` to resume the exact same agent later — a process restart, a saved session, etc.
-
-```ts
-import { writeFileSync, existsSync, readFileSync } from "fs";
-
-const initData = existsSync("./state.json")
-  ? JSON.parse(readFileSync("./state.json", "utf-8"))
-  : undefined;
-
-const agent = new SimpleAgent({
-  aiProvider: ollamaProvider,
-  instruction: "You are a helpful assistant.",
-  tools: [GetCurrentTimeTool()],
-  ...(initData ? { initData } : {}),
-});
-
-// after any run() call:
-writeFileSync("./state.json", JSON.stringify(agent.getCurrentAgentStates()));
-```
-
-Old messages are never rewritten once written — the agent only ever appends. When the conversation grows past its memory limit, OrbitX keeps the full history intact on disk (`messagesFull`) and instead resets the model's working context window from a running summary of what it already did, so it can keep going indefinitely without losing the ability to act on what happened earlier.
-
-## Providers
-
-OrbitX ships with pluggable AI providers so you can swap models without changing your agent logic.
-
-### Ollama
-
-```ts
-import { OllamaProvider } from "orbitx";
-
-const ollamaProvider = new OllamaProvider("gemma4:e4b");
-```
-
-### DeepSeek
-
-```ts
-import { DeepSeekProvider } from "orbitx";
-
-const deepseekProvider = new DeepSeekProvider("api-key", "deepseek-v4-flash");
-```
-
-### Anthropic
-
-```ts
-import { AnthropicProvider } from "orbitx";
-
-const anthropicProvider = new AnthropicProvider("api-key", "claude-sonnet-5");
-```
-
-### OpenAI
-
-```ts
-import { OpenAIProvider } from "orbitx";
-
-const openaiProvider = new OpenAIProvider("api-key", "gpt-5");
-```
-
-### Think effort
-
-Every provider accepts a universal `thinkEffort` option (`0`-`1`, e.g. `0.5` or `0.8`) instead of a provider-specific string — each provider maps it onto whatever scale it actually accepts (DeepSeek's `none/low/high/max`, OpenAI/Ollama's `low/medium/high`, Anthropic's numeric thinking budget), and it's silently ignored by providers/models that don't support thinking at all:
-
-```ts
-import { AnthropicProvider } from "orbitx";
-
-const anthropicProvider = new AnthropicProvider("api-key", "claude-sonnet-5", { thinkEffort: 0.7 });
-```
-
-See the [docs](./docs/providers.md#think-effort) for the per-provider mapping and how thinking text streams (where supported).
-
-### Two providers: main + image
-
-An agent uses exactly two provider roles — `main` (drives the agent loop itself) and `image` (describes image tool output, e.g. screenshots, so the main conversation doesn't have to carry raw image bytes). Pass a single provider to use it for both roles, or an array to split them:
-
-```ts
-import { BaseAgent, DeepSeekProvider, OllamaProvider } from "orbitx";
-
-const agent = new BaseAgent({
-  aiProvider: [
-    { type: "main", aiProvider: new DeepSeekProvider("api-key", "deepseek-v4-flash") },
-    { type: "image", aiProvider: new OllamaProvider("llava:latest") },
-  ],
-  instruction: "You are a helpful assistant.",
-  mcpClient,
-  allowedTools: [/* ... */],
-});
-```
-
-## Available Tools
-
-Tools are grouped by domain. Import each group's array (e.g. `FsTools()`) to get every tool in that group at once, or import individual tools by name.
-
-### Filesystem (`FsTools`)
-
-⚠️ EXTREMELY IMPORTANT WARNING ABOUT `FsWriteFileTool` / `FsDeleteTool` ⚠️
-
-🔴 CRITICAL: FsWriteFileTool and FsDeleteTool can permanently overwrite, delete, or corrupt existing files – no undo available.
-
-We strongly prefer running bash commands through MCPComputer, which provides a sandboxed, isolated environment – protecting your host system from accidental damage.
-
-
-| Tool | Purpose |
-|---|---|
-| `FsReadFileTool` | Read a text file, paging through large files by line. |
-| `FsWriteFileTool` | Write/overwrite a file's full content (creates parent dirs as needed). ⚠️ No undo. |
-| `FsEditFileTool` | Replace a specific line range in an existing file without rewriting the whole thing. |
-| `FsListDirTool` | List a directory's entries, paged by index for large directories. |
-| `FsCreateDirTool` | Create a directory, including missing parents. |
-| `FsDeleteTool` | Permanently delete a file or directory (recursive optional). ⚠️ No undo. |
-| `FsMoveTool` | Move or rename a file or directory. |
-| `FsStatTool` | Check whether a path exists and get its metadata (type, size, modified time). |
-
-### Bash / processes (`BashTools`)
-
-⚠️ EXTREMELY IMPORTANT WARNING ABOUT `BashRunTool` ⚠️
-
-🔴 CRITICAL: Shell commands can permanently delete files, corrupt data, modify system settings, or execute harmful operations – no undo available.
-
-We strongly prefer running bash commands through MCPComputer, which provides a sandboxed, isolated environment – protecting your host system from accidental damage.
-
-| Tool | Purpose |
-|---|---|
-| `BashRunTool` | Launch a shell command as a background process; returns immediately if it's still running after `waitMs` (e.g. a dev server). |
-| `BashWaitTool` | Wait again on a previously started process and get its latest status/output. |
-| `BashLogsTool` | Read a process's combined stdout/stderr, paged by line. |
-| `BashListTool` | List every process launched so far with its status. |
-| `BashWriteInputTool` | Send text to a running process's stdin (answer an interactive prompt like `(y/n)`). |
-| `BashTerminateTool` | Terminate a running process. |
-
-### Browser (`BrowserTools`)
-
-Drives a real headless browser session.
-
-| Tool | Purpose |
-|---|---|
-| `BrowserCreateSessionTool` | Open a new headless browser session at a URL, returns its `sessionId`. |
-| `BrowserRemoveSessionTool` | Close and remove a browser session. |
-| `BrowserGetSessionsTool` | List all currently open session ids. |
-| `BrowserNavigateTool` | Navigate an existing session to a new URL. |
-| `BrowserReadTool` | Read the page as a text outline (headings, tables, links, forms), assigning ref ids to clickable/fillable elements. |
-| `BrowserClickTool` | Click a `[CLICKABLE]` element by ref id. |
-| `BrowserFillTool` | Type into a `[FILLABLE]` element by ref id; can submit via Enter if the field's form has no visible submit button. |
-| `BrowserSubmitFormTool` | Submit a `[FORM]` ref directly — for forms with no visible submit button. |
-| `BrowserScrollInfoTool` | Get total scrollable length and current scroll position. |
-| `BrowserScrollTool` | Scroll to a given vertical pixel position. |
-| `BrowserConsoleTool` | Read captured browser console log messages. |
-| `BrowserNetworkTool` | Read captured network request/response activity. |
-| `BrowserNetworkStatusTool` | Check whether the page currently has in-flight network activity (use before assuming a "no response yet" state means something broke). |
-| `BrowserInjectTool` | Evaluate arbitrary JS in the page and return the result. |
-| `BrowserScreenshotTool` | Capture a screenshot; can be described by the `image` provider instead of passed raw to the main model. |
-
-### Todo lists (`TodoTools`)
-
-| Tool | Purpose |
-|---|---|
-| `TodoCreateListTool` | Create a new todo list, returns its `todoListId`. |
-| `TodoRemoveListTool` | Remove one or more todo lists (and their tasks). |
-| `TodoGetListsTool` | Get all existing todo list ids. |
-| `TodoGetListTool` | Get all tasks belonging to a list. |
-| `TodoCreateTaskTool` | Create one or more tasks inside a list. |
-| `TodoRemoveTaskTool` | Remove one or more tasks by id. |
-| `TodoCheckTaskTool` | Set the checked/unchecked state of one or more tasks. |
-
-### Present / deliverables (`PresentTools`)
-
-| Tool | Purpose |
-|---|---|
-| `PresentAddTool` | Present a file to the user by copying it into the present folder (zip folders first — this only accepts single files). |
-| `PresentClearTool` | Clear out every file currently presented. |
-| `PresentGetListTool` | Get the list of files currently presented. |
-
-### Utility (`UtilTools`)
-
-| Tool | Purpose |
-|---|---|
-| `GetCurrentTimeTool` | Get the current date/time (ISO string, unix timestamp, timezone). |
-| `DelayTool` | Wait a given number of milliseconds (max 60000ms) before continuing. |
-
-### Multi-agent (`AgentTools`) — Experimental
-
-⚠️ This feature is new and still settling — names and behavior may change in a future release.
-
-Unlike the other domains, this one takes parameters — a roster of `WorkerAgent`s (a `BaseAgent` with a name/description/rating) you build ahead of time, and an optional hiring cap: `AgentTools([worker1, worker2, ...], { maxHired: 2 })`. Give the result to your planner agent so it can list, hire, and prompt those workers as sub-agents; give each worker its own `AgentReportTool()` so it can hand a result back and stop. Full walkthrough in the [docs](./docs/agents.md#multi-agent-workeragent-experimental).
-
-| Tool | Purpose |
-|---|---|
-| `agent-list` | List every worker in the roster — name, description, rating, hired status. |
-| `agent-hire` | Hire a worker by name, making it eligible for `agent-prompt`. |
-| `agent-prompt` | Send a prompt to a hired worker and return its response once it's done. |
-
-## Available Skills
-
-A `Skill` bundles instructions with the tools that go with them. Passing a skill into an agent adds its tools automatically and folds its instructions into the system prompt.
-
-| Skill | Purpose |
-|---|---|
-| `PlannerSkill` | Stands up a persistent, checkable todo list for any large/multi-step/vague job so progress survives long conversations and context resets. |
-| `BigTaskSkill` | Keeps the agent from stopping short on large or ambitious jobs — no declaring victory on a partial slice, no handing a big job back half-finished. |
-| `LongTaskEfficiencySkill` | Keeps a long job efficient — batching, avoiding redundant reads, checkpointing, not gold-plating — without giving up on getting through the full scope. |
-| `NodeBackendSkill` | Building, running, and debugging Node.js backends: APIs, servers, CLIs, workers, schedulers, DB access layers — new or existing. |
-| `ReactFrontendSkill` | Building, running, and debugging modern React (`.tsx`/`.jsx`) projects, typically Vite-scaffolded — new or existing. |
-| `UiUxDesignSkill` | Visual and interaction design quality for any user-facing UI — layout, hierarchy, feedback states, accessibility, responsiveness. |
-| `BackendSecuritySkill` | Hardening server-side code that touches auth, sessions, tokens, uploads, DB queries, payments, or any trust boundary. |
-| `CodeVerificationSkill` | Running the right type checker/build/lint/test suite before handing code back, and telling real bugs apart from sandbox artifacts. |
-| `WebEndToEndTestSkill` | Testing a live web app like a real user would (fill, click, navigate) and verifying via the rendered page, console, and network — not by reading source and assuming. |
-| `ResearchSkill` | Answering questions that need real, current information from the live web — opens pages, cross-checks multiple sources, never trusts one page. |
-| `ShoppingSkill` | Purchase-decision help — real current listings, prices, links, and review sentiment instead of recommending from memory. |
-| `PresentSkill` | Deciding how to hand back a job's output as files (individually or zipped) and cleaning build artifacts out first. |
-
-## Building from the Base Agent
-
-For full control over the MCP server, connection, and client, compose an agent from the base primitives:
-
-```ts
-import {
-  OllamaProvider,
-  MCPConnection,
-  MCPServer,
-  MCPClient,
-  BaseAgent,
-  GetCurrentTimeTool,
-} from "orbitx";
-
-const ollamaProvider = new OllamaProvider("gemma4:e4b");
-
-const connection = new MCPConnection();
-
-const mcpServer = new MCPServer(connection);
-mcpServer.registerTool(GetCurrentTimeTool());
-
-const mcpClient = new MCPClient("DEFAULT_ENV", connection);
-
-const agent = new BaseAgent({
-  aiProvider: ollamaProvider,
-  instruction: "",
-  mcpClient,
-  allowedTools: [GetCurrentTimeTool()],
-});
-
-let oldRole: "assistant" | "tool" | "user" | undefined;
-
-agent.run("what is current time?", (chunk) => {
-  if (oldRole !== chunk.role) {
-    process.stdout.write(`\n${chunk.role}: `);
-    oldRole = chunk.role;
-  }
-  process.stdout.write(chunk.content);
-  if (chunk.done) {
-    process.stdout.write("\n\n");
-    oldRole = undefined;
-  }
-});
-```
-
-### IPC Connections
-
-Run your MCP server as a separate process and connect to it over an inter-process communication (IPC) channel:
-
-```ts
-import os from "os";
-import { MCPIPCConnection } from "orbitx";
-
-const path =
-  os.platform() === "win32" ? `\\\\.\\pipe\\mcp_test` : `/tmp/mcp_test.sock`;
-
-const ipcConnection = new MCPIPCConnection({ mode: "server", socketPath: path });
-```
-
-### WS Connections
-
-Run your MCP server as a separate process and connect to it over an web-socket communication (WS) channel:
-
-```ts
-import os from "os";
-import { MCPWSConnection } from "orbitx";
-
-const wsConnection = new MCPWSConnection({ mode: "server", host: "0.0.0.0", port: 9257, token: "1234" });
-```
-
-
-## Creating a Custom Tool
-
-Define your own tools with `MCPTool` to extend an agent's capabilities and integrate with your own ecosystem.
-
-```ts
-import { MCPTool } from "orbitx";
-
-export const SumTool = () => new MCPTool({
-  name: "math-sum",
-  description: "get two numbers and sum them",
-  inputs: [
-    {
-      name: "first",
-      type: "number",
-      description: "first number",
-      required: true,
-    },
-    {
-      name: "second",
-      type: "number",
-      description: "second number",
-      required: true,
-    },
-  ],
-  execute: async (_envID: string, inputs: Record<string, any>) => {
-    const { first, second } = inputs;
-
-    if (typeof first !== "number") {
-      throw new Error("first must be a number");
-    }
-    if (typeof second !== "number") {
-      throw new Error("second must be a number");
-    }
-
-    return { output: first + second };
-  },
-});
-```
-
-Use it like any built-in tool:
-
-```ts
-const agent = new SimpleAgent({
-  aiProvider: ollamaProvider,
-  instruction: "You are a helpful assistant.",
-  tools: [SumTool()],
-});
-```
-
-## Creating a Custom Skill
-
-A `Skill` bundles instructions with the tools it needs, so an agent that includes it automatically gets both.
-
-```ts
-import { Skill, FsReadFileTool, FsWriteFileTool } from "orbitx";
-import { SumTool } from "./sum-tool.js";
-
-export const MathHelperSkill = () => new Skill({
-  name: "math-helper",
-  description:
-    "Use this skill whenever the user asks for arithmetic that should be computed exactly " +
-    "rather than estimated from the model's own reasoning — sums, running totals, or " +
-    "anything written to a file afterward.",
-  instructions: `
-- Always use the math-sum tool for addition instead of computing it yourself.
-- If asked to save a result, write it to disk with fs-write-file and confirm the path back to the user.
-  `,
-  tools: [
-    SumTool(),
-    FsReadFileTool(),
-    FsWriteFileTool(),
-  ],
-});
-```
-
-```ts
-const agent = new SimpleAgent({
-  aiProvider: ollamaProvider,
-  instruction: "You are a helpful assistant.",
-  skills: [MathHelperSkill()],
-});
-```
-
-## MCPComputer (Experimental Feature)
-
-Spins up a sandboxed Docker container running the MCP server and returns a ready-to-use client connection — no need to manage IPC sockets, ports, or tokens manually.
-
-```typescript
-import { MCPComputer } from "orbitx";
-
-const computer = new MCPComputer("/path/to/mount", [3000, 8080]);
-await computer.start();
-
-const connection = computer.getConnection();
-await computer.stop();
-```
-
-- **`mountPath`**: host directory mounted into the container
-- **`ports`**: ports to expose, or `"*"` for host network mode (Linux only, or Windows via WSL2)
-- **`getConnection()`**: returns a ready `MCPConnection` (IPC on Linux/macOS, WebSocket on Windows)
-- **`stop()`**: kills the container
-
+[![OrbitX Logo](https://raw.githubusercontent.com/ali39af/orbitx/refs/heads/main/orbitx.svg)](#)
+
+📖 **[Full documentation](./docs/index.md)** — a deeper, page-by-page guide (providers, agents, swarms, tools, skills, MCP transport, streaming, full API reference), written to be useful both to humans learning the library and to AI agents coding against it.
+
+## Installation
+
+```bash
+npm install orbitx
+```
+
+## Demo
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://www.youtube.com/watch?v=nuIhIBdBjTI">
+        <img src="https://img.youtube.com/vi/nuIhIBdBjTI/maxresdefault.jpg" width="400" alt="Demo 1">
+      </a>
+      <br>
+      <b>Demo 1</b>
+    </td>
+    <td align="center">
+      <a href="https://www.youtube.com/watch?v=Go1PIYo0sFw">
+        <img src="https://img.youtube.com/vi/Go1PIYo0sFw/maxresdefault.jpg" width="400" alt="Demo 2">
+      </a>
+      <br>
+      <b>Demo 2</b>
+    </td>
+  </tr>
+</table>
+
+
+## Quick Start
+
+The fastest way to get an agent running is `SimpleAgent` — give it a provider, an instruction, and a list of tools/skills.
+
+```ts
+import { OllamaProvider, SimpleAgent, GetCurrentTimeTool } from "orbitx";
+
+const ollamaProvider = new OllamaProvider("gemma4:e4b");
+
+const agent = new SimpleAgent({
+  aiProvider: ollamaProvider,
+  instruction: "You are a helpful assistant.",
+  tools: [GetCurrentTimeTool()],
+});
+
+let oldRole: "assistant" | "tool" | "user" | undefined;
+
+agent.run("what is current time?", (chunk) => {
+  if (oldRole !== chunk.role) {
+    process.stdout.write(`\n${chunk.role}: `);
+    oldRole = chunk.role;
+  }
+  process.stdout.write(chunk.content);
+
+  if (chunk.done && chunk.role === "assistant" && chunk.toolCalls?.length) {
+    console.log(chunk.toolCalls);
+  }
+  if (chunk.role === "tool") {
+    console.log({ toolCallId: chunk.toolCallId, toolName: chunk.toolName });
+  }
+
+  if (chunk.done) {
+    process.stdout.write("\n\n");
+    oldRole = undefined;
+  }
+});
+```
+
+All tools and skills passed in are baked into the system prompt once, up front — there's no separate routing/selection step deciding what the model can see turn to turn.
+
+### Recovering an agent's state
+
+`getCurrentAgentStates()` returns a plain JSON-serializable snapshot (messages, memory, token counters). Save it wherever you like, and pass it back in as `initData` to resume the exact same agent later — a process restart, a saved session, etc.
+
+```ts
+import { writeFileSync, existsSync, readFileSync } from "fs";
+
+const initData = existsSync("./state.json")
+  ? JSON.parse(readFileSync("./state.json", "utf-8"))
+  : undefined;
+
+const agent = new SimpleAgent({
+  aiProvider: ollamaProvider,
+  instruction: "You are a helpful assistant.",
+  tools: [GetCurrentTimeTool()],
+  ...(initData ? { initData } : {}),
+});
+
+// after any run() call:
+writeFileSync("./state.json", JSON.stringify(agent.getCurrentAgentStates()));
+```
+
+Old messages are never rewritten once written — the agent only ever appends. When the conversation grows past its memory limit, OrbitX keeps the full history intact on disk (`messagesFull`) and instead resets the model's working context window from a running summary of what it already did, so it can keep going indefinitely without losing the ability to act on what happened earlier.
+
+## Providers
+
+OrbitX ships with pluggable AI providers so you can swap models without changing your agent logic.
+
+### Ollama
+
+```ts
+import { OllamaProvider } from "orbitx";
+
+const ollamaProvider = new OllamaProvider("gemma4:e4b");
+```
+
+### DeepSeek
+
+```ts
+import { DeepSeekProvider } from "orbitx";
+
+const deepseekProvider = new DeepSeekProvider("api-key", "deepseek-v4-flash");
+```
+
+### Anthropic
+
+```ts
+import { AnthropicProvider } from "orbitx";
+
+const anthropicProvider = new AnthropicProvider("api-key", "claude-sonnet-5");
+```
+
+### OpenAI
+
+```ts
+import { OpenAIProvider } from "orbitx";
+
+const openaiProvider = new OpenAIProvider("api-key", "gpt-5");
+```
+
+### Think effort
+
+Every provider accepts a universal `thinkEffort` option (`0`-`1`, e.g. `0.5` or `0.8`) instead of a provider-specific string — each provider maps it onto whatever scale it actually accepts (DeepSeek's `none/low/high/max`, OpenAI/Ollama's `low/medium/high`, Anthropic's numeric thinking budget), and it's silently ignored by providers/models that don't support thinking at all:
+
+```ts
+import { AnthropicProvider } from "orbitx";
+
+const anthropicProvider = new AnthropicProvider("api-key", "claude-sonnet-5", { thinkEffort: 0.7 });
+```
+
+See the [docs](./docs/providers.md#think-effort) for the per-provider mapping and how thinking text streams (where supported).
+
+### Two providers: main + image
+
+An agent uses exactly two provider roles — `main` (drives the agent loop itself) and `image` (describes image tool output, e.g. screenshots, so the main conversation doesn't have to carry raw image bytes). Pass a single provider to use it for both roles, or an array to split them:
+
+```ts
+import { BaseAgent, DeepSeekProvider, OllamaProvider } from "orbitx";
+
+const agent = new BaseAgent({
+  aiProvider: [
+    { type: "main", aiProvider: new DeepSeekProvider("api-key", "deepseek-v4-flash") },
+    { type: "image", aiProvider: new OllamaProvider("llava:latest") },
+  ],
+  instruction: "You are a helpful assistant.",
+  mcpClient,
+  allowedTools: [/* ... */],
+});
+```
+
+## Available Tools
+
+Tools are grouped by domain. Import each group's array (e.g. `FsTools()`) to get every tool in that group at once, or import individual tools by name.
+
+### Filesystem (`FsTools`)
+
+⚠️ EXTREMELY IMPORTANT WARNING ABOUT `FsWriteFileTool` / `FsDeleteTool` ⚠️
+
+🔴 CRITICAL: FsWriteFileTool and FsDeleteTool can permanently overwrite, delete, or corrupt existing files – no undo available.
+
+We strongly prefer running bash commands through MCPComputer, which provides a sandboxed, isolated environment – protecting your host system from accidental damage.
+
+
+| Tool | Purpose |
+|---|---|
+| `FsReadFileTool` | Read a text file, paging through large files by line. |
+| `FsWriteFileTool` | Write/overwrite a file's full content (creates parent dirs as needed). ⚠️ No undo. |
+| `FsEditFileTool` | Replace a specific line range in an existing file without rewriting the whole thing. |
+| `FsListDirTool` | List a directory's entries, paged by index for large directories. |
+| `FsCreateDirTool` | Create a directory, including missing parents. |
+| `FsDeleteTool` | Permanently delete a file or directory (recursive optional). ⚠️ No undo. |
+| `FsMoveTool` | Move or rename a file or directory. |
+| `FsStatTool` | Check whether a path exists and get its metadata (type, size, modified time). |
+
+### Bash / processes (`BashTools`)
+
+⚠️ EXTREMELY IMPORTANT WARNING ABOUT `BashRunTool` ⚠️
+
+🔴 CRITICAL: Shell commands can permanently delete files, corrupt data, modify system settings, or execute harmful operations – no undo available.
+
+We strongly prefer running bash commands through MCPComputer, which provides a sandboxed, isolated environment – protecting your host system from accidental damage.
+
+| Tool | Purpose |
+|---|---|
+| `BashRunTool` | Launch a shell command as a background process; returns immediately if it's still running after `waitMs` (e.g. a dev server). |
+| `BashWaitTool` | Wait again on a previously started process and get its latest status/output. |
+| `BashLogsTool` | Read a process's combined stdout/stderr, paged by line. |
+| `BashListTool` | List every process launched so far with its status. |
+| `BashWriteInputTool` | Send text to a running process's stdin (answer an interactive prompt like `(y/n)`). |
+| `BashTerminateTool` | Terminate a running process. |
+
+### Browser (`BrowserTools`)
+
+Drives a real headless browser session.
+
+| Tool | Purpose |
+|---|---|
+| `BrowserCreateSessionTool` | Open a new headless browser session at a URL, returns its `sessionId`. |
+| `BrowserRemoveSessionTool` | Close and remove a browser session. |
+| `BrowserGetSessionsTool` | List all currently open session ids. |
+| `BrowserNavigateTool` | Navigate an existing session to a new URL. |
+| `BrowserReadTool` | Read the page as a text outline (headings, tables, links, forms), assigning ref ids to clickable/fillable elements. |
+| `BrowserClickTool` | Click a `[CLICKABLE]` element by ref id. |
+| `BrowserFillTool` | Type into a `[FILLABLE]` element by ref id; can submit via Enter if the field's form has no visible submit button. |
+| `BrowserSubmitFormTool` | Submit a `[FORM]` ref directly — for forms with no visible submit button. |
+| `BrowserScrollInfoTool` | Get total scrollable length and current scroll position. |
+| `BrowserScrollTool` | Scroll to a given vertical pixel position. |
+| `BrowserConsoleTool` | Read captured browser console log messages. |
+| `BrowserNetworkTool` | Read captured network request/response activity. |
+| `BrowserNetworkStatusTool` | Check whether the page currently has in-flight network activity (use before assuming a "no response yet" state means something broke). |
+| `BrowserInjectTool` | Evaluate arbitrary JS in the page and return the result. |
+| `BrowserScreenshotTool` | Capture a screenshot; can be described by the `image` provider instead of passed raw to the main model. |
+
+### Todo lists (`TodoTools`)
+
+| Tool | Purpose |
+|---|---|
+| `TodoCreateListTool` | Create a new todo list, returns its `todoListId`. |
+| `TodoRemoveListTool` | Remove one or more todo lists (and their tasks). |
+| `TodoGetListsTool` | Get all existing todo list ids. |
+| `TodoGetListTool` | Get all tasks belonging to a list. |
+| `TodoCreateTaskTool` | Create one or more tasks inside a list. |
+| `TodoRemoveTaskTool` | Remove one or more tasks by id. |
+| `TodoCheckTaskTool` | Set the checked/unchecked state of one or more tasks. |
+
+### Present / deliverables (`PresentTools`)
+
+| Tool | Purpose |
+|---|---|
+| `PresentAddTool` | Present a file to the user by copying it into the present folder (zip folders first — this only accepts single files). |
+| `PresentClearTool` | Clear out every file currently presented. |
+| `PresentGetListTool` | Get the list of files currently presented. |
+
+### Utility (`UtilTools`)
+
+| Tool | Purpose |
+|---|---|
+| `GetCurrentTimeTool` | Get the current date/time (ISO string, unix timestamp, timezone). |
+| `DelayTool` | Wait a given number of milliseconds (max 60000ms) before continuing. |
+
+### Swarm (`getAgentTools`)
+
+The tools a group of agents uses to hire, task, and report to each other. Unlike the other domains this one returns a **handle**, not an array — `handle.tools` goes into your tool pool, and the handle itself goes into `SwarmBase`, because both sides share the state built with it (the shared hire pool, and which swarm the tools drive).
+
+```ts
+const agentTools = getAgentTools({ maxHired: 5 });
+
+const swarm = new SwarmBase({
+  tools: [...FsTools(), ...BashTools(), ...UtilTools(), ...agentTools.tools],
+  agents: DefaultAgents(),   // planner, reasoner, backend, frontend, tester, research
+  default: "planner",
+  agentTools,
+  aiProvider,
+});
+
+const done = await swarm.run("Build the checkout flow", chunk => {
+  process.stdout.write(`[${chunk.agentId}] ${chunk.content}`);
+});
+// true only once the planner AND every agent it hired are idle
+```
+
+| Tool | Purpose |
+|---|---|
+| `agent-types` | List the kinds of agent this swarm can hire — description, ratings, how many are working, slots left. |
+| `agent-hire` | Spawn an agent of a type, optionally into a group and with a standing briefing. |
+| `agent-fire` | Release one of your own hires and free its slot. |
+| `agent-active` | List every hired agent — id, type, groups, parent, busy. |
+| `agent-prompt` | Hand a task to one of your hires; returns immediately, the answer arrives later as a report. |
+| `agent-report-parent` | Send a result to the agent that hired you, ending your turn. |
+| `agent-report-group` | Message your group's other members; your parent never sees it. |
+
+Which agent can do what is decided by its `allowedTools` — hiring tools for a planner, reporting tools for a worker — and agents themselves are written as reusable `AgentDefinition`s (the `Skill` idea, applied to agents) that you import rather than assemble.
+
+`DefaultAgents()` ships a pipeline, not just a list: the planner hires a **reasoner** (five personas arguing for a measured five minutes before answering), then a **backend** agent that must publish an API contract, then a **tester** that verifies that contract against the running server *before* it reaches anyone, then one to three **frontend** agents in a shared group who agree on the scaffold and claim files between themselves so they never overwrite each other, and finally a **tester** on the whole flow. Point the shared `MCPClient` at an [`MCPComputer`](./docs/mcp-architecture.md#mcpcomputer-sandboxed-execution) and all of that happens inside a container instead of on your machine. Full walkthrough in the [docs](./docs/swarm.md).
+
+## Available Skills
+
+A `Skill` bundles instructions with the tools that go with them. Passing a skill into an agent adds its tools automatically and folds its instructions into the system prompt.
+
+| Skill | Purpose |
+|---|---|
+| `PlannerSkill` | Stands up a persistent, checkable todo list for any large/multi-step/vague job so progress survives long conversations and context resets. |
+| `BigTaskSkill` | Keeps the agent from stopping short on large or ambitious jobs — no declaring victory on a partial slice, no handing a big job back half-finished. |
+| `LongTaskEfficiencySkill` | Keeps a long job efficient — batching, avoiding redundant reads, checkpointing, not gold-plating — without giving up on getting through the full scope. |
+| `NodeBackendSkill` | Building, running, and debugging Node.js backends: APIs, servers, CLIs, workers, schedulers, DB access layers — new or existing. |
+| `ReactFrontendSkill` | Building, running, and debugging modern React (`.tsx`/`.jsx`) projects, typically Vite-scaffolded — new or existing. |
+| `UiUxDesignSkill` | Visual and interaction design quality for any user-facing UI — layout, hierarchy, feedback states, accessibility, responsiveness. |
+| `BackendSecuritySkill` | Hardening server-side code that touches auth, sessions, tokens, uploads, DB queries, payments, or any trust boundary. |
+| `CodeVerificationSkill` | Running the right type checker/build/lint/test suite before handing code back, and telling real bugs apart from sandbox artifacts. |
+| `WebEndToEndTestSkill` | Testing a live web app like a real user would (fill, click, navigate) and verifying via the rendered page, console, and network — not by reading source and assuming. |
+| `ResearchSkill` | Answering questions that need real, current information from the live web — opens pages, cross-checks multiple sources, never trusts one page. |
+| `PresentSkill` | Deciding how to hand back a job's output as files (individually or zipped) and cleaning build artifacts out first. |
+
+## Building from the Base Agent
+
+For full control over the MCP server, connection, and client, compose an agent from the base primitives:
+
+```ts
+import {
+  OllamaProvider,
+  MCPConnection,
+  MCPServer,
+  MCPClient,
+  BaseAgent,
+  GetCurrentTimeTool,
+} from "orbitx";
+
+const ollamaProvider = new OllamaProvider("gemma4:e4b");
+
+const connection = new MCPConnection();
+
+const mcpServer = new MCPServer(connection);
+mcpServer.registerTool(GetCurrentTimeTool());
+
+const mcpClient = new MCPClient("DEFAULT_ENV", connection);
+
+const agent = new BaseAgent({
+  aiProvider: ollamaProvider,
+  instruction: "",
+  mcpClient,
+  allowedTools: [GetCurrentTimeTool()],
+});
+
+let oldRole: "assistant" | "tool" | "user" | undefined;
+
+agent.run("what is current time?", (chunk) => {
+  if (oldRole !== chunk.role) {
+    process.stdout.write(`\n${chunk.role}: `);
+    oldRole = chunk.role;
+  }
+  process.stdout.write(chunk.content);
+  if (chunk.done) {
+    process.stdout.write("\n\n");
+    oldRole = undefined;
+  }
+});
+```
+
+### IPC Connections
+
+Run your MCP server as a separate process and connect to it over an inter-process communication (IPC) channel:
+
+```ts
+import os from "os";
+import { MCPIPCConnection } from "orbitx";
+
+const path =
+  os.platform() === "win32" ? `\\\\.\\pipe\\mcp_test` : `/tmp/mcp_test.sock`;
+
+const ipcConnection = new MCPIPCConnection({ mode: "server", socketPath: path });
+```
+
+### WS Connections
+
+Run your MCP server as a separate process and connect to it over an web-socket communication (WS) channel:
+
+```ts
+import os from "os";
+import { MCPWSConnection } from "orbitx";
+
+const wsConnection = new MCPWSConnection({ mode: "server", host: "0.0.0.0", port: 9257, token: "1234" });
+```
+
+
+## Creating a Custom Tool
+
+Define your own tools with `MCPTool` to extend an agent's capabilities and integrate with your own ecosystem.
+
+```ts
+import { MCPTool } from "orbitx";
+
+export const SumTool = () => new MCPTool({
+  name: "math-sum",
+  description: "get two numbers and sum them",
+  inputs: [
+    {
+      name: "first",
+      type: "number",
+      description: "first number",
+      required: true,
+    },
+    {
+      name: "second",
+      type: "number",
+      description: "second number",
+      required: true,
+    },
+  ],
+  execute: async (_envID: string, inputs: Record<string, any>) => {
+    const { first, second } = inputs;
+
+    if (typeof first !== "number") {
+      throw new Error("first must be a number");
+    }
+    if (typeof second !== "number") {
+      throw new Error("second must be a number");
+    }
+
+    return { output: first + second };
+  },
+});
+```
+
+Use it like any built-in tool:
+
+```ts
+const agent = new SimpleAgent({
+  aiProvider: ollamaProvider,
+  instruction: "You are a helpful assistant.",
+  tools: [SumTool()],
+});
+```
+
+## Creating a Custom Skill
+
+A `Skill` bundles instructions with the tools it needs, so an agent that includes it automatically gets both.
+
+```ts
+import { Skill, FsReadFileTool, FsWriteFileTool } from "orbitx";
+import { SumTool } from "./sum-tool.js";
+
+export const MathHelperSkill = () => new Skill({
+  name: "math-helper",
+  description:
+    "Use this skill whenever the user asks for arithmetic that should be computed exactly " +
+    "rather than estimated from the model's own reasoning — sums, running totals, or " +
+    "anything written to a file afterward.",
+  instructions: `
+- Always use the math-sum tool for addition instead of computing it yourself.
+- If asked to save a result, write it to disk with fs-write-file and confirm the path back to the user.
+  `,
+  tools: [
+    SumTool(),
+    FsReadFileTool(),
+    FsWriteFileTool(),
+  ],
+});
+```
+
+```ts
+const agent = new SimpleAgent({
+  aiProvider: ollamaProvider,
+  instruction: "You are a helpful assistant.",
+  skills: [MathHelperSkill()],
+});
+```
+
+## MCPComputer (Experimental Feature)
+
+Spins up a sandboxed Docker container running the MCP server and returns a ready-to-use client connection — no need to manage IPC sockets, ports, or tokens manually.
+
+```typescript
+import { MCPComputer } from "orbitx";
+
+const computer = new MCPComputer("/path/to/mount", [3000, 8080]);
+await computer.start();
+
+const connection = computer.getConnection();
+await computer.stop();
+```
+
+- **`mountPath`**: host directory mounted into the container
+- **`ports`**: ports to expose, or `"*"` for host network mode (Linux only, or Windows via WSL2)
+- **`getConnection()`**: returns a ready `MCPConnection` (IPC on Linux/macOS, WebSocket on Windows)
+- **`stop()`**: kills the container
+
 Requires the `aliafsordeh/orbitx-sandbox:0.1` image (pull it, or build from the `Dockerfile.sandbox` reference on our GitHub page).