@thenajs/tools 0.6.0 → 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 castroneto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALING IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { ShellTool } from "./shell.tool.js";
+export { ParallelTool } from "./parallel.tool.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { ShellTool } from "./shell.tool.js";
+export { ParallelTool } from "./parallel.tool.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/parallel.tool.d.ts

@@ -0,0 +1,21 @@
+import type { ToolOutput, ToolType } from "@thenajs/core";
+/**
+ * Executa várias tools do próprio agente numa única chamada ao modelo.
+ *
+ * O ganho é **round-trip**: ler três arquivos custa uma ida ao modelo em vez de
+ * três.
+ *
+ * Ela não recebe tool nenhuma — o `@tools()` entrega as irmãs **já embrulhadas**
+ * na cadeia de middleware. É isso que faz cada chamada interna continuar abrindo
+ * o próprio nó no report e passando pelos hooks, pela autorização, pelo
+ * orçamento e pela política de erro.
+ */
+export declare class ParallelTool {
+    execute({ calls }: {
+        calls: {
+            tool: string;
+            args: Record<string, unknown>;
+        }[];
+    }, siblings: ToolType[]): Promise<ToolOutput>;
+}
+//# sourceMappingURL=parallel.tool.d.ts.map

package/dist/parallel.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.tool.d.ts","sourceRoot":"","sources":["../src/parallel.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG1D;;;;;;;;;;GAUG;AACH,qBAoBa,YAAY;IACjB,OAAO,CACF,EAAE,KAAK,EAAE,EAAE;QAAE,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,EAAE,CAAA;KAAE,EACvE,QAAQ,EAAE,QAAQ,EAAE,GAC5B,OAAO,CAAC,UAAU,CAAC;CA4CvB"}

package/dist/parallel.tool.js

@@ -0,0 +1,93 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Tool, input, toToolOutput, tools } from "@thenajs/core";
+import { z } from "zod";
+/**
+ * Executa várias tools do próprio agente numa única chamada ao modelo.
+ *
+ * O ganho é **round-trip**: ler três arquivos custa uma ida ao modelo em vez de
+ * três.
+ *
+ * Ela não recebe tool nenhuma — o `@tools()` entrega as irmãs **já embrulhadas**
+ * na cadeia de middleware. É isso que faz cada chamada interna continuar abrindo
+ * o próprio nó no report e passando pelos hooks, pela autorização, pelo
+ * orçamento e pela política de erro.
+ */
+let ParallelTool = class ParallelTool {
+    async execute({ calls }, siblings) {
+        // Sem a si mesma: `parallel` dentro de `parallel` só aninharia lote em lote.
+        const available = siblings.filter((t) => t.name !== "parallel");
+        const results = await Promise.all(calls.map(async (call) => {
+            const target = available.find((t) => t.name === call.tool);
+            if (!target) {
+                const names = available.map((t) => t.name).join(", ");
+                return {
+                    content: `unknown tool. Available: ${names}`,
+                    isError: true,
+                };
+            }
+            try {
+                // O schema da irmã é obrigatório aqui: no caminho normal quem valida
+                // os argumentos é o provider, e o `buildToolStep` embrulha o `execute`
+                // sem validar. Sem este `parse`, a tool receberia lixo tipado errado.
+                const args = target.schema.parse(call.args);
+                return toToolOutput(await target.execute(args));
+            }
+            catch (err) {
+                // Falha de uma chamada não pode derrubar o lote: as irmãs já custaram
+                // trabalho, e o modelo consegue corrigir só a que errou.
+                return { content: err.message, isError: true };
+            }
+        }));
+        return {
+            content: results
+                .map((r, i) => {
+                const status = r.isError ? "error" : "ok";
+                return `[${i + 1}] ${calls[i].tool} → ${status}\n${r.content}`;
+            })
+                .join("\n\n"),
+            // Erro só quando **tudo** falhou: um lote parcialmente bom não é um turno
+            // perdido, e marcá-lo como erro faria o `maxFails` do loop contar uma
+            // falha que não houve.
+            isError: results.every((r) => r.isError),
+        };
+    }
+};
+__decorate([
+    __param(0, input()),
+    __param(1, tools()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Array]),
+    __metadata("design:returntype", Promise)
+], ParallelTool.prototype, "execute", null);
+ParallelTool = __decorate([
+    Tool({
+        name: "parallel",
+        description: "Run several of the other available tools at once and return every result. " +
+            "Use it when you need two or more calls that do not depend on each other. " +
+            "If one call needs another's result, make them in separate turns.",
+        schema: z.object({
+            calls: z
+                .array(z.object({
+                tool: z.string().describe("the name of one of the other available tools"),
+                args: z
+                    .record(z.string(), z.unknown())
+                    .describe("that tool's arguments, in the shape it declares"),
+            }))
+                .min(2, "use this tool only for two or more calls")
+                .max(8),
+        }),
+    })
+], ParallelTool);
+export { ParallelTool };
+//# sourceMappingURL=parallel.tool.js.map

package/dist/parallel.tool.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thenajs/tools",
-  "version": "0.6.0",
-  "description": "Tools prontas para agentes ThenaJS (ex.: ShellTool).",
+  "version": "0.11.0",
+  "description": "Tools prontas para agentes ThenaJS (ex.: ParallelTool).",
   "license": "MIT",
   "author": "castroneto",
   "repository": {
@@ -22,8 +22,16 @@
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=20.19"
+  },
   "dependencies": {
-    "@thenajs/core": "^0.6.0",
+    "@thenajs/core": "^0.11.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
     "zod": "^4.0.0"
   }
 }

package/dist/shell.tool.d.ts

@@ -1,6 +0,0 @@
-export declare class ShellTool {
-    execute({ command }: {
-        command: string;
-    }): Promise<string>;
-}
-//# sourceMappingURL=shell.tool.d.ts.map

package/dist/shell.tool.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"shell.tool.d.ts","sourceRoot":"","sources":["../src/shell.tool.ts"],"names":[],"mappings":"AAOA,qBAKa,SAAS;IACd,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE;CAI/C"}

package/dist/shell.tool.js

@@ -1,26 +0,0 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
-import { Tool } from "@thenajs/core";
-import { z } from "zod";
-const run = promisify(exec);
-let ShellTool = class ShellTool {
-    async execute({ command }) {
-        const { stdout, stderr } = await run(command);
-        return stdout || stderr;
-    }
-};
-ShellTool = __decorate([
-    Tool({
-        name: "shell",
-        description: "Executa um comando shell e retorna a saída.",
-        schema: z.object({ command: z.string() }),
-    })
-], ShellTool);
-export { ShellTool };
-//# sourceMappingURL=shell.tool.js.map

package/dist/shell.tool.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"shell.tool.js","sourceRoot":"","sources":["../src/shell.tool.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AAOrB,IAAM,SAAS,GAAf,MAAM,SAAS;IACpB,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAuB;QAC5C,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,MAAM,IAAI,MAAM,CAAC;IAC1B,CAAC;CACF,CAAA;AALY,SAAS;IALrB,IAAI,CAAC;QACJ,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,6CAA6C;QAC1D,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;KAC1C,CAAC;GACW,SAAS,CAKrB"}