orbitx 0.2.9 → 0.3.0

package/docs/getting-started.md

@@ -1,78 +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 (each message carrying its own token usage) and running memory summary. 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 retires the working context into `retiredMessages` and resets the model's *active* context (`messagesCompact`) from a running summary (`compactMemory`), so an agent can keep going indefinitely without losing the ability to act on what happened earlier — nothing on disk is ever deleted, it just moves from one array to the other. 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).
+# 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 (each message carrying its own token usage) and running memory summary. 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 retires the working context into `retiredMessages` and resets the model's *active* context (`messagesCompact`) from a running summary (`compactMemory`), so an agent can keep going indefinitely without losing the ability to act on what happened earlier — nothing on disk is ever deleted, it just moves from one array to the other. 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

@@ -1,23 +1,24 @@
-# 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.
+# 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.
+4. [Swarm](./swarm.md) — many agents that hire, task, and report to each other: `SwarmBase`, `AgentDefinition`, `getAgentTools()`.
+5. [Tools](./tools.md) — the `MCPTool` shape, built-in tool catalog, writing your own tools.
+6. [Skills](./skills.md) — bundling instructions + tools, built-in skill catalog, writing your own.
+7. [MCP Architecture](./mcp-architecture.md) — `MCPServer`/`MCPClient`/connections, in-process vs IPC vs WS, `MCPComputer` sandbox.
+8. [Streaming](./streaming.md) — the `StreamCallback` chunk shape and how to consume it.
+9. [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

@@ -30,7 +30,7 @@ mcpClient.callTool(name: string, inputs: Record<string, any>, toolCallId?: strin
 mcpClient.setExecuteProviderHandler(handler: (toolCallId: string, type: ProviderType, input: Record<string, any>) => Promise<{ output: Record<string, any> }>): void;
 ```
 
-`toolCallId` on `callTool()` and the handler installed via `setExecuteProviderHandler()` are what `BaseAgent` wires up automatically so `mcp.executeProvider(...)` works inside a tool's `execute()` — see [Custom `MCP` subclasses](#custom-mcp-subclasses) below. You don't need to call either yourself unless you're driving `MCPClient` outside of `BaseAgent`.
+`toolCallId` on `callTool()` and the handler installed via `setExecuteProviderHandler()` are what `BaseAgent` wires up automatically so `mcp.executeProvider(...)` works inside a tool's `execute()` — see [Custom `MCP` subclasses](#custom-mcp-subclasses) below. You don't need to call either yourself unless you're driving `MCPClient` outside of `BaseAgent`. A `SwarmBase` takes that handler back after building each agent, so in a swarm the provider call is answered by the swarm — see [Swarm](./swarm.md#providers-a-tool-reaches-for).
 
 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.
 
@@ -82,12 +82,35 @@ const connection = computer.getConnection();
 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.
+```ts
+new MCPComputer(mountPath: string, ports: number[] | "*", image?: string, options?: MCPComputerOptions);
+```
+
+- `mountPath` — host directory mounted into the container (this is what filesystem tools inside the sandbox actually touch). Four subdirectories are created under it and mounted: `workspace`, `mcp-server-storage`, `presents`, `user-inputs`.
+- `ports` — ports to publish from the container, or `"*"` for host network mode. **`"*"` is Linux-only**: on Windows and macOS the container joins a VM's network namespace, so nothing it binds is reachable from your machine and published ports are ignored — the constructor throws rather than letting that surface later as a connection timeout.
+- `image` — defaults to `aliafsordeh/orbitx-sandbox:0.2`.
+- `start()` — verifies the Docker daemon is reachable, prepares the mount, launches the container, waits for its ready log, and then waits for the connection endpoint to actually accept traffic. It resolves only when the sandbox is genuinely reachable, and rejects with the container's own output when it is not.
+- `getConnection(wsHost?)` — returns a ready `MCPConnection`, cached (repeated calls hand back the same object). In `"ws"` mode it must be called after `start()`, since the port is only chosen there.
+- `waitUntilConnected(timeoutMs?)` — optional; resolves once the transport is carrying traffic, if you want the MCP handshake up before the first tool call.
+- `getPresentsHostPath()`, `getConnectionPort()`, `getContainerName()`, `isRunning()` — host-side accessors.
+- `stop()` — removes the container, closes the connection, and cleans up the socket directory. Idempotent.
+
+`MCPComputerOptions`:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `connectionMode` | `"ipc"` on Linux, `"ws"` elsewhere | Transport between your process and the sandbox. |
+| `readyTimeoutMs` | `60_000` | Wait for the sandbox's ready log once the container is running. |
+| `pullTimeoutMs` | `300_000` | Inactivity budget while docker pulls the image, so a first run isn't killed mid-download. |
+| `handshakeTimeoutMs` | `20_000` | Wait for the endpoint to accept traffic after the ready log. |
+| `onLog` | — | `(line, "stdout" \| "stderr") => void`; receives everything the container writes. |
+| `dockerBin` | `"docker"` | Override the executable (e.g. `"podman"`, or an absolute path). |
+
+The transport default is not a style choice: Docker Desktop on Windows and macOS runs the daemon inside a VM and shares the mount over a network filesystem, which cannot carry a unix-domain socket. IPC therefore only works when the daemon and your process share a kernel, and WebSocket (loopback-published, with an auto-generated auth token) is used everywhere else.
+
+Requires the `aliafsordeh/orbitx-sandbox:0.2` image (pull it, or build it yourself from the `Dockerfile.sandbox` at the repo root). Note that the sandbox's own stdout/stderr are drained continuously for the life of the container — a piped-but-unread stream fills its OS buffer after ~64KB and blocks the sandbox process on its next write, which surfaces much later as tool calls that never return.
 
-Requires the `aliafsordeh/orbitx-sandbox:0.1` image (pull it, or build it yourself from the `Dockerfile.sandbox` at the repo root).
+Servers started *inside* the sandbox must bind `0.0.0.0`, not `localhost`, to be reachable through a published port; `getInstructions()` tells agents this.
 
 ## Storage and RNG