@acontext/acontext 0.1.0 → 0.1.1

package/dist/agent/base.d.ts

@@ -2,6 +2,7 @@
  * Base classes for agent tools.
  */
 export interface BaseContext {
+    getContextPrompt(): string;
 }
 export interface BaseConverter {
     toOpenAIToolSchema(): Record<string, unknown>;
@@ -35,5 +36,5 @@ export declare abstract class BaseToolPool {
     toOpenAIToolSchema(): Record<string, unknown>[];
     toAnthropicToolSchema(): Record<string, unknown>[];
     toGeminiToolSchema(): Record<string, unknown>[];
-    abstract formatContext(...args: unknown[]): BaseContext;
+    abstract formatContext(...args: unknown[]): BaseContext | Promise<BaseContext>;
 }

package/dist/agent/disk.d.ts

@@ -6,9 +6,10 @@ import { AbstractBaseTool, BaseContext, BaseToolPool } from './base';
 export interface DiskContext extends BaseContext {
     client: AcontextClient;
     diskId: string;
+    getContextPrompt(): string;
 }
 export declare class WriteFileTool extends AbstractBaseTool {
-    readonly name = "write_file";
+    readonly name = "write_file_disk";
     readonly description = "Write text content to a file in the file system. Creates the file if it doesn't exist, overwrites if it does.";
     readonly arguments: {
         file_path: {
@@ -28,7 +29,7 @@ export declare class WriteFileTool extends AbstractBaseTool {
     execute(ctx: DiskContext, llmArguments: Record<string, unknown>): Promise<string>;
 }
 export declare class ReadFileTool extends AbstractBaseTool {
-    readonly name = "read_file";
+    readonly name = "read_file_disk";
     readonly description = "Read a text file from the file system and return its content.";
     readonly arguments: {
         file_path: {
@@ -52,7 +53,7 @@ export declare class ReadFileTool extends AbstractBaseTool {
     execute(ctx: DiskContext, llmArguments: Record<string, unknown>): Promise<string>;
 }
 export declare class ReplaceStringTool extends AbstractBaseTool {
-    readonly name = "replace_string";
+    readonly name = "replace_string_disk";
     readonly description = "Replace an old string with a new string in a file. Reads the file, performs the replacement, and writes it back.";
     readonly arguments: {
         file_path: {
@@ -76,7 +77,7 @@ export declare class ReplaceStringTool extends AbstractBaseTool {
     execute(ctx: DiskContext, llmArguments: Record<string, unknown>): Promise<string>;
 }
 export declare class ListTool extends AbstractBaseTool {
-    readonly name = "list_artifacts";
+    readonly name = "list_disk";
     readonly description = "List all files and directories in a specified path on the disk.";
     readonly arguments: {
         file_path: {
@@ -88,7 +89,7 @@ export declare class ListTool extends AbstractBaseTool {
     execute(ctx: DiskContext, llmArguments: Record<string, unknown>): Promise<string>;
 }
 export declare class DownloadFileTool extends AbstractBaseTool {
-    readonly name = "download_file";
+    readonly name = "download_file_disk";
     readonly description = "Get a public URL to download a file. Returns a presigned URL that can be shared or used to access the file.";
     readonly arguments: {
         file_path: {
@@ -108,7 +109,7 @@ export declare class DownloadFileTool extends AbstractBaseTool {
     execute(ctx: DiskContext, llmArguments: Record<string, unknown>): Promise<string>;
 }
 export declare class GrepArtifactsTool extends AbstractBaseTool {
-    readonly name = "grep_artifacts";
+    readonly name = "grep_disk";
     readonly description = "Search for text patterns within file contents using regex. Only searches text-based files (code, markdown, json, csv, etc.). Use this to find specific code patterns, TODO comments, function definitions, or any text content.";
     readonly arguments: {
         query: {
@@ -124,7 +125,7 @@ export declare class GrepArtifactsTool extends AbstractBaseTool {
     execute(ctx: DiskContext, llmArguments: Record<string, unknown>): Promise<string>;
 }
 export declare class GlobArtifactsTool extends AbstractBaseTool {
-    readonly name = "glob_artifacts";
+    readonly name = "glob_disk";
     readonly description = "Find files by path pattern using glob syntax. Use * for any characters, ? for single character, ** for recursive directories. Perfect for finding files by extension or location.";
     readonly arguments: {
         query: {

package/dist/agent/disk.js

@@ -6,6 +6,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DISK_TOOLS = exports.DiskToolPool = exports.GlobArtifactsTool = exports.GrepArtifactsTool = exports.DownloadFileTool = exports.ListTool = exports.ReplaceStringTool = exports.ReadFileTool = exports.WriteFileTool = void 0;
 const uploads_1 = require("../uploads");
 const base_1 = require("./base");
+const DISK_CONTEXT_PROMPT = `<disk>
+Consider Disk as the google drive for you and user to store and share files.
+You can use tool ends with \`*_disk\` to read, write, edit, and share files with users.
+Disk is only a sharable file storage, you can't use it to execute code or run commands.
+</disk>
+`;
 function normalizePath(path) {
     if (!path) {
         return '/';
@@ -19,7 +25,7 @@ function normalizePath(path) {
 class WriteFileTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
-        this.name = 'write_file';
+        this.name = 'write_file_disk';
         this.description = "Write text content to a file in the file system. Creates the file if it doesn't exist, overwrites if it does.";
         this.arguments = {
             file_path: {
@@ -64,7 +70,7 @@ exports.WriteFileTool = WriteFileTool;
 class ReadFileTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
-        this.name = 'read_file';
+        this.name = 'read_file_disk';
         this.description = 'Read a text file from the file system and return its content.';
         this.arguments = {
             file_path: {
@@ -115,7 +121,7 @@ exports.ReadFileTool = ReadFileTool;
 class ReplaceStringTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
-        this.name = 'replace_string';
+        this.name = 'replace_string_disk';
         this.description = 'Replace an old string with a new string in a file. Reads the file, performs the replacement, and writes it back.';
         this.arguments = {
             file_path: {
@@ -195,7 +201,7 @@ exports.ReplaceStringTool = ReplaceStringTool;
 class ListTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
-        this.name = 'list_artifacts';
+        this.name = 'list_disk';
         this.description = 'List all files and directories in a specified path on the disk.';
         this.arguments = {
             file_path: {
@@ -223,7 +229,7 @@ exports.ListTool = ListTool;
 class DownloadFileTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
-        this.name = 'download_file';
+        this.name = 'download_file_disk';
         this.description = 'Get a public URL to download a file. Returns a presigned URL that can be shared or used to access the file.';
         this.arguments = {
             file_path: {
@@ -265,7 +271,7 @@ exports.DownloadFileTool = DownloadFileTool;
 class GrepArtifactsTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
-        this.name = 'grep_artifacts';
+        this.name = 'grep_disk';
         this.description = 'Search for text patterns within file contents using regex. Only searches text-based files (code, markdown, json, csv, etc.). Use this to find specific code patterns, TODO comments, function definitions, or any text content.';
         this.arguments = {
             query: {
@@ -300,7 +306,7 @@ exports.GrepArtifactsTool = GrepArtifactsTool;
 class GlobArtifactsTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
-        this.name = 'glob_artifacts';
+        this.name = 'glob_disk';
         this.description = 'Find files by path pattern using glob syntax. Use * for any characters, ? for single character, ** for recursive directories. Perfect for finding files by extension or location.';
         this.arguments = {
             query: {
@@ -337,6 +343,9 @@ class DiskToolPool extends base_1.BaseToolPool {
         return {
             client,
             diskId,
+            getContextPrompt() {
+                return DISK_CONTEXT_PROMPT;
+            },
         };
     }
 }

package/dist/agent/index.d.ts

@@ -3,4 +3,6 @@
  */
 export * from './base';
 export * from './disk';
+export * from './prompts';
+export * from './sandbox';
 export * from './skill';

package/dist/agent/index.js

@@ -19,4 +19,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./base"), exports);
 __exportStar(require("./disk"), exports);
+__exportStar(require("./prompts"), exports);
+__exportStar(require("./sandbox"), exports);
 __exportStar(require("./skill"), exports);

package/dist/agent/prompts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Prompt constants for agent tools.
+ */
+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";

package/dist/agent/prompts.js

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

package/dist/agent/sandbox.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Agent tools for sandbox operations using the Acontext Sandbox API.
+ */
+import { AcontextClient } from '../client';
+import { AbstractBaseTool, BaseContext, BaseToolPool } from './base';
+export interface MountedSkill {
+    name: string;
+    description: string;
+    basePath: string;
+}
+export interface SandboxContext extends BaseContext {
+    client: AcontextClient;
+    sandboxId: string;
+    diskId: string;
+    mountedSkillPaths: Map<string, MountedSkill>;
+    getContextPrompt(): string;
+    formatMountedSkills(): string;
+    mountSkills(skillIds: string[]): Promise<void>;
+}
+export declare class BashTool extends AbstractBaseTool {
+    private _timeout?;
+    constructor(timeout?: number);
+    readonly name = "bash_execution_sandbox";
+    readonly description = "The bash_execution_sandbox tool enables execution of bash scripts in a secure sandboxed container environment.";
+    readonly arguments: {
+        command: {
+            type: string;
+            description: string;
+        };
+        timeout: {
+            type: string[];
+            description: string;
+        };
+    };
+    readonly requiredArguments: string[];
+    execute(ctx: SandboxContext, llmArguments: Record<string, unknown>): Promise<string>;
+}
+export declare class TextEditorTool extends AbstractBaseTool {
+    private _timeout?;
+    constructor(timeout?: number);
+    readonly name = "text_editor_sandbox";
+    readonly description = "A tool for viewing, creating, and editing text files in the sandbox.";
+    readonly arguments: {
+        command: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        path: {
+            type: string;
+            description: string;
+        };
+        file_text: {
+            type: string[];
+            description: string;
+        };
+        old_str: {
+            type: string[];
+            description: string;
+        };
+        new_str: {
+            type: string[];
+            description: string;
+        };
+        view_range: {
+            type: string[];
+            description: string;
+        };
+    };
+    readonly requiredArguments: string[];
+    execute(ctx: SandboxContext, llmArguments: Record<string, unknown>): Promise<string>;
+}
+export declare class ExportSandboxFileTool extends AbstractBaseTool {
+    readonly name = "export_file_sandbox";
+    readonly description = "Export a file from the sandbox to persistent, shared disk storage, and return you a public download URL.\nIf the sandbox file is changed, the disk file won't be updated unless you export the file again.";
+    readonly arguments: {
+        sandbox_path: {
+            type: string;
+            description: string;
+        };
+        sandbox_filename: {
+            type: string;
+            description: string;
+        };
+    };
+    readonly requiredArguments: string[];
+    execute(ctx: SandboxContext, llmArguments: Record<string, unknown>): Promise<string>;
+}
+export declare class SandboxToolPool extends BaseToolPool {
+    /**
+     * Create a sandbox context.
+     *
+     * @param client - The Acontext client instance.
+     * @param sandboxId - The UUID of the sandbox.
+     * @param diskId - The UUID of the disk for file exports.
+     * @param mountSkills - Optional list of skill IDs to download to the sandbox.
+     *                     Skills are downloaded to /skills/{skill_name}/ in the sandbox.
+     * @returns Promise resolving to SandboxContext for use with sandbox tools.
+     */
+    formatContext(client: AcontextClient, sandboxId: string, diskId: string, mountSkills?: string[]): Promise<SandboxContext>;
+}
+export declare const SANDBOX_TOOLS: SandboxToolPool;