@agentier/tools 0.1.0

package/dist/read-file.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Configuration options for the {@link readFileTool} factory.
+ */
+export interface ReadFileToolOptions {
+    /**
+     * Glob patterns specifying which paths the tool is allowed to read.
+     * When provided, only matching paths are accessible.
+     */
+    allowedPaths?: string[];
+    /**
+     * Glob patterns specifying which paths the tool must not read.
+     * Defaults to node_modules and .env patterns.
+     */
+    deniedPaths?: string[];
+    /**
+     * Maximum file size in bytes that the tool will read.
+     * Files exceeding this limit cause an error.
+     * @defaultValue `1_048_576` (1 MB)
+     */
+    maxSize?: number;
+    /**
+     * Base directory against which relative file paths are resolved.
+     * @defaultValue `process.cwd()`
+     */
+    basePath?: string;
+}
+/**
+ * Creates a tool definition that reads file contents from the filesystem.
+ *
+ * The tool enforces path-based security via allow/deny glob patterns and
+ * rejects files that exceed the configured size limit.
+ *
+ * @param options - Optional configuration for path security and size limits.
+ * @returns A tool definition compatible with the agentier core runtime.
+ *
+ * @example
+ * ```ts
+ * import { readFileTool } from '@agentier/tools'
+ *
+ * const tool = readFileTool({
+ *   basePath: '/project',
+ *   maxSize: 512 * 1024,
+ * })
+ * ```
+ */
+export declare function readFileTool(options?: ReadFileToolOptions): import("@agentier/core").Tool<{
+    path: string;
+    encoding?: "utf-8" | "base64" | undefined;
+}, string>;

package/dist/shell.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Configuration options for the {@link shellTool} factory.
+ */
+export interface ShellToolOptions {
+    /**
+     * Regex patterns specifying which commands the tool is allowed to execute.
+     * When provided, only matching commands are permitted.
+     */
+    allowedCommands?: RegExp[];
+    /**
+     * Regex patterns specifying which commands the tool must not execute.
+     * When omitted, a default deny list blocks destructive operations such as
+     * `rm -rf /`, `sudo`, `shutdown`, and `reboot`.
+     */
+    deniedCommands?: RegExp[];
+    /**
+     * Maximum time in milliseconds to wait for the command to complete.
+     * @defaultValue `30_000` (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Working directory in which the command is executed.
+     * @defaultValue `process.cwd()`
+     */
+    cwd?: string;
+    /**
+     * Maximum size in bytes for stdout and stderr buffers.
+     * @defaultValue `1_048_576` (1 MB)
+     */
+    maxOutput?: number;
+}
+/**
+ * Creates a tool definition that executes shell commands via Node.js
+ * `child_process.exec`.
+ *
+ * Commands are validated against configurable allow/deny regex lists before
+ * execution. The parent context's abort signal is forwarded so the child
+ * process is killed on cancellation.
+ *
+ * @param options - Optional configuration for command security, timeouts,
+ *                  working directory, and output limits.
+ * @returns A tool definition compatible with the agentier core runtime.
+ *
+ * @example
+ * ```ts
+ * import { shellTool } from '@agentier/tools'
+ *
+ * const tool = shellTool({
+ *   cwd: '/project',
+ *   timeout: 10_000,
+ *   deniedCommands: [/rm/, /sudo/],
+ * })
+ * ```
+ */
+export declare function shellTool(options?: ShellToolOptions): import("@agentier/core").Tool<{
+    command: string;
+}, {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;

package/dist/utils/security.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @module security
+ *
+ * Utility functions for validating file paths, URLs, and shell commands
+ * against configurable allow/deny lists. Used internally by the tool
+ * implementations to enforce security boundaries.
+ */
+/**
+ * Checks whether a file path is permitted given a base directory and
+ * optional allow/deny glob patterns.
+ *
+ * Evaluation order:
+ * 1. Path traversal outside `basePath` is always denied.
+ * 2. If the path matches any `deniedPaths` pattern it is denied.
+ * 3. If `allowedPaths` is provided and non-empty, the path must match at
+ *    least one pattern.
+ * 4. Otherwise the path is allowed.
+ *
+ * @param filePath - The file path to check (relative or absolute).
+ * @param basePath - The root directory all paths are resolved against.
+ * @param allowedPaths - Optional glob patterns that explicitly allow access.
+ * @param deniedPaths - Optional glob patterns that explicitly deny access.
+ * @returns `true` if the path is permitted, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isPathAllowed('src/index.ts', '/project')           // true
+ * isPathAllowed('../etc/passwd', '/project')           // false (traversal)
+ * isPathAllowed('.env.local', '/project', undefined,
+ *   ['.env*'])                                          // false (denied)
+ * ```
+ */
+export declare function isPathAllowed(filePath: string, basePath: string, allowedPaths?: string[], deniedPaths?: string[]): boolean;
+/**
+ * Checks whether a URL is permitted given optional allow/deny regex lists.
+ *
+ * Evaluation order:
+ * 1. If the URL matches any `deniedUrls` pattern it is denied.
+ * 2. If `allowedUrls` is provided and non-empty, the URL must match at
+ *    least one pattern.
+ * 3. Otherwise the URL is allowed.
+ *
+ * @param url - The URL string to validate.
+ * @param allowedUrls - Optional regex patterns that explicitly allow access.
+ * @param deniedUrls - Optional regex patterns that explicitly deny access.
+ * @returns `true` if the URL is permitted, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isUrlAllowed('https://api.example.com/data', [/^https:\/\/api\.example\.com/])
+ * // true
+ * ```
+ */
+export declare function isUrlAllowed(url: string, allowedUrls?: RegExp[], deniedUrls?: RegExp[]): boolean;
+/**
+ * Checks whether a shell command is permitted given optional allow/deny
+ * regex lists.
+ *
+ * When no `deniedCommands` list is provided, a sensible default deny list
+ * is used that blocks destructive operations such as `rm -rf /`, `sudo`,
+ * `shutdown`, and `reboot`.
+ *
+ * @param command - The shell command string to validate.
+ * @param allowedCommands - Optional regex patterns that explicitly allow
+ *                          execution.
+ * @param deniedCommands - Optional regex patterns that explicitly deny
+ *                         execution. Overrides the built-in defaults when
+ *                         provided.
+ * @returns `true` if the command is permitted, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * isCommandAllowed('ls -la')         // true
+ * isCommandAllowed('sudo rm -rf /') // false (matches default deny list)
+ * ```
+ */
+export declare function isCommandAllowed(command: string, allowedCommands?: RegExp[], deniedCommands?: RegExp[]): boolean;

package/dist/write-file.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Configuration options for the {@link writeFileTool} factory.
+ */
+export interface WriteFileToolOptions {
+    /**
+     * Glob patterns specifying which paths the tool is allowed to write to.
+     * When provided, only matching paths are accessible.
+     */
+    allowedPaths?: string[];
+    /**
+     * Glob patterns specifying which paths the tool must not write to.
+     * Defaults to node_modules and .env patterns.
+     */
+    deniedPaths?: string[];
+    /**
+     * Whether to automatically create parent directories if they do not exist.
+     * @defaultValue `true`
+     */
+    createDirs?: boolean;
+    /**
+     * Base directory against which relative file paths are resolved.
+     * @defaultValue `process.cwd()`
+     */
+    basePath?: string;
+}
+/**
+ * Creates a tool definition that writes content to a file on the filesystem.
+ *
+ * The tool enforces path-based security via allow/deny glob patterns and
+ * can optionally create intermediate directories.
+ *
+ * @param options - Optional configuration for path security and directory
+ *                  creation.
+ * @returns A tool definition compatible with the agentier core runtime.
+ *
+ * @example
+ * ```ts
+ * import { writeFileTool } from '@agentier/tools'
+ *
+ * const tool = writeFileTool({
+ *   basePath: '/project',
+ *   createDirs: true,
+ * })
+ * ```
+ */
+export declare function writeFileTool(options?: WriteFileToolOptions): import("@agentier/core").Tool<{
+    path: string;
+    content: string;
+}, string>;

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@agentier/tools",
+    "version": "0.1.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "bun build ./src/index.ts --outdir ./dist --target node",
+        "test": "bun test",
+        "typecheck": "tsc --noEmit"
+    },
+    "peerDependencies": {
+        "@agentier/core": "^0.1.0"
+    },
+    "dependencies": {
+        "zod": "^3.23.0"
+    },
+    "devDependencies": {
+        "@agentier/core": "workspace:*",
+        "typescript": "^5.5.0",
+        "@types/bun": "latest"
+    }
+}