@agentscope-ai/agentscope 0.0.2

package/src/storage/file-system.ts

@@ -0,0 +1,269 @@
+import fs from 'fs';
+import path from 'path';
+
+import * as mime from 'mime-types';
+
+import { Msg } from '../message';
+import { AgentState, StorageBase } from './base';
+
+/**
+ * Local file system storage implementation.
+ * Stores agent state in JSON files with support for incremental context updates.
+ */
+export class LocalFileStorage extends StorageBase {
+    saveDir: string;
+    offloadDir?: string;
+
+    /**
+     * Internal metadata key prefix for storage-layer fields.
+     * Fields with this prefix are managed by storage and filtered out when returning to agent layer.
+     */
+    private readonly INTERNAL_PREFIX = '_storage_';
+
+    /**
+     * Initialize a LocalFileStorage instance.
+     * @param root0
+     * @param root0.pathSegments - Path segments to determine the directory for saving agent state (e.g. ['rootDir', '{sessionId}'])
+     * @param root0.offloadPathSegments - Optional path segments for offloading compressed context for agentic search (e.g. ['rootDir', 'offload'])
+     */
+    constructor({
+        pathSegments = [],
+        offloadPathSegments = [],
+    }: {
+        pathSegments?: string[];
+        offloadPathSegments?: string[];
+    }) {
+        super();
+        this.saveDir = path.join(...pathSegments);
+        this.offloadDir =
+            offloadPathSegments.length > 0 ? path.join(...offloadPathSegments) : undefined;
+    }
+
+    /**
+     * Load the complete agent state including context and metadata.
+     * @param options
+     * @param options.agentId - The agent identifier
+     * @returns The agent state with context and metadata (internal fields filtered out)
+     */
+    async loadAgentState(options?: { agentId?: string }): Promise<AgentState> {
+        const agentDir = path.join(this.saveDir, options?.agentId || '');
+
+        // If the agent directory doesn't exist, return empty state
+        if (!fs.existsSync(agentDir)) {
+            console.log(`Agent directory ${agentDir} does not exist. Returning empty state.`);
+            return {
+                context: [],
+                metadata: {},
+            };
+        }
+        console.log(`Loading agent state from directory: ${agentDir}`);
+
+        const contextFile = path.join(agentDir, 'context.jsonl');
+        const stateFile = path.join(agentDir, 'state.json');
+
+        // Load metadata
+        let metadata: Record<string, unknown> = {};
+        if (fs.existsSync(stateFile)) {
+            const content = fs.readFileSync(stateFile, 'utf-8');
+            metadata = JSON.parse(content);
+        }
+
+        // Extract internal compression boundary ID
+        const compressionBoundaryMsgId = metadata[
+            `${this.INTERNAL_PREFIX}compressionBoundaryMsgId`
+        ] as string | undefined;
+
+        // Load context (incrementally if compression boundary exists)
+        let context: Msg[] = [];
+        if (fs.existsSync(contextFile)) {
+            const content = fs.readFileSync(contextFile, 'utf-8');
+            const allMsgs = content
+                .trim()
+                .split('\n')
+                .filter(line => line.length > 0)
+                .map(line => JSON.parse(line));
+
+            if (compressionBoundaryMsgId) {
+                // Load only messages after the compression boundary
+                const boundaryIndex = allMsgs.findIndex(msg => msg.id === compressionBoundaryMsgId);
+                if (boundaryIndex !== -1) {
+                    // Include the boundary message itself
+                    context = allMsgs.slice(boundaryIndex);
+                } else {
+                    // Boundary not found, load all messages
+                    context = allMsgs;
+                }
+            } else {
+                // No compression, load all messages
+                context = allMsgs;
+            }
+        }
+
+        // Filter out internal fields from metadata before returning
+        const publicMetadata = this._filterInternalFields(metadata);
+
+        return {
+            context,
+            metadata: publicMetadata,
+        };
+    }
+
+    /**
+     * Save the complete agent state including context and metadata.
+     * @param options
+     * @param options.agentId - The agent identifier
+     * @param options.context - The conversation context to save
+     * @param options.metadata - The agent metadata to save
+     */
+    async saveAgentState(options: {
+        agentId?: string;
+        context: Msg[];
+        metadata: Record<string, unknown>;
+    }): Promise<void> {
+        const agentDir = path.join(this.saveDir, options.agentId || '');
+        const contextFile = path.join(agentDir, 'context.jsonl');
+        const stateFile = path.join(agentDir, 'state.json');
+
+        // Ensure directory exists
+        if (!fs.existsSync(agentDir)) {
+            fs.mkdirSync(agentDir, { recursive: true });
+        }
+
+        // Determine compression boundary (first message in current context)
+        const compressionBoundaryMsgId = options.context[0]?.id;
+
+        // Save context with incremental append optimization
+        if (!fs.existsSync(contextFile)) {
+            // First time: write all messages
+            const content = options.context.map(msg => JSON.stringify(msg)).join('\n');
+            if (content) {
+                fs.writeFileSync(contextFile, content + '\n', 'utf-8');
+            }
+        } else {
+            // File exists: append only new messages
+            const existingContent = fs.readFileSync(contextFile, 'utf-8');
+            const existingLines = existingContent
+                .trim()
+                .split('\n')
+                .filter(line => line.length > 0);
+
+            if (existingLines.length > 0) {
+                const lastLine = existingLines[existingLines.length - 1];
+                const lastMsg = JSON.parse(lastLine);
+
+                // Find new messages that need to be saved (including the last saved message to overwrite it)
+                const lastMsgIndex = options.context.findIndex(msg => msg.id === lastMsg.id);
+                const newMsgs =
+                    lastMsgIndex >= 0 ? options.context.slice(lastMsgIndex) : options.context;
+
+                if (newMsgs.length > 0) {
+                    // Combine existing messages (without last line) with new messages
+                    const allLines = [
+                        ...existingLines.slice(0, -1),
+                        ...newMsgs.map(msg => JSON.stringify(msg)),
+                    ];
+                    const content = allLines.join('\n') + '\n';
+                    fs.writeFileSync(contextFile, content, 'utf-8');
+                }
+            } else {
+                // File is empty, write all messages
+                const content = options.context.map(msg => JSON.stringify(msg)).join('\n');
+                if (content) {
+                    fs.writeFileSync(contextFile, content + '\n', 'utf-8');
+                }
+            }
+        }
+
+        // Save metadata with internal compression boundary
+        const internalMetadata = {
+            ...options.metadata,
+            [`${this.INTERNAL_PREFIX}compressionBoundaryMsgId`]: compressionBoundaryMsgId,
+        };
+        fs.writeFileSync(stateFile, JSON.stringify(internalMetadata, null, 2), 'utf-8');
+    }
+
+    /**
+     * Filter out internal storage fields from metadata.
+     * @param metadata - The metadata object
+     * @returns Metadata with internal fields removed
+     */
+    private _filterInternalFields(metadata: Record<string, unknown>): Record<string, unknown> {
+        const filtered: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(metadata)) {
+            if (!key.startsWith(this.INTERNAL_PREFIX)) {
+                filtered[key] = value;
+            }
+        }
+        return filtered;
+    }
+
+    /**
+     * Offload the compressed context to external storage for agentic search if needed.
+     * @param options
+     * @param options.agentId - The agent identifier
+     * @param options.msgs - The messages to offload
+     * @returns The file path of the offloaded context, or undefined if offloading is not implemented or not needed
+     */
+    async offloadContext(options: { agentId?: string; msgs: Msg[] }): Promise<string | undefined> {
+        if (!this.offloadDir) {
+            return;
+        }
+
+        // Offload the compressed context to the text file
+        // e.g. 2026-03-01.txt
+        const fileName = `${new Date().toISOString().split('T')[0]}.txt`;
+        const offloadFile = path.join(this.offloadDir, options.agentId || '', fileName);
+        const offloadDataDir = path.join(this.offloadDir, options.agentId || '', 'data');
+
+        // Create the dir if it doesn't exist
+        const offloadAgentDir = path.dirname(offloadFile);
+        if (!fs.existsSync(offloadAgentDir)) {
+            fs.mkdirSync(offloadAgentDir, { recursive: true });
+        }
+
+        // Append the new context to the offload file
+        let appendContent = '';
+        for (const msg of options.msgs) {
+            const msgContent: string[] = [];
+            for (const block of msg.content) {
+                switch (block.type) {
+                    case 'text':
+                        msgContent.push(`${msg.name}: ${block.text}`);
+                        break;
+                    case 'data':
+                        if (block.source.type === 'url') {
+                            msgContent.push(
+                                `${msg.name}: <data src={${block.source.url}} type={${block.source.mediaType}} />`
+                            );
+                        } else if (block.source.type === 'base64') {
+                            // Save the base64 data to a file and add a reference to the file in the offload content
+                            const mainType = block.source.mediaType.split('/')[0];
+                            const extension = mime.extension(block.source.mediaType) || 'bin';
+                            const filePath = path.join(
+                                offloadDataDir,
+                                `${mainType}-${Date.now()}.${extension}`
+                            );
+                            if (!fs.existsSync(offloadDataDir)) {
+                                fs.mkdirSync(offloadDataDir, { recursive: true });
+                            }
+                            const buffer = Buffer.from(block.source.data, 'base64');
+                            fs.writeFileSync(filePath, buffer);
+                            msgContent.push(
+                                `${msg.name}: <data src={${filePath}} type={${block.source.mediaType}} />`
+                            );
+                        }
+                        break;
+                    case 'tool_call':
+                        msgContent.push(`${msg.name}: Calling tool ${block.name} ...`);
+                        break;
+                }
+            }
+            appendContent += msgContent.join('\n') + '\n';
+        }
+
+        // Append to the offload file
+        fs.appendFileSync(offloadFile, appendContent, 'utf-8');
+
+        return offloadFile;
+    }
+}

package/src/storage/index.ts

@@ -0,0 +1,2 @@
+export { AgentState, StorageBase } from './base';
+export { LocalFileStorage } from './file-system';

package/src/tool/base.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+import { ToolResponse } from './response';
+import { ToolInputSchema } from '../type';
+
+export interface Tool {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject | ToolInputSchema;
+    call?: (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        input: any
+    ) =>
+        | string
+        | Promise<string>
+        | Generator<string>
+        | AsyncGenerator<string>
+        | ToolResponse
+        | Promise<ToolResponse>
+        | Generator<ToolResponse>
+        | AsyncGenerator<ToolResponse>;
+    requireUserConfirm?: boolean;
+}

package/src/tool/bash.test.ts

@@ -0,0 +1,174 @@
+import { Bash } from './bash';
+
+describe('Bash', () => {
+    test('Normal command execution', async () => {
+        const bash = Bash();
+        // Use cross-platform compatible command
+        const command = process.platform === 'win32' ? 'echo Hello World' : 'echo "Hello World"';
+        const result = await bash.call({ command });
+
+        expect(result.state).toBe('success');
+        expect(result.content).toHaveLength(1);
+        expect(result.content[0].type).toBe('text');
+        expect((result.content[0] as { type: 'text'; text: string }).text).toContain('Hello World');
+    });
+
+    test('Command with description parameter', async () => {
+        const bash = Bash();
+        const command = process.platform === 'win32' ? 'echo Test' : 'echo "Test"';
+        const result = await bash.call({
+            command,
+            description: 'Test command with description',
+        });
+
+        expect(result.state).toBe('success');
+        expect(result.content).toHaveLength(1);
+        expect((result.content[0] as { type: 'text'; text: string }).text).toContain('Test');
+    });
+
+    test('Error command - non-existent command', async () => {
+        const bash = Bash();
+        const result = await bash.call({
+            command: 'nonexistentcommand123',
+        });
+
+        expect(result.state).toBe('error');
+        expect(result.content).toHaveLength(1);
+        expect(result.content[0].type).toBe('text');
+        const text = (result.content[0] as { type: 'text'; text: string }).text;
+        expect(text).toContain('Command failed');
+        expect(text).toContain('nonexistentcommand123');
+    });
+
+    test('Error command - division by zero in bash', async () => {
+        const bash = Bash();
+        // In bash, division by zero causes an error
+        // On Windows cmd, this syntax doesn't work, so use a different failing command
+        const command = process.platform === 'win32' ? 'set /a 10/0' : 'echo $((10/0))';
+        const result = await bash.call({ command });
+
+        expect(result.state).toBe('error');
+        expect(result.content).toHaveLength(1);
+        const text = (result.content[0] as { type: 'text'; text: string }).text;
+        expect(text).toContain('Command failed');
+    });
+
+    test('Timeout command', async () => {
+        const bash = Bash();
+        // Use cross-platform sleep command
+        // On Windows, use ping as a delay mechanism (more reliable than timeout in non-interactive mode)
+        const command = process.platform === 'win32' ? 'ping 127.0.0.1 -n 6 > nul' : 'sleep 5';
+        const result = await bash.call({
+            command,
+            timeout: 1000, // 1 second timeout
+        });
+
+        expect(result.state).toBe('error');
+        expect(result.content).toHaveLength(1);
+        const text = (result.content[0] as { type: 'text'; text: string }).text;
+        expect(text).toContain('Command failed');
+    }, 10000); // Increase Jest timeout for this test
+
+    test('Command with custom timeout that succeeds', async () => {
+        const bash = Bash();
+        // On Windows, use ping as a delay (ping waits ~1 second per count)
+        const command = process.platform === 'win32' ? 'ping 127.0.0.1 -n 2 > nul' : 'sleep 1';
+        const result = await bash.call({
+            command,
+            timeout: 3000, // 3 second timeout
+        });
+
+        expect(result.state).toBe('success');
+    }, 10000);
+
+    test('Output truncation - exceeds 30000 characters', async () => {
+        const bash = Bash();
+        // Generate output longer than 30000 characters
+        const command =
+            process.platform === 'win32'
+                ? 'for /L %i in (1,1,10000) do @echo This is line %i with some extra text'
+                : 'for i in {1..10000}; do echo "This is line $i with some extra text"; done';
+        const result = await bash.call({ command });
+
+        expect(result.state).toBe('success');
+        expect(result.content).toHaveLength(1);
+        const text = (result.content[0] as { type: 'text'; text: string }).text;
+        expect(text).toContain('[Output truncated - exceeded 30000 characters]');
+        expect(text.length).toBeLessThanOrEqual(30100); // Allow some buffer for truncation message
+    }, 10000);
+
+    test('Command with stderr output', async () => {
+        const bash = Bash();
+        // Use a command that writes to stderr - cross-platform
+        const command =
+            process.platform === 'win32'
+                ? 'dir C:\\nonexistent_directory_12345'
+                : 'ls /nonexistent_directory_12345';
+        const result = await bash.call({ command });
+
+        expect(result.state).toBe('error');
+        expect(result.content).toHaveLength(1);
+        const text = (result.content[0] as { type: 'text'; text: string }).text;
+        expect(text).toContain('Command failed');
+    });
+
+    test('Command with both stdout and stderr', async () => {
+        const bash = Bash();
+        // Command that produces both stdout and stderr
+        const command =
+            process.platform === 'win32'
+                ? 'echo stdout message && dir C:\\nonexistent_directory_12345'
+                : 'echo "stdout message" && ls /nonexistent_directory_12345';
+        const result = await bash.call({ command });
+
+        expect(result.state).toBe('error');
+        expect(result.content).toHaveLength(1);
+        const text = (result.content[0] as { type: 'text'; text: string }).text;
+        expect(text).toContain('Command failed');
+        expect(text).toContain('stdout message');
+    });
+
+    test('Maximum timeout enforcement', async () => {
+        const bash = Bash();
+        // Try to set timeout beyond maximum (600000ms)
+        const command = process.platform === 'win32' ? 'echo test' : 'echo "test"';
+        const result = await bash.call({
+            command,
+            timeout: 700000, // 700 seconds, should be capped at 600000
+        });
+
+        // Should still succeed because the command is fast
+        expect(result.state).toBe('success');
+    });
+
+    test('Command with special characters', async () => {
+        const bash = Bash();
+        // Windows cmd has different special character handling
+        const command =
+            process.platform === 'win32'
+                ? 'echo Special chars: %USERPROFILE%'
+                : 'echo "Special chars: $HOME | & ; < > ( ) { }"';
+        const result = await bash.call({ command });
+
+        expect(result.state).toBe('success');
+        expect(result.content).toHaveLength(1);
+        const text = (result.content[0] as { type: 'text'; text: string }).text;
+        expect(text).toContain('Special chars');
+    });
+
+    test('Multi-line output', async () => {
+        const bash = Bash();
+        const command =
+            process.platform === 'win32'
+                ? 'echo Line 1 && echo Line 2 && echo Line 3'
+                : 'echo "Line 1" && echo "Line 2" && echo "Line 3"';
+        const result = await bash.call({ command });
+
+        expect(result.state).toBe('success');
+        expect(result.content).toHaveLength(1);
+        const text = (result.content[0] as { type: 'text'; text: string }).text;
+        expect(text).toContain('Line 1');
+        expect(text).toContain('Line 2');
+        expect(text).toContain('Line 3');
+    });
+});

package/src/tool/bash.ts

@@ -0,0 +1,152 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+import { z } from 'zod';
+
+import { createToolResponse, ToolResponse } from './response';
+
+const execAsync = promisify(exec);
+
+/**
+ * Tool for executing bash commands in a shell environment.
+ * Intended for terminal operations such as git, npm, and docker.
+ * File operations should use the dedicated Read, Write, Edit, Glob, and Grep tools instead.
+ *
+ * @returns A Tool object for executing bash commands, with a call method that performs the execution and returns the output or error message.
+ */
+export function Bash() {
+    return {
+        name: 'Bash',
+        description: `Executes a given bash command and returns its output.
+
+The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile (bash or zsh).
+
+IMPORTANT: Avoid using this tool to run \`find\`, \`grep\`, \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
+
+ - File search: Use Glob (NOT find or ls)
+ - Content search: Use Grep (NOT grep or rg)
+ - Read files: Use Read (NOT cat/head/tail)
+ - Edit files: Use Edit (NOT sed/awk)
+ - Write files: Use Write (NOT echo >/cat <<EOF)
+ - Communication: Output text directly (NOT echo/printf)
+
+While the Bash tool can do similar things, it's better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
+
+# Instructions
+ - If your command will create new directories or files, first use this tool to run \`ls\` to verify the parent directory exists and is the correct location.
+ - Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt")
+ - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of \`cd\`. You may use \`cd\` if the User explicitly requests it.
+ - You may specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). By default, your command will timeout after 120000ms (2 minutes).
+ - Write a clear, concise description of what your command does. For simple commands, keep it brief (5-10 words). For complex commands (piped commands, obscure flags, or anything hard to understand at a glance), include enough context so that the user can understand what your command will do.
+ - When issuing multiple commands:
+  - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. Example: if you need to run "git status" and "git diff", send a single message with two Bash tool calls in parallel.
+  - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together.
+  - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.
+  - DO NOT use newlines to separate commands (newlines are ok in quoted strings).
+ - For git commands:
+  - Prefer to create a new commit rather than amending an existing commit.
+  - Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
+  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
+ - Avoid unnecessary \`sleep\` commands:
+  - Do not sleep between commands that can run immediately — just run them.
+  - Do not retry failing commands in a sleep loop — diagnose the root cause or consider an alternative approach.
+  - If you must sleep, keep the duration short (1-5 seconds) to avoid blocking the user.`,
+        inputSchema: z.object({
+            command: z.string().describe('The bash command to execute'),
+            description: z
+                .string()
+                .optional()
+                .describe(
+                    'Clear, concise description of what this command does. For simple commands, keep it brief (5-10 words). For complex commands, include enough context.'
+                ),
+            timeout: z
+                .number()
+                .int()
+                .min(0)
+                .max(600000)
+                .optional()
+                .describe('Optional timeout in milliseconds (default: 120000, max: 600000)'),
+        }),
+        requireUserConfirm: true,
+
+        /**
+         * Executes a bash command and returns its output.
+         *
+         * @param root0 - The parameters object
+         * @param root0.command - The bash command to execute
+         * @param root0.description - Optional description of what the command does
+         * @param root0.timeout - Optional timeout in milliseconds (default: 120000, max: 600000)
+         * @returns The stdout of the command, or an error message if the command fails
+         */
+        async call({
+            command,
+            description: _description,
+            timeout = 120000,
+        }: {
+            command: string;
+            description?: string;
+            timeout?: number;
+        }): Promise<ToolResponse> {
+            try {
+                const maxTimeout = 600000;
+                const effectiveTimeout = Math.min(timeout, maxTimeout);
+
+                // Determine the appropriate shell based on platform
+                let shell: string;
+                if (process.platform === 'win32') {
+                    // On Windows, use cmd.exe or PowerShell
+                    shell = process.env.COMSPEC || 'cmd.exe';
+                } else {
+                    // On Unix-like systems, use the user's shell or default to bash
+                    shell = process.env.SHELL || '/bin/bash';
+                }
+
+                const { stdout } = await execAsync(command, {
+                    encoding: 'utf-8',
+                    timeout: effectiveTimeout,
+                    maxBuffer: 30000 * 1024,
+                    shell,
+                });
+
+                // Normalize line endings to LF for cross-platform consistency
+                const normalizedOutput = stdout.replace(/\r\n/g, '\n');
+
+                const maxOutputLength = 30000;
+                if (normalizedOutput.length > maxOutputLength) {
+                    return createToolResponse({
+                        content: [
+                            {
+                                id: crypto.randomUUID(),
+                                type: 'text',
+                                text:
+                                    normalizedOutput.substring(0, maxOutputLength) +
+                                    '\n\n[Output truncated - exceeded 30000 characters]',
+                            },
+                        ],
+                        state: 'success',
+                    });
+                }
+
+                return createToolResponse({
+                    content: [{ id: crypto.randomUUID(), type: 'text', text: normalizedOutput }],
+                    state: 'success',
+                });
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            } catch (error: any) {
+                const errorMessage = error.message || 'Unknown error';
+                const stderr = error.stderr?.toString().replace(/\r\n/g, '\n') || '';
+                const stdout = error.stdout?.toString().replace(/\r\n/g, '\n') || '';
+
+                let result = `Command failed: ${command}\n`;
+                if (stdout) result += `\nStdout:\n${stdout}`;
+                if (stderr) result += `\nStderr:\n${stderr}`;
+                if (errorMessage && !stderr) result += `\nError: ${errorMessage}`;
+
+                return createToolResponse({
+                    content: [{ id: crypto.randomUUID(), type: 'text', text: result }],
+                    state: 'error',
+                });
+            }
+        },
+    };
+}