orbitx 0.3.5 → 0.3.7

package/docs/agents.md

@@ -17,6 +17,7 @@ new BaseAgent({
   aiProvider: AIProvider | AgentProviderEntry[];   // see Providers doc
   mcpClient: MCPClient;
   skills?: Skill[];
+  compactInstructions?: string; // what a compact_memory note must also keep in this app (see Memory compaction)
   maxMemorizeToken?: number;   // default: derived from the main provider's contextWindow * safeUsageRatio
   initData?: {
     compactMemory: string;
@@ -99,13 +100,17 @@ For a **streaming** call, an abort doesn't throw the turn away: `chat()` resolve
 
 ## Memory compaction
 
-OrbitX never truncates or deletes conversation history. Compaction happens through a real, always-available native tool — `compact_memory({ new_memory: string, continue_iterating?: boolean })` — that `BaseAgent` appends to every tool schema list alongside whatever MCP tools you allowed. This means the model can compact its own context whenever *it* judges the conversation has grown long, not only when forced to.
+OrbitX never truncates or deletes conversation history. Compaction happens through a real, always-available native tool — `compact_memory({ new_memory: string, language?: string, files_to_reread?: {path, reason}[], continue_iterating?: boolean })` — that `BaseAgent` appends to every tool schema list alongside whatever MCP tools you allowed. This means the model can compact its own context whenever *it* judges the conversation has grown long, not only when forced to.
 
 Calling `compact_memory`:
 
-1. Replaces the running `compactMemory` string with `new_memory`, which is injected into every future system prompt (`MEMORY:` section). The cached system prompt is invalidated at the same time, so the very next turn's system prompt is rebuilt with the new summary rather than replaying the stale one.
+1. Replaces the running `compactMemory` string with `new_memory` — followed by a `Conversation language: …` line when `language` is given and a `Files to read again …` list from `files_to_reread` (so both survive a restore from `AgentState` without a new field) — which is injected into every future system prompt (`MEMORY:` section). The cached system prompt is invalidated at the same time, so the very next turn's system prompt is rebuilt with the new summary rather than replaying the stale one.
 2. Once every tool call in that turn has been dispatched and had its normal tool-response message appended to `messagesCompact` — `compact_memory`'s own response included — the *entire* turn's `messagesCompact` (the assistant message, every tool-response message, all of it) is moved into `retiredMessages` and `messagesCompact` is cleared. Nothing is lost, it's just retired from what gets replayed to the model every turn. Nothing needs to be separately "rolled into a lifetime total" — every message already carries its own `usage`, so `getFullTotalToken()` (see [Token accounting](#token-accounting)) just sums `retiredMessages` + `messagesCompact` directly.
-3. A single hidden `role: "user"` message — `"Memory compacted. Continue where you left off, using MEMORY above for context."` — is pushed onto the now-empty `messagesCompact`, but *only if `run()` is actually about to take another turn right now* (see `continue_iterating` below for when it isn't). With nothing left to respond to it this turn, an unconditional push would just leave it sitting in `messagesCompact` as a stray, unanswered `"user"` entry until some later, unrelated user message showed up after it. When it is added, the model's next turn already has the new summary via the system prompt's MEMORY section, so nothing about the compacted turn — including the `compact_memory` call/response pair itself — needs to stay in the replayed working context; the message is just the nudge to keep going.
+3. A single hidden `role: "user"` message — `"Memory compacted. Continue where you left off, using MEMORY above for context."`, followed by the user's latest real (non-hidden) message verbatim (clipped to its head and tail past 6 000 characters), the files to read again, and the language to reply in — is pushed onto the now-empty `messagesCompact`, but *only if `run()` is actually about to take another turn right now* (see `continue_iterating` below for when it isn't). With nothing left to respond to it this turn, an unconditional push would just leave it sitting in `messagesCompact` as a stray, unanswered `"user"` entry until some later, unrelated user message showed up after it. When it is added, the model's next turn already has the new summary via the system prompt's MEMORY section, so nothing about the compacted turn — including the `compact_memory` call/response pair itself — needs to stay in the replayed working context; the message is just the nudge to keep going.
+
+### What a note keeps
+
+Only the note, the language, the files to read again and the user's latest message cross a compaction; every tool result and file content in the working context is dropped. The tool's own descriptions and a `COMPACTION RULES:` block in the system prompt tell the model to write the note as a hand-over — the user's requests and constraints, what's done, decisions, the exact next steps, open questions — and to name files by path in `files_to_reread` instead of copying their contents (a re-read costs less than carrying them in every later system prompt). Carrying the user's own words over is what keeps the model answering in their language and on their request after a compaction. An application adds its own must-keep items with the `compactInstructions` constructor option (appended to those rules).
 
 Archiving is deliberately deferred until the whole turn is dispatched, rather than happening the instant `compact_memory` itself resolves: providers reject a `"tool"`-role message that isn't preceded, in the same request, by the assistant message carrying the `tool_calls` it's answering, so archiving mid-turn would strand the response of any *other* tool call made alongside `compact_memory` in the same turn. Doing it once, after every call in the turn already has its response in `messagesCompact`, avoids that regardless of how many other tools were called or in what order.
 
@@ -161,9 +166,13 @@ Every other `type` entry comes from a tool calling `mcp.executeProvider(toolCall
 - `getCompactTotalTokens(type: ProviderType)` / `getFullTotalToken(type: ProviderType)` — return `{ total, inputHit, inputMiss, output }`, summing `unit: "tokens"` entries matching `type` over `messagesCompact` only, or `retiredMessages` + `messagesCompact` (this agent's whole lifetime), respectively.
 - `getCompactTotalCost(type: ProviderType)` / `getFullTotalCost(type: ProviderType)` — return a plain `number`, summing `unit: "cost"` entries matching `type` over the same two scopes.
 
+## Tool schemas
+
+Each run sends the model the tools `mcpClient.getTools()` reports, filtered to `allowedTools`, plus `compact_memory`. A remote tool that reports no inputs at all (a bare proxy that only forwards calls, e.g. a desktop app relaying a browser extension's tools) takes the description and inputs of the `allowedTools` entry with the same name, so the model still sees its parameters; a remote tool that publishes its own inputs is sent as published.
+
 ## Instructions, skills, and memory in the system prompt
 
-The system prompt is built lazily on first use and cached — a stable prefix between compactions, 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 (sourced from `compactMemory`), and your `instruction` string, in that order. Each `compact_memory` call invalidates the cache (see [Memory compaction](#memory-compaction)), so the next turn's system prompt is rebuilt with the fresh `MEMORY:` block instead of the one that was current when the prompt was first built.
+The system prompt is built lazily on first use and cached — a stable prefix between compactions, 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 (sourced from `compactMemory`) followed by the `COMPACTION RULES:` block (plus `compactInstructions`), and your `instruction` string, in that order. Each `compact_memory` call invalidates the cache (see [Memory compaction](#memory-compaction)), so the next turn's system prompt is rebuilt with the fresh `MEMORY:` block instead of the one that was current when the prompt was first built.
 
 ## `StatelessAgent`
 

package/docs/api-reference.md

@@ -1,59 +1,59 @@
-# 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()`, `ProviderRegistry`
-- Types: `AgentProviderEntry`, `AgentProvidersInput`
-- Types: `ChatResponse`, `Message`, `MessageUsage`, `MessageUsageTokens`, `MessageUsageCost`, `StreamCallback`, `ToolSchema`, `ToolCallRequest`, `MessageContentPart`, `ProviderCapabilities`, `ProviderType` — see [Providers](./providers.md#provider-roles)
-- `resolveThinkEffortLevel()`, `clampThinkEffort()` — the universal 0-1 `thinkEffort` → provider-native-level mapping helpers; see [Providers](./providers.md#think-effort)
-- Type: `ThinkEffortLevel`
-- `toOpenAIFunctionTools()` — translates a `ToolSchema[]` into OpenAI's function-calling format; exported for building custom providers.
-
-## Agents — see [Agents](./agents.md)
-
-- `BaseAgent`
-- `SimpleAgent`
-- Types: `ExtractedSegment`, `ParsedToolCall`
-
-## Swarm — see [Swarm](./swarm.md)
-
-- `SwarmBase` — types `SwarmBaseProps`, `SwarmRunOptions`, `SwarmState`, `SwarmAgentState`, `SwarmStreamChunk`, `SwarmStreamCallback`, `SwarmAgentFailure`
-- `AgentDefinition`, `selectTools()`, `applyTextOverride()` — types `AgentDefinitionProps`, `AgentOverrides`, `AgentFactory`, `AgentFactoryOptions`, `TextOverride`
-- Ready-made definitions: `PlannerAgent`, `ReasonerAgent` (+ `REASONER_PANEL_MS`), `BackendAgent`, `FrontendAgent`, `TestAgent`, `ResearchAgent`, `DefaultAgents()`, and the shared instruction fragments `PLANNER_PROTOCOL` / `WORKER_PROTOCOL` / `TEAM_PROTOCOL` / `PRODUCTION_BAR`
-
-## Tools — see [Tools](./tools.md)
-
-- `MCPTool`, `generateRefId()`, `normalizeToolOutput()`
-- Types: `MCP`, `MCPToolOutput`
-
-Built-in tool factories, grouped by domain (each domain also exports a `*Tools()` array):
-
-| Domain | Exports |
-|---|---|
-| Filesystem | `FsReadFileTool`, `FsWriteFileTool`, `FsEditFileTool`, `FsListDirTool`, `FsCreateDirTool`, `FsDeleteTool`, `FsMoveTool`, `FsStatTool`, `FsTools` |
-| Bash | `BashRunTool`, `BashWaitTool`, `BashLogsTool`, `BashListTool`, `BashWriteInputTool`, `BashTerminateTool`, `BashTools` |
-| Browser | `BrowserCreateSessionTool`, `BrowserRemoveSessionTool`, `BrowserGetSessionsTool`, `BrowserNavigateTool`, `BrowserConsoleTool`, `BrowserInjectTool`, `BrowserReadTool`, `BrowserClickTool`, `BrowserFillTool`, `BrowserScrollInfoTool`, `BrowserScrollTool`, `BrowserNetworkStatusTool`, `BrowserNetworkTool`, `BrowserSubmitFormTool`, `BrowserScreenshotTool`, `BrowserTools` |
-| Todo | `TodoCreateListTool`, `TodoRemoveListTool`, `TodoGetListsTool`, `TodoGetListTool`, `TodoCreateTaskTool`, `TodoRemoveTaskTool`, `TodoCheckTaskTool`, `TodoTools`, types `TodoTask`, `TodoList` |
-| Present | `PresentAddTool`, `PresentClearTool`, `PresentGetListTool`, `PresentTools`, `getPresentFolder()` |
-| Question/Answer | `QuestionAnswerTool`, `QuestionAnswerTools` |
-| Utility | `GetCurrentTimeTool`, `DelayTool`, `ReadImageTool`, `UtilTools` |
-| Swarm | `getAgentTools(options?)`, `AgentTypesTool`, `AgentHireTool`, `AgentFireTool`, `AgentActiveTool`, `AgentPromptTool`, `AgentReportParentTool`, `AgentReportGroupTool`, `AgentToolsRegistry`, types `AgentToolsOptions`, `AgentToolsHandle`, `SwarmController`, `SwarmAgentTypeInfo`, `SwarmAgentInfo`, `AgentToolsEvent`, `AgentToolsAck`, `AgentToolsListener` — see [Swarm](./swarm.md#getagenttoolsoptions) |
-
-## Skills — see [Skills](./skills.md)
-
-- `Skill`
-- `BackendSecuritySkill`, `BigTaskSkill`, `CodeVerificationSkill`, `LongTaskEfficiencySkill`, `NodeBackendSkill`, `PlannerSkill`, `PresentSkill`, `QuestionAnswerSkill`, `ReactFrontendSkill`, `ResearchSkill`, `UiUxDesignSkill`, `WebEndToEndTestSkill`
-
-## MCP transport — see [MCP Architecture](./mcp-architecture.md)
-
-- `MCPServer`, `MCPClient`
-- `MCPConnection`, `MCPIPCConnection`, `MCPWSConnection`
-- `MCPComputer`, type `MCPComputerOptions` *(experimental)*
-- `MCPStorage`, `MCPFSStorage`
-- `MCPRNG`
-- `MCPOutputFilter` (`MCPFilter` is a deprecated alias, removed in `1.0.0`)
-- `MCPExecutionPolicy`, `MCPBypassExecutionPolicy`, type `MCPToolCallRequest`
+# 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()`, `ProviderRegistry`
+- Types: `AgentProviderEntry`, `AgentProvidersInput`
+- Types: `ChatResponse`, `Message`, `MessageUsage`, `MessageUsageTokens`, `MessageUsageCost`, `StreamCallback`, `ToolSchema`, `ToolCallRequest`, `MessageContentPart`, `ProviderCapabilities`, `ProviderType` — see [Providers](./providers.md#provider-roles)
+- `resolveThinkEffortLevel()`, `clampThinkEffort()` — the universal 0-1 `thinkEffort` → provider-native-level mapping helpers; see [Providers](./providers.md#think-effort)
+- Type: `ThinkEffortLevel`
+- `toOpenAIFunctionTools()` — translates a `ToolSchema[]` into OpenAI's function-calling format; exported for building custom providers.
+
+## Agents — see [Agents](./agents.md)
+
+- `BaseAgent`
+- `SimpleAgent`
+- Types: `ExtractedSegment`, `ParsedToolCall`
+
+## Swarm — see [Swarm](./swarm.md)
+
+- `SwarmBase` — types `SwarmBaseProps`, `SwarmRunOptions`, `SwarmState`, `SwarmAgentState`, `SwarmStreamChunk`, `SwarmStreamCallback`, `SwarmAgentFailure`
+- `AgentDefinition`, `selectTools()`, `applyTextOverride()` — types `AgentDefinitionProps`, `AgentOverrides`, `AgentFactory`, `AgentFactoryOptions`, `TextOverride`
+- Ready-made definitions: `PlannerAgent`, `ReasonerAgent` (+ `REASONER_PANEL_MS`), `BackendAgent`, `FrontendAgent`, `TestAgent`, `ResearchAgent`, `DefaultAgents()`, and the shared instruction fragments `PLANNER_PROTOCOL` / `WORKER_PROTOCOL` / `TEAM_PROTOCOL` / `PRODUCTION_BAR`
+
+## Tools — see [Tools](./tools.md)
+
+- `MCPTool`, `generateRefId()`, `normalizeToolOutput()`
+- Types: `MCP`, `MCPToolOutput`
+
+Built-in tool factories, grouped by domain (each domain also exports a `*Tools()` array):
+
+| Domain | Exports |
+|---|---|
+| Filesystem | `FsReadFileTool`, `FsWriteFileTool`, `FsEditFileTool`, `FsListDirTool`, `FsCreateDirTool`, `FsDeleteTool`, `FsMoveTool`, `FsStatTool`, `FsTools` |
+| Bash | `BashRunTool`, `BashWaitTool`, `BashLogsTool`, `BashListTool`, `BashWriteInputTool`, `BashTerminateTool`, `BashTools` |
+| Browser | `BrowserCreateSessionTool`, `BrowserRemoveSessionTool`, `BrowserGetSessionsTool`, `BrowserNavigateTool`, `BrowserConsoleTool`, `BrowserInjectTool`, `BrowserReadTool`, `BrowserClickTool`, `BrowserFillTool`, `BrowserScrollInfoTool`, `BrowserScrollTool`, `BrowserNetworkStatusTool`, `BrowserNetworkTool`, `BrowserSubmitFormTool`, `BrowserScreenshotTool`, `BrowserTools` |
+| Todo | `TodoCreateListTool`, `TodoRemoveListTool`, `TodoGetListsTool`, `TodoGetListTool`, `TodoCreateTaskTool`, `TodoRemoveTaskTool`, `TodoCheckTaskTool`, `TodoTools`, types `TodoTask`, `TodoList` |
+| Present | `PresentAddTool`, `PresentClearTool`, `PresentGetListTool`, `PresentTools`, `getPresentFolder()` |
+| Question/Answer | `QuestionAnswerTool`, `QuestionAnswerTools` |
+| Utility | `GetCurrentTimeTool`, `DelayTool`, `ReadImageTool`, `UtilTools` |
+| Swarm | `getAgentTools(options?)`, `AgentTypesTool`, `AgentHireTool`, `AgentFireTool`, `AgentActiveTool`, `AgentPromptTool`, `AgentReportParentTool`, `AgentReportGroupTool`, `AgentToolsRegistry`, types `AgentToolsOptions`, `AgentToolsHandle`, `SwarmController`, `SwarmAgentTypeInfo`, `SwarmAgentInfo`, `AgentToolsEvent`, `AgentToolsAck`, `AgentToolsListener` — see [Swarm](./swarm.md#getagenttoolsoptions) |
+
+## Skills — see [Skills](./skills.md)
+
+- `Skill`
+- `BackendSecuritySkill`, `BigTaskSkill`, `CodeVerificationSkill`, `LongTaskEfficiencySkill`, `NodeBackendSkill`, `PlannerSkill`, `PresentSkill`, `QuestionAnswerSkill`, `ReactFrontendSkill`, `ResearchSkill`, `UiUxDesignSkill`, `WebEndToEndTestSkill`
+
+## MCP transport — see [MCP Architecture](./mcp-architecture.md)
+
+- `MCPServer`, `MCPClient`
+- `MCPConnection`, `MCPIPCConnection`, `MCPWSConnection`
+- `MCPComputer`, type `MCPComputerOptions` *(experimental)*
+- `MCPStorage`, `MCPFSStorage`
+- `MCPRNG`
+- `MCPOutputFilter` (`MCPFilter` is a deprecated alias, removed in `1.0.0`)
+- `MCPExecutionPolicy`, `MCPBypassExecutionPolicy`, type `MCPToolCallRequest`