@acontext/acontext 0.1.0 → 0.1.2

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- 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

@@ -0,0 +1,102 @@
+"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
+- 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

@@ -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;