orbitx 0.2.1 → 0.2.4

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/edit-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit-file.d.ts","sourceRoot":"","sources":["../../../src/tools/fs/edit-file.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,eAAO,MAAM,cAAc,8BAiFzB,CAAC;AAEH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"edit-file.d.ts","sourceRoot":"","sources":["../../../src/tools/fs/edit-file.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,eAAO,MAAM,cAAc,8BAkFzB,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/dist/tools/fs/edit-file.js

@@ -4,7 +4,7 @@ import { FsInteraction } from "./interaction.js";
 import { resolvePath, toLines } from "./utils.js";
 export const FsEditFileTool = () => new MCPTool({
     name: "fs-edit-file",
-    description: "replace a specific line range in an existing file without rewriting the whole file. lines are 0-indexed; the range [offsetLine, offsetLine+limitLine) is replaced entirely by `content` (use limitLine 0 to insert at offsetLine without deleting anything). read the file first (fs-read-file) to get accurate line numbers, since another edit may have shifted them.",
+    description: "replace a specific line range in an existing file without rewriting the whole file. lines are 1-indexed (line 1 is the first line of the file, matching fs-read-file); the range [offsetLine, offsetLine+limitLine) 1-indexed lines is replaced entirely by `content` (use limitLine 0 to insert before offsetLine without deleting anything; use offsetLine totalLines+1 to append at end of file). read the file first (fs-read-file) to get accurate line numbers, since another edit may have shifted them.",
     inputs: [
         {
             name: "path",
@@ -15,7 +15,7 @@ export const FsEditFileTool = () => new MCPTool({
         {
             name: "offsetLine",
             type: "number",
-            description: "0-indexed line to start replacing from",
+            description: "1-indexed line to start replacing from (line 1 is the first line of the file)",
             required: true,
         },
         {
@@ -34,8 +34,8 @@ export const FsEditFileTool = () => new MCPTool({
     customClass: new FsInteraction(),
     execute: async (_envID, inputs, _mcp, customClass) => {
         const { path, offsetLine, limitLine, content } = inputs;
-        if (typeof offsetLine !== "number" || offsetLine < 0) {
-            throw new Error("offsetLine must be a non-negative number");
+        if (typeof offsetLine !== "number" || offsetLine < 1) {
+            throw new Error("offsetLine is 1-indexed (line 1 is the first line of the file) and must be >= 1");
         }
         if (typeof limitLine !== "number" || limitLine < 0) {
             throw new Error("limitLine must be a non-negative number");
@@ -55,12 +55,13 @@ export const FsEditFileTool = () => new MCPTool({
             throw err;
         }
         const lines = toLines(raw);
-        if (offsetLine > lines.length) {
-            throw new Error(`offsetLine ${offsetLine} is past end of file (${lines.length} lines)`);
+        const index = offsetLine - 1;
+        if (index > lines.length) {
+            throw new Error(`offsetLine ${offsetLine} is past end of file (${lines.length} lines; use offsetLine ${lines.length + 1} to append)`);
         }
-        const removedCount = Math.min(limitLine, lines.length - offsetLine);
+        const removedCount = Math.min(limitLine, lines.length - index);
         const insertedLines = content.length === 0 ? [] : content.split(/\r\n|\r|\n/);
-        lines.splice(offsetLine, removedCount, ...insertedLines);
+        lines.splice(index, removedCount, ...insertedLines);
         await writeFile(fullPath, lines.join("\n"), { encoding: "utf-8" });
         return {
             message: "success",

package/dist/tools/fs/edit-file.js.map

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

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":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,qBAAqB,GAAG;IAC1B,cAAc;IACd,MAAM;IACN,OAAO;IACP,QAAQ;IACR,MAAM;IACN,OAAO;IACP,QAAQ;IACR,UAAU;IACV,SAAS;IACT,OAAO;CACV,CAAC;AAUF,KAAK,UAAU,IAAI,CACf,OAAe,EACf,SAAkB,EAClB,UAAuB,EACvB,KAAK,GAAG,CAAC;IAET,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAEhE,MAAM,OAAO,GAAY,EAAE,CAAC;IAE5B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QACpC,MAAM,UAAU,GAAG,WAAW,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAEzD,IAAI,IAAwB,CAAC;QAC7B,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;YACb,IAAI,CAAC;gBACD,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;YACxC,CAAC;YAAC,MAAM,CAAC;gBACL,IAAI,GAAG,SAAS,CAAC;YACrB,CAAC;QACL,CAAC;QAED,MAAM,KAAK,GAAU;YACjB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM;YACzE,IAAI;YACJ,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5C,CAAC;QAEF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEpB,IAAI,SAAS,IAAI,WAAW,IAAI,CAAC,UAAU,EAAE,CAAC;YAC1C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YACzE,OAAO,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;QAC9B,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAgB;IAC1D,IAAI,EAAE,aAAa;IACnB,WAAW,EACP,2TAA2T;IAC/T,MAAM,EAAE;QACJ;YACI,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,gDAAgD;YAC7D,QAAQ,EAAE,IAAI;SACjB;QACD;YACI,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,6BAA6B;YAC1C,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;SACjB;QACD;YACI,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,OAAO;YACb,WAAW,EACP,mMAAmM;YACvM,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,qBAAqB;SACjC;QACD;YACI,IAAI,EAAE,cAAc;YACpB,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,2EAA2E;YACxF,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,CAAC;SACb;QACD;YACI,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,iCAAiC;YAC9C,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,GAAG;SACf;KACJ;IACD,WAAW,EAAE,IAAI,aAAa,EAAE;IAChC,OAAO,EAAE,KAAK,EACV,MAAc,EACd,MAA2B,EAC3B,IAAU,EACV,WAA2B,EACf,EAAE;QACd,MAAM,EACF,IAAI,EACJ,SAAS,GAAG,KAAK,EACjB,WAAW,GAAG,qBAAqB,EACnC,YAAY,GAAG,CAAC,EAChB,WAAW,GAAG,GAAG,GACpB,GAAG,MAAM,CAAC;QAEX,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAEnC,WAAW,EAAE,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAE9D,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,WAAW,CAAC,CAAC;QAEhD,IAAI,OAAgB,CAAC;QACrB,IAAI,CAAC;YACD,OAAO,GAAG,SAAS;gBACf,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC;gBACxC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,GAAG,CAAC,CAAC;YAC9E,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,8BAA8B,CAAC,CAAC;YACpF,MAAM,GAAG,CAAC;QACd,CAAC;QAED,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;QACxE,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAEvC,OAAO;YACH,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,WAAW;YAClB,WAAW;YACX,YAAY,EAAE,KAAK;YACnB,WAAW;SACd,CAAC;IACN,CAAC;CACJ,CAAC,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/dist/tools/fs/read-file.js

@@ -15,9 +15,9 @@ export const FsReadFileTool = () => new MCPTool({
         {
             name: "offsetLine",
             type: "number",
-            description: "line offset to start reading from",
+            description: "1-indexed line number to start reading from (line 1 is the first line of the file)",
             required: false,
-            default: 0,
+            default: 1,
         },
         {
             name: "limitLine",
@@ -29,7 +29,7 @@ export const FsReadFileTool = () => new MCPTool({
     ],
     customClass: new FsInteraction(),
     execute: async (_envID, inputs, _mcp, customClass) => {
-        const { path, offsetLine = 0, limitLine = 2000 } = inputs;
+        const { path, offsetLine = 1, limitLine = 2000 } = inputs;
         const fullPath = resolvePath(path);
         customClass?.emitFsEvent({ type: "reading", path: fullPath });
         let raw;

package/dist/tools/fs/read-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"read-file.js","sourceRoot":"","sources":["../../../src/tools/fs/read-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAgB;IAC3D,IAAI,EAAE,cAAc;IACpB,WAAW,EACP,mHAAmH;IACvH,MAAM,EAAE;QACJ;YACI,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,2CAA2C;YACxD,QAAQ,EAAE,IAAI;SACjB;QACD;YACI,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,mCAAmC;YAChD,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,CAAC;SACb;QACD;YACI,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,+BAA+B;YAC5C,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,IAAI;SAChB;KACJ;IACD,WAAW,EAAE,IAAI,aAAa,EAAE;IAChC,OAAO,EAAE,KAAK,EACV,MAAc,EACd,MAA2B,EAC3B,IAAU,EACV,WAA2B,EACf,EAAE;QACd,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAE1D,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAEnC,WAAW,EAAE,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAE9D,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACD,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,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,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;QAEhG,OAAO;YACH,OAAO;YACP,UAAU;YACV,SAAS;YACT,OAAO;SACV,CAAC;IACN,CAAC;CACJ,CAAC,CAAC;AAEH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"read-file.js","sourceRoot":"","sources":["../../../src/tools/fs/read-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAgB;IAC3D,IAAI,EAAE,cAAc;IACpB,WAAW,EACP,mHAAmH;IACvH,MAAM,EAAE;QACJ;YACI,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,2CAA2C;YACxD,QAAQ,EAAE,IAAI;SACjB;QACD;YACI,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,oFAAoF;YACjG,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,CAAC;SACb;QACD;YACI,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,+BAA+B;YAC5C,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,IAAI;SAChB;KACJ;IACD,WAAW,EAAE,IAAI,aAAa,EAAE;IAChC,OAAO,EAAE,KAAK,EACV,MAAc,EACd,MAA2B,EAC3B,IAAU,EACV,WAA2B,EACf,EAAE;QACd,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAE1D,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAEnC,WAAW,EAAE,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAE9D,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACD,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,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,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;QAEhG,OAAO;YACH,OAAO;YACP,UAAU;YACV,SAAS;YACT,OAAO;SACV,CAAC;IACN,CAAC;CACJ,CAAC,CAAC;AAEH,eAAe,cAAc,CAAC"}

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

@@ -10,6 +10,13 @@ export declare function toLines(content: string): string[];
  * Slices an array of lines by offset/limit, clamping to bounds, and returns
  * both the slice and the total line count so callers can page through large
  * files without ever loading the whole thing into a response.
+ *
+ * `offsetLine` is 1-indexed (the first line of the file is line 1), matching
+ * the convention every fs tool that talks about line numbers uses — this is
+ * what LLMs already expect from editors/`cat -n`, and keeping it consistent
+ * with `fs-edit-file`'s `offsetLine` is the whole point: a line number read
+ * here can be pasted straight into an edit call without an off-by-one.
+ * `startLine`/`endLine` in the result are 1-indexed and inclusive.
  */
 export declare function paginateLines(lines: string[], offsetLine: number, limitLine: number): {
     content: string;

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/tools/fs/utils.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;;;;;EAUnF"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/tools/fs/utils.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;;;;;EAUnF"}

package/dist/tools/fs/utils.js

@@ -18,15 +18,22 @@ export function toLines(content) {
  * Slices an array of lines by offset/limit, clamping to bounds, and returns
  * both the slice and the total line count so callers can page through large
  * files without ever loading the whole thing into a response.
+ *
+ * `offsetLine` is 1-indexed (the first line of the file is line 1), matching
+ * the convention every fs tool that talks about line numbers uses — this is
+ * what LLMs already expect from editors/`cat -n`, and keeping it consistent
+ * with `fs-edit-file`'s `offsetLine` is the whole point: a line number read
+ * here can be pasted straight into an edit call without an off-by-one.
+ * `startLine`/`endLine` in the result are 1-indexed and inclusive.
  */
 export function paginateLines(lines, offsetLine, limitLine) {
     const totalLines = lines.length;
-    const start = Math.max(0, Math.min(offsetLine, totalLines));
+    const start = Math.max(0, Math.min(offsetLine - 1, totalLines));
     const end = Math.max(start, Math.min(start + limitLine, totalLines));
     return {
         content: lines.slice(start, end).join("\n"),
         totalLines,
-        startLine: start,
+        startLine: start + 1,
         endLine: end,
     };
 }

package/dist/tools/fs/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/tools/fs/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,OAAO,CAAC,OAAe;IACnC,OAAO,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe,EAAE,UAAkB,EAAE,SAAiB;IAChF,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IACrE,OAAO;QACH,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC3C,UAAU;QACV,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,GAAG;KACf,CAAC;AACN,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/tools/fs/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,OAAO,CAAC,OAAe;IACnC,OAAO,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe,EAAE,UAAkB,EAAE,SAAiB;IAChF,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IACrE,OAAO;QACH,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC3C,UAAU;QACV,SAAS,EAAE,KAAK,GAAG,CAAC;QACpB,OAAO,EAAE,GAAG;KACf,CAAC;AACN,CAAC"}

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

@@ -1,4 +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>[];
 //# 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;AAOvC,eAAO,MAAM,SAAS,qDAGrB,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,qDAIrB,CAAC"}

package/dist/tools/utils/index.js

@@ -1,9 +1,12 @@
 export { GetCurrentTimeTool } from "./get-current-time.js";
 export { DelayTool } from "./delay.js";
+export { ReadImageTool } from "./read-image.js";
 import { GetCurrentTimeTool } from "./get-current-time.js";
 import { DelayTool } from "./delay.js";
+import { ReadImageTool } from "./read-image.js";
 export const UtilTools = () => [
     GetCurrentTimeTool(),
-    DelayTool()
+    DelayTool(),
+    ReadImageTool()
 ];
 //# sourceMappingURL=index.js.map

package/dist/tools/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","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;AAGvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC;IAC3B,kBAAkB,EAAE;IACpB,SAAS,EAAE;CACd,CAAC"}
+{"version":3,"file":"index.js","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;AAGhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC;IAC3B,kBAAkB,EAAE;IACpB,SAAS,EAAE;IACX,aAAa,EAAE;CAClB,CAAC"}

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

@@ -0,0 +1,12 @@
+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.
+ */
+export declare const ReadImageTool: () => MCPTool<undefined>;
+export default ReadImageTool;
+//# sourceMappingURL=read-image.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,70 @@
+import { readFile } from "fs/promises";
+import { extname } from "path";
+import { MCPTool } from "../../core/mcp.js";
+import { resolvePath } from "../fs/utils.js";
+const MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+};
+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.
+ */
+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.",
+    inputs: [
+        {
+            name: "path",
+            type: "string",
+            description: "absolute or cwd-relative path to the image file (png, jpg, gif, webp, bmp)",
+            required: true,
+        },
+        {
+            name: "focusHint",
+            type: "string",
+            description: "what to focus on when describing the image",
+            required: false,
+        },
+    ],
+    execute: async (_envID, inputs) => {
+        const { path, focusHint } = inputs;
+        if (!path || typeof path !== "string") {
+            throw new Error("path must be a non-empty string");
+        }
+        const fullPath = resolvePath(path);
+        let image;
+        try {
+            image = (await readFile(fullPath)).toString("base64");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                throw new Error(`no file found at "${path}"`);
+            if (err.code === "EISDIR")
+                throw new Error(`"${path}" is a directory, not a file`);
+            throw err;
+        }
+        return {
+            type: "image",
+            output: {
+                image,
+                mimeType: mimeTypeForPath(fullPath),
+                ...(focusHint ? { focusHint } : {}),
+            },
+        };
+    },
+});
+export default ReadImageTool;
+//# sourceMappingURL=read-image.js.map

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

@@ -0,0 +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"}

package/docs/agents.md

@@ -0,0 +1,181 @@
+# 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.
+
+### Calling `run()` again mid-flight: prompt coalescing, not truncation
+
+This is a deliberate design for absorbing multiple user prompts that arrive while the agent is still mid-turn (e.g. a chat UI where the user sends a couple of follow-up messages before the first reply lands) — not a bug, and nothing gets cut off mid-tool-call. The currently running loop iteration (one model turn plus all of that turn's tool dispatches) always finishes; only the *next* iteration is skipped once another `run()` call has queued:
+
+- **One call queues up:** the in-flight run finishes its current iteration and stops there; the queued call then runs its own fresh loop from scratch, in a context that already contains everything the first run produced (including any pending tool results).
+- **Multiple calls queue up:** every queued call except the last one has its prompt appended straight into history as a plain `role: "user"` message (with a matching stream chunk) and its own `run()` promise resolves immediately — no model turn is generated for that prompt specifically. The *last* queued call is the one that actually drives a real model turn, in a context that now includes every prompt that queued before it. The model's eventual reply addresses the whole accumulated batch at once, not each queued prompt individually.
+
+Practical implication: don't treat an early queued call's resolved `run()` promise as "the model has now answered this prompt" — for anything but the last queued call, it only means the prompt was recorded. Drive replies off `streamCallback` if you need to know when the model has actually responded.
+
+`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. Compaction happens through a real, always-available native tool — `compact_memory({ new_memory: string })` — 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 `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.
+
+`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.
+
+`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).
+
+The two image counters are optional on `initData` — a snapshot taken before image-usage tracking existed still loads, with both defaulting to `0`.
+
+## Token accounting
+
+Four read methods, all returning `{ total, inputHit, inputMiss, output }`:
+
+- `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).
+
+`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.
+
+`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`.
+
+## 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`, 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)
+
+- `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`, `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) |
+
+## 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`