orbitx 0.2.6 → 0.2.7

package/dist/tools/todo/remove-task.d.ts

@@ -1,5 +1,4 @@
 import { MCPTool } from "../../core/mcp.js";
-import { TodoInteraction } from "./interaction.js";
-export declare const TodoRemoveTaskTool: () => MCPTool<TodoInteraction>;
+export declare const TodoRemoveTaskTool: () => MCPTool;
 export default TodoRemoveTaskTool;
 //# sourceMappingURL=remove-task.d.ts.map

package/dist/tools/todo/remove-task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remove-task.d.ts","sourceRoot":"","sources":["../../../src/tools/todo/remove-task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,eAAO,MAAM,kBAAkB,gCAkD7B,CAAC;AAEH,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"remove-task.d.ts","sourceRoot":"","sources":["../../../src/tools/todo/remove-task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AAGtD,eAAO,MAAM,kBAAkB,eA+C7B,CAAC;AAEH,eAAe,kBAAkB,CAAC"}

package/dist/tools/todo/remove-task.js

@@ -1,5 +1,4 @@
 import { MCPTool } from "../../core/mcp.js";
-import { TodoInteraction } from "./interaction.js";
 import { getTask, getList, setList, deleteTaskKey } from "./storage.js";
 export const TodoRemoveTaskTool = () => new MCPTool({
     name: "todo-remove-task",
@@ -12,8 +11,7 @@ export const TodoRemoveTaskTool = () => new MCPTool({
             required: true,
         },
     ],
-    customClass: new TodoInteraction(),
-    execute: async (_envID, inputs, mcp, customClass) => {
+    execute: async (_envID, inputs, _toolCallId, mcp) => {
         const { tasks } = inputs;
         if (!Array.isArray(tasks) || tasks.some((t) => typeof t !== "string")) {
             throw new Error("tasks must be an array of task id strings");
@@ -35,7 +33,6 @@ export const TodoRemoveTaskTool = () => new MCPTool({
                 await setList(mcp, list);
             }
         }
-        customClass?.emitTodoEvent({ type: "task-removed", taskIds: tasks });
         return {
             message: "success",
         };

package/dist/tools/todo/remove-task.js.map

@@ -1 +1 @@
-{"version":3,"file":"remove-task.js","sourceRoot":"","sources":["../../../src/tools/todo/remove-task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAExE,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAkB;IACjE,IAAI,EAAE,kBAAkB;IACxB,WAAW,EAAE,gCAAgC;IAC7C,MAAM,EAAE;QACJ;YACI,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,+BAA+B;YAC5C,QAAQ,EAAE,IAAI;SACjB;KACJ;IACD,WAAW,EAAE,IAAI,eAAe,EAAE;IAClC,OAAO,EAAE,KAAK,EACV,MAAc,EACd,MAA2B,EAC3B,GAAS,EACT,WAA6B,EACjB,EAAE;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QAEzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;YACpE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QACjE,CAAC;QAED,IAAI,CAAC,GAAG,EAAE,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;QAE1C,KAAK,MAAM,MAAM,IAAI,KAAiB,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACxC,IAAI,IAAI;gBAAE,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC3C,MAAM,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACrC,CAAC;QAED,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACxC,IAAI,IAAI,EAAE,CAAC;gBACP,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;gBAChE,MAAM,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC7B,CAAC;QACL,CAAC;QAED,WAAW,EAAE,aAAa,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAErE,OAAO;YACH,OAAO,EAAE,SAAS;SACrB,CAAC;IACN,CAAC;CACJ,CAAC,CAAC;AAEH,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"remove-task.js","sourceRoot":"","sources":["../../../src/tools/todo/remove-task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAExE,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAC;IAChD,IAAI,EAAE,kBAAkB;IACxB,WAAW,EAAE,gCAAgC;IAC7C,MAAM,EAAE;QACJ;YACI,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,+BAA+B;YAC5C,QAAQ,EAAE,IAAI;SACjB;KACJ;IACD,OAAO,EAAE,KAAK,EACV,MAAc,EACd,MAA2B,EAC3B,WAAoB,EACpB,GAAS,EACG,EAAE;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QAEzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;YACpE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QACjE,CAAC;QAED,IAAI,CAAC,GAAG,EAAE,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;QAE1C,KAAK,MAAM,MAAM,IAAI,KAAiB,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACxC,IAAI,IAAI;gBAAE,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC3C,MAAM,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACrC,CAAC;QAED,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACxC,IAAI,IAAI,EAAE,CAAC;gBACP,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;gBAChE,MAAM,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC7B,CAAC;QACL,CAAC;QAED,OAAO;YACH,OAAO,EAAE,SAAS;SACrB,CAAC;IACN,CAAC;CACJ,CAAC,CAAC;AAEH,eAAe,kBAAkB,CAAC"}

package/dist/tools/utils/delay.d.ts

@@ -5,6 +5,6 @@ import { MCPTool } from "../../core/mcp.js";
  * a frontend time to render a status update, or throttling itself between
  * repeated tool calls) rather than firing calls back-to-back.
  */
-export declare const DelayTool: () => MCPTool<undefined>;
+export declare const DelayTool: () => MCPTool;
 export default DelayTool;
 //# sourceMappingURL=delay.d.ts.map

package/dist/tools/utils/delay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/delay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAI5C;;;;;GAKG;AACH,eAAO,MAAM,SAAS,0BA0BpB,CAAC;AAEH,eAAe,SAAS,CAAC"}
+{"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/delay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAI5C;;;;;GAKG;AACH,eAAO,MAAM,SAAS,eA0BpB,CAAC;AAEH,eAAe,SAAS,CAAC"}

package/dist/tools/utils/get-current-time.d.ts

@@ -4,6 +4,6 @@ import { MCPTool } from "../../core/mcp.js";
  * time-sensitive search queries or reasoning about "latest"/"current" facts,
  * since the model's own training data has no reliable sense of "now".
  */
-export declare const GetCurrentTimeTool: () => MCPTool<undefined>;
+export declare const GetCurrentTimeTool: () => MCPTool;
 export default GetCurrentTimeTool;
 //# sourceMappingURL=get-current-time.d.ts.map

package/dist/tools/utils/get-current-time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-current-time.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/get-current-time.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,0BAa7B,CAAC;AAEH,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"get-current-time.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/get-current-time.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,eAa7B,CAAC;AAEH,eAAe,kBAAkB,CAAC"}

package/dist/tools/utils/index.d.ts

@@ -1,5 +1,5 @@
 export { GetCurrentTimeTool } from "./get-current-time.js";
 export { DelayTool } from "./delay.js";
 export { ReadImageTool } from "./read-image.js";
-export declare const UtilTools: () => import("../../index.js").MCPTool<undefined>[];
+export declare const UtilTools: () => import("../../index.js").MCPTool[];
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAQhD,eAAO,MAAM,SAAS,qDAIrB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAQhD,eAAO,MAAM,SAAS,0CAIrB,CAAC"}

package/dist/tools/utils/read-image.d.ts

@@ -1,12 +1,17 @@
 import { MCPTool } from "../../core/mcp.js";
 /**
- * Reads an image straight off disk and hands it to the agent as an image
- * tool-output — same shape and same downstream handling as
- * `browser-screenshot` (see BaseAgent#resolveToolOutputForModel): depending
- * on how the agent is configured, the raw bytes go straight to the main
- * model, or a separate image-capable provider describes it first so the
- * main conversation doesn't have to carry image bytes.
+ * Reads an image straight off disk and describes it itself, via
+ * `mcp.executeProvider(toolCallId, "image-describer", { parts })` — works
+ * identically whether this tool is registered directly on an `MCPClient` or
+ * on a sandboxed/remote `MCPServer` (see `MCP#executeProvider` in mcp.ts). The
+ * raw image bytes never leave this tool; only the resulting text
+ * description is returned. Usage is recorded on the trusted side of that
+ * call, not by this tool — see `BaseAgent#executeProvider`. `parts` (not a
+ * plain `content` string) is what actually reaches the provider as a real
+ * image — every built-in `AIProvider` only builds a multimodal image block
+ * from `Message.parts`, so a base64 string folded into `content` would be
+ * sent as literal text instead.
  */
-export declare const ReadImageTool: () => MCPTool<undefined>;
+export declare const ReadImageTool: () => MCPTool;
 export default ReadImageTool;
 //# sourceMappingURL=read-image.d.ts.map

package/dist/tools/utils/read-image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-image.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/read-image.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAgB5C;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,0BA8CxB,CAAC;AAEH,eAAe,aAAa,CAAC"}
+{"version":3,"file":"read-image.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/read-image.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AAgBtD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,eAsDxB,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/dist/tools/utils/read-image.js

@@ -14,17 +14,22 @@ function mimeTypeForPath(path) {
     return MIME_TYPES[extname(path).toLowerCase()] ?? "image/png";
 }
 /**
- * Reads an image straight off disk and hands it to the agent as an image
- * tool-output — same shape and same downstream handling as
- * `browser-screenshot` (see BaseAgent#resolveToolOutputForModel): depending
- * on how the agent is configured, the raw bytes go straight to the main
- * model, or a separate image-capable provider describes it first so the
- * main conversation doesn't have to carry image bytes.
+ * Reads an image straight off disk and describes it itself, via
+ * `mcp.executeProvider(toolCallId, "image-describer", { parts })` — works
+ * identically whether this tool is registered directly on an `MCPClient` or
+ * on a sandboxed/remote `MCPServer` (see `MCP#executeProvider` in mcp.ts). The
+ * raw image bytes never leave this tool; only the resulting text
+ * description is returned. Usage is recorded on the trusted side of that
+ * call, not by this tool — see `BaseAgent#executeProvider`. `parts` (not a
+ * plain `content` string) is what actually reaches the provider as a real
+ * image — every built-in `AIProvider` only builds a multimodal image block
+ * from `Message.parts`, so a base64 string folded into `content` would be
+ * sent as literal text instead.
  */
 export const ReadImageTool = () => new MCPTool({
     name: "read-image",
-    description: "read an image file from disk and hand it to the agent. works just like browser-screenshot: returns an image tool-output — depending on how the agent is configured, the raw image may be handed directly to the model, or first described by a separate image-capable AI so the main conversation doesn't have to carry image bytes. " +
-        "use `focusHint` to tell that description step what you actually care about (e.g. 'read out any visible text' or 'check whether the chart trend is up or down'), so the resulting description is useful for your task instead of a generic caption.",
+    description: "read an image file from disk and get back a text description of it. " +
+        "use `focusHint` to tell the description step what you actually care about (e.g. 'read out any visible text' or 'check whether the chart trend is up or down'), so the resulting description is useful for your task instead of a generic caption.",
     inputs: [
         {
             name: "path",
@@ -39,7 +44,7 @@ export const ReadImageTool = () => new MCPTool({
             required: false,
         },
     ],
-    execute: async (_envID, inputs) => {
+    execute: async (_envID, inputs, toolCallId, mcp) => {
         const { path, focusHint } = inputs;
         if (!path || typeof path !== "string") {
             throw new Error("path must be a non-empty string");
@@ -56,14 +61,19 @@ export const ReadImageTool = () => new MCPTool({
                 throw new Error(`"${path}" is a directory, not a file`);
             throw err;
         }
-        return {
-            type: "image",
-            output: {
-                image,
-                mimeType: mimeTypeForPath(fullPath),
-                ...(focusHint ? { focusHint } : {}),
-            },
-        };
+        if (!mcp || !toolCallId) {
+            throw new Error("read-image requires an MCP context");
+        }
+        const instruction = focusHint
+            ? `Describe this image concisely for another AI agent that cannot see it. Focus specifically on: ${focusHint}`
+            : "Describe this image concisely for another AI agent that cannot see it. Mention layout, visible text, colors, and anything that looks unusual or broken.";
+        const { output } = await mcp.executeProvider(toolCallId, "image-describer", {
+            parts: [
+                { type: "text", text: instruction },
+                { type: "image", image, mimeType: mimeTypeForPath(fullPath) },
+            ],
+        });
+        return { description: output.content };
     },
 });
 export default ReadImageTool;

package/dist/tools/utils/read-image.js.map

@@ -1 +1 @@
-{"version":3,"file":"read-image.js","sourceRoot":"","sources":["../../../src/tools/utils/read-image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,MAAM,UAAU,GAA2B;IACvC,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;CACtB,CAAC;AAEF,SAAS,eAAe,CAAC,IAAY;IACjC,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,WAAW,CAAC;AAClE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAC;IAC3C,IAAI,EAAE,YAAY;IAClB,WAAW,EACP,uUAAuU;QACvU,oPAAoP;IACxP,MAAM,EAAE;QACJ;YACI,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,4EAA4E;YACzF,QAAQ,EAAE,IAAI;SACjB;QACD;YACI,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,4CAA4C;YACzD,QAAQ,EAAE,KAAK;SAClB;KACJ;IACD,OAAO,EAAE,KAAK,EAAE,MAAc,EAAE,MAA2B,EAAgB,EAAE;QACzE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;QAEnC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACvD,CAAC;QAED,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAEnC,IAAI,KAAa,CAAC;QAClB,IAAI,CAAC;YACD,KAAK,GAAG,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,GAAG,CAAC,CAAC;YACzE,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,8BAA8B,CAAC,CAAC;YACnF,MAAM,GAAG,CAAC;QACd,CAAC;QAED,OAAO;YACH,IAAI,EAAE,OAAO;YACb,MAAM,EAAE;gBACJ,KAAK;gBACL,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC;gBACnC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtC;SACJ,CAAC;IACN,CAAC;CACJ,CAAC,CAAC;AAEH,eAAe,aAAa,CAAC"}
+{"version":3,"file":"read-image.js","sourceRoot":"","sources":["../../../src/tools/utils/read-image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,MAAM,UAAU,GAA2B;IACvC,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;CACtB,CAAC;AAEF,SAAS,eAAe,CAAC,IAAY;IACjC,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,WAAW,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAC;IAC3C,IAAI,EAAE,YAAY;IAClB,WAAW,EACP,sEAAsE;QACtE,mPAAmP;IACvP,MAAM,EAAE;QACJ;YACI,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,4EAA4E;YACzF,QAAQ,EAAE,IAAI;SACjB;QACD;YACI,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,4CAA4C;YACzD,QAAQ,EAAE,KAAK;SAClB;KACJ;IACD,OAAO,EAAE,KAAK,EAAE,MAAc,EAAE,MAA2B,EAAE,UAAmB,EAAE,GAAS,EAAgB,EAAE;QACzG,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;QAEnC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACvD,CAAC;QAED,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAEnC,IAAI,KAAa,CAAC;QAClB,IAAI,CAAC;YACD,KAAK,GAAG,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,GAAG,CAAC,CAAC;YACzE,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,8BAA8B,CAAC,CAAC;YACnF,MAAM,GAAG,CAAC;QACd,CAAC;QAED,IAAI,CAAC,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAC1D,CAAC;QAED,MAAM,WAAW,GAAG,SAAS;YACzB,CAAC,CAAC,iGAAiG,SAAS,EAAE;YAC9G,CAAC,CAAC,yJAAyJ,CAAC;QAEhK,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,UAAU,EAAE,iBAAiB,EAAE;YACxE,KAAK,EAAE;gBACH,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE;gBACnC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE;aAChE;SACJ,CAAC,CAAC;QAEH,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IAC3C,CAAC;CACJ,CAAC,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/docs/agents.md

@@ -11,26 +11,36 @@
 ```ts
 new BaseAgent({
   instruction: string;
+  safetyPolicies?: string;   // default: "" — see "Guardrail system prompt" below
   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;
+    compactMemory: string;
+    retiredMessages: Message[];   // complete, ever-appended history of retired messages — each Message carries its own usage/timestamp
+    messagesCompact: Message[];   // the working context currently replayed to the provider every turn
+  };
+  features?: {
+    executeProviderFromMCPTool?: boolean;   // default: false — see "executeProvider feature flag" below
   };
 });
 ```
 
-`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.
+### Guardrail system prompt
+
+`safetyPolicies` is a separate `role: "system"` message, sent as its own leading entry ahead of the regular system prompt (see [Instructions, skills, and memory](#instructions-skills-and-memory-in-the-system-prompt)) on every main-provider `chat()` call in the run loop. Keep house rules/guardrails here rather than folding them into `instruction`, since it's a separate, cache-stable prefix ahead of the rest of the system prompt.
+
+It is **not** prepended on an `executeProvider` call (see below) — stuffing a policy paragraph ahead of a narrow, single-purpose call (e.g. "describe this image") measurably degrades that call's output, and not every registered provider role even accepts a `system` message the way the main LLM does. A pre-dispatch content-safety check is the intended replacement there; not implemented yet.
+
+### `executeProvider` feature flag
+
+A tool's `execute()` can reach a registered `AIProvider` directly via `mcp.executeProvider(toolCallId, type, input)` (see [Tools](./tools.md#mcpexecuteprovider--calling-a-provider-from-inside-a-tool)) — a bigger trust surface than a tool that only returns data to the model, since it lets a tool spend real provider calls (and, per the point above, without a guardrail system prompt ahead of them). It's off by default: `BaseAgent#executeProvider` throws immediately unless `features.executeProviderFromMCPTool` was set `true` on construction. This gates every role uniformly (`image-describer` included) — enable it once you're ready to trust the tools you've allowed with direct provider access.
+
+`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. `safetyPolicies` and `features` pass straight through to the underlying `BaseAgent`.
+
+Token accounting no longer lives in `initData` as separate counters — every `Message` carries its own `usage` (see [Token accounting](#token-accounting)), so `retiredMessages`/`messagesCompact` alone are enough to resume with full token history intact.
 
 ## The run loop
 
@@ -60,6 +70,8 @@ Practical implication: don't treat an early queued call's resolved `run()` promi
 
 `immediateStop()` requests the same stop but returns right away without waiting for confirmation, **and** aborts the in-flight `chat()` call to the main provider immediately — the underlying HTTP request is cancelled rather than left to run to completion, so no further output tokens get generated (and billed) past that point. Input tokens, and any output already generated before the abort landed, are already committed — cancelling can't retroactively make those free. This is the one to reach for when a call has to be killed regardless of how far through it is (e.g. a credit balance that just went negative). A tool dispatch already in progress isn't aborted (tools have no generic cancellation hook) — the loop stops as soon as that call returns. Abort support is real for Anthropic, OpenAI, and DeepSeek (both streaming and non-streaming); for Ollama it only takes effect on streaming calls — see the note in `ollama-provider.ts`.
 
+If you're deciding *when* to call `immediateStop()` from outside — e.g. against an external credit/cost system — watch `usage` on the `StreamCallback` chunks (see [Streaming](./streaming.md)) rather than waiting for `run()` to resolve: it's the same callback passed into `run()`, forwarded straight through to the provider, so external code sees the same numbers `BaseAgent` itself uses to build `Message.usage`. Note this is only genuinely live for Anthropic — the other three providers only report usage once a turn is already complete, so for them there's no earlier signal to react to, cancellation-timing-wise, than the final chunk.
+
 For a **streaming** call, an abort doesn't throw the turn away: `chat()` resolves normally with whatever text, thinking, and tool calls were already accumulated before the cutoff — the same as if the model had naturally stopped there — so anything already sent to `streamCallback` still ends up recorded in message history instead of vanishing. A tool call the model was still in the middle of generating when the abort hit is dropped even then (its arguments may be truncated JSON); only tool calls that had already fully finished are included — e.g. if the model requested 3 tool calls and the abort landed while the 3rd was still streaming, only the first 2 come back. For a **non-streaming** call there's nothing to salvage (the API only returns a response once, in full) — abort there still surfaces as a thrown error, and `BaseAgent` discards that turn entirely rather than recording a broken one.
 
 `stop()` is a deprecated alias for `safeStop()` and will be removed in the 1.0.0 major release.
@@ -74,37 +86,50 @@ OrbitX never truncates or deletes conversation history. Compaction happens throu
 
 Calling `compact_memory`:
 
-1. Replaces the running `memory` string with `new_memory`, which is injected into every future system prompt (`MEMORY:` section).
-2. Clears `messagesCompact` — the *working* context sent to the provider each turn.
-3. Leaves `messagesFull` — the complete, ever-appended history — untouched, so nothing is lost; it's just no longer replayed to the model every turn.
-4. Rolls the current token counters into the lifetime totals (see [Token accounting](#token-accounting)) and resets them to zero.
+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.
+2. Moves everything currently in `messagesCompact` — the *working* context sent to the provider each turn — into `retiredMessages`, then clears `messagesCompact`. 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.
+
+Before each turn, `BaseAgent` also checks the current context size: the summed `inputMissTokens` of every message's `"main"` usage entry across `messagesCompact` (see [Token accounting](#token-accounting)) — a cheap proxy for context size, not a precise replay-cost measurement. When that sum exceeds `maxMemorizeToken`, the agent doesn't compact on the model's behalf — instead it appends a `role: "user"` message telling the model to call `compact_memory` before doing anything else, and loops back for another turn. This keeps compaction on the same native tool-call path the model already uses for everything else, rather than a side-channel the model never sees; a model that ignores the nudge (rare, since the instruction is explicit) will simply see it repeated on the next turn until it complies.
 
-`BaseAgent` also tracks two token totals per run: `currentInputMissTokens` (uncached input) and `currentLastOutputTokens` (the last turn's output). When their sum exceeds `maxMemorizeToken`, the agent doesn't compact on the model's behalf — instead it appends a `role: "user"` message telling the model to call `compact_memory` before doing anything else, and loops back for another turn. This keeps compaction on the same native tool-call path the model already uses for everything else, rather than a hidden side-channel; a model that ignores the nudge (rare, since the instruction is explicit) will simply see it repeated on the next turn until it complies.
+This nudge message (and its matching `StreamCallback` chunk) is marked `hidden: true`, since it's `BaseAgent` talking to the model on the caller's behalf, not something a human said or the model produced — a chat UI built on this SDK should filter it out of what it shows an end user, the same way it wouldn't show raw system-prompt text. See [Streaming](./streaming.md) for the full `Message`/chunk field reference.
 
 `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`, the six main-loop token counters, and the two image-usage counters (`imageInputMissTokens`, `imageOutputTokens` — see [Token accounting](#token-accounting)). 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).
+`getCurrentAgentStates()` returns exactly the shape expected by the `initData` constructor option — `compactMemory`, `retiredMessages`, `messagesCompact`. 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, since every message already carries its own `usage`. See the example in [Getting Started](./getting-started.md#recovering-an-agents-state).
 
-The two image counters are optional on `initData` — a snapshot taken before image-usage tracking existed still loads, with both defaulting to `0`.
+A snapshot taken with an older SDK version, before per-message `usage` existed, still loads fine — messages with no `usage` field just contribute `0` to every token total below.
 
 ## Token accounting
 
-Four read methods, all returning `{ total, inputHit, inputMiss, output }`:
+Token usage lives on `Message.usage` (`MessageUsage[]`), not on separate counters — `BaseAgent` populates it as `chat()` responses come back, and the four read methods below are pure derived sums over `retiredMessages`/`messagesCompact`. There's no rollover bookkeeping to keep in sync on compaction (see [Memory compaction](#memory-compaction)): a message lives in exactly one of `retiredMessages` (retired) or `messagesCompact` (active) at a time — they're disjoint, not overlapping — so "already compacted away" is simply `retiredMessages` itself, with no slicing required. The complete history at any point is the concatenation of the two, in that order, not `retiredMessages` alone.
+
+Each entry in `Message.usage` is one of:
+
+```ts
+{ type: ProviderType; unit: "tokens"; inputMissTokens: number; inputCacheTokens: number; outputTokens: number }
+{ type: ProviderType; unit: "cost"; cost: number }
+```
+
+`type` is the provider role that produced the entry (see [Provider roles](./providers.md#provider-roles) — `"main"`, `"image-describer"`, or anything else registered/looked up). `unit` distinguishes real token billing from anything that isn't naturally token-shaped — an image/audio/3D-generation call billed as a flat price reports `unit: "cost"` instead.
+
+**Attribution** — a `type: "main"` entry is set only on the assistant message a `chat()` call produced, straight from that call's own `inputMissTokens`/`inputCacheTokens`/`outputTokens`. There's no splitting or attribution onto the user/tool messages that triggered the call, and no per-message context-size measurement — a user or tool message never carries a `"main"` entry. These are real, provider-reported numbers (Anthropic's `cache_read_input_tokens`/`cache_creation_input_tokens`, DeepSeek's `prompt_cache_hit_tokens`/`prompt_cache_miss_tokens`, OpenAI's `prompt_tokens_details.cached_tokens`), not a client-side guess — see [Providers](./providers.md) for what each one actually reports and Ollama's lack of any cache concept (`inputCacheTokens` always `0` there).
+
+The compaction trigger (see [Memory compaction](#memory-compaction)) sums `inputMissTokens` across every assistant message's `"main"` entry in `messagesCompact` as a cheap proxy for context size — not a precise measurement of what replaying `messagesCompact` right now would actually cost, since each entry reflects the call that produced that one assistant message, not the whole context at that point.
+
+Every other `type` entry comes from a tool calling `mcp.executeProvider(toolCallId, type, input)` (see [Tools](./tools.md#mcpexecuteprovider--calling-a-provider-from-inside-a-tool)) — but the entry itself is recorded by `BaseAgent`, the instant the real provider call resolves, never by the tool's own return value. This is deliberate: a tool can't under-report (or hide) what it spent, because it never holds the usage number to begin with — `BaseAgent` keys it by `toolCallId` and moves it onto that call's result `Message.usage` only after `execute()` returns, regardless of what the tool itself returns. `read-image`/`browser-screenshot`, for example, trigger a `type: "image-describer", unit: "tokens"` entry with no hit/miss split (each call is a fresh, standalone chat issued directly against the resolved provider by `BaseAgent`, so every input token counts as `inputMissTokens`).
 
-- `getCurrentTotalTokens()` — main-loop tokens used since the last memory compaction.
-- `getFullTotalTokens()` — main-loop tokens used across all *prior* compacted segments.
-- `getImageTotalTokens()` — tokens used by every `ImageDescriber` call this agent has made (see [Providers](./providers.md#two-provider-roles-main--image)), tracked separately since a one-off image-description call has no conversation history to compact and so doesn't fit the current/full split.
-- `getTotalTokens()` — the sum of all three (lifetime total for this agent instance, main loop and image calls combined).
+`executeProvider` picks `unit: "tokens"` vs `unit: "cost"` dynamically from what the provider's `ChatResponse` actually reported, rather than assuming one or the other: if the response set `cost` (a flat, non-token price — see [`ChatResponse`](./providers.md#writing-a-custom-provider)), the entry is `unit: "cost"`; otherwise it falls back to the token fields (`inputMissTokens`/`inputCacheTokens`/`outputTokens`, each defaulting to `0` if the provider omitted them). Every built-in provider (Anthropic/OpenAI/DeepSeek/Ollama) is token-billed and always takes the token path — `cost` only comes into play for a custom provider registered under an image/video/audio-generation-style role that bills per-request instead of per-token.
 
-`inputHit`/`inputMiss` on the main-loop methods 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 — this is a heuristic `BaseAgent` computes itself from the growing/reset conversation history: whatever was `inputMiss` last turn rolls into `inputHit` this turn, and `inputMiss` becomes this turn's raw input token count.
+**The four read methods:**
 
-`getImageTotalTokens()`'s `inputHit` is always `0` — each `ImageDescriber` call is a fresh, standalone chat with no prior turns to replay, so there's nothing for that heuristic to apply to. Every input token an image call reports counts as `inputMiss`.
+- `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.
 
 ## 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.
+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.
 
 ## Multi-agent: `WorkerAgent` *(experimental)*
 

package/docs/api-reference.md

@@ -6,12 +6,11 @@ Flat index of every public export from `orbitx` (see `src/index.ts`), grouped by
 
 - `AIProvider` (abstract base class)
 - `OpenAIProvider`, `AnthropicProvider`, `DeepSeekProvider`, `OllamaProvider`
-- `resolveAgentProviders()`
-- Types: `AgentProviderRole`, `AgentProviderEntry`, `AgentProvidersInput`, `ResolvedAgentProviders`
-- Types: `ChatResponse`, `Message`, `StreamCallback`, `ToolSchema`, `ToolCallRequest`, `MessageContentPart`, `ProviderCapabilities`
+- `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`
-- `ImageDescriber`, type `ImageDescription` — 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. `describe()` returns an `ImageDescription` (`{ description, inputTokens, outputTokens }`), not a bare string.
 - `toOpenAIFunctionTools()` — translates a `ToolSchema[]` into OpenAI's function-calling format; exported for building custom providers.
 
 ## Agents — see [Agents](./agents.md)
@@ -23,21 +22,21 @@ Flat index of every public export from `orbitx` (see `src/index.ts`), grouped by
 
 ## Tools — see [Tools](./tools.md)
 
-- `MCPTool`, `MCPCustomClass`, `generateRefId()`, `normalizeToolOutput()`
+- `MCPTool`, `generateRefId()`, `normalizeToolOutput()`
 - Types: `MCP`, `MCPToolOutput`
 
-Built-in tool factories, grouped by domain (each domain also exports a `*Tools()` array and a `*Interaction` EventEmitter):
+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`, `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` |
+| 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` |
-| 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) |
+| Multi-agent *(experimental)* | `AgentTools(availableAgents, options?)`, `AgentListTool`, `AgentHireTool`, `AgentPromptTool`, `AgentReportTool`, `AgentRegistry`, type `AgentInfo`, type `AgentToolsOptions` — see [Agents](./agents.md#multi-agent-workeragent-experimental) |
 
 ## Skills — see [Skills](./skills.md)
 

package/docs/getting-started.md

@@ -49,7 +49,7 @@ Every provider implements the same `AIProvider` interface, so switching models i
 
 ## 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.):
+`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";
@@ -69,7 +69,7 @@ const agent = new SimpleAgent({
 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).
+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
 

package/docs/mcp-architecture.md

@@ -26,9 +26,12 @@ Registers tools and listens on its `connection` for incoming tool-call requests,
 ```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>;
+mcpClient.callTool(name: string, inputs: Record<string, any>, toolCallId?: string): Promise<MCPToolOutput>;
+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`.
+
 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.
@@ -100,4 +103,13 @@ Pass literal strings (e.g. an API key you never want echoed back to the model) o
 
 ## 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.
+Both `MCPServer` and `MCPClient` extend the abstract `MCP` class — `getStorage()`, `getRNG()`, and `executeProvider(toolCallId, type, input)`. Tool `execute` functions receive the calling `MCP` instance directly, as their 4th argument (after a `toolCallId` — see [Tools](./tools.md#the-mcptool-shape)), so a tool can reach storage/RNG scoped to whichever client dispatched the call.
+
+`executeProvider` is where the two subclasses genuinely differ:
+
+- **`MCPClient`** answers it in-process, by delegating to a handler `BaseAgent` installs on the client via `setExecuteProviderHandler(...)` at construction time. `MCPClient` itself never imports anything from `ai-provider.ts` — it just holds an opaque callback.
+- **`MCPServer`** has no such handler — it never touches a provider directly. It proxies the request over its `MCPConnection` (an `executeProvider`/`executeProviderResponse` message pair, mirroring `toolCall`/`toolCallCallback` but initiated by the server instead of the client) to whichever `MCPClient` is attached, which runs the same installed handler and answers back.
+
+So a **server-registered** tool — the kind meant to run inside `MCPComputer`'s sandbox, or in a genuinely separate process over IPC/WS — can still call `mcp.executeProvider(...)` and get a real result, without a provider instance (or the credentials it holds) ever crossing into that process. Only a scoped request/response for one call does. This is deliberate: filesystem/browser-touching tools like `ReadImageTool`/`BrowserScreenshotTool` are exactly the kind this doc already recommends sandboxing (see above), and they both need a provider to do their job.
+
+That accessor also carries provider access (`agent.getProvider(type)`/`getProviders(type)`) — but **only for a tool dispatched by `MCPClient.callTool`'s local branch** (a tool registered directly on the client, per the section above). `MCPServer`'s dispatch (both the `toolCall` handler above and, transitively, anything a remote/sandboxed tool triggers) builds an accessor with no provider registry behind it at all, so `getProvider`/`getProviders` there always resolve `undefined`. This is deliberate, not a gap to work around: provider instances hold API keys, and `MCPServer` is precisely the thing that runs inside a separate process or an `MCPComputer` sandbox — credentials never need to, and never do, cross that boundary. A tool that needs to call a provider directly (e.g. to describe an image it just read) has to be registered on the `MCPClient`, in the same process as the agent that owns those providers.