@thenajs/tools 0.6.0 → 0.9.0

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { ShellTool } from "./shell.tool.js";
+export { ShellTool, shellTool } from "./shell.tool.js";
+export type { ShellToolOptions } from "./shell.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,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { ShellTool } from "./shell.tool.js";
+export { ShellTool, shellTool } from "./shell.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,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/shell.tool.d.ts

@@ -1,6 +1,55 @@
+import type { ToolType } from "@thenajs/core";
+export interface ShellToolOptions {
+    /** Teto de tempo do comando, em ms. Default: 30s. */
+    timeoutMs?: number;
+    /** Diretório de trabalho. Default: o do processo. */
+    cwd?: string;
+    /**
+     * Só executa comandos cujo **primeiro token** esteja nesta lista.
+     *
+     * É a única proteção real contra prompt injection nesta tool. Sem allowlist,
+     * qualquer coisa que o modelo escrever é executada com as permissões do
+     * processo.
+     *
+     * ```ts
+     * shellTool({ allow: ["ls", "cat", "grep", "git"] })
+     * ```
+     */
+    allow?: string[];
+    /** Teto de caracteres devolvidos ao modelo. Default: 8000. */
+    maxChars?: number;
+}
+/**
+ * Executa um comando shell.
+ *
+ * ## ⚠️ Leia antes de usar
+ *
+ * Esta tool dá ao modelo **execução arbitrária de comando** com as permissões
+ * do seu processo. Um agente que leia conteúdo de terceiro — um README, uma
+ * issue, um arquivo do repositório — pode ser induzido a executar o que
+ * estiver escrito lá. O framework não tem defesa contra prompt injection.
+ *
+ * Use `allow` sempre que o agente puder ver entrada não confiável:
+ *
+ * ```ts
+ * @Agent({ provider, prompt: "./a.agent.md", tools: [shellTool({ allow: ["git", "ls"] })] })
+ * ```
+ *
+ * Sem `allow`, restrinja o uso a ambiente controlado — sua máquina, um
+ * container descartável — e nunca a um serviço exposto.
+ */
+export declare function shellTool(options?: ShellToolOptions): ToolType;
+/**
+ * Versão sem configuração, para uso rápido em ambiente controlado.
+ *
+ * ⚠️ **Sem allowlist** — o modelo executa qualquer comando. Leia o aviso de
+ * `shellTool` antes de usar; para agente que vê entrada não confiável, prefira
+ * `shellTool({ allow: [...] })`.
+ */
 export declare class ShellTool {
-    execute({ command }: {
+    private readonly impl;
+    execute(args: {
         command: string;
-    }): Promise<string>;
+    }): Promise<string | import("@thenajs/core").ToolOutput>;
 }
 //# sourceMappingURL=shell.tool.d.ts.map

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"shell.tool.d.ts","sourceRoot":"","sources":["../src/shell.tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAa9C,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,QAAQ,CA4DlE;AAED;;;;;;GAMG;AACH,qBAKa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IAEpC,OAAO,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE;CAGlC"}

package/dist/shell.tool.js

@@ -9,17 +9,105 @@ import { promisify } from "node:util";
 import { Tool } from "@thenajs/core";
 import { z } from "zod";
 const run = promisify(exec);
+const schema = z.object({ command: z.string() });
+/** Teto de tempo padrão. Sem ele, um comando pendurado trava a run para sempre. */
+const DEFAULT_TIMEOUT = 30_000;
+/** Teto de saída devolvida ao modelo, para não entupir a janela de contexto. */
+const MAX_CHARS = 8_000;
+/**
+ * Executa um comando shell.
+ *
+ * ## ⚠️ Leia antes de usar
+ *
+ * Esta tool dá ao modelo **execução arbitrária de comando** com as permissões
+ * do seu processo. Um agente que leia conteúdo de terceiro — um README, uma
+ * issue, um arquivo do repositório — pode ser induzido a executar o que
+ * estiver escrito lá. O framework não tem defesa contra prompt injection.
+ *
+ * Use `allow` sempre que o agente puder ver entrada não confiável:
+ *
+ * ```ts
+ * @Agent({ provider, prompt: "./a.agent.md", tools: [shellTool({ allow: ["git", "ls"] })] })
+ * ```
+ *
+ * Sem `allow`, restrinja o uso a ambiente controlado — sua máquina, um
+ * container descartável — e nunca a um serviço exposto.
+ */
+export function shellTool(options = {}) {
+    const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT;
+    const maxChars = options.maxChars ?? MAX_CHARS;
+    const allow = options.allow?.map((c) => c.trim()).filter(Boolean);
+    return {
+        name: "shell",
+        description: allow
+            ? `Executa um comando shell. Permitidos: ${allow.join(", ")}.`
+            : "Executa um comando shell e retorna a saída.",
+        schema,
+        async execute({ command }) {
+            if (allow) {
+                // O primeiro token decide. Não tenta interpretar a linha inteira: um
+                // parser de shell parcial dá falsa sensação de segurança, e `;`, `&&`,
+                // `$(…)` e pipes contornariam qualquer coisa mais esperta que isto.
+                const programa = command.trim().split(/\s+/)[0] ?? "";
+                if (!allow.includes(programa)) {
+                    return {
+                        content: `Comando "${programa}" não permitido. ` +
+                            `Disponíveis: ${allow.join(", ")}.`,
+                        isError: true,
+                    };
+                }
+                if (/[;&|`$><]/.test(command)) {
+                    // Com allowlist ligada, encadeamento anularia a lista.
+                    return {
+                        content: "Encadeamento e redirecionamento não são permitidos " +
+                            "(`;`, `&&`, `|`, `$(…)`, `>`). Rode um comando por vez.",
+                        isError: true,
+                    };
+                }
+            }
+            try {
+                const { stdout, stderr } = await run(command, {
+                    timeout,
+                    cwd: options.cwd,
+                    maxBuffer: 10 * 1024 * 1024,
+                });
+                const saida = stdout || stderr || "(sem saída)";
+                return saida.length > maxChars
+                    ? `${saida.slice(0, maxChars)}\n… [truncado]`
+                    : saida;
+            }
+            catch (err) {
+                const e = err;
+                if (e.killed) {
+                    return {
+                        content: `O comando excedeu ${timeout}ms e foi encerrado.`,
+                        isError: true,
+                    };
+                }
+                // Erro vira observação: o modelo lê e tenta outra coisa.
+                return { content: e.stderr || e.message, isError: true };
+            }
+        },
+    };
+}
+/**
+ * Versão sem configuração, para uso rápido em ambiente controlado.
+ *
+ * ⚠️ **Sem allowlist** — o modelo executa qualquer comando. Leia o aviso de
+ * `shellTool` antes de usar; para agente que vê entrada não confiável, prefira
+ * `shellTool({ allow: [...] })`.
+ */
 let ShellTool = class ShellTool {
-    async execute({ command }) {
-        const { stdout, stderr } = await run(command);
-        return stdout || stderr;
+    impl = shellTool();
+    execute(args) {
+        return this.impl.execute(args);
     }
 };
 ShellTool = __decorate([
     Tool({
         name: "shell",
         description: "Executa um comando shell e retorna a saída.",
-        schema: z.object({ command: z.string() }),
+        schema,
     })
 ], ShellTool);
 export { ShellTool };

package/dist/shell.tool.js.map

@@ -1 +1 @@
-{"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"}
+{"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;AAErC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AAE5B,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAEjD,mFAAmF;AACnF,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B,gFAAgF;AAChF,MAAM,SAAS,GAAG,KAAK,CAAC;AAuBxB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,SAAS,CAAC,UAA4B,EAAE;IACtD,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,eAAe,CAAC;IACrD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC;IAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAElE,OAAO;QACL,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,KAAK;YAChB,CAAC,CAAC,yCAAyC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC9D,CAAC,CAAC,6CAA6C;QACjD,MAAM;QAEN,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAuB;YAC5C,IAAI,KAAK,EAAE,CAAC;gBACV,qEAAqE;gBACrE,uEAAuE;gBACvE,oEAAoE;gBACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACtD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC9B,OAAO;wBACL,OAAO,EACL,YAAY,QAAQ,mBAAmB;4BACvC,gBAAgB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;wBACrC,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;gBACD,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC9B,uDAAuD;oBACvD,OAAO;wBACL,OAAO,EACL,qDAAqD;4BACrD,yDAAyD;wBAC3D,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE;oBAC5C,OAAO;oBACP,GAAG,EAAE,OAAO,CAAC,GAAG;oBAChB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;iBAC5B,CAAC,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,IAAI,MAAM,IAAI,aAAa,CAAC;gBAChD,OAAO,KAAK,CAAC,MAAM,GAAG,QAAQ;oBAC5B,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,gBAAgB;oBAC7C,CAAC,CAAC,KAAK,CAAC;YACZ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,GAAoE,CAAC;gBAC/E,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;oBACb,OAAO;wBACL,OAAO,EAAE,qBAAqB,OAAO,qBAAqB;wBAC1D,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;gBACD,yDAAyD;gBACzD,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC3D,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AAMI,IAAM,SAAS,GAAf,MAAM,SAAS;IACH,IAAI,GAAG,SAAS,EAAE,CAAC;IAEpC,OAAO,CAAC,IAAyB;QAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;CACF,CAAA;AANY,SAAS;IALrB,IAAI,CAAC;QACJ,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,6CAA6C;QAC1D,MAAM;KACP,CAAC;GACW,SAAS,CAMrB"}

package/package.json

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