orbitx 0.2.1 → 0.2.3

package/docs/mcp-architecture.md

@@ -0,0 +1,103 @@
+# MCP Architecture
+
+OrbitX's tool execution layer is built around a small client/server protocol (called "MCP" in this codebase — not to be confused with Anthropic's separate Model Context Protocol spec; it's an internal naming choice). It exists to decouple *where tools run* from *where the agent loop runs* — the same `MCPTool` definitions work whether they execute in the same process, in a separate process over a Unix socket / named pipe, over a WebSocket, or inside a sandboxed Docker container.
+
+`SimpleAgent` hides all of this behind an in-process connection. Reach for these primitives directly only when you need one of the other transports.
+
+## The three pieces
+
+```
+MCPServer  — owns the registered tools, actually executes them
+MCPClient  — what BaseAgent calls; sends tool invocations to a server, returns results
+MCPConnection — the transport wiring a client to a server (in-process, IPC, or WS)
+```
+
+### `MCPServer`
+
+```ts
+new MCPServer(connection: MCPConnection, storage?: MCPStorage, rng?: MCPRNG);
+mcpServer.registerTool(tool: MCPTool<any>): void;
+```
+
+Registers tools and listens on its `connection` for incoming tool-call requests, executing them and sending results back. Defaults to `MCPFSStorage` (filesystem-backed key/value storage — see below) if no `storage` is given.
+
+### `MCPClient`
+
+```ts
+new MCPClient(envID: string, connection: MCPConnection | MCPConnection[], storage?: MCPStorage, rng?: MCPRNG, mcpFilter?: MCPFilter);
+mcpClient.getTools(): Promise<ToolSchema[]>;
+mcpClient.callTool(name: string, inputs: Record<string, any>): Promise<MCPToolOutput>;
+```
+
+This is what you pass into `BaseAgent({ mcpClient, ... })`. `envID` scopes storage/RNG state per logical environment/session — pass a stable id (e.g. a user or conversation id) if you want isolated tool state per agent instance sharing a server. Accepting an array of connections lets one client fan out across multiple servers.
+
+`mcpFilter` (an `MCPFilter`) redacts sensitive substrings/patterns from tool output before it reaches the model — see [`MCPFilter`](#mcpfilter-redacting-tool-output) below.
+
+#### Registering tools directly on the client (bypassing the connection)
+
+`MCPClient` also has its own `registerTool(tool: MCPTool<any>)`, separate from `MCPServer.registerTool()`. A tool registered on the client executes locally, on whatever machine/process the client itself is running in — it never crosses the connection to the remote server at all. `callTool()` checks the client's own tool list first, and only falls back to sending the call across the connection if no local match is found; `getTools()` merges both lists the same way (a client-registered tool shadows a same-named server tool).
+
+This matters when you're using `MCPIPCConnection`/`MCPWSConnection`/`MCPComputer` to run most tools inside a separate process or sandbox: routing every single call across that boundary adds latency for tools that don't need the isolation. If a tool is cheap and can't do any harm (e.g. `GetCurrentTimeTool`, a pure computation like the `SumTool` example in [Tools](./tools.md#writing-a-custom-tool)), register it directly on the `MCPClient` instead of the sandboxed `MCPServer` — it still shows up to the model exactly like any other tool, it just answers immediately from the host process instead of round-tripping through IPC/WS/Docker. Keep anything that touches the filesystem, shell, or network on the sandboxed server side, where `MCPComputer`'s isolation actually protects you.
+
+### `MCPConnection` and its variants
+
+- **`MCPConnection`** (base/in-process) — tools run in the same process as the agent. What `SimpleAgent` uses internally; you'd construct one directly only when composing `BaseAgent` by hand (see the README's "Building from the Base Agent" example).
+- **`MCPIPCConnection`** — connects client and server across two processes over a named pipe (Windows) or Unix domain socket (`socketPath`), with `mode: "server" | "client"` on each side:
+
+  ```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 });
+  ```
+
+- **`MCPWSConnection`** — connects over a WebSocket, optionally with a shared `token` for auth and `tls: { key, cert, ca? }` for WSS:
+
+  ```ts
+  import { MCPWSConnection } from "orbitx";
+
+  const wsConnection = new MCPWSConnection({ mode: "server", host: "0.0.0.0", port: 9257, token: "1234" });
+  ```
+
+  Client-mode options use `url` instead of `host`/`port`. Both IPC and WS auto-reconnect on disconnect (`reconnectDelay`, default 500ms).
+
+## `MCPComputer` — sandboxed execution *(experimental)*
+
+Spins up a Docker container running an MCP server and hands you back a ready-to-use connection — no manual socket/port/token wiring. This is the recommended way to let an agent run filesystem/bash tools without risking the host machine.
+
+```ts
+import { MCPComputer } from "orbitx";
+
+const computer = new MCPComputer("/path/to/mount", [3000, 8080]);
+await computer.start();
+
+const connection = computer.getConnection();
+// ... build MCPClient/MCPServer/BaseAgent around `connection` as usual ...
+await computer.stop();
+```
+
+- `mountPath` — host directory mounted into the container (this is what filesystem tools inside the sandbox actually touch).
+- `ports` — ports to expose from the container, or `"*"` for host network mode (Linux only, or Windows via WSL2).
+- `getConnection()` — returns a ready `MCPConnection`: IPC on Linux/macOS, WebSocket on Windows (auth token generated automatically).
+- `stop()` — kills the container.
+
+Requires the `aliafsordeh/orbitx-sandbox:0.1` image (pull it, or build it yourself from the `Dockerfile.sandbox` at the repo root).
+
+## Storage and RNG
+
+- **`MCPStorage`** — abstract `{ get(key): Promise<string>; set(key, value): Promise<void> }`. `MCPFSStorage` is the default filesystem-backed implementation (`new MCPFSStorage(path?)`, defaults to a randomly-named folder under `./data`). `MCPStorage` and `MCPFSStorage` are both exported if you want to implement your own backend (Redis, a database, etc.) or point the default one at a specific path.
+- **`MCPRNG`** — deterministic-ish id generator backed by an `MCPStorage` instance (used internally for things like `generateRefId()`, the helper behind ref ids in `BrowserReadTool`'s output).
+
+## `MCPFilter` — redacting tool output
+
+```ts
+new MCPFilter(values: (string | RegExp)[]);
+mcpFilter.filter(input: any): any;   // replaces every match with "FILTERED_OUTPUT"
+```
+
+Pass literal strings (e.g. an API key you never want echoed back to the model) or regexes (e.g. `/sk-[a-zA-Z0-9]{20,}/`) as the `mcpFilter` argument to `MCPClient` to scrub tool output before it's returned — useful when a tool might read a file or environment variable containing a secret.
+
+## Custom `MCP` subclasses
+
+Both `MCPServer` and `MCPClient` extend the abstract `MCP` class (`getStorage()`, `getRNG()`). Tool `execute` functions receive the calling `MCP` instance as their third argument, so a custom `MCPCustomClass`-based tool (see [Tools](./tools.md#the-mcptool-shape)) can reach storage/RNG scoped to whichever client dispatched the call.

package/docs/providers.md

@@ -0,0 +1,148 @@
+# Providers
+
+An `AIProvider` is OrbitX's abstraction over a model API. All four built-in providers implement the same interface (`src/core/ai-provider.ts`):
+
+```ts
+abstract class AIProvider {
+  abstract chat(
+    messages: Message[],
+    streamCallback?: StreamCallback,
+    tools?: ToolSchema[]
+  ): Promise<ChatResponse>;
+
+  abstract getCapabilities(): ProviderCapabilities;
+}
+```
+
+- `chat` sends the full message history (plus a provider-agnostic `tools` schema, when supplied) and returns a `ChatResponse` (`{ content, inputTokens, outputTokens, toolCalls? }`). If `streamCallback` is passed, text is streamed to it incrementally as it arrives — see [Streaming](./streaming.md).
+- `getCapabilities()` returns a static description used by `BaseAgent` to decide things like when to trigger memory compaction — it is **not** re-queried per call:
+
+```ts
+interface ProviderCapabilities {
+  supportsTools: boolean;     // must be true — BaseAgent requires native tool-calling
+  supportsImages: boolean;    // whether this provider/model accepts image content
+  contextWindow: number;      // total context window, in tokens
+  safeUsageRatio?: number;    // fraction of contextWindow safe to fill before compacting (default 0.5)
+}
+```
+
+`BaseAgent.run()` throws immediately if `getCapabilities().supportsTools` is `false` — the legacy JSON-in-text tool-call convention has been removed from the main loop. All providers default `supportsTools` to `true` except Ollama, which defaults it to `false` (many locally-hosted models don't support native function calling; pass `{ supportsTools: true }` explicitly if your model does).
+
+## Think effort
+
+Reasoning/thinking models each expose a different native "how hard should the model think" knob — OpenAI and Ollama use `low`/`medium`/`high`, DeepSeek uses `none`/`low`/`high`/`max`, Anthropic uses a numeric thinking-token budget. OrbitX replaces all of that with one universal option on every provider's constructor:
+
+```ts
+thinkEffort?: number;   // 0-1, e.g. 0.5 or 0.8 — never a provider-specific string
+```
+
+Each provider maps that 0-1 value onto whatever scale it actually accepts (`src/core/think-effort.ts`'s `resolveThinkEffortLevel()` buckets it evenly across a provider's supported levels; Anthropic instead scales it into a `budget_tokens` range). A provider or model that doesn't support thinking at all — or doesn't recognize the resulting native value — simply ignores it:
+
+```ts
+import { AnthropicProvider, DeepSeekProvider } from "orbitx";
+
+const anthropicProvider = new AnthropicProvider("api-key", "claude-sonnet-5", { thinkEffort: 0.7 });
+const deepseekProvider = new DeepSeekProvider("api-key", "deepseek-v4-flash", { thinkEffort: 0.3 });
+```
+
+Per-provider specifics:
+
+| Provider | Native scale | Notes |
+|---|---|---|
+| Anthropic | `thinking.budget_tokens` (numeric) | Scales with `maxTokens`; `max_tokens` sent to the API is automatically bumped so it always exceeds the thinking budget. Signed thinking blocks are carried forward automatically via `Message.providerThinking` when a thinking turn also made a tool call — required by Anthropic's API, handled for you. |
+| DeepSeek | `none` / `low` / `high` / `max` | Sent as `reasoning_effort` on reasoner models. |
+| OpenAI | `low` / `medium` / `high` | Sent as `reasoning_effort`, and **only** for reasoning-capable model families (`o1`/`o3`/`o4`/`gpt-5*` prefixes) — silently ignored for every other model, since the Chat Completions API rejects the param on non-reasoning models. |
+| Ollama | `false` / `low` / `medium` / `high` | `thinkEffort <= 0` maps to `false` (works as an on/off switch for models that only understand a boolean, e.g. deepseek-r1/qwen3); higher values map to a level string for models that support graded effort (e.g. gpt-oss). |
+
+See [Streaming](./streaming.md#thinking-chunks) for how (and whether) a given provider's reasoning text is observable while it streams.
+
+## Built-in providers
+
+### Ollama
+
+```ts
+import { OllamaProvider } from "orbitx";
+
+new OllamaProvider(model: string, host = "http://localhost:11434", options?: {
+  supportsTools?: boolean;   // default false
+  contextWindow?: number;    // default 32_000
+  thinkEffort?: number;      // 0-1, see "Think effort" above
+});
+```
+
+Wraps the `ollama` npm package, talking to a local (or remote) Ollama server. Always reports `supportsImages: true`.
+
+### DeepSeek
+
+```ts
+import { DeepSeekProvider } from "orbitx";
+
+new DeepSeekProvider(apiKey: string, model = "deepseek-v4-flash", options?: {
+  supportsTools?: boolean;   // default true
+  contextWindow?: number;    // default 1_000_000 (deepseek-v4-flash / deepseek-v4-pro)
+  thinkEffort?: number;      // 0-1, see "Think effort" above
+});
+```
+
+Uses the `openai` SDK pointed at `https://api.deepseek.com` (DeepSeek's API is OpenAI-compatible). Always reports `supportsImages: false`.
+
+### Anthropic
+
+```ts
+import { AnthropicProvider } from "orbitx";
+
+new AnthropicProvider(apiKey: string, model = "claude-sonnet-5", options?: {
+  supportsTools?: boolean;    // default true
+  supportsImages?: boolean;   // default true
+  contextWindow?: number;     // default from a per-model table, else 200_000
+  maxTokens?: number;         // output token cap, default 4096
+  thinkEffort?: number;       // 0-1, see "Think effort" above
+});
+```
+
+Wraps `@anthropic-ai/sdk`. `maxTokens` is the only provider with an explicit output-length cap in its options today.
+
+### OpenAI
+
+```ts
+import { OpenAIProvider } from "orbitx";
+
+new OpenAIProvider(apiKey: string, model = "gpt-5", options?: {
+  supportsTools?: boolean;    // default true
+  supportsImages?: boolean;   // default true unless model is in a small denylist (e.g. o3-mini, o1-mini)
+  contextWindow?: number;     // default from a per-model table, else 128_000
+  baseURL?: string;           // point at an OpenAI-compatible endpoint
+  thinkEffort?: number;       // 0-1, see "Think effort" above — ignored on non-reasoning models
+});
+```
+
+Uses the Chat Completions API (not the Responses API). `baseURL` makes this usable against any OpenAI-compatible provider, not just OpenAI itself.
+
+## Two provider roles: main + image
+
+An agent has exactly two provider "roles":
+
+- **`main`** — drives the agent loop itself (required).
+- **`image`** — describes image tool output (e.g. a screenshot from `BrowserScreenshotTool`) into text, so the main conversation doesn't have to carry raw image bytes. Optional.
+
+Pass a single provider to use it for both roles (if it supports images, it's also used as the image describer; otherwise images are dropped with an explanatory error message back to the model). Pass 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: [/* ... */],
+});
+```
+
+This resolution is done by `resolveAgentProviders()` (`AgentProvidersInput = AIProvider | AgentProviderEntry[]`), exported from `orbitx` if you need it directly. There is no third "utils" role — every tool/skill is included in the system prompt from the start, so there's nothing left for a separate pass to decide.
+
+## Writing a custom provider
+
+Extend `AIProvider` and implement `chat`/`getCapabilities`. Follow an existing provider (e.g. `src/core/ollama-provider.ts`) as a template: translate `Message[]` to your API's wire format, stream text chunks to `streamCallback` as they arrive, accumulate tool-call deltas and emit them on the final chunk, and translate `ToolSchema[]` into your API's function-calling format (see `src/core/tool-schema-translator.ts` for existing OpenAI/Anthropic translators you can reuse or reference).

package/docs/skills.md

@@ -0,0 +1,68 @@
+# Skills
+
+A `Skill` bundles instructions with the tools those instructions depend on, so including the skill in an agent gets you both at once — the tools are auto-registered, and the instructions are folded into the system prompt under a `SKILLS:` block.
+
+```ts
+class Skill {
+  constructor(skill: {
+    name: string;
+    description: string;
+    instructions: string;
+    tools: MCPTool<any>[];
+  });
+  getSkill(): { name; description; instructions; tools };
+}
+```
+
+`description` is shown alongside `instructions` in the system prompt (`${name} - ${description}` followed by the instructions text) — write it as a short "when to use this" pointer, since it's the model's first signal for whether the skill is relevant to the current task.
+
+## Built-in skills
+
+| Skill | Purpose |
+|---|---|
+| `PlannerSkill` | Stands up a persistent, checkable todo list (via `TodoTools`) 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 — 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. |
+| `ReactFrontendSkill` | Building, running, and debugging modern React (`.tsx`/`.jsx`) projects, typically Vite-scaffolded. |
+| `UiUxDesignSkill` | Visual and interaction design quality for 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. |
+| `ResearchSkill` | Answering questions that need real, current information from the live web — cross-checks multiple sources. |
+| `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 — pairs with `PresentTools`. |
+| `QuestionAnswerSkill` | Pausing to ask the user for missing information, a decision, or confirmation before continuing, instead of guessing — batches every pending question into one call and stops the turn immediately after asking (`QuestionAnswerTool` sets `stopIterationAfterUsingThisTool`). |
+| `QuestionAnswerSkill` | Wraps `QuestionAnswerTool` with instructions for when it's appropriate to stop and ask the human operator a clarifying question. |
+
+Each of these lives in its own file under `src/skills/` and is a plain factory function (`PlannerSkill()`), same convention as tools.
+
+## Writing a custom skill
+
+```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: provider,
+  instruction: "You are a helpful assistant.",
+  skills: [MathHelperSkill()],
+});
+```
+
+If a tool is already passed in `tools` *and* included inside a skill, `SimpleAgent` de-duplicates it — you won't get it registered twice. If you're building on `BaseAgent` directly instead, remember `allowedTools` and each skill's `tools` are two separate lists that both need to reach the same `MCPServer` registration — `SimpleAgent`'s constructor is the reference implementation for getting this wiring right.

package/docs/streaming.md

@@ -0,0 +1,116 @@
+# Streaming
+
+`agent.run(prompt, streamCallback)` and `AIProvider.chat(messages, streamCallback, tools)` both accept an optional `StreamCallback`:
+
+```ts
+type StreamCallback = (chunk: {
+  role: "assistant" | "tool" | "user";
+  content: string;
+  done: boolean;
+  toolCalls?: ToolCallRequest[];  // a single just-finished call, as a 1-element array — see "Incremental tool-call chunks" below
+  toolCallId?: string;            // on "tool"-role chunks
+  toolName?: string;              // on "tool"-role chunks
+  thinking?: string;               // reasoning-text delta, mirroring `content` — see "Thinking chunks" below
+}) => Promise<void> | void;
+```
+
+## What you actually receive, turn by turn
+
+1. **`role: "user"`** — one chunk, `done: true`, echoing the prompt that was just added to history (either the one you passed to `run()`, or a queued one — see [Agents](./agents.md#the-run-loop)).
+2. **`role: "assistant"`** — the model's reply, streamed incrementally: zero or more `done: false` chunks each carrying the next slice of `content` as it arrives from the provider, followed by one final `done: true` chunk. `content` is delta text, not the accumulated total — append it yourself if you need the running message.
+   - If the model requested tool calls this turn, each one is emitted individually, mid-stream, as soon as *that* call finishes generating — `toolCalls: [thatOneCall]` on a `done: false` chunk. See "Incremental tool-call chunks" below.
+3. **`role: "tool"`** — one chunk per dispatched tool call, `done: true`, with `content` set to the tool's result text and `toolCallId`/`toolName` identifying which call it answers. Emitted after the tool has actually finished executing (there is no streaming/progress signal for tool execution itself through this callback — see below for how to get that separately).
+
+A full run of "call one tool, then answer" therefore looks like:
+
+```
+{ role: "user", content: "<prompt>", done: true }
+{ role: "assistant", content: "<partial>", done: false }   // repeated
+{ role: "assistant", content: "", done: false, toolCalls: [{...}] }
+{ role: "assistant", content: "", done: true }
+{ role: "tool", content: "<result>", done: true, toolCallId, toolName }
+{ role: "assistant", content: "<partial>", done: false }   // repeated
+{ role: "assistant", content: "", done: true }
+```
+
+Note the final `done: true` chunk for the tool-call turn carries no `toolCalls` — every call this turn was already streamed individually by the time it arrives, so resending the full list would just be a duplicate. If you need the complete, aggregated list for a turn (e.g. you're driving `AIProvider.chat()` directly rather than going through `agent.run()`), it's on the returned `ChatResponse.toolCalls` instead — see below.
+
+## Incremental tool-call chunks
+
+Deciding *whether* to call a tool and building its arguments is itself something the model streams token by token — so as soon as one call's arguments are fully generated, that call is emitted on its own as `toolCalls: [thatOneCall]`, without waiting for the rest of the turn (more tool calls, or trailing text) to finish too. This is purely observational: it exists so a consumer can show "the model just decided to call `X`" the moment it happens.
+
+**It does not change when a tool actually runs.** Dispatch is still all-or-nothing at the end of the turn: `BaseAgent` only executes tool calls after `AIProvider.chat()` fully resolves and returns the complete `ChatResponse.toolCalls` array — nothing is ever called early just because its single-call chunk arrived first. If you want to reconcile the two: the incremental `toolCalls: [...]` chunks tell you a call was *decided*, in the order the model produced them; the eventual `role: "tool"` result chunks tell you a call was *executed*, in whatever order `BaseAgent` dispatches them.
+
+Detection differs by provider, since not every API has an explicit "this call is done" signal:
+
+| Provider | How completion is detected |
+|---|---|
+| Anthropic | Native `content_block_stop` event — exact and immediate. |
+| OpenAI / DeepSeek | Inferred: the API streams one call's arguments at a time with no end marker, so a call is treated as finished the instant the *next* call's first delta (carrying a fresh `id`) arrives, or the stream ends (for the last/only call). |
+| Ollama | Ollama sends each tool call already fully formed (not built up token by token), so it's emitted the moment it's seen — deduplicated in case the same call reappears in a later chunk. |
+
+## Minimal consumer
+
+```ts
+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;
+  }
+
+  if (chunk.thinking) {
+    process.stdout.write(`\x1b[2m${chunk.thinking}\x1b[0m`); // dim, to visually separate it from the answer
+  } else {
+    process.stdout.write(chunk.content);
+  }
+
+  if (chunk.toolCalls?.length) {
+    console.log("decided to call:", chunk.toolCalls[0]);
+  }
+  if (chunk.role === "tool") {
+    console.log({ toolCallId: chunk.toolCallId, toolName: chunk.toolName });
+  }
+
+  if (chunk.done) {
+    process.stdout.write("\n\n");
+    oldRole = undefined;
+  }
+});
+```
+
+## Thinking chunks
+
+When a provider is constructed with `thinkEffort` (see [Providers](./providers.md#think-effort)) and it can actually surface reasoning text (`getCapabilities().supportsThinking`), that text streams incrementally too — as `role: "assistant"` chunks carrying their delta on `thinking` instead of `content`, interleaved *before* the model's normal answer chunks in the same turn:
+
+```
+{ role: "assistant", content: "", done: false, thinking: "<reasoning...>" }   // repeated
+{ role: "assistant", content: "<answer...>", done: false }                    // thinking absent from here on
+{ role: "assistant", content: "", done: true }
+```
+
+`thinking` mirrors `content`: a chunk carries text on exactly one of the two, never both, and `thinking` is only ever present on non-`done` chunks — the final `done: true` chunk never carries it. Once accumulated, the full reasoning text for the turn is also available non-streaming on `ChatResponse.thinking` / `Message.thinking` (e.g. for logging or persisting alongside the answer).
+
+Support varies by provider — set `thinkEffort` and check `getCapabilities().supportsThinking` before assuming thinking chunks will actually arrive:
+
+| Provider | Streams `thinking` chunks? |
+|---|---|
+| Anthropic | Yes — native `thinking_delta` events. |
+| DeepSeek | Yes — `delta.reasoning_content` on reasoner models. |
+| Ollama | Yes — `message.thinking` on models that support it. |
+| OpenAI | **No.** `thinkEffort` is still honored server-side (via `reasoning_effort`) on reasoning-capable models, but the Chat Completions API this provider uses never returns the reasoning text itself — there's nothing to stream. |
+
+### `thinking` vs `providerThinking` on `Message`/`ChatResponse`
+
+Once a turn finishes, its accumulated reasoning is available two ways on both `ChatResponse` (returned from `AIProvider.chat()`) and `Message` (as stored in an agent's history):
+
+- **`thinking?: string`** — the plain reasoning text, for display or logging. Never required by any provider's API; read-only from your side.
+- **`providerThinking?: any[]`** — opaque, provider-specific data (currently only Anthropic populates this: signed `thinking` content blocks). When a turn both thinks and calls a tool, Anthropic's API requires the exact signed thinking block(s) from that turn to be replayed verbatim on the next request or it rejects the call. `BaseAgent` carries this field through automatically when it builds the next turn's message history, so if you're using `BaseAgent`/`SimpleAgent` you never touch it directly. It only matters if you're driving an `AIProvider` yourself (see [Providers](./providers.md)) — in that case, copy `providerThinking` from the response straight onto the `Message` you push for that assistant turn, unchanged.
+
+## What's *not* in the stream today
+
+- **No live per-tool progress channel through `StreamCallback`.** For domains that emit their own progress (browser navigation, long-running bash processes), subscribe to that domain's `*Interaction` `EventEmitter` directly instead (e.g. `BrowserInteraction`, `BashInteraction`) — see [Tools](./tools.md).
+- **Tool calls still only appear once, fully assembled** — see above. `thinkEffort`/thinking chunks don't change that.
+
+If your use case depends on either of these, check the project's issue tracker / recent changes before assuming they're unavailable — this area of the SDK is actively evolving.

package/docs/tools.md

@@ -0,0 +1,174 @@
+# Tools
+
+## The `MCPTool` shape
+
+Every tool — built-in or custom — is an `MCPTool` instance (`src/core/mcp.ts`):
+
+```ts
+new MCPTool({
+  name: string;
+  description: string;
+  inputs: {
+    name: string;
+    type: "number" | "string" | "boolean" | "object" | "array";
+    description: string;
+    required?: boolean;
+    default?: any;
+  }[];
+  stopIterationAfterUsingThisTool?: boolean;   // default false
+  customClass?: MCPCustomClass;                // optional stateful helper, see below
+  execute: (
+    envID: string,
+    inputs: Record<string, any>,
+    mcp?: MCP,
+    customClass?: typeof customClass
+  ) => Promise<any>;
+});
+```
+
+- `inputs` doubles as both the JSON-schema-like description sent to the model (translated per-provider by `src/core/tool-schema-translator.ts`) and the shape `execute` should expect on `inputs`.
+- `stopIterationAfterUsingThisTool: true` ends the agent's run loop immediately after this tool fires, even if the model didn't naturally stop calling tools — useful for a "final answer" or "hand off" style tool.
+- `execute`'s return value is normalized via `normalizeToolOutput()` into either `{ type: "text", output: {...} }` or `{ type: "image", output: { image, mimeType, ... } }`. Return `{ type: "image", output: {...} }` explicitly to hand back an image (it gets routed through the agent's image provider — see [Providers](./providers.md#two-provider-roles-main--image)); anything else is treated as a plain JSON text result.
+- `envID` identifies which "environment" (in-process client id, IPC/WS session) the call came from — most tools ignore it unless they need per-environment isolated state (see `MCPStorage`/`MCPFSStorage` in [MCP Architecture](./mcp-architecture.md)).
+- `customClass` (a subclass of `MCPCustomClass`) is a way to give a tool its own persistent helper object with access to the owning `MCP` instance (`getMCP()`) and an `EventEmitter` (`getEvents()`) for progress/status events — see how the built-in `*Interaction` classes are used (e.g. `FsInteraction`, `BrowserInteraction`) if you want to expose live progress to a UI. **Experimental:** `customClass` is still settling — its name and shape may change (or it may be removed) in a future release, so avoid depending on it for anything beyond the built-in `*Interaction` pattern until it stabilizes.
+
+Tools are registered on an `MCPServer` and invoked through an `MCPClient`; `SimpleAgent` does this wiring for you from a flat `tools` array.
+
+## Built-in tool catalog
+
+Import a whole domain's tools at once (e.g. `FsTools()`), or import individual tools by name. Every domain also exports a `*Interaction` `EventEmitter` for subscribing to that domain's live progress events (e.g. `FsInteraction`, `BashInteraction`).
+
+### Filesystem — `FsTools()`
+
+> ⚠️ `FsWriteFileTool` and `FsDeleteTool` can permanently overwrite, delete, or corrupt existing files — no undo. Prefer routing filesystem access through `MCPComputer`'s sandbox (see [MCP Architecture](./mcp-architecture.md#mcpcomputer-sandboxed-execution)) to protect the host system.
+
+| 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()`
+
+> ⚠️ Shell commands can permanently delete files, corrupt data, modify system settings, or execute harmful operations — no undo. Same sandboxing recommendation as above.
+
+| 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. |
+| `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()`
+
+Backs the `PlannerSkill` (see [Skills](./skills.md)), but usable standalone.
+
+| 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. |
+
+### Question / answer — `QuestionAnswerTools()`
+
+| Tool | Purpose |
+|---|---|
+| `QuestionAnswerTool` | Ask the human operator a clarifying question and wait for their answer. |
+
+### 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(availableAgents, options?)` *(experimental)*
+
+**Experimental** — see the note in [Agents](./agents.md#multi-agent-workeragent-experimental).
+
+Unlike every other domain above, this one takes parameters: a fixed roster of `WorkerAgent` instances (see [Agents](./agents.md#multi-agent-workeragent-experimental)) you build ahead of time, and an optional `{ maxHired?: number }` cap on how many can be hired at once. Give the result to your **planner** agent.
+
+| Tool | Purpose |
+|---|---|
+| `agent-list` | List every worker in the roster — name, description, rating, and hired status. Also returns `hiredCount` and (when set) `maxHired`. |
+| `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. |
+
+`AgentReportTool` is a separate, standalone factory in the same module — put it on each **worker's own** tool list instead (not the planner's), so a worker can hand a result back and end its turn. See [Agents](./agents.md#agent-report--for-workers-not-the-planner) for the full walkthrough.
+
+## Writing a custom tool
+
+```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 exactly like a built-in tool:
+
+```ts
+const agent = new SimpleAgent({
+  aiProvider: provider,
+  instruction: "You are a helpful assistant.",
+  tools: [SumTool()],
+});
+```
+
+Conventions worth following, based on the built-in tools:
+- Export a **factory function** (`SumTool()`), not the `MCPTool` instance itself — this keeps each agent's tool list made of fresh instances.
+- Throw inside `execute` for invalid input rather than returning an error object — thrown errors are caught by `BaseAgent` and turned into a `Error: ...` result the model sees, which is usually what you want.
+- Keep `description` and each input's `description` written for the model, not for a human reader of your source — they go straight into the tool schema.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orbitx",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "An AI SDK providing agents, swarms, planners, skills, MCP tools, workflows, and multi-provider AI integrations.",
   "repository": {
     "type": "git",
@@ -22,7 +22,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "scripts": {
     "build": "tsc",
@@ -54,4 +55,4 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3"
   }
-}
+}