@acontext/acontext 0.1.1 → 0.1.3

package/dist/agent/prompts.d.ts

@@ -3,4 +3,4 @@
  */
 export declare const SKILL_REMINDER = "MANDATORY SKILL READING AND EXECUTION PROTOCOL:\nBEFORE writing ANY code or using ANY execution tools, You MUST complete ALL of\nthese steps:\n\nSTEP 1 - IDENTIFY ALL RELEVANT SKILLS:\n- Scan the user message for ALL trigger words from ALL skills\n- Identify EVERY skill that matches ANY trigger word\n- If multiple skills match, ALL must be processed\n- If no skills match, you can skip the following steps\n\nSTEP 2 - READ ALL SKILL FILES:\n- Use the text_editor_sandbox tool to view EACH identified skill's SKILL.md file\n- READ COMPLETELY - do not skim or skip sections\n- This step is MANDATORY even if multiple skills are involved\n- DO NOT proceed until ALL relevant skill files have been read\n\nSTEP 3 - EXECUTE ALL SKILL INSTRUCTIONS:\n- Follow the EXACT instructions from EACH skill file read\n- If a skill file says to execute file X, then EXECUTE file X\n- If a skill file provides code patterns, USE those patterns\n- Apply instructions from ALL skills, not just the first one\n- NEVER write generic code when skill-specific code exists\n\nCRITICAL RULES:\n- Reading the skill file is NOT sufficient - you must FOLLOW its instructions\n- Multiple skills = multiple skill files to read AND follow\n- Each skill's instructions must be executed, not just acknowledged\n- NEVER skip a skill because you already read another skill\n- The skills contain specialized, tested code that MUST be used\n\nDO NOT SKIP ANY SKILL FILES OR THEIR INSTRUCTIONS. This protocol applies to EVERY\nskill that matches the user's request, without exception.";
 export declare const SANDBOX_TEXT_EDITOR_REMINDER = "The text_editor_sandbox tool enables viewing, creating, and modifying text files within\nthe secure sandboxed container environment.\n\nHow it works:\n- All file operations occur within the sandboxed container filesystem\n\nCommand guidelines:\n- Always use view before editing to understand file structure\n- For str_replace commands, ensure search strings are unique and exact\n- Include sufficient context in str_replace for accurate placement\n- Use proper escaping for special characters in search/replace strings";
-export declare const SANDBOX_BASH_REMINDER = "When to use the bash_execution_sandbox tool directly:\n- File system operations requiring shell commands (moving, copying, renaming, organizing files)\n- Text processing and manipulation using standard Unix tools (grep, sed, awk, cut, sort, etc.) that\nshould not be done by the text editor tool\n- Batch processing of multiple files using shell loops and wildcards\n- System inspection tasks (checking file sizes, permissions, directory structures)\n- Combining multiple command-line tools in pipelines for complex data processing\n- Archive operations (tar, unzip) and file compression/decompression\n- Converting between file formats using command-line utilities\n\nWhen you should write Python file and use bash tool to run it:\n- Complex data analysis or numerical computation (use file operations to write a Python script instead, and\nthen the bash to run the script)\n- Tasks requiring advanced programming logic or data structures\n\nWhen NOT to use the bash_execution_sandbox tool:\n- Simple questions that can be answered without executing commands\n- Tasks that only require explaining shell concepts without actual execution\n\nHow it works:\n- Scripts are saved to a temporary sandbox and executed with bash\n- Tool results will include stdout, stderr, and return code\n- User-uploaded files are accessible in the directory specified by the INPUT_DIR environment variable. If\nyou know the file path and don't need to open the full INPUT_DIR, then just open the file directly\n\nFile Operations (CRITICAL - READ CAREFULLY):\n- use text_editor_sandbox tool to view, create, and edit files.\n\nExport Your Result:\n- All the files you created kept in the sandbox, which user can't see or access.\n- If you want to export them to user, use `export_file_sandbox` tool.\n- If too many files to export(>= 6 files), zip those files and export the zip file.\n- Result files' names should be unique and descriptive, (wrong: result.md, output.md... right: 2026_us_market_trending.png)\n\nScript guidelines:\n- Write POSIX-compliant bash scripts\n- Use proper error handling and exit codes\n- Quote variables appropriately to handle spaces in filenames\n- Keep scripts clean and well-organized\n- For file operations, use text_editor_sandbox tool instead of bash commands.\n\nNever write blocking script:\n- python codes like `plt.show()` or `input()`... will block the execution of the script, don't use them. write non-blocking code instead.\n\nContainer environment:\n- Filesystem persists across multiple executions within the same container\n- Standard Unix utilities available (grep, sed, awk, etc.)\n- Archive tools: tar, unzip, zip\n- Additional tools: ripgrep, fd, sqlite3, jq, imagemagick\n- Do not try to install new packages and libraries with pip as there is no internet access\n";
+export declare const SANDBOX_BASH_REMINDER = "When to use the bash_execution_sandbox tool directly:\n- File system operations requiring shell commands (moving, copying, renaming, organizing files)\n- Text processing and manipulation using standard Unix tools (grep, sed, awk, cut, sort, etc.) that\nshould not be done by the text editor tool\n- Batch processing of multiple files using shell loops and wildcards\n- System inspection tasks (checking file sizes, permissions, directory structures)\n- Combining multiple command-line tools in pipelines for complex data processing\n- Archive operations (tar, unzip) and file compression/decompression\n- Converting between file formats using command-line utilities\n\nWhen you should write Python file and use bash tool to run it:\n- Complex data analysis or numerical computation (use file operations to write a Python script instead, and\nthen the bash to run the script)\n- Tasks requiring advanced programming logic or data structures\n\nWhen NOT to use the bash_execution_sandbox tool:\n- Simple questions that can be answered without executing commands\n- Tasks that only require explaining shell concepts without actual execution\n\nHow it works:\n- Scripts are saved to a temporary sandbox and executed with bash\n- Tool results will include stdout, stderr, and return code\n- User-uploaded files are accessible in the directory specified by the INPUT_DIR environment variable. If\nyou know the file path and don't need to open the full INPUT_DIR, then just open the file directly\n\nFile Operations (CRITICAL - READ CAREFULLY):\n- use text_editor_sandbox tool to view, create, and edit files.\n\nExport Your Result:\n- All the files you created kept in the sandbox, which user can't see or access.\n- If you want to export them to user, use `export_file_sandbox` tool.\n- If too many files to export(>= 6 files), zip those files and export the zip file.\n- Result files' names should be unique and descriptive, (wrong: result.md, output.md... right: 2026_us_market_trending.png)\n\nScript guidelines:\n- Write POSIX-compliant bash scripts\n- Use proper error handling and exit codes\n- Quote variables appropriately to handle spaces in filenames\n- Keep scripts clean and well-organized\n- For file operations, use text_editor_sandbox tool instead of bash commands.\n\nNever write blocking script:\n- python codes like `plt.show()` or `input()`... will block the execution of the script, don't use them. write non-blocking code instead.\n\nContainer environment:\n- Filesystem persists across multiple executions within the same container\n- Standard Unix utilities available (grep, sed, awk, etc.)\n- Archive tools: tar, unzip, zip\n- Additional tools: ripgrep, fd, sqlite3, jq, imagemagick\n- You can install new packages with pip if needed (internet access is available)\n\nRemember to always export your artifacts at the end of your task so that the user can view them.\n";

package/dist/agent/prompts.js

@@ -96,5 +96,7 @@ Container environment:
 - Standard Unix utilities available (grep, sed, awk, etc.)
 - Archive tools: tar, unzip, zip
 - Additional tools: ripgrep, fd, sqlite3, jq, imagemagick
-- Do not try to install new packages and libraries with pip as there is no internet access
+- You can install new packages with pip if needed (internet access is available)
+
+Remember to always export your artifacts at the end of your task so that the user can view them.
 `;

package/dist/agent/sandbox.d.ts

@@ -64,6 +64,9 @@ export declare class TextEditorTool extends AbstractBaseTool {
         };
         view_range: {
             type: string[];
+            items: {
+                type: string;
+            };
             description: string;
         };
     };

package/dist/agent/sandbox.js

@@ -41,6 +41,13 @@ const path = __importStar(require("path"));
 const base_1 = require("./base");
 const prompts_1 = require("./prompts");
 const text_editor_1 = require("./text-editor");
+const MAX_OUTPUT_CHARS = 20000;
+function truncateOutput(text, maxChars = MAX_OUTPUT_CHARS) {
+    if (text.length > maxChars) {
+        return text.slice(0, maxChars) + '...[truncated]';
+    }
+    return text;
+}
 function formatMountedSkills(mountedSkillPaths) {
     if (mountedSkillPaths.size === 0) {
         return '';
@@ -120,8 +127,8 @@ class BashTool extends base_1.AbstractBaseTool {
             timeout,
         });
         return JSON.stringify({
-            stdout: result.stdout,
-            stderr: result.stderr,
+            stdout: truncateOutput(result.stdout),
+            stderr: truncateOutput(result.stderr),
             exit_code: result.exit_code,
         });
     }
@@ -136,27 +143,32 @@ class TextEditorTool extends base_1.AbstractBaseTool {
             command: {
                 type: 'string',
                 enum: ['view', 'create', 'str_replace'],
-                description: "The operation to perform: 'view', 'create', or 'str_replace'",
+                description: "The operation to perform: 'view', 'create', or 'str_replace'. " +
+                    "Required parameters per command: " +
+                    "'view' requires path (view_range is optional); " +
+                    "'create' requires path and file_text; " +
+                    "'str_replace' requires path, old_str, and new_str.",
             },
             path: {
                 type: 'string',
-                description: "The file path in the sandbox (e.g., '/workspace/script.py')",
+                description: "Required for all commands. The file path in the sandbox (e.g., '/workspace/script.py')",
             },
             file_text: {
                 type: ['string', 'null'],
-                description: "For 'create' command: the content to write to the file",
+                description: "Required for 'create' command. The content to write to the file.",
             },
             old_str: {
                 type: ['string', 'null'],
-                description: "For 'str_replace' command: the exact string to find and replace",
+                description: "Required for 'str_replace' command. The exact string to find and replace.",
             },
             new_str: {
                 type: ['string', 'null'],
-                description: "For 'str_replace' command: the string to replace old_str with",
+                description: "Required for 'str_replace' command. The string to replace old_str with.",
             },
             view_range: {
                 type: ['array', 'null'],
-                description: "For 'view' command: optional [start_line, end_line] to view specific lines",
+                items: { type: 'integer' },
+                description: "Optional for 'view' command. An array [start_line, end_line] to view specific lines. If not provided, shows the first 200 lines.",
             },
         };
         this.requiredArguments = ['command', 'path'];

package/dist/agent/text-editor.d.ts

@@ -22,23 +22,22 @@ export interface CreateFileResult {
     stderr?: string;
 }
 export interface StrReplaceResult {
-    oldStart?: number;
-    oldLines?: number;
-    newStart?: number;
-    newLines?: number;
-    lines?: string[];
+    msg?: string;
     error?: string;
     stderr?: string;
 }
 /**
  * View file content with line numbers.
  */
-export declare function viewFile(ctx: SandboxContext, path: string, viewRange: number[] | null, timeout?: number): Promise<ViewFileResult>;
+export declare function viewFile(ctx: SandboxContext, filePath: string, viewRange: number[] | null, timeout?: number): Promise<ViewFileResult>;
 /**
  * Create a new file with content.
  */
-export declare function createFile(ctx: SandboxContext, path: string, fileText: string, timeout?: number): Promise<CreateFileResult>;
+export declare function createFile(ctx: SandboxContext, filePath: string, fileText: string, timeout?: number): Promise<CreateFileResult>;
 /**
  * Replace a string in a file.
+ *
+ * Uses a Python script on the sandbox to avoid transferring the entire file.
+ * Only the base64-encoded oldStr and newStr are sent.
  */
-export declare function strReplace(ctx: SandboxContext, path: string, oldStr: string, newStr: string, timeout?: number): Promise<StrReplaceResult>;
+export declare function strReplace(ctx: SandboxContext, filePath: string, oldStr: string, newStr: string, timeout?: number): Promise<StrReplaceResult>;

package/dist/agent/text-editor.js

@@ -2,11 +2,25 @@
 /**
  * Text editor file operations for sandbox environments.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.escapeForShell = escapeForShell;
 exports.viewFile = viewFile;
 exports.createFile = createFile;
 exports.strReplace = strReplace;
+const path_1 = __importDefault(require("path"));
+const MAX_CONTENT_CHARS = 20000;
+/**
+ * Truncate text to maxChars, appending a truncation flag if needed.
+ */
+function truncateContent(text, maxChars = MAX_CONTENT_CHARS) {
+    if (text.length > maxChars) {
+        return text.slice(0, maxChars) + '...[truncated]';
+    }
+    return text;
+}
 /**
  * Escape a string for safe use in shell commands.
  */
@@ -17,54 +31,48 @@ function escapeForShell(s) {
 /**
  * View file content with line numbers.
  */
-async function viewFile(ctx, path, viewRange, timeout) {
-    // First check if file exists and get total lines
-    const checkCmd = `wc -l < ${escapeForShell(path)} 2>/dev/null || echo 'FILE_NOT_FOUND'`;
-    const checkResult = await ctx.client.sandboxes.execCommand({
-        sandboxId: ctx.sandboxId,
-        command: checkCmd,
-        timeout,
-    });
-    if (checkResult.stdout.includes('FILE_NOT_FOUND') || checkResult.exit_code !== 0) {
-        return {
-            error: `File not found: ${path}`,
-            stderr: checkResult.stderr,
-        };
-    }
-    const totalLines = /^\d+$/.test(checkResult.stdout.trim())
-        ? parseInt(checkResult.stdout.trim(), 10)
-        : 0;
-    // Build the view command with line numbers
-    let cmd;
+async function viewFile(ctx, filePath, viewRange, timeout) {
+    const escapedPath = escapeForShell(filePath);
+    // Build combined command: check existence, get total lines, and view content in one exec
+    let viewCmd;
     let startLine;
     if (viewRange && viewRange.length === 2) {
         const [rangeStart, rangeEnd] = viewRange;
-        cmd = `sed -n '${rangeStart},${rangeEnd}p' ${escapeForShell(path)} | nl -ba -v ${rangeStart}`;
+        viewCmd = `sed -n '${rangeStart},${rangeEnd}p' ${escapedPath} | nl -ba -v ${rangeStart}`;
         startLine = rangeStart;
     }
     else {
-        cmd = `nl -ba ${escapeForShell(path)}`;
+        const maxLines = 200;
+        viewCmd = `head -n ${maxLines} ${escapedPath} | nl -ba`;
         startLine = 1;
     }
+    // Single combined command: outputs "TOTAL:<n>" on first line, then file content
+    const cmd = `if [ ! -f ${escapedPath} ]; then echo 'FILE_NOT_FOUND'; exit 1; fi; echo "TOTAL:$(wc -l < ${escapedPath})"; ${viewCmd}`;
     const result = await ctx.client.sandboxes.execCommand({
         sandboxId: ctx.sandboxId,
         command: cmd,
         timeout,
     });
-    if (result.exit_code !== 0) {
+    if (result.exit_code !== 0 || result.stdout.includes('FILE_NOT_FOUND')) {
         return {
-            error: `Failed to view file: ${path}`,
+            error: `File not found: ${filePath}`,
             stderr: result.stderr,
         };
     }
-    // Count lines in output
-    const contentLines = result.stdout.trim()
-        ? result.stdout.trimEnd().split('\n')
-        : [];
+    // Parse output: first line is "TOTAL:<n>", rest is content
+    const lines = result.stdout.split('\n');
+    let totalLines = 0;
+    let content = '';
+    if (lines.length > 0 && lines[0].startsWith('TOTAL:')) {
+        const totalStr = lines[0].substring(6).trim();
+        totalLines = /^\d+$/.test(totalStr) ? parseInt(totalStr, 10) : 0;
+        content = lines.slice(1).join('\n');
+    }
+    const contentLines = content.trim() ? content.trimEnd().split('\n') : [];
     const numLines = contentLines.length;
     return {
         file_type: 'text',
-        content: result.stdout,
+        content: truncateContent(content),
         numLines,
         startLine: viewRange ? startLine : 1,
         totalLines: totalLines + 1, // wc -l doesn't count last line without newline
@@ -73,129 +81,83 @@ async function viewFile(ctx, path, viewRange, timeout) {
 /**
  * Create a new file with content.
  */
-async function createFile(ctx, path, fileText, timeout) {
-    // Check if file already exists
-    const checkCmd = `test -f ${escapeForShell(path)} && echo 'EXISTS' || echo 'NEW'`;
-    const checkResult = await ctx.client.sandboxes.execCommand({
-        sandboxId: ctx.sandboxId,
-        command: checkCmd,
-        timeout,
-    });
-    const isUpdate = checkResult.stdout.includes('EXISTS');
-    // Create directory if needed
-    const parts = path.split('/');
-    parts.pop();
-    const dirPath = parts.join('/');
-    if (dirPath) {
-        const mkdirCmd = `mkdir -p ${escapeForShell(dirPath)}`;
-        await ctx.client.sandboxes.execCommand({
-            sandboxId: ctx.sandboxId,
-            command: mkdirCmd,
-            timeout,
-        });
-    }
-    // Write file using base64 encoding to safely transfer content
+async function createFile(ctx, filePath, fileText, timeout) {
+    const escapedPath = escapeForShell(filePath);
     const encodedContent = Buffer.from(fileText, 'utf-8').toString('base64');
-    const writeCmd = `echo ${escapeForShell(encodedContent)} | base64 -d > ${escapeForShell(path)}`;
+    // Get directory path for mkdir
+    const dirPath = path_1.default.posix.dirname(filePath);
+    const mkdirPart = dirPath && dirPath !== '.' ? `mkdir -p ${escapeForShell(dirPath)} && ` : '';
+    // Single combined command: check existence, create dir, write file
+    const cmd = `is_update=$(test -f ${escapedPath} && echo 1 || echo 0); ${mkdirPart}echo ${escapeForShell(encodedContent)} | base64 -d > ${escapedPath} && echo "STATUS:$is_update"`;
     const result = await ctx.client.sandboxes.execCommand({
         sandboxId: ctx.sandboxId,
-        command: writeCmd,
+        command: cmd,
         timeout,
     });
-    if (result.exit_code !== 0) {
+    if (result.exit_code !== 0 || !result.stdout.includes('STATUS:')) {
         return {
-            error: `Failed to create file: ${path}`,
+            error: `Failed to create file: ${filePath}`,
             stderr: result.stderr,
         };
     }
+    const isUpdate = result.stdout.includes('STATUS:1');
     return {
         is_file_update: isUpdate,
-        message: `File ${isUpdate ? 'updated' : 'created'}: ${path}`,
+        message: `File ${isUpdate ? 'updated' : 'created'}: ${filePath}`,
     };
 }
 /**
  * Replace a string in a file.
+ *
+ * Uses a Python script on the sandbox to avoid transferring the entire file.
+ * Only the base64-encoded oldStr and newStr are sent.
  */
-async function strReplace(ctx, path, oldStr, newStr, timeout) {
-    // First read the file content
-    const readCmd = `cat ${escapeForShell(path)}`;
+async function strReplace(ctx, filePath, oldStr, newStr, timeout) {
+    const oldB64 = Buffer.from(oldStr, 'utf-8').toString('base64');
+    const newB64 = Buffer.from(newStr, 'utf-8').toString('base64');
+    // Write Python script and base64 encode it to avoid shell escaping issues
+    const pyScript = `import sys, base64, os
+old = base64.b64decode("${oldB64}").decode()
+new = base64.b64decode("${newB64}").decode()
+path = "${filePath}"
+if not os.path.exists(path):
+    print("FILE_NOT_FOUND")
+    sys.exit(1)
+with open(path, "r") as f:
+    content = f.read()
+count = content.count(old)
+if count == 0:
+    print("NOT_FOUND")
+    sys.exit(0)
+if count > 1:
+    print(f"MULTIPLE:{count}")
+    sys.exit(0)
+with open(path, "w") as f:
+    f.write(content.replace(old, new, 1))
+print("SUCCESS")
+`;
+    const scriptB64 = Buffer.from(pyScript, 'utf-8').toString('base64');
+    const cmd = `echo ${escapeForShell(scriptB64)} | base64 -d | python3`;
     const result = await ctx.client.sandboxes.execCommand({
         sandboxId: ctx.sandboxId,
-        command: readCmd,
+        command: cmd,
         timeout,
     });
-    if (result.exit_code !== 0) {
-        return {
-            error: `File not found: ${path}`,
-            stderr: result.stderr,
-        };
-    }
-    const originalContent = result.stdout;
-    // Check if oldStr exists in the file
-    if (!originalContent.includes(oldStr)) {
-        return {
-            error: `String not found in file: ${oldStr.substring(0, 50)}...`,
-        };
-    }
-    // Count occurrences
-    let occurrences = 0;
-    let searchIndex = 0;
-    while (searchIndex < originalContent.length) {
-        const foundIndex = originalContent.indexOf(oldStr, searchIndex);
-        if (foundIndex === -1)
-            break;
-        occurrences++;
-        searchIndex = foundIndex + oldStr.length;
-    }
-    if (occurrences > 1) {
-        return {
-            error: `Multiple occurrences (${occurrences}) of the string found. Please provide more context to make the match unique.`,
-        };
+    const output = result.stdout.trim();
+    if (result.exit_code !== 0 || output === 'FILE_NOT_FOUND') {
+        return { error: `File not found: ${filePath}`, stderr: result.stderr };
     }
-    // Perform the replacement
-    const newContent = originalContent.replace(oldStr, newStr);
-    // Find the line numbers affected
-    const oldLines = originalContent.split('\n');
-    const newLines = newContent.split('\n');
-    // Find where the change starts
-    let oldStart = 1;
-    const minLen = Math.min(oldLines.length, newLines.length);
-    for (let i = 0; i < minLen; i++) {
-        if (oldLines[i] !== newLines[i]) {
-            oldStart = i + 1;
-            break;
-        }
+    if (output === 'NOT_FOUND') {
+        return { error: `String not found in file: ${oldStr.substring(0, 50)}...` };
     }
-    // Write the new content
-    const encodedContent = Buffer.from(newContent, 'utf-8').toString('base64');
-    const writeCmd = `echo ${escapeForShell(encodedContent)} | base64 -d > ${escapeForShell(path)}`;
-    const writeResult = await ctx.client.sandboxes.execCommand({
-        sandboxId: ctx.sandboxId,
-        command: writeCmd,
-        timeout,
-    });
-    if (writeResult.exit_code !== 0) {
+    if (output.startsWith('MULTIPLE:')) {
+        const count = output.split(':')[1];
         return {
-            error: `Failed to write file: ${path}`,
-            stderr: writeResult.stderr,
+            error: `Multiple occurrences (${count}) of the string found. Please provide more context to make the match unique.`,
         };
     }
-    // Calculate diff info
-    const oldStrLines = oldStr.split('\n').length;
-    const newStrLines = newStr.split('\n').length;
-    // Build diff lines
-    const diffLines = [];
-    for (const line of oldStr.split('\n')) {
-        diffLines.push(`-${line}`);
-    }
-    for (const line of newStr.split('\n')) {
-        diffLines.push(`+${line}`);
+    if (output === 'SUCCESS') {
+        return { msg: 'Successfully replaced text at exactly one location.' };
     }
-    return {
-        oldStart,
-        oldLines: oldStrLines,
-        newStart: oldStart,
-        newLines: newStrLines,
-        lines: diffLines,
-    };
+    return { error: `Unexpected response: ${output}`, stderr: result.stderr };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acontext/acontext",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "TypeScript SDK for the Acontext API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",