orbitx 0.2.0 → 0.2.3

package/dist/tools/agent/prompt.js

@@ -0,0 +1,73 @@
+import { MCPTool } from "../../core/mcp.js";
+import { AgentInteraction } from "./interaction.js";
+export const AgentPromptTool = (registry) => new MCPTool({
+    name: "agent-prompt",
+    description: "send a prompt to a hired worker agent and wait for its response. The worker runs its own full turn (its own reasoning, its own tools) and either calls agent-report to hand back a result, or just stops on its own — either way this returns once it's done. You can call this again later on the same agent to continue the conversation (it remembers everything from earlier prompts), or move on and never call it again if its report says the work is finished.",
+    inputs: [
+        {
+            name: "name",
+            type: "string",
+            description: "the hired worker agent's name, exactly as shown by agent-list",
+            required: true,
+        },
+        {
+            name: "prompt",
+            type: "string",
+            description: "the message to send to the worker agent",
+            required: true,
+        },
+    ],
+    customClass: new AgentInteraction(),
+    execute: async (_envID, inputs, _mcp, customClass) => {
+        const { name, prompt } = inputs;
+        if (!name || typeof name !== "string") {
+            throw new Error("name must be a non-empty string");
+        }
+        if (!prompt || typeof prompt !== "string") {
+            throw new Error("prompt must be a non-empty string");
+        }
+        const agent = registry.get(name);
+        if (!agent) {
+            throw new Error(`no worker agent named "${name}" — check agent-list for available names.`);
+        }
+        if (!registry.isHired(name)) {
+            throw new Error(`worker agent "${name}" is not hired yet — call agent-hire first.`);
+        }
+        customClass?.emitAgentEvent({ type: "prompted", name, prompt });
+        const beforeLength = agent.getCurrentAgentStates().messagesFull.length;
+        await agent.run(prompt);
+        // Only look at messages this specific call produced — otherwise a
+        // worker that answers in plain text (no fresh agent-report) could
+        // surface a stale report left over from an earlier prompt.
+        const newMessages = agent.getCurrentAgentStates().messagesFull.slice(beforeLength);
+        let report;
+        let reported = false;
+        for (let i = newMessages.length - 1; i >= 0; i--) {
+            const msg = newMessages[i];
+            if (msg.role === "tool" && msg.toolName === "agent-report") {
+                try {
+                    report = JSON.parse(msg.content || "{}").report;
+                }
+                catch {
+                    report = msg.content;
+                }
+                reported = true;
+                break;
+            }
+        }
+        if (!reported) {
+            for (let i = newMessages.length - 1; i >= 0; i--) {
+                const msg = newMessages[i];
+                if (msg.role === "assistant" && msg.content) {
+                    report = msg.content;
+                    break;
+                }
+            }
+        }
+        report ??= "(worker agent produced no output this turn)";
+        customClass?.emitAgentEvent({ type: "reported", name, reported, report });
+        return { report, reported };
+    },
+});
+export default AgentPromptTool;
+//# sourceMappingURL=prompt.js.map

package/dist/tools/agent/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../src/tools/agent/prompt.ts"],"names":[],"mappings":"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"}

package/dist/tools/agent/registry.d.ts

@@ -0,0 +1,33 @@
+import type WorkerAgent from "../../core/worker-agent.js";
+import type { WorkerAgentRating } from "../../core/worker-agent.js";
+export interface AgentInfo {
+    name: string;
+    description: string;
+    rating: WorkerAgentRating;
+    hired: boolean;
+}
+/**
+ * In-memory catalog of WorkerAgents a planner can see/hire/prompt, plus
+ * which of them are currently "active" (hired). Scoped to one AgentTools()
+ * call — not a process-wide singleton — so multiple independent planners in
+ * the same process each get their own roster and hire state.
+ *
+ * WorkerAgent instances are live objects (their own AI provider, message
+ * history, etc.), not serializable data, so — unlike MCPTool state such as
+ * TodoTools' lists — this can't live in MCPStorage. The roster itself is
+ * fixed at construction (only the developer can safely wire up a worker's
+ * provider/instruction/tools); the model can only hire/prompt from what's
+ * already here, never create new ones.
+ */
+export declare class AgentRegistry {
+    #private;
+    constructor(agents: WorkerAgent[], maxHired?: number);
+    getMaxHired(): number | undefined;
+    getHiredCount(): number;
+    list(): AgentInfo[];
+    hire(name: string): void;
+    isHired(name: string): boolean;
+    get(name: string): WorkerAgent | undefined;
+}
+export default AgentRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/agent/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/tools/agent/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAa;;gBAKV,MAAM,EAAE,WAAW,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM;IAepD,WAAW,IAAI,MAAM,GAAG,SAAS;IAIjC,aAAa,IAAI,MAAM;IAIvB,IAAI,IAAI,SAAS,EAAE;IASnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAkBxB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;CAG7C;AAED,eAAe,aAAa,CAAC"}

package/dist/tools/agent/registry.js

@@ -0,0 +1,68 @@
+/**
+ * In-memory catalog of WorkerAgents a planner can see/hire/prompt, plus
+ * which of them are currently "active" (hired). Scoped to one AgentTools()
+ * call — not a process-wide singleton — so multiple independent planners in
+ * the same process each get their own roster and hire state.
+ *
+ * WorkerAgent instances are live objects (their own AI provider, message
+ * history, etc.), not serializable data, so — unlike MCPTool state such as
+ * TodoTools' lists — this can't live in MCPStorage. The roster itself is
+ * fixed at construction (only the developer can safely wire up a worker's
+ * provider/instruction/tools); the model can only hire/prompt from what's
+ * already here, never create new ones.
+ */
+export class AgentRegistry {
+    #agents = new Map();
+    #hired = new Set();
+    #maxHired;
+    constructor(agents, maxHired) {
+        if (maxHired !== undefined && (!Number.isInteger(maxHired) || maxHired < 1)) {
+            throw new Error(`AgentTools: maxHired must be a positive integer when given, got ${maxHired}.`);
+        }
+        this.#maxHired = maxHired;
+        for (const agent of agents) {
+            const name = agent.getName();
+            if (this.#agents.has(name)) {
+                throw new Error(`AgentTools: duplicate worker agent name "${name}" — names must be unique across the roster.`);
+            }
+            this.#agents.set(name, agent);
+        }
+    }
+    getMaxHired() {
+        return this.#maxHired;
+    }
+    getHiredCount() {
+        return this.#hired.size;
+    }
+    list() {
+        return [...this.#agents.values()].map(agent => ({
+            name: agent.getName(),
+            description: agent.getDescription(),
+            rating: agent.getRating(),
+            hired: this.#hired.has(agent.getName()),
+        }));
+    }
+    hire(name) {
+        if (!this.#agents.has(name)) {
+            throw new Error(`no worker agent named "${name}" — check agent-list for available names.`);
+        }
+        // Re-hiring an already-hired agent is a no-op — it must never count
+        // against the limit a second time.
+        if (this.#hired.has(name)) {
+            return;
+        }
+        if (this.#maxHired !== undefined && this.#hired.size >= this.#maxHired) {
+            throw new Error(`cannot hire "${name}" — maximum of ${this.#maxHired} hired agent(s) already reached ` +
+                `(currently hired: ${[...this.#hired].join(", ") || "none"}).`);
+        }
+        this.#hired.add(name);
+    }
+    isHired(name) {
+        return this.#hired.has(name);
+    }
+    get(name) {
+        return this.#agents.get(name);
+    }
+}
+export default AgentRegistry;
+//# sourceMappingURL=registry.js.map

package/dist/tools/agent/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/tools/agent/registry.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,aAAa;IACtB,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IACzC,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IAC3B,SAAS,CAAU;IAEnB,YAAY,MAAqB,EAAE,QAAiB;QAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,KAAK,CAAC,mEAAmE,QAAQ,GAAG,CAAC,CAAC;QACpG,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAE1B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;YAC7B,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CAAC,4CAA4C,IAAI,6CAA6C,CAAC,CAAC;YACnH,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;IACL,CAAC;IAED,WAAW;QACP,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED,aAAa;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,IAAI;QACA,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC5C,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE;YACrB,WAAW,EAAE,KAAK,CAAC,cAAc,EAAE;YACnC,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE;YACzB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;SAC1C,CAAC,CAAC,CAAC;IACR,CAAC;IAED,IAAI,CAAC,IAAY;QACb,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,2CAA2C,CAAC,CAAC;QAC/F,CAAC;QACD,oEAAoE;QACpE,mCAAmC;QACnC,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,OAAO;QACX,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACrE,MAAM,IAAI,KAAK,CACX,gBAAgB,IAAI,kBAAkB,IAAI,CAAC,SAAS,kCAAkC;gBACtF,qBAAqB,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,IAAI,CACjE,CAAC;QACN,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,CAAC,IAAY;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,GAAG,CAAC,IAAY;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;CACJ;AAED,eAAe,aAAa,CAAC"}

package/dist/tools/agent/report.d.ts

@@ -0,0 +1,12 @@
+import { MCPTool } from "../../core/mcp.js";
+/**
+ * For WorkerAgents, not planners: include this in a worker's own
+ * `allowedTools` (and register it on whatever MCPServer that worker uses)
+ * so it can hand a result back to whoever hired and prompted it. Calling
+ * this always ends the worker's current turn immediately
+ * (stopIterationAfterUsingThisTool) — AgentPromptTool picks the reported
+ * text back up on the hiring agent's side once agent.run() resolves.
+ */
+export declare const AgentReportTool: () => MCPTool<undefined>;
+export default AgentReportTool;
+//# sourceMappingURL=report.d.ts.map

package/dist/tools/agent/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/tools/agent/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,0BAqB1B,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/dist/tools/agent/report.js

@@ -0,0 +1,31 @@
+import { MCPTool } from "../../core/mcp.js";
+/**
+ * For WorkerAgents, not planners: include this in a worker's own
+ * `allowedTools` (and register it on whatever MCPServer that worker uses)
+ * so it can hand a result back to whoever hired and prompted it. Calling
+ * this always ends the worker's current turn immediately
+ * (stopIterationAfterUsingThisTool) — AgentPromptTool picks the reported
+ * text back up on the hiring agent's side once agent.run() resolves.
+ */
+export const AgentReportTool = () => new MCPTool({
+    name: "agent-report",
+    description: "report your result back to whichever agent hired and prompted you, then stop. This ends your current turn immediately — do not call any other tool or add commentary after this. The hiring agent decides what happens next: it may prompt you again to continue this same task, or move on and not call you again if your report shows you're done.",
+    inputs: [
+        {
+            name: "report",
+            type: "string",
+            description: "the result/findings/answer to hand back — write it so it's understandable on its own, without the hiring agent needing to see your internal reasoning",
+            required: true,
+        },
+    ],
+    stopIterationAfterUsingThisTool: true,
+    execute: async (_envID, inputs) => {
+        const { report } = inputs;
+        if (!report || typeof report !== "string") {
+            throw new Error("report must be a non-empty string");
+        }
+        return { report };
+    },
+});
+export default AgentReportTool;
+//# sourceMappingURL=report.js.map

package/dist/tools/agent/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/tools/agent/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAC;IAC7C,IAAI,EAAE,cAAc;IACpB,WAAW,EAAE,sVAAsV;IACnW,MAAM,EAAE;QACJ;YACI,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,uJAAuJ;YACpK,QAAQ,EAAE,IAAI;SACjB;KACJ;IACD,+BAA+B,EAAE,IAAI;IACrC,OAAO,EAAE,KAAK,EAAE,MAAc,EAAE,MAA2B,EAAgB,EAAE;QACzE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;QAE1B,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzD,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,CAAC;IACtB,CAAC;CACJ,CAAC,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/dist/tools/fs/list-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-dir.d.ts","sourceRoot":"","sources":["../../../src/tools/fs/list-dir.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAmEjD,eAAO,MAAM,aAAa,8BAuFxB,CAAC;AAEH,eAAe,aAAa,CAAC"}
+{"version":3,"file":"list-dir.d.ts","sourceRoot":"","sources":["../../../src/tools/fs/list-dir.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAmEjD,eAAO,MAAM,aAAa,8BAsFxB,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/dist/tools/fs/list-dir.js

@@ -109,7 +109,6 @@ export const FsListDirTool = () => new MCPTool({
         const end = Math.max(start, Math.min(start + limitResult, totalResult));
         const page = entries.slice(start, end);
         return {
-            entries: page,
             result: page,
             total: totalResult,
             totalResult,

package/dist/tools/fs/list-dir.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-dir.js","sourceRoot":"","sources":["../../../src/tools/fs/list-dir.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"list-dir.js","sourceRoot":"","sources":["../../../src/tools/fs/list-dir.ts"],"names":[],"mappings":"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"}

package/docs/agents.md

@@ -0,0 +1,163 @@
+# Agents
+
+## `BaseAgent` vs `SimpleAgent`
+
+- **`BaseAgent`** (`src/core/base-agent.ts`) is the real engine — the run loop, memory compaction, tool dispatch, token accounting. It requires you to bring your own `MCPClient` (and therefore your own `MCPServer`/connection), which is what gives you the choice of in-process, IPC, or WebSocket execution (see [MCP Architecture](./mcp-architecture.md)).
+- **`SimpleAgent`** (`src/templates/simple.ts`) is a thin subclass that wires up an in-process `MCPConnection` + `MCPServer` + `MCPClient` for you from a flat `tools`/`skills` list. Use this unless you specifically need a different transport.
+- **`WorkerAgent`** *(experimental)* (`src/core/worker-agent.ts`) is a `BaseAgent` with an identity — name, description, per-task-type rating — so another agent can list, compare, hire, and prompt it as a sub-agent. See [Multi-agent: WorkerAgent](#multi-agent-workeragent-experimental) below.
+
+## `BaseAgent` constructor
+
+```ts
+new BaseAgent({
+  instruction: string;
+  allowedTools: MCPTool<any>[];
+  aiProvider: AIProvider | AgentProviderEntry[];   // see Providers doc
+  mcpClient: MCPClient;
+  skills?: Skill[];
+  maxMemorizeToken?: number;   // default: derived from the main provider's contextWindow * safeUsageRatio
+  initData?: {
+    memory: string;
+    messagesFull: Message[];
+    fullInputMissTokens: number;
+    fullInputHitTokens: number;
+    fullOutputTokens: number;
+    messagesCompact: Message[];
+    currentInputMissTokens: number;
+    currentInputHitTokens: number;
+    currentOutputTokens: number;
+  };
+});
+```
+
+`SimpleAgent`'s constructor is the same shape minus `mcpClient`/`allowedTools` (it builds those from `tools`), plus `tools?: MCPTool<any>[]` and `maxMemorizeToken` defaulting to `16000` instead of being derived.
+
+## The run loop
+
+```ts
+await agent.run(prompt: string, streamCallback?: StreamCallback): Promise<void>;
+```
+
+Each call to `run()`:
+
+1. Pushes the user prompt onto the message history and emits it as a `role: "user"` stream chunk.
+2. Sends `[system, ...history]` plus the full tool schema list to the main provider's `chat()`.
+3. If the model requested tool calls, dispatches each one (via the `MCPClient` this agent was built with), pushes a `role: "tool"` message + stream chunk per result, and loops back to step 2.
+4. Repeats until the model's turn produces no tool calls (or a tool marked `stopIterationAfterUsingThisTool` fired — see [Tools](./tools.md)).
+
+If `run()` is called again while a previous call is still in flight, the new call is queued and resolves once the current run finishes (or times out after 4 minutes) — it does not run concurrently or interleave.
+
+`stop()` requests the current run stop at the next safe point; it resolves once the loop has actually stopped, or rejects if it doesn't stop within 4 minutes.
+
+### Native tool-calling is required
+
+`run()` throws immediately if the main provider's `getCapabilities().supportsTools` is `false`. There is no legacy JSON-in-text fallback in the main loop anymore — pick a provider/model combination (or pass `{ supportsTools: true }`) that supports native function calling.
+
+## Memory compaction
+
+OrbitX never truncates or deletes conversation history. Instead, `BaseAgent` tracks two token totals per run: `currentInputMissTokens` (uncached input) and `currentLastOutputTokens` (the last turn's output). When their sum exceeds `maxMemorizeToken`:
+
+1. The agent asks the main provider to summarize the conversation so far into a single JSON tool call (`{"tool":"set_memory","inputs":{"new_memory":"..."}}`), which becomes the running `memory` string injected into every future system prompt (`MEMORY:` section).
+2. `messagesCompact` — the *working* context sent to the provider each turn — is cleared.
+3. `messagesFull` — the complete, ever-appended history — is untouched, so nothing is lost; it's just no longer replayed to the model every turn.
+4. If no tool was called this turn (i.e. compaction happened on an otherwise-idle turn), the agent auto-continues with a synthetic "Continue where you left off, using MEMORY above for context." prompt so the model doesn't just stop mid-task.
+
+`maxMemorizeToken`, if not passed explicitly, is derived as `contextWindow * safeUsageRatio` (default ratio `0.5`) from the main provider's `getCapabilities()` — so it scales automatically with whatever model you plug in.
+
+## Persisting and resuming state
+
+`getCurrentAgentStates()` returns exactly the shape expected by the `initData` constructor option — `memory`, `messagesFull`, `messagesCompact`, and all six token counters. Serialize it (it's plain JSON) after any `run()` call, and pass it back into a fresh `BaseAgent`/`SimpleAgent` to resume — same conversation, same memory, same token history. See the example in [Getting Started](./getting-started.md#recovering-an-agents-state).
+
+## Token accounting
+
+Three read methods, all returning `{ total, inputHit, inputMiss, output }`:
+
+- `getCurrentTotalTokens()` — tokens used since the last memory compaction.
+- `getFullTotalTokens()` — tokens used across all *prior* compacted segments.
+- `getTotalTokens()` — the sum of both (lifetime total for this agent instance).
+
+`inputHit`/`inputMiss` track cached vs. uncached input tokens, since the compacted-context-replay pattern means most of a long conversation's prefix is a cache hit on providers that support prompt caching.
+
+## Instructions, skills, and memory in the system prompt
+
+The system prompt is built once (lazily, on first use) and never changes for the lifetime of an agent instance — a stable prefix, which matters for provider-side prompt caching. It's assembled from: a fixed "you have tools" preamble, each skill's name/description/instructions (see [Skills](./skills.md)), the current `MEMORY:` block, and your `instruction` string, in that order.
+
+## Multi-agent: `WorkerAgent` *(experimental)*
+
+**Experimental:** this whole feature (`WorkerAgent`, `AgentTools`, `AgentReportTool`) is new and still settling — names, the hire/prompt/report shape, and the fallback behavior when a worker never reports may change in a future release. Treat it as unstable if you're building something you don't want to have to revisit.
+
+`WorkerAgent` (`src/core/worker-agent.ts`) is a `BaseAgent` with three extra fields on top of the usual constructor options:
+
+```ts
+new WorkerAgent({
+  name: string;           // unique id used to hire/prompt this worker
+  description: string;    // persona/specialty, written for a hiring agent to judge fit from
+  rating?: Record<string, number>;  // per-task-type fit score, e.g. { backend: 9, "3d-web": 10 }, convention 0-10
+  // ...plus every BaseAgent option: instruction, allowedTools, aiProvider, mcpClient, skills?, maxMemorizeToken?, initData?
+});
+
+worker.getName();
+worker.getDescription();
+worker.getRating();
+```
+
+It's a raw building block, same as `BaseAgent` — you still bring your own `mcpClient`/`allowedTools` for it. The only thing `WorkerAgent` adds is identity metadata; running it (`.run()`, streaming, memory, tokens) is unchanged.
+
+### The `agent-*` tools
+
+`AgentTools(availableAgents: WorkerAgent[], options?: { maxHired?: number })` (from `src/tools/agent/`) builds a fixed roster of hireable workers into three planner-facing tools:
+
+| Tool | Purpose |
+|---|---|
+| `agent-list` | List every worker in the roster — name, description, rating, and whether it's currently hired. Also returns `hiredCount` and (when set) `maxHired`. |
+| `agent-hire` | Hire a worker by name, making it eligible for `agent-prompt`. Hiring an already-hired worker is a no-op. |
+| `agent-prompt` | Send a prompt to a hired worker and wait for its response. |
+
+`maxHired` caps how many workers can be hired at once — omit it for no limit. When set, it's woven directly into `agent-hire`'s own tool description (so the model learns the constraint from the tool itself, not out-of-band instructions) and exceeding it throws a clear error naming the current limit and who's currently hired. Re-hiring an already-hired worker is still a free no-op and never counts against the cap.
+
+Give these to your **planner** agent (the one that decides which workers to use), not to the workers themselves:
+
+```ts
+import { AgentTools, SimpleAgent, WorkerAgent, AnthropicProvider, AgentReportTool, MCPConnection, MCPServer, MCPClient } from "orbitx";
+
+function buildWorker(name: string, description: string, rating: Record<string, number>) {
+  const connection = new MCPConnection();
+  const server = new MCPServer(connection);
+  const reportTool = AgentReportTool();
+  server.registerTool(reportTool);
+  // ...register whatever other tools this worker needs on `server` too...
+
+  return new WorkerAgent({
+    name,
+    description,
+    rating,
+    instruction: `You are the ${name} specialist.`,
+    aiProvider: new AnthropicProvider("api-key", "claude-sonnet-5"),
+    mcpClient: new MCPClient(name, connection),
+    allowedTools: [reportTool /* , ...other tools registered above */],
+  });
+}
+
+const backendWorker = buildWorker("backend-worker", "Node.js APIs, databases, servers.", { backend: 9, frontend: 2 });
+const frontendWorker = buildWorker("frontend-worker", "React UI work.", { backend: 2, frontend: 9 });
+
+const planner = new SimpleAgent({
+  aiProvider: new AnthropicProvider("api-key", "claude-sonnet-5"),
+  instruction: "You coordinate work across specialist worker agents.",
+  // At most 1 hired at a time here, just as an example constraint.
+  tools: AgentTools([backendWorker, frontendWorker], { maxHired: 1 }),
+});
+```
+
+### `agent-report` — for workers, not the planner
+
+Include `AgentReportTool()` in each **worker's own** `allowedTools` (and register it on that worker's own `MCPServer`, as in the example above) — it's what lets a worker hand a result back once it's done. Calling it always ends the worker's current turn immediately (`stopIterationAfterUsingThisTool`), so a worker should call it and stop, not keep reasoning afterward.
+
+### How a prompt/report round-trip actually works
+
+1. Planner calls `agent-hire`, then `agent-prompt` with a task.
+2. `agent-prompt`'s implementation calls `workerAgent.run(prompt)` and waits for it to resolve — the worker runs its own full turn (its own reasoning, its own tools), completely independently of the planner's own loop.
+3. Once the worker's `run()` resolves, `agent-prompt` looks at only the messages that turn produced: if the worker called `agent-report`, that report text is returned (`{ report, reported: true }`); otherwise it falls back to the worker's last plain-text answer (`{ report, reported: false }`).
+4. The planner sees this as a normal tool result. It's the planner's call what happens next — prompt the same worker again to continue (its message history persists across `agent-prompt` calls, same as any agent's `run()`), or move on and never call it again if the report shows the work is done. Nothing about the worker's lifecycle is automatic.
+
+`AgentTools(...)` state (which agents are hired) is scoped to that one call — building a second, independent planner with its own `AgentTools([...])` call gets its own hire state, even in the same process.

package/docs/api-reference.md

@@ -0,0 +1,54 @@
+# API Reference
+
+Flat index of every public export from `orbitx` (see `src/index.ts`), grouped by area. Each links to the doc page with the actual explanation and examples.
+
+## Core / Providers — see [Providers](./providers.md)
+
+- `AIProvider` (abstract base class)
+- `OpenAIProvider`, `AnthropicProvider`, `DeepSeekProvider`, `OllamaProvider`
+- `resolveAgentProviders()`
+- Types: `AgentProviderRole`, `AgentProviderEntry`, `AgentProvidersInput`, `ResolvedAgentProviders`
+- Types: `ChatResponse`, `Message`, `StreamCallback`, `ToolSchema`, `ToolCallRequest`, `MessageContentPart`, `ProviderCapabilities`
+- `resolveThinkEffortLevel()`, `clampThinkEffort()` — the universal 0-1 `thinkEffort` → provider-native-level mapping helpers; see [Providers](./providers.md#think-effort)
+- Type: `ThinkEffortLevel`
+- `ImageDescriber` — used internally by `BaseAgent` to describe image tool output via the `image` provider role; exported for direct use if you want to describe an image outside the agent loop.
+- `toOpenAIFunctionTools()` — translates a `ToolSchema[]` into OpenAI's function-calling format; exported for building custom providers.
+
+## Agents — see [Agents](./agents.md)
+
+- `BaseAgent`
+- `SimpleAgent`
+- `WorkerAgent` *(experimental)*, type `WorkerAgentRating`
+- Types: `ExtractedSegment`, `ParsedToolCall`
+
+## Tools — see [Tools](./tools.md)
+
+- `MCPTool`, `MCPCustomClass`, `generateRefId()`, `normalizeToolOutput()`
+- Types: `MCP`, `MCPToolOutput`
+
+Built-in tool factories, grouped by domain (each domain also exports a `*Tools()` array and a `*Interaction` EventEmitter):
+
+| Domain | Exports |
+|---|---|
+| Filesystem | `FsReadFileTool`, `FsWriteFileTool`, `FsEditFileTool`, `FsListDirTool`, `FsCreateDirTool`, `FsDeleteTool`, `FsMoveTool`, `FsStatTool`, `FsTools`, `FsInteraction`, type `FsEvent` |
+| Bash | `BashRunTool`, `BashWaitTool`, `BashLogsTool`, `BashListTool`, `BashWriteInputTool`, `BashTerminateTool`, `BashTools`, `BashInteraction`, type `BashEvent` |
+| Browser | `BrowserCreateSessionTool`, `BrowserRemoveSessionTool`, `BrowserGetSessionsTool`, `BrowserNavigateTool`, `BrowserConsoleTool`, `BrowserInjectTool`, `BrowserReadTool`, `BrowserClickTool`, `BrowserFillTool`, `BrowserScrollInfoTool`, `BrowserScrollTool`, `BrowserNetworkStatusTool`, `BrowserNetworkTool`, `BrowserSubmitFormTool`, `BrowserScreenshotTool`, `BrowserTools`, `BrowserInteraction`, type `BrowserEvent` |
+| Todo | `TodoCreateListTool`, `TodoRemoveListTool`, `TodoGetListsTool`, `TodoGetListTool`, `TodoCreateTaskTool`, `TodoRemoveTaskTool`, `TodoCheckTaskTool`, `TodoTools`, `TodoInteraction`, types `TodoTask`, `TodoList`, `TodoEvent` |
+| Present | `PresentAddTool`, `PresentClearTool`, `PresentGetListTool`, `PresentTools`, `getPresentFolder()`, `PresentInteraction`, type `PresentEvent` |
+| Question/Answer | `QuestionAnswerTool`, `QuestionAnswerTools`, `QuestionAnswerInteraction`, type `QuestionAnswerEvent` |
+| Utility | `GetCurrentTimeTool`, `DelayTool`, `UtilTools` |
+| Multi-agent *(experimental)* | `AgentTools(availableAgents, options?)`, `AgentListTool`, `AgentHireTool`, `AgentPromptTool`, `AgentReportTool`, `AgentRegistry`, `AgentInteraction`, type `AgentInfo`, type `AgentEvent`, type `AgentToolsOptions` — see [Agents](./agents.md#multi-agent-workeragent-experimental) |
+
+## Skills — see [Skills](./skills.md)
+
+- `Skill`
+- `BackendSecuritySkill`, `BigTaskSkill`, `CodeVerificationSkill`, `LongTaskEfficiencySkill`, `NodeBackendSkill`, `PlannerSkill`, `PresentSkill`, `QuestionAnswerSkill`, `ReactFrontendSkill`, `ResearchSkill`, `ShoppingSkill`, `UiUxDesignSkill`, `WebEndToEndTestSkill`
+
+## MCP transport — see [MCP Architecture](./mcp-architecture.md)
+
+- `MCPServer`, `MCPClient`
+- `MCPConnection`, `MCPIPCConnection`, `MCPWSConnection`
+- `MCPComputer` *(experimental)*
+- `MCPStorage`, `MCPFSStorage`
+- `MCPRNG`
+- `MCPFilter`

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.