orbitx 0.2.1 → 0.2.4

package/docs/getting-started.md

@@ -0,0 +1,78 @@
+# Getting Started
+
+## Install
+
+```bash
+npm install orbitx
+```
+
+## Your first agent
+
+The fastest path is `SimpleAgent`: give it a provider, an instruction, and a list of tools/skills. It wires up an in-process MCP server/client for you automatically.
+
+```ts
+import { OllamaProvider, SimpleAgent, GetCurrentTimeTool } from "orbitx";
+
+const provider = new OllamaProvider("gemma4:e4b");
+
+const agent = new SimpleAgent({
+  aiProvider: provider,
+  instruction: "You are a helpful assistant.",
+  tools: [GetCurrentTimeTool()],
+});
+
+await agent.run("what is current time?", (chunk) => {
+  process.stdout.write(chunk.content);
+});
+```
+
+`agent.run(prompt, streamCallback)` resolves once the model has stopped calling tools and produced a final answer. The `streamCallback` is optional — omit it if you only care about the eventual message history via `getCurrentAgentStates()`.
+
+See [Streaming](./streaming.md) for the full chunk shape (roles, tool call/result chunks, `done` flag).
+
+## Choosing a provider
+
+```ts
+import { OllamaProvider, DeepSeekProvider, AnthropicProvider, OpenAIProvider } from "orbitx";
+
+new OllamaProvider("gemma4:e4b");                        // local, via Ollama
+new DeepSeekProvider("api-key", "deepseek-v4-flash");     // hosted
+new AnthropicProvider("api-key", "claude-sonnet-5");      // hosted
+new OpenAIProvider("api-key", "gpt-5");                   // hosted
+```
+
+Every provider implements the same `AIProvider` interface, so switching models is a one-line change to your agent's `aiProvider`. Details, capability flags, and the main/image role split are in [Providers](./providers.md).
+
+## Tools and skills up front
+
+`SimpleAgent`'s `tools` and `skills` lists are baked into the system prompt once, at construction time — there's no per-turn tool selection/routing step deciding what the model is allowed to see. If you want the model to be able to call something, put it in `tools` (or bundle it inside a `Skill`). See [Tools](./tools.md) and [Skills](./skills.md).
+
+## Recovering an agent's state
+
+`getCurrentAgentStates()` returns a plain JSON-serializable snapshot: message history, running memory summary, and token counters. Persist it anywhere; pass it back in as `initData` to resume the exact same agent later (after a process restart, in a new request handler, 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: provider,
+  instruction: "You are a helpful assistant.",
+  tools: [GetCurrentTimeTool()],
+  ...(initData ? { initData } : {}),
+});
+
+// after any run() call:
+writeFileSync("./state.json", JSON.stringify(agent.getCurrentAgentStates()));
+```
+
+Messages are only ever appended, never rewritten. When the conversation grows past the memory threshold, OrbitX keeps the full history on disk (`messagesFull`) but resets the model's *working* context from a running summary, so an agent can keep going indefinitely without losing the ability to act on what happened earlier. Mechanics are covered in [Agents](./agents.md#memory-compaction).
+
+## Next steps
+
+- Full control over the MCP transport (custom server/client, IPC, WebSocket, sandboxed Docker execution): [MCP Architecture](./mcp-architecture.md).
+- Writing your own tool or skill: [Tools](./tools.md#writing-a-custom-tool), [Skills](./skills.md#writing-a-custom-skill).
+- Every public export: [API Reference](./api-reference.md).

package/docs/index.md

@@ -0,0 +1,23 @@
+# OrbitX Docs
+
+OrbitX is a TypeScript SDK for building AI agents: pluggable model providers, a tool/skill system, an MCP-based execution layer (in-process, IPC, or WebSocket), and a resumable agent loop with automatic memory compaction.
+
+This directory is written for two audiences at once:
+
+- **Humans** learning the library for the first time — read top to bottom.
+- **AI coding agents** working inside a project that depends on `orbitx` — each page is self-contained enough to be read on its own when you only need one topic (e.g. "how do I define a tool").
+
+## Pages
+
+1. [Getting Started](./getting-started.md) — install, first agent, streaming output, resuming state.
+2. [Providers](./providers.md) — `AIProvider`, the four built-in providers, capabilities, main/image roles.
+3. [Agents](./agents.md) — `BaseAgent` vs `SimpleAgent`, the run loop, memory compaction, tokens, and multi-agent (`WorkerAgent`/`AgentTools`).
+4. [Tools](./tools.md) — the `MCPTool` shape, built-in tool catalog, writing your own tools.
+5. [Skills](./skills.md) — bundling instructions + tools, built-in skill catalog, writing your own.
+6. [MCP Architecture](./mcp-architecture.md) — `MCPServer`/`MCPClient`/connections, in-process vs IPC vs WS, `MCPComputer` sandbox.
+7. [Streaming](./streaming.md) — the `StreamCallback` chunk shape and how to consume it.
+8. [API Reference](./api-reference.md) — flat index of every public export from `orbitx`.
+
+## The shape of the library, in one paragraph
+
+You construct one or more `AIProvider` instances (OpenAI, Anthropic, DeepSeek, or Ollama), a list of `MCPTool`s and/or `Skill`s (a skill is just instructions + tools bundled together), and hand them to `SimpleAgent` (or `BaseAgent` for full control over the underlying MCP transport). Calling `agent.run(prompt, streamCallback)` drives a loop: send the conversation + tool schemas to the provider, dispatch any tool calls the model requests, feed results back, repeat until the model stops calling tools. Everything the model can see (tools, skills, instructions) is decided once, up front — there's no dynamic tool routing/selection step. Long conversations are handled by summarizing into a running `memory` string instead of ever deleting messages; the full history is preserved in `getCurrentAgentStates()` for persistence/resume.

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,151 @@
+# 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
+  supportsImages?: boolean;  // default: true only for deepseek-v4-flash-vision-exp
+  contextWindow?: number;    // default 1_000_000 (deepseek-v4-flash / deepseek-v4-flash-vision-exp / 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). `getCapabilities().supportsImages` is `false` for every model except `deepseek-v4-flash-vision-exp`, which is `deepseek-v4-flash` plus native image input (same context window, same reasoning support) — pass `supportsImages: true` explicitly if a future model adds vision support before this SDK's allowlist is updated.
+
+Token usage (`inputTokens`/`outputTokens`) is only accurate on the non-streaming path (`chat()` called without `streamCallback`), which reads `response.usage` directly. On the streaming path this provider deliberately does not set `stream_options: { include_usage: true }`, so DeepSeek never sends a usage-bearing chunk and both counts report as `0`. This matters most for `ImageDescriber`, which always calls `chat()` without a `streamCallback` (see [Token accounting](./agents.md#token-accounting)) — so image-description usage is captured correctly even though live agent streaming isn't.
+
+### 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.