@aigne/agent-library 1.23.0-beta.7 → 1.23.0-beta.8

package/CHANGELOG.md

@@ -7,6 +7,13 @@
     * @aigne/core bumped to 1.22.0
     * @aigne/openai bumped to 0.3.4
 
+## [1.23.0-beta.8](https://github.com/AIGNE-io/aigne-framework/compare/agent-library-v1.23.0-beta.7...agent-library-v1.23.0-beta.8) (2025-12-12)
+
+
+### Features
+
+* **agent-library:** add BashAgent with sandbox support ([#816](https://github.com/AIGNE-io/aigne-framework/issues/816)) ([0d4feee](https://github.com/AIGNE-io/aigne-framework/commit/0d4feeeac2b71df1c4d725adeee76c9318ce8e02))
+
 ## [1.23.0-beta.7](https://github.com/AIGNE-io/aigne-framework/compare/agent-library-v1.23.0-beta.6...agent-library-v1.23.0-beta.7) (2025-12-11)
 
 

package/README.md

@@ -29,6 +29,7 @@ Collection of agent libraries for [AIGNE Framework](https://github.com/AIGNE-io/
 ## Features
 
 * **Orchestrator Agent**: Provides OrchestratorAgent implementation for coordinating workflows between multiple agents
+* **Bash Agent**: Secure execution of bash scripts with sandboxed environment and comprehensive output handling
 * **Task Concurrency**: Supports parallel execution of multiple tasks to improve processing efficiency
 * **Planning & Execution**: Automatically generates execution plans and executes them step by step
 * **Result Synthesis**: Intelligently synthesizes results from multiple steps and tasks
@@ -62,6 +63,8 @@ The library provides the following components:
 
 * **[Orchestrator Agent](src/orchestrator/README.md)**: A sophisticated agent pattern that enables autonomous task planning and execution through a three-phase architecture: Planner → Worker → Completer. It breaks down complex objectives into manageable tasks, executes them iteratively, and synthesizes the final results. Perfect for coordinating complex workflows and multi-step tasks.
 
+* **[Bash Agent](src/bash/README.md)**: Enables secure execution of bash scripts within a sandboxed environment. Provides controlled access to system commands, network resources, and the filesystem while returning comprehensive execution results including stdout, stderr, and exit codes. Ideal for running system commands, interacting with CLI tools, and executing shell scripts safely.
+
 ## License
 
 Elastic-2.0

package/lib/cjs/bash/index.d.ts

@@ -0,0 +1,124 @@
+import { type SpawnOptions } from "node:child_process";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentResponseStream, type Message } from "@aigne/core";
+import { type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
+import { type LoadOptions } from "@aigne/core/loader/index.js";
+import { type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+export interface BashAgentOptions extends AgentOptions<BashAgentInput, BashAgentOutput> {
+    sandbox?: Partial<{
+        [K in keyof SandboxRuntimeConfig]: Partial<SandboxRuntimeConfig[K]>;
+    }> | boolean;
+    inputKey?: string;
+    /**
+     * Optional timeout for script execution in milliseconds
+     * @default 60000 (60 seconds)
+     */
+    timeout?: number;
+    /**
+     * Optional permissions configuration for command execution control
+     * Inspired by Claude Code's permission system
+     */
+    permissions?: {
+        /**
+         * Whitelist: Commands that are allowed to execute without approval
+         * Supports exact match or prefix match with ':*' wildcard
+         * Examples: ['npm run test:*', 'git status', 'ls:*']
+         */
+        allow?: string[];
+        /**
+         * Blacklist: Commands that are completely forbidden
+         * Takes highest priority over allow and defaultMode
+         * Examples: ['rm:*', 'sudo:*', 'curl:*']
+         */
+        deny?: string[];
+        /**
+         * Default permission mode when command doesn't match allow/deny lists
+         * @default 'allow'
+         */
+        defaultMode?: "allow" | "ask" | "deny";
+        /**
+         * Callback function invoked when a command requires user approval (ask mode)
+         * Return true to approve, false to reject
+         * @param script - The script that requires approval
+         * @returns Promise resolving to approval decision
+         */
+        guard?: BashAgent["guard"];
+    };
+}
+export interface LoadBashAgentOptions extends Omit<BashAgentOptions, "permissions"> {
+    permissions?: Omit<NonNullable<BashAgentOptions["permissions"]>, "guard"> & {
+        guard?: NestAgentSchema;
+    };
+}
+export interface BashAgentInput extends Message {
+    script?: string;
+}
+export interface BashAgentOutput extends Message {
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+}
+export declare class BashAgent extends Agent<BashAgentInput, BashAgentOutput> {
+    options: BashAgentOptions;
+    static load(options: {
+        filepath: string;
+        parsed: LoadBashAgentOptions;
+        options?: LoadOptions;
+    }): Promise<Agent<any, any>>;
+    constructor(options: BashAgentOptions);
+    inputKey?: string;
+    guard?: Agent<{
+        script?: string;
+    }, {
+        approved: boolean;
+        reason?: string;
+    }>;
+    process(input: BashAgentInput, options: AgentInvokeOptions): Promise<AgentResponseStream<BashAgentOutput>>;
+    spawn(command: string, args?: string[], options?: SpawnOptions): Promise<AgentResponseStream<BashAgentOutput>>;
+    runInSandbox<T>(config: Exclude<BashAgentOptions["sandbox"], boolean>, script: string, task: (script: string) => Promise<T>): Promise<T>;
+    /**
+     * Check permission for executing a script
+     * Permission priority: deny > allow > defaultMode
+     *
+     * For complex commands (with pipes, chaining, etc.), each sub-command
+     * is validated separately. All sub-commands must pass permission checks.
+     *
+     * @param script - The script to check permission for
+     * @returns Permission decision: 'allow', 'ask', or 'deny'
+     */
+    checkPermission(script: string): Promise<"allow" | "ask" | "deny">;
+    /**
+     * Split a script into individual commands by pipes, command chaining, etc.
+     * Separators: | (pipe), && (AND), || (OR), & (background), ; (sequential), \n (newline)
+     *
+     * Note: Redirection operators (>, >>, <, <<, &>, 2>, etc.) are treated as part of
+     * the command, not as separators.
+     *
+     * @param script - The script to split
+     * @returns Array of individual commands
+     */
+    private splitCommands;
+    /**
+     * Check permission for a single command
+     * @param command - The command to check
+     * @param permissions - Permission configuration
+     * @returns Permission decision for this command
+     */
+    private checkSingleCommandPermission;
+    /**
+     * Match a single command against a permission pattern
+     * Supports exact match and prefix match with ':*' wildcard
+     *
+     * Note: This method is called for individual commands after splitting,
+     * so it doesn't need to handle complex command chaining.
+     *
+     * Examples:
+     * - "ls:*" matches "ls", "ls -la", "ls:option"
+     * - "npm run test:*" matches "npm run test", "npm run test:unit", "npm run test arg"
+     *
+     * @param command - The command to match (should be a single command)
+     * @param pattern - The pattern to match against
+     * @returns true if command matches pattern
+     */
+    private matchPattern;
+}
+export default BashAgent;

package/lib/cjs/bash/index.js

@@ -0,0 +1,359 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BashAgent = void 0;
+const node_child_process_1 = require("node:child_process");
+const core_1 = require("@aigne/core");
+const agent_yaml_js_1 = require("@aigne/core/loader/agent-yaml.js");
+const index_js_1 = require("@aigne/core/loader/index.js");
+const schema_js_1 = require("@aigne/core/loader/schema.js");
+const sandbox_runtime_1 = require("@anthropic-ai/sandbox-runtime");
+const ripgrep_1 = require("@vscode/ripgrep");
+const zod_1 = __importStar(require("zod"));
+const mutex_js_1 = require("../utils/mutex.js");
+const DEFAULT_TIMEOUT = 60e3; // 60 seconds
+let sandboxInitialization;
+const mutex = new mutex_js_1.Mutex();
+class BashAgent extends core_1.Agent {
+    options;
+    static async load(options) {
+        const schema = getBashAgentSchema({ filepath: options.filepath });
+        const parsed = await schema.parseAsync(options.parsed);
+        return new BashAgent({
+            ...parsed,
+            permissions: {
+                ...parsed.permissions,
+                guard: parsed.permissions?.guard
+                    ? await (0, index_js_1.loadNestAgent)(options.filepath, parsed.permissions.guard, options.options ?? {}, {
+                        outputSchema: zod_1.default.object({
+                            approved: zod_1.default.boolean().describe("Whether the command is approved by the user."),
+                            reason: zod_1.default.string().describe("Optional reason for rejection.").optional(),
+                        }),
+                    })
+                    : undefined,
+            },
+        });
+    }
+    constructor(options) {
+        super({
+            name: "Bash",
+            description: `\
+Execute bash scripts and return stdout and stderr output.
+
+When to use:
+- Running system commands or bash scripts
+- Interacting with command-line tools
+`,
+            ...options,
+            inputSchema: zod_1.default.object({
+                [options.inputKey || "script"]: zod_1.default.string().describe("The bash script to execute."),
+            }),
+            outputSchema: zod_1.default.object({
+                stdout: zod_1.default.string().describe("The standard output from the bash script.").optional(),
+                stderr: zod_1.default.string().describe("The standard error output from the bash script.").optional(),
+                exitCode: zod_1.default.number().describe("The exit code of the bash script execution.").optional(),
+            }),
+        });
+        this.options = options;
+        this.guard = this.options.permissions?.guard;
+        this.inputKey = this.options.inputKey;
+    }
+    inputKey;
+    guard;
+    async process(input, options) {
+        const script = input[this.inputKey || "script"];
+        if (typeof script !== "string")
+            throw new Error(`Invalid or missing script input: ${this.inputKey || "script"}`);
+        // Permission check
+        const permission = await this.checkPermission(script);
+        if (permission === "deny") {
+            throw new Error(`Command blocked by permissions: ${script}`);
+        }
+        if (permission === "ask") {
+            if (!this.guard) {
+                throw new Error(`No guard agent configured for permission 'ask'`);
+            }
+            const { approved, reason } = await this.invokeChildAgent(this.guard, input, {
+                ...options,
+                streaming: false,
+            });
+            if (!approved) {
+                throw new Error(`Command rejected by guard agent (${this.guard.name}): ${script}, reason: ${reason || "no reason provided"}`);
+            }
+        }
+        const platform = {
+            win32: "windows",
+            darwin: "macos",
+            linux: "linux",
+        }[globalThis.process.platform] || "unknown";
+        if (this.options.sandbox === false) {
+            return this.spawn("bash", ["-c", script]);
+        }
+        else {
+            if (!sandbox_runtime_1.SandboxManager.isSupportedPlatform(platform)) {
+                throw new Error(`Sandboxed execution is not supported on this platform ${platform}`);
+            }
+            return await this.runInSandbox(typeof this.options.sandbox === "boolean" ? {} : this.options.sandbox, script, async (sandboxedCommand) => {
+                return this.spawn(sandboxedCommand, undefined, {
+                    shell: true,
+                });
+            });
+        }
+    }
+    async spawn(command, args, options) {
+        return new ReadableStream({
+            start: (controller) => {
+                try {
+                    const timeout = this.options.timeout ?? DEFAULT_TIMEOUT;
+                    const child = (0, node_child_process_1.spawn)(command, args, {
+                        ...options,
+                        stdio: "pipe",
+                        timeout,
+                    });
+                    let stderr = "";
+                    child.stdout.on("data", (chunk) => {
+                        controller.enqueue({ delta: { text: { stdout: chunk.toString() } } });
+                    });
+                    child.stderr.on("data", (chunk) => {
+                        controller.enqueue({ delta: { text: { stderr: chunk.toString() } } });
+                        stderr += chunk.toString();
+                    });
+                    child.on("error", (error) => {
+                        controller.error(error);
+                    });
+                    child.on("close", (code, signal) => {
+                        // Handle timeout or killed by signal
+                        if (signal) {
+                            const timeoutHint = signal === "SIGTERM" ? ` (likely timeout ${timeout})` : "";
+                            controller.error(new Error(`Bash script killed by signal ${signal}${timeoutHint}: ${stderr}`));
+                            return;
+                        }
+                        // Handle normal exit
+                        if (typeof code === "number") {
+                            if (code === 0) {
+                                controller.enqueue({ delta: { json: { exitCode: code } } });
+                                controller.close();
+                            }
+                            else {
+                                controller.error(new Error(`Bash script exited with code ${code}: ${stderr}`));
+                            }
+                        }
+                        else {
+                            // Unexpected case: no code and no signal
+                            controller.error(new Error(`Bash script closed unexpectedly: ${stderr}`));
+                        }
+                    });
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+        });
+    }
+    async runInSandbox(config, script, task) {
+        return await mutex.runExclusive(async () => {
+            sandboxInitialization ??= sandbox_runtime_1.SandboxManager.initialize({
+                network: {
+                    allowedDomains: [],
+                    deniedDomains: [],
+                },
+                filesystem: {
+                    denyRead: [],
+                    denyWrite: [],
+                    allowWrite: [],
+                },
+                ripgrep: {
+                    command: ripgrep_1.rgPath,
+                },
+            });
+            await sandboxInitialization;
+            sandbox_runtime_1.SandboxManager.updateConfig({
+                ...config,
+                network: {
+                    ...config?.network,
+                    allowedDomains: config?.network?.allowedDomains || [],
+                    deniedDomains: config?.network?.deniedDomains || [],
+                },
+                filesystem: {
+                    ...config?.filesystem,
+                    denyRead: config?.filesystem?.denyRead || [],
+                    denyWrite: config?.filesystem?.denyWrite || [],
+                    allowWrite: config?.filesystem?.allowWrite || [],
+                },
+                ripgrep: {
+                    command: ripgrep_1.rgPath,
+                },
+            });
+            const sandboxedCommand = await sandbox_runtime_1.SandboxManager.wrapWithSandbox(script);
+            return await task(sandboxedCommand);
+        });
+    }
+    /**
+     * Check permission for executing a script
+     * Permission priority: deny > allow > defaultMode
+     *
+     * For complex commands (with pipes, chaining, etc.), each sub-command
+     * is validated separately. All sub-commands must pass permission checks.
+     *
+     * @param script - The script to check permission for
+     * @returns Permission decision: 'allow', 'ask', or 'deny'
+     */
+    async checkPermission(script) {
+        const { permissions } = this.options;
+        if (!permissions) {
+            return "allow"; // No permissions configured, default to allow
+        }
+        // Split complex commands into individual commands
+        const commands = this.splitCommands(script);
+        // Check permission for each command
+        for (const command of commands) {
+            const commandPermission = this.checkSingleCommandPermission(command, permissions);
+            // If any command is denied, deny the whole script
+            if (commandPermission === "deny") {
+                return "deny";
+            }
+            // If any command requires asking, the whole script requires asking
+            if (commandPermission === "ask") {
+                return "ask";
+            }
+        }
+        // All commands are allowed
+        return "allow";
+    }
+    /**
+     * Split a script into individual commands by pipes, command chaining, etc.
+     * Separators: | (pipe), && (AND), || (OR), & (background), ; (sequential), \n (newline)
+     *
+     * Note: Redirection operators (>, >>, <, <<, &>, 2>, etc.) are treated as part of
+     * the command, not as separators.
+     *
+     * @param script - The script to split
+     * @returns Array of individual commands
+     */
+    splitCommands(script) {
+        // Split by pipes, &&, ||, &, ;, and newlines
+        // IMPORTANT: Match longer patterns first to avoid incorrect splitting:
+        // - && and || before single & and |
+        // - Must use negative lookbehind/lookahead to avoid matching &> (redirect)
+        // Pattern explanation: (?<!&) means "not preceded by &", (?!>) means "not followed by >"
+        const parts = script.split(/(\||&&|\|\||(?<!&)&(?!>)|;|\n)/);
+        const commands = [];
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            if (!part)
+                continue;
+            const trimmedPart = part.trim();
+            // Skip empty parts and separator tokens
+            if (trimmedPart && !["|", "&&", "||", "&", ";"].includes(trimmedPart)) {
+                commands.push(trimmedPart);
+            }
+        }
+        return commands.length > 0 ? commands : [script];
+    }
+    /**
+     * Check permission for a single command
+     * @param command - The command to check
+     * @param permissions - Permission configuration
+     * @returns Permission decision for this command
+     */
+    checkSingleCommandPermission(command, permissions) {
+        // Priority 1: Check deny list (highest priority)
+        if (permissions.deny?.some((pattern) => this.matchPattern(command, pattern))) {
+            return "deny";
+        }
+        // Priority 2: Check allow list
+        if (permissions.allow?.some((pattern) => this.matchPattern(command, pattern))) {
+            return "allow";
+        }
+        // Priority 3: Apply default mode
+        return permissions.defaultMode || "allow";
+    }
+    /**
+     * Match a single command against a permission pattern
+     * Supports exact match and prefix match with ':*' wildcard
+     *
+     * Note: This method is called for individual commands after splitting,
+     * so it doesn't need to handle complex command chaining.
+     *
+     * Examples:
+     * - "ls:*" matches "ls", "ls -la", "ls:option"
+     * - "npm run test:*" matches "npm run test", "npm run test:unit", "npm run test arg"
+     *
+     * @param command - The command to match (should be a single command)
+     * @param pattern - The pattern to match against
+     * @returns true if command matches pattern
+     */
+    matchPattern(command, pattern) {
+        // Trim whitespace
+        command = command.trim();
+        pattern = pattern.trim();
+        // Exact match
+        if (pattern === command) {
+            return true;
+        }
+        // Prefix match with ':*' wildcard
+        if (pattern.endsWith(":*")) {
+            const prefix = pattern.slice(0, -2).trim();
+            // Match if command equals prefix or starts with prefix followed by space or colon
+            return command === prefix || command.startsWith(prefix) || command.startsWith(`${prefix}:`);
+        }
+        return false;
+    }
+}
+exports.BashAgent = BashAgent;
+exports.default = BashAgent;
+function getBashAgentSchema({ filepath }) {
+    const nestAgentSchema = (0, agent_yaml_js_1.getNestAgentSchema)({ filepath });
+    return (0, schema_js_1.camelizeSchema)(zod_1.default.object({
+        sandbox: (0, schema_js_1.optionalize)(zod_1.default.union([makeShapePropertiesOptions(sandbox_runtime_1.SandboxRuntimeConfigSchema, 2), zod_1.default.boolean()])),
+        inputKey: (0, schema_js_1.optionalize)(zod_1.default.string().describe("The input key for the bash script.")),
+        timeout: (0, schema_js_1.optionalize)(zod_1.default.number().describe("Timeout for script execution in milliseconds.")),
+        permissions: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(zod_1.default.object({
+            allow: (0, schema_js_1.optionalize)(zod_1.default.array(zod_1.default.string())),
+            deny: (0, schema_js_1.optionalize)(zod_1.default.array(zod_1.default.string())),
+            defaultMode: (0, schema_js_1.optionalize)(zod_1.default.enum(["allow", "ask", "deny"])),
+            guard: (0, schema_js_1.optionalize)(nestAgentSchema),
+        }))),
+    }));
+}
+function makeShapePropertiesOptions(schema, depth = 1) {
+    return zod_1.default.object(Object.fromEntries(Object.entries(schema.shape).map(([key, value]) => {
+        const isObject = value instanceof zod_1.ZodObject;
+        if (isObject && depth > 1) {
+            return [key, (0, schema_js_1.optionalize)(makeShapePropertiesOptions(value, depth - 1))];
+        }
+        return [key, (0, schema_js_1.optionalize)(value)];
+    })));
+}

package/lib/cjs/utils/mutex.d.ts

@@ -0,0 +1,6 @@
+export declare class Mutex {
+    constructor();
+    private _lock;
+    lock(): Promise<() => void>;
+    runExclusive<T>(callback: () => Promise<T> | T): Promise<T>;
+}

package/lib/cjs/utils/mutex.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mutex = void 0;
+class Mutex {
+    constructor() {
+        this._lock = Promise.resolve();
+    }
+    _lock;
+    lock() {
+        let unlockNext;
+        const willLock = new Promise((resolve) => {
+            unlockNext = resolve;
+        });
+        const willUnlock = this._lock.then(() => unlockNext);
+        this._lock = willLock;
+        return willUnlock;
+    }
+    async runExclusive(callback) {
+        const unlock = await this.lock();
+        try {
+            return await callback();
+        }
+        finally {
+            unlock();
+        }
+    }
+}
+exports.Mutex = Mutex;

package/lib/dts/bash/index.d.ts

@@ -0,0 +1,124 @@
+import { type SpawnOptions } from "node:child_process";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentResponseStream, type Message } from "@aigne/core";
+import { type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
+import { type LoadOptions } from "@aigne/core/loader/index.js";
+import { type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+export interface BashAgentOptions extends AgentOptions<BashAgentInput, BashAgentOutput> {
+    sandbox?: Partial<{
+        [K in keyof SandboxRuntimeConfig]: Partial<SandboxRuntimeConfig[K]>;
+    }> | boolean;
+    inputKey?: string;
+    /**
+     * Optional timeout for script execution in milliseconds
+     * @default 60000 (60 seconds)
+     */
+    timeout?: number;
+    /**
+     * Optional permissions configuration for command execution control
+     * Inspired by Claude Code's permission system
+     */
+    permissions?: {
+        /**
+         * Whitelist: Commands that are allowed to execute without approval
+         * Supports exact match or prefix match with ':*' wildcard
+         * Examples: ['npm run test:*', 'git status', 'ls:*']
+         */
+        allow?: string[];
+        /**
+         * Blacklist: Commands that are completely forbidden
+         * Takes highest priority over allow and defaultMode
+         * Examples: ['rm:*', 'sudo:*', 'curl:*']
+         */
+        deny?: string[];
+        /**
+         * Default permission mode when command doesn't match allow/deny lists
+         * @default 'allow'
+         */
+        defaultMode?: "allow" | "ask" | "deny";
+        /**
+         * Callback function invoked when a command requires user approval (ask mode)
+         * Return true to approve, false to reject
+         * @param script - The script that requires approval
+         * @returns Promise resolving to approval decision
+         */
+        guard?: BashAgent["guard"];
+    };
+}
+export interface LoadBashAgentOptions extends Omit<BashAgentOptions, "permissions"> {
+    permissions?: Omit<NonNullable<BashAgentOptions["permissions"]>, "guard"> & {
+        guard?: NestAgentSchema;
+    };
+}
+export interface BashAgentInput extends Message {
+    script?: string;
+}
+export interface BashAgentOutput extends Message {
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+}
+export declare class BashAgent extends Agent<BashAgentInput, BashAgentOutput> {
+    options: BashAgentOptions;
+    static load(options: {
+        filepath: string;
+        parsed: LoadBashAgentOptions;
+        options?: LoadOptions;
+    }): Promise<Agent<any, any>>;
+    constructor(options: BashAgentOptions);
+    inputKey?: string;
+    guard?: Agent<{
+        script?: string;
+    }, {
+        approved: boolean;
+        reason?: string;
+    }>;
+    process(input: BashAgentInput, options: AgentInvokeOptions): Promise<AgentResponseStream<BashAgentOutput>>;
+    spawn(command: string, args?: string[], options?: SpawnOptions): Promise<AgentResponseStream<BashAgentOutput>>;
+    runInSandbox<T>(config: Exclude<BashAgentOptions["sandbox"], boolean>, script: string, task: (script: string) => Promise<T>): Promise<T>;
+    /**
+     * Check permission for executing a script
+     * Permission priority: deny > allow > defaultMode
+     *
+     * For complex commands (with pipes, chaining, etc.), each sub-command
+     * is validated separately. All sub-commands must pass permission checks.
+     *
+     * @param script - The script to check permission for
+     * @returns Permission decision: 'allow', 'ask', or 'deny'
+     */
+    checkPermission(script: string): Promise<"allow" | "ask" | "deny">;
+    /**
+     * Split a script into individual commands by pipes, command chaining, etc.
+     * Separators: | (pipe), && (AND), || (OR), & (background), ; (sequential), \n (newline)
+     *
+     * Note: Redirection operators (>, >>, <, <<, &>, 2>, etc.) are treated as part of
+     * the command, not as separators.
+     *
+     * @param script - The script to split
+     * @returns Array of individual commands
+     */
+    private splitCommands;
+    /**
+     * Check permission for a single command
+     * @param command - The command to check
+     * @param permissions - Permission configuration
+     * @returns Permission decision for this command
+     */
+    private checkSingleCommandPermission;
+    /**
+     * Match a single command against a permission pattern
+     * Supports exact match and prefix match with ':*' wildcard
+     *
+     * Note: This method is called for individual commands after splitting,
+     * so it doesn't need to handle complex command chaining.
+     *
+     * Examples:
+     * - "ls:*" matches "ls", "ls -la", "ls:option"
+     * - "npm run test:*" matches "npm run test", "npm run test:unit", "npm run test arg"
+     *
+     * @param command - The command to match (should be a single command)
+     * @param pattern - The pattern to match against
+     * @returns true if command matches pattern
+     */
+    private matchPattern;
+}
+export default BashAgent;

package/lib/dts/utils/mutex.d.ts

@@ -0,0 +1,6 @@
+export declare class Mutex {
+    constructor();
+    private _lock;
+    lock(): Promise<() => void>;
+    runExclusive<T>(callback: () => Promise<T> | T): Promise<T>;
+}

package/lib/esm/bash/index.d.ts

@@ -0,0 +1,124 @@
+import { type SpawnOptions } from "node:child_process";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentResponseStream, type Message } from "@aigne/core";
+import { type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
+import { type LoadOptions } from "@aigne/core/loader/index.js";
+import { type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+export interface BashAgentOptions extends AgentOptions<BashAgentInput, BashAgentOutput> {
+    sandbox?: Partial<{
+        [K in keyof SandboxRuntimeConfig]: Partial<SandboxRuntimeConfig[K]>;
+    }> | boolean;
+    inputKey?: string;
+    /**
+     * Optional timeout for script execution in milliseconds
+     * @default 60000 (60 seconds)
+     */
+    timeout?: number;
+    /**
+     * Optional permissions configuration for command execution control
+     * Inspired by Claude Code's permission system
+     */
+    permissions?: {
+        /**
+         * Whitelist: Commands that are allowed to execute without approval
+         * Supports exact match or prefix match with ':*' wildcard
+         * Examples: ['npm run test:*', 'git status', 'ls:*']
+         */
+        allow?: string[];
+        /**
+         * Blacklist: Commands that are completely forbidden
+         * Takes highest priority over allow and defaultMode
+         * Examples: ['rm:*', 'sudo:*', 'curl:*']
+         */
+        deny?: string[];
+        /**
+         * Default permission mode when command doesn't match allow/deny lists
+         * @default 'allow'
+         */
+        defaultMode?: "allow" | "ask" | "deny";
+        /**
+         * Callback function invoked when a command requires user approval (ask mode)
+         * Return true to approve, false to reject
+         * @param script - The script that requires approval
+         * @returns Promise resolving to approval decision
+         */
+        guard?: BashAgent["guard"];
+    };
+}
+export interface LoadBashAgentOptions extends Omit<BashAgentOptions, "permissions"> {
+    permissions?: Omit<NonNullable<BashAgentOptions["permissions"]>, "guard"> & {
+        guard?: NestAgentSchema;
+    };
+}
+export interface BashAgentInput extends Message {
+    script?: string;
+}
+export interface BashAgentOutput extends Message {
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+}
+export declare class BashAgent extends Agent<BashAgentInput, BashAgentOutput> {
+    options: BashAgentOptions;
+    static load(options: {
+        filepath: string;
+        parsed: LoadBashAgentOptions;
+        options?: LoadOptions;
+    }): Promise<Agent<any, any>>;
+    constructor(options: BashAgentOptions);
+    inputKey?: string;
+    guard?: Agent<{
+        script?: string;
+    }, {
+        approved: boolean;
+        reason?: string;
+    }>;
+    process(input: BashAgentInput, options: AgentInvokeOptions): Promise<AgentResponseStream<BashAgentOutput>>;
+    spawn(command: string, args?: string[], options?: SpawnOptions): Promise<AgentResponseStream<BashAgentOutput>>;
+    runInSandbox<T>(config: Exclude<BashAgentOptions["sandbox"], boolean>, script: string, task: (script: string) => Promise<T>): Promise<T>;
+    /**
+     * Check permission for executing a script
+     * Permission priority: deny > allow > defaultMode
+     *
+     * For complex commands (with pipes, chaining, etc.), each sub-command
+     * is validated separately. All sub-commands must pass permission checks.
+     *
+     * @param script - The script to check permission for
+     * @returns Permission decision: 'allow', 'ask', or 'deny'
+     */
+    checkPermission(script: string): Promise<"allow" | "ask" | "deny">;
+    /**
+     * Split a script into individual commands by pipes, command chaining, etc.
+     * Separators: | (pipe), && (AND), || (OR), & (background), ; (sequential), \n (newline)
+     *
+     * Note: Redirection operators (>, >>, <, <<, &>, 2>, etc.) are treated as part of
+     * the command, not as separators.
+     *
+     * @param script - The script to split
+     * @returns Array of individual commands
+     */
+    private splitCommands;
+    /**
+     * Check permission for a single command
+     * @param command - The command to check
+     * @param permissions - Permission configuration
+     * @returns Permission decision for this command
+     */
+    private checkSingleCommandPermission;
+    /**
+     * Match a single command against a permission pattern
+     * Supports exact match and prefix match with ':*' wildcard
+     *
+     * Note: This method is called for individual commands after splitting,
+     * so it doesn't need to handle complex command chaining.
+     *
+     * Examples:
+     * - "ls:*" matches "ls", "ls -la", "ls:option"
+     * - "npm run test:*" matches "npm run test", "npm run test:unit", "npm run test arg"
+     *
+     * @param command - The command to match (should be a single command)
+     * @param pattern - The pattern to match against
+     * @returns true if command matches pattern
+     */
+    private matchPattern;
+}
+export default BashAgent;

package/lib/esm/bash/index.js

@@ -0,0 +1,322 @@
+import { spawn } from "node:child_process";
+import { Agent, } from "@aigne/core";
+import { getNestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
+import { loadNestAgent } from "@aigne/core/loader/index.js";
+import { camelizeSchema, optionalize } from "@aigne/core/loader/schema.js";
+import { SandboxManager, SandboxRuntimeConfigSchema, } from "@anthropic-ai/sandbox-runtime";
+import { rgPath } from "@vscode/ripgrep";
+import z, { ZodObject } from "zod";
+import { Mutex } from "../utils/mutex.js";
+const DEFAULT_TIMEOUT = 60e3; // 60 seconds
+let sandboxInitialization;
+const mutex = new Mutex();
+export class BashAgent extends Agent {
+    options;
+    static async load(options) {
+        const schema = getBashAgentSchema({ filepath: options.filepath });
+        const parsed = await schema.parseAsync(options.parsed);
+        return new BashAgent({
+            ...parsed,
+            permissions: {
+                ...parsed.permissions,
+                guard: parsed.permissions?.guard
+                    ? await loadNestAgent(options.filepath, parsed.permissions.guard, options.options ?? {}, {
+                        outputSchema: z.object({
+                            approved: z.boolean().describe("Whether the command is approved by the user."),
+                            reason: z.string().describe("Optional reason for rejection.").optional(),
+                        }),
+                    })
+                    : undefined,
+            },
+        });
+    }
+    constructor(options) {
+        super({
+            name: "Bash",
+            description: `\
+Execute bash scripts and return stdout and stderr output.
+
+When to use:
+- Running system commands or bash scripts
+- Interacting with command-line tools
+`,
+            ...options,
+            inputSchema: z.object({
+                [options.inputKey || "script"]: z.string().describe("The bash script to execute."),
+            }),
+            outputSchema: z.object({
+                stdout: z.string().describe("The standard output from the bash script.").optional(),
+                stderr: z.string().describe("The standard error output from the bash script.").optional(),
+                exitCode: z.number().describe("The exit code of the bash script execution.").optional(),
+            }),
+        });
+        this.options = options;
+        this.guard = this.options.permissions?.guard;
+        this.inputKey = this.options.inputKey;
+    }
+    inputKey;
+    guard;
+    async process(input, options) {
+        const script = input[this.inputKey || "script"];
+        if (typeof script !== "string")
+            throw new Error(`Invalid or missing script input: ${this.inputKey || "script"}`);
+        // Permission check
+        const permission = await this.checkPermission(script);
+        if (permission === "deny") {
+            throw new Error(`Command blocked by permissions: ${script}`);
+        }
+        if (permission === "ask") {
+            if (!this.guard) {
+                throw new Error(`No guard agent configured for permission 'ask'`);
+            }
+            const { approved, reason } = await this.invokeChildAgent(this.guard, input, {
+                ...options,
+                streaming: false,
+            });
+            if (!approved) {
+                throw new Error(`Command rejected by guard agent (${this.guard.name}): ${script}, reason: ${reason || "no reason provided"}`);
+            }
+        }
+        const platform = {
+            win32: "windows",
+            darwin: "macos",
+            linux: "linux",
+        }[globalThis.process.platform] || "unknown";
+        if (this.options.sandbox === false) {
+            return this.spawn("bash", ["-c", script]);
+        }
+        else {
+            if (!SandboxManager.isSupportedPlatform(platform)) {
+                throw new Error(`Sandboxed execution is not supported on this platform ${platform}`);
+            }
+            return await this.runInSandbox(typeof this.options.sandbox === "boolean" ? {} : this.options.sandbox, script, async (sandboxedCommand) => {
+                return this.spawn(sandboxedCommand, undefined, {
+                    shell: true,
+                });
+            });
+        }
+    }
+    async spawn(command, args, options) {
+        return new ReadableStream({
+            start: (controller) => {
+                try {
+                    const timeout = this.options.timeout ?? DEFAULT_TIMEOUT;
+                    const child = spawn(command, args, {
+                        ...options,
+                        stdio: "pipe",
+                        timeout,
+                    });
+                    let stderr = "";
+                    child.stdout.on("data", (chunk) => {
+                        controller.enqueue({ delta: { text: { stdout: chunk.toString() } } });
+                    });
+                    child.stderr.on("data", (chunk) => {
+                        controller.enqueue({ delta: { text: { stderr: chunk.toString() } } });
+                        stderr += chunk.toString();
+                    });
+                    child.on("error", (error) => {
+                        controller.error(error);
+                    });
+                    child.on("close", (code, signal) => {
+                        // Handle timeout or killed by signal
+                        if (signal) {
+                            const timeoutHint = signal === "SIGTERM" ? ` (likely timeout ${timeout})` : "";
+                            controller.error(new Error(`Bash script killed by signal ${signal}${timeoutHint}: ${stderr}`));
+                            return;
+                        }
+                        // Handle normal exit
+                        if (typeof code === "number") {
+                            if (code === 0) {
+                                controller.enqueue({ delta: { json: { exitCode: code } } });
+                                controller.close();
+                            }
+                            else {
+                                controller.error(new Error(`Bash script exited with code ${code}: ${stderr}`));
+                            }
+                        }
+                        else {
+                            // Unexpected case: no code and no signal
+                            controller.error(new Error(`Bash script closed unexpectedly: ${stderr}`));
+                        }
+                    });
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+        });
+    }
+    async runInSandbox(config, script, task) {
+        return await mutex.runExclusive(async () => {
+            sandboxInitialization ??= SandboxManager.initialize({
+                network: {
+                    allowedDomains: [],
+                    deniedDomains: [],
+                },
+                filesystem: {
+                    denyRead: [],
+                    denyWrite: [],
+                    allowWrite: [],
+                },
+                ripgrep: {
+                    command: rgPath,
+                },
+            });
+            await sandboxInitialization;
+            SandboxManager.updateConfig({
+                ...config,
+                network: {
+                    ...config?.network,
+                    allowedDomains: config?.network?.allowedDomains || [],
+                    deniedDomains: config?.network?.deniedDomains || [],
+                },
+                filesystem: {
+                    ...config?.filesystem,
+                    denyRead: config?.filesystem?.denyRead || [],
+                    denyWrite: config?.filesystem?.denyWrite || [],
+                    allowWrite: config?.filesystem?.allowWrite || [],
+                },
+                ripgrep: {
+                    command: rgPath,
+                },
+            });
+            const sandboxedCommand = await SandboxManager.wrapWithSandbox(script);
+            return await task(sandboxedCommand);
+        });
+    }
+    /**
+     * Check permission for executing a script
+     * Permission priority: deny > allow > defaultMode
+     *
+     * For complex commands (with pipes, chaining, etc.), each sub-command
+     * is validated separately. All sub-commands must pass permission checks.
+     *
+     * @param script - The script to check permission for
+     * @returns Permission decision: 'allow', 'ask', or 'deny'
+     */
+    async checkPermission(script) {
+        const { permissions } = this.options;
+        if (!permissions) {
+            return "allow"; // No permissions configured, default to allow
+        }
+        // Split complex commands into individual commands
+        const commands = this.splitCommands(script);
+        // Check permission for each command
+        for (const command of commands) {
+            const commandPermission = this.checkSingleCommandPermission(command, permissions);
+            // If any command is denied, deny the whole script
+            if (commandPermission === "deny") {
+                return "deny";
+            }
+            // If any command requires asking, the whole script requires asking
+            if (commandPermission === "ask") {
+                return "ask";
+            }
+        }
+        // All commands are allowed
+        return "allow";
+    }
+    /**
+     * Split a script into individual commands by pipes, command chaining, etc.
+     * Separators: | (pipe), && (AND), || (OR), & (background), ; (sequential), \n (newline)
+     *
+     * Note: Redirection operators (>, >>, <, <<, &>, 2>, etc.) are treated as part of
+     * the command, not as separators.
+     *
+     * @param script - The script to split
+     * @returns Array of individual commands
+     */
+    splitCommands(script) {
+        // Split by pipes, &&, ||, &, ;, and newlines
+        // IMPORTANT: Match longer patterns first to avoid incorrect splitting:
+        // - && and || before single & and |
+        // - Must use negative lookbehind/lookahead to avoid matching &> (redirect)
+        // Pattern explanation: (?<!&) means "not preceded by &", (?!>) means "not followed by >"
+        const parts = script.split(/(\||&&|\|\||(?<!&)&(?!>)|;|\n)/);
+        const commands = [];
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            if (!part)
+                continue;
+            const trimmedPart = part.trim();
+            // Skip empty parts and separator tokens
+            if (trimmedPart && !["|", "&&", "||", "&", ";"].includes(trimmedPart)) {
+                commands.push(trimmedPart);
+            }
+        }
+        return commands.length > 0 ? commands : [script];
+    }
+    /**
+     * Check permission for a single command
+     * @param command - The command to check
+     * @param permissions - Permission configuration
+     * @returns Permission decision for this command
+     */
+    checkSingleCommandPermission(command, permissions) {
+        // Priority 1: Check deny list (highest priority)
+        if (permissions.deny?.some((pattern) => this.matchPattern(command, pattern))) {
+            return "deny";
+        }
+        // Priority 2: Check allow list
+        if (permissions.allow?.some((pattern) => this.matchPattern(command, pattern))) {
+            return "allow";
+        }
+        // Priority 3: Apply default mode
+        return permissions.defaultMode || "allow";
+    }
+    /**
+     * Match a single command against a permission pattern
+     * Supports exact match and prefix match with ':*' wildcard
+     *
+     * Note: This method is called for individual commands after splitting,
+     * so it doesn't need to handle complex command chaining.
+     *
+     * Examples:
+     * - "ls:*" matches "ls", "ls -la", "ls:option"
+     * - "npm run test:*" matches "npm run test", "npm run test:unit", "npm run test arg"
+     *
+     * @param command - The command to match (should be a single command)
+     * @param pattern - The pattern to match against
+     * @returns true if command matches pattern
+     */
+    matchPattern(command, pattern) {
+        // Trim whitespace
+        command = command.trim();
+        pattern = pattern.trim();
+        // Exact match
+        if (pattern === command) {
+            return true;
+        }
+        // Prefix match with ':*' wildcard
+        if (pattern.endsWith(":*")) {
+            const prefix = pattern.slice(0, -2).trim();
+            // Match if command equals prefix or starts with prefix followed by space or colon
+            return command === prefix || command.startsWith(prefix) || command.startsWith(`${prefix}:`);
+        }
+        return false;
+    }
+}
+export default BashAgent;
+function getBashAgentSchema({ filepath }) {
+    const nestAgentSchema = getNestAgentSchema({ filepath });
+    return camelizeSchema(z.object({
+        sandbox: optionalize(z.union([makeShapePropertiesOptions(SandboxRuntimeConfigSchema, 2), z.boolean()])),
+        inputKey: optionalize(z.string().describe("The input key for the bash script.")),
+        timeout: optionalize(z.number().describe("Timeout for script execution in milliseconds.")),
+        permissions: optionalize(camelizeSchema(z.object({
+            allow: optionalize(z.array(z.string())),
+            deny: optionalize(z.array(z.string())),
+            defaultMode: optionalize(z.enum(["allow", "ask", "deny"])),
+            guard: optionalize(nestAgentSchema),
+        }))),
+    }));
+}
+function makeShapePropertiesOptions(schema, depth = 1) {
+    return z.object(Object.fromEntries(Object.entries(schema.shape).map(([key, value]) => {
+        const isObject = value instanceof ZodObject;
+        if (isObject && depth > 1) {
+            return [key, optionalize(makeShapePropertiesOptions(value, depth - 1))];
+        }
+        return [key, optionalize(value)];
+    })));
+}

package/lib/esm/utils/mutex.d.ts

@@ -0,0 +1,6 @@
+export declare class Mutex {
+    constructor();
+    private _lock;
+    lock(): Promise<() => void>;
+    runExclusive<T>(callback: () => Promise<T> | T): Promise<T>;
+}

package/lib/esm/utils/mutex.js

@@ -0,0 +1,24 @@
+export class Mutex {
+    constructor() {
+        this._lock = Promise.resolve();
+    }
+    _lock;
+    lock() {
+        let unlockNext;
+        const willLock = new Promise((resolve) => {
+            unlockNext = resolve;
+        });
+        const willUnlock = this._lock.then(() => unlockNext);
+        this._lock = willLock;
+        return willUnlock;
+    }
+    async runExclusive(callback) {
+        const unlock = await this.lock();
+        try {
+            return await callback();
+        }
+        finally {
+            unlock();
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/agent-library",
-  "version": "1.23.0-beta.7",
+  "version": "1.23.0-beta.8",
   "description": "Collection of agent libraries for AIGNE framework",
   "publishConfig": {
     "access": "public"
@@ -48,6 +48,8 @@
   },
   "dependencies": {
     "@aigne/uuid": "^13.0.1",
+    "@anthropic-ai/sandbox-runtime": "^0.0.19",
+    "@vscode/ripgrep": "^1.15.14",
     "drizzle-orm": "^0.44.5",
     "fastq": "^1.19.1",
     "jsonata": "^2.1.0",
@@ -56,8 +58,8 @@
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.6",
     "@aigne/core": "^1.71.0-beta.6",
-    "@aigne/openai": "^0.16.15-beta.6",
-    "@aigne/sqlite": "^0.4.8-beta"
+    "@aigne/sqlite": "^0.4.8-beta",
+    "@aigne/openai": "^0.16.15-beta.6"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",