@acontext/acontext 0.1.0 → 0.1.2

package/dist/agent/sandbox.js

@@ -0,0 +1,320 @@
+"use strict";
+/**
+ * Agent tools for sandbox operations using the Acontext Sandbox API.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SANDBOX_TOOLS = exports.SandboxToolPool = exports.ExportSandboxFileTool = exports.TextEditorTool = exports.BashTool = void 0;
+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 '';
+    }
+    // Sort by skill name
+    const sortedSkills = Array.from(mountedSkillPaths.values()).sort((a, b) => a.name.localeCompare(b.name));
+    const skillEntries = sortedSkills.map((skill) => {
+        const location = path.posix.join(skill.basePath, 'SKILL.md');
+        return `<skill>
+<name>${skill.name}</name>
+<description>${skill.description}</description>
+<location>${location}</location>
+</skill>`;
+    });
+    return skillEntries.join('\n');
+}
+function getSandboxContextPrompt(mountedSkillPaths) {
+    let baseBody = `<text_editor_sandbox>
+${prompts_1.SANDBOX_TEXT_EDITOR_REMINDER}
+</text_editor_sandbox>
+<bash_execution_sandbox>
+${prompts_1.SANDBOX_BASH_REMINDER}
+</bash_execution_sandbox>`;
+    if (mountedSkillPaths.size > 0) {
+        const formattedSkills = formatMountedSkills(mountedSkillPaths);
+        baseBody += `
+<skills>
+${prompts_1.SKILL_REMINDER}
+<available_skills>
+${formattedSkills}
+</available_skills>
+</skills>`;
+    }
+    return `<sandbox>
+By default, you are in \`/workspace\`.
+${baseBody}
+</sandbox>
+`;
+}
+function normalizePath(path) {
+    if (!path) {
+        return '/';
+    }
+    let normalized = path.startsWith('/') ? path : `/${path}`;
+    if (!normalized.endsWith('/')) {
+        normalized += '/';
+    }
+    return normalized;
+}
+class BashTool extends base_1.AbstractBaseTool {
+    constructor(timeout) {
+        super();
+        this.name = 'bash_execution_sandbox';
+        this.description = 'The bash_execution_sandbox tool enables execution of bash scripts in a secure sandboxed container environment.';
+        this.arguments = {
+            command: {
+                type: 'string',
+                description: "The bash command to execute. Examples: 'ls -la', 'python3 script.py', 'sed -i 's/old_string/new_string/g' file.py'",
+            },
+            timeout: {
+                type: ['number', 'null'],
+                description: 'Optional timeout in seconds for this command. Use for long-running commands that may exceed the default timeout.',
+            },
+        };
+        this.requiredArguments = ['command'];
+        this._timeout = timeout;
+    }
+    async execute(ctx, llmArguments) {
+        const command = llmArguments.command;
+        const timeout = llmArguments.timeout ?? this._timeout;
+        if (!command) {
+            throw new Error('command is required');
+        }
+        const result = await ctx.client.sandboxes.execCommand({
+            sandboxId: ctx.sandboxId,
+            command,
+            timeout,
+        });
+        return JSON.stringify({
+            stdout: truncateOutput(result.stdout),
+            stderr: truncateOutput(result.stderr),
+            exit_code: result.exit_code,
+        });
+    }
+}
+exports.BashTool = BashTool;
+class TextEditorTool extends base_1.AbstractBaseTool {
+    constructor(timeout) {
+        super();
+        this.name = 'text_editor_sandbox';
+        this.description = 'A tool for viewing, creating, and editing text files in the sandbox.';
+        this.arguments = {
+            command: {
+                type: 'string',
+                enum: ['view', 'create', '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: "Required for all commands. The file path in the sandbox (e.g., '/workspace/script.py')",
+            },
+            file_text: {
+                type: ['string', 'null'],
+                description: "Required for 'create' command. The content to write to the file.",
+            },
+            old_str: {
+                type: ['string', 'null'],
+                description: "Required for 'str_replace' command. The exact string to find and replace.",
+            },
+            new_str: {
+                type: ['string', 'null'],
+                description: "Required for 'str_replace' command. The string to replace old_str with.",
+            },
+            view_range: {
+                type: ['array', 'null'],
+                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'];
+        this._timeout = timeout;
+    }
+    async execute(ctx, llmArguments) {
+        const command = llmArguments.command;
+        const path = llmArguments.path;
+        if (!command) {
+            throw new Error('command is required');
+        }
+        if (!path) {
+            throw new Error('path is required');
+        }
+        if (command === 'view') {
+            const viewRange = llmArguments.view_range;
+            const result = await (0, text_editor_1.viewFile)(ctx, path, viewRange, this._timeout);
+            return JSON.stringify(result);
+        }
+        else if (command === 'create') {
+            const fileText = llmArguments.file_text;
+            if (fileText === null || fileText === undefined) {
+                throw new Error('file_text is required for create command');
+            }
+            const result = await (0, text_editor_1.createFile)(ctx, path, fileText, this._timeout);
+            return JSON.stringify(result);
+        }
+        else if (command === 'str_replace') {
+            const oldStr = llmArguments.old_str;
+            const newStr = llmArguments.new_str;
+            if (oldStr === null || oldStr === undefined) {
+                throw new Error('old_str is required for str_replace command');
+            }
+            if (newStr === null || newStr === undefined) {
+                throw new Error('new_str is required for str_replace command');
+            }
+            const result = await (0, text_editor_1.strReplace)(ctx, path, oldStr, newStr, this._timeout);
+            return JSON.stringify(result);
+        }
+        else {
+            throw new Error(`Unknown command: ${command}. Must be 'view', 'create', or 'str_replace'`);
+        }
+    }
+}
+exports.TextEditorTool = TextEditorTool;
+class ExportSandboxFileTool extends base_1.AbstractBaseTool {
+    constructor() {
+        super(...arguments);
+        this.name = 'export_file_sandbox';
+        this.description = `Export a file from the sandbox to persistent, shared disk storage, and return you a public download URL.
+If the sandbox file is changed, the disk file won't be updated unless you export the file again.`;
+        this.arguments = {
+            sandbox_path: {
+                type: 'string',
+                description: "The directory path in the sandbox where the file is located. Must end with '/'. Examples: '/workspace/', '/home/user/output/'",
+            },
+            sandbox_filename: {
+                type: 'string',
+                description: 'The name of the file to export from the sandbox.',
+            },
+        };
+        this.requiredArguments = ['sandbox_path', 'sandbox_filename'];
+    }
+    async execute(ctx, llmArguments) {
+        const sandboxPath = llmArguments.sandbox_path;
+        const sandboxFilename = llmArguments.sandbox_filename;
+        const diskPath = '/artifacts/';
+        if (!sandboxPath) {
+            throw new Error('sandbox_path is required');
+        }
+        if (!sandboxFilename) {
+            throw new Error('sandbox_filename is required');
+        }
+        const normalizedSandboxPath = normalizePath(sandboxPath);
+        const normalizedDiskPath = normalizePath(diskPath);
+        const artifact = await ctx.client.disks.artifacts.uploadFromSandbox(ctx.diskId, {
+            sandboxId: ctx.sandboxId,
+            sandboxPath: normalizedSandboxPath,
+            sandboxFilename,
+            filePath: normalizedDiskPath,
+        });
+        // Get the public URL for the uploaded artifact
+        const artifactInfo = await ctx.client.disks.artifacts.get(ctx.diskId, {
+            filePath: artifact.path,
+            filename: artifact.filename,
+            withPublicUrl: true,
+            withContent: false,
+        });
+        return JSON.stringify({
+            message: 'successfully exported file to disk',
+            public_url: artifactInfo.public_url,
+        });
+    }
+}
+exports.ExportSandboxFileTool = ExportSandboxFileTool;
+class SandboxToolPool extends base_1.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.
+     */
+    async formatContext(client, sandboxId, diskId, mountSkills) {
+        const mountedSkillPaths = new Map();
+        const ctx = {
+            client,
+            sandboxId,
+            diskId,
+            mountedSkillPaths,
+            getContextPrompt() {
+                return getSandboxContextPrompt(mountedSkillPaths);
+            },
+            formatMountedSkills() {
+                return formatMountedSkills(mountedSkillPaths);
+            },
+            async mountSkills(skillIds) {
+                for (const skillId of skillIds) {
+                    if (mountedSkillPaths.has(skillId)) {
+                        // Skip already mounted skills
+                        continue;
+                    }
+                    const result = await client.skills.downloadToSandbox(skillId, {
+                        sandboxId,
+                    });
+                    if (result.success) {
+                        mountedSkillPaths.set(skillId, {
+                            basePath: result.dir_path,
+                            name: result.name,
+                            description: result.description,
+                        });
+                    }
+                }
+            },
+        };
+        if (mountSkills && mountSkills.length > 0) {
+            await ctx.mountSkills(mountSkills);
+        }
+        return ctx;
+    }
+}
+exports.SandboxToolPool = SandboxToolPool;
+// Pre-configured tool pool with sandbox tools
+exports.SANDBOX_TOOLS = new SandboxToolPool();
+exports.SANDBOX_TOOLS.addTool(new BashTool());
+exports.SANDBOX_TOOLS.addTool(new TextEditorTool());
+exports.SANDBOX_TOOLS.addTool(new ExportSandboxFileTool());

package/dist/agent/skill.d.ts

@@ -10,6 +10,7 @@ import { AbstractBaseTool, BaseContext, BaseToolPool } from './base';
 export interface SkillContext extends BaseContext {
     client: AcontextClient;
     skills: Map<string, Skill>;
+    getContextPrompt(): string;
 }
 /**
  * Create a SkillContext by preloading skills from a list of skill IDs.
@@ -33,13 +34,6 @@ export declare function getSkillFromContext(ctx: SkillContext, skillName: string
  * Return list of available skill names in this context.
  */
 export declare function listSkillNamesFromContext(ctx: SkillContext): string[];
-export declare class ListSkillsTool extends AbstractBaseTool {
-    readonly name = "list_skills";
-    readonly description = "List all available skills in the current context with their names and descriptions.";
-    readonly arguments: {};
-    readonly requiredArguments: string[];
-    execute(ctx: SkillContext, _llmArguments: Record<string, unknown>): Promise<string>;
-}
 export declare class GetSkillTool extends AbstractBaseTool {
     readonly name = "get_skill";
     readonly description = "Get a skill by its name. Returns the skill information including the relative paths of the files and their mime type categories.";
@@ -65,7 +59,7 @@ export declare class GetSkillFileTool extends AbstractBaseTool {
             description: string;
         };
         expire: {
-            type: string;
+            type: string[];
             description: string;
         };
     };

package/dist/agent/skill.js

@@ -3,7 +3,7 @@
  * Skill tools for agent operations.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SKILL_TOOLS = exports.SkillToolPool = exports.GetSkillFileTool = exports.GetSkillTool = exports.ListSkillsTool = void 0;
+exports.SKILL_TOOLS = exports.SkillToolPool = exports.GetSkillFileTool = exports.GetSkillTool = void 0;
 exports.createSkillContext = createSkillContext;
 exports.getSkillFromContext = getSkillFromContext;
 exports.listSkillNamesFromContext = listSkillNamesFromContext;
@@ -27,7 +27,30 @@ async function createSkillContext(client, skillIds) {
         }
         skills.set(skill.name, skill);
     }
-    return { client, skills };
+    return {
+        client,
+        skills,
+        getContextPrompt() {
+            if (skills.size === 0) {
+                return '';
+            }
+            const lines = ['<available_skills>'];
+            for (const [skillName, skill] of skills.entries()) {
+                lines.push('<skill>');
+                lines.push(`<name>${skillName}</name>`);
+                lines.push(`<description>${skill.description}</description>`);
+                lines.push('</skill>');
+            }
+            lines.push('</available_skills>');
+            const skillSection = lines.join('\n');
+            return `<skill_view>
+Use get_skill and get_skill_file to view the available skills and their contexts.
+Below is the list of available skills:
+${skillSection}        
+</skill_view>
+`;
+        },
+    };
 }
 /**
  * Get a skill by name from the preloaded skills.
@@ -51,26 +74,6 @@ function getSkillFromContext(ctx, skillName) {
 function listSkillNamesFromContext(ctx) {
     return Array.from(ctx.skills.keys());
 }
-class ListSkillsTool extends base_1.AbstractBaseTool {
-    constructor() {
-        super(...arguments);
-        this.name = 'list_skills';
-        this.description = 'List all available skills in the current context with their names and descriptions.';
-        this.arguments = {};
-        this.requiredArguments = [];
-    }
-    async execute(ctx, _llmArguments) {
-        if (ctx.skills.size === 0) {
-            return 'No skills available in the current context.';
-        }
-        const skillList = [];
-        for (const [skillName, skill] of ctx.skills.entries()) {
-            skillList.push(`- ${skillName}: ${skill.description}`);
-        }
-        return `Available skills (${ctx.skills.size}):\n${skillList.join('\n')}`;
-    }
-}
-exports.ListSkillsTool = ListSkillsTool;
 class GetSkillTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
@@ -124,7 +127,7 @@ class GetSkillFileTool extends base_1.AbstractBaseTool {
                 description: "Relative path to the file within the skill (e.g., 'scripts/extract_text.json').",
             },
             expire: {
-                type: 'number',
+                type: ['integer', 'null'],
                 description: 'URL expiration time in seconds (only used for non-parseable files). Defaults to 900 (15 minutes).',
             },
         };
@@ -179,6 +182,5 @@ class SkillToolPool extends base_1.BaseToolPool {
 }
 exports.SkillToolPool = SkillToolPool;
 exports.SKILL_TOOLS = new SkillToolPool();
-exports.SKILL_TOOLS.addTool(new ListSkillsTool());
 exports.SKILL_TOOLS.addTool(new GetSkillTool());
 exports.SKILL_TOOLS.addTool(new GetSkillFileTool());

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

@@ -0,0 +1,44 @@
+/**
+ * Text editor file operations for sandbox environments.
+ */
+import type { SandboxContext } from './sandbox';
+/**
+ * Escape a string for safe use in shell commands.
+ */
+export declare function escapeForShell(s: string): string;
+export interface ViewFileResult {
+    file_type?: string;
+    content?: string;
+    numLines?: number;
+    startLine?: number;
+    totalLines?: number;
+    error?: string;
+    stderr?: string;
+}
+export interface CreateFileResult {
+    is_file_update?: boolean;
+    message?: string;
+    error?: string;
+    stderr?: string;
+}
+export interface StrReplaceResult {
+    oldStart?: number;
+    oldLines?: number;
+    newStart?: number;
+    newLines?: number;
+    lines?: 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>;
+/**
+ * Create a new file with content.
+ */
+export declare function createFile(ctx: SandboxContext, path: string, fileText: string, timeout?: number): Promise<CreateFileResult>;
+/**
+ * Replace a string in a file.
+ */
+export declare function strReplace(ctx: SandboxContext, path: string, oldStr: string, newStr: string, timeout?: number): Promise<StrReplaceResult>;

package/dist/agent/text-editor.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Text editor file operations for sandbox environments.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeForShell = escapeForShell;
+exports.viewFile = viewFile;
+exports.createFile = createFile;
+exports.strReplace = strReplace;
+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.
+ */
+function escapeForShell(s) {
+    // Use single quotes and escape any single quotes in the string
+    return "'" + s.replace(/'/g, "'\"'\"'") + "'";
+}
+/**
+ * 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;
+    let startLine;
+    if (viewRange && viewRange.length === 2) {
+        const [rangeStart, rangeEnd] = viewRange;
+        cmd = `sed -n '${rangeStart},${rangeEnd}p' ${escapeForShell(path)} | nl -ba -v ${rangeStart}`;
+        startLine = rangeStart;
+    }
+    else {
+        // Default to first 200 lines if no range specified
+        const maxLines = 200;
+        cmd = `head -n ${maxLines} ${escapeForShell(path)} | nl -ba`;
+        startLine = 1;
+    }
+    const result = await ctx.client.sandboxes.execCommand({
+        sandboxId: ctx.sandboxId,
+        command: cmd,
+        timeout,
+    });
+    if (result.exit_code !== 0) {
+        return {
+            error: `Failed to view file: ${path}`,
+            stderr: result.stderr,
+        };
+    }
+    // Count lines in output
+    const contentLines = result.stdout.trim()
+        ? result.stdout.trimEnd().split('\n')
+        : [];
+    const numLines = contentLines.length;
+    return {
+        file_type: 'text',
+        content: truncateContent(result.stdout),
+        numLines,
+        startLine: viewRange ? startLine : 1,
+        totalLines: totalLines + 1, // wc -l doesn't count last line without newline
+    };
+}
+/**
+ * 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
+    const encodedContent = Buffer.from(fileText, 'utf-8').toString('base64');
+    const writeCmd = `echo ${escapeForShell(encodedContent)} | base64 -d > ${escapeForShell(path)}`;
+    const result = await ctx.client.sandboxes.execCommand({
+        sandboxId: ctx.sandboxId,
+        command: writeCmd,
+        timeout,
+    });
+    if (result.exit_code !== 0) {
+        return {
+            error: `Failed to create file: ${path}`,
+            stderr: result.stderr,
+        };
+    }
+    return {
+        is_file_update: isUpdate,
+        message: `File ${isUpdate ? 'updated' : 'created'}: ${path}`,
+    };
+}
+/**
+ * Replace a string in a file.
+ */
+async function strReplace(ctx, path, oldStr, newStr, timeout) {
+    // First read the file content
+    const readCmd = `cat ${escapeForShell(path)}`;
+    const result = await ctx.client.sandboxes.execCommand({
+        sandboxId: ctx.sandboxId,
+        command: readCmd,
+        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.`,
+        };
+    }
+    // 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;
+        }
+    }
+    // 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) {
+        return {
+            error: `Failed to write file: ${path}`,
+            stderr: writeResult.stderr,
+        };
+    }
+    // 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}`);
+    }
+    return {
+        oldStart,
+        oldLines: oldStrLines,
+        newStart: oldStart,
+        newLines: newStrLines,
+        lines: diffLines,
+    };
+}

package/dist/client-types.d.ts

@@ -12,5 +12,6 @@ export interface RequesterProtocol {
             contentType: string;
         }>;
         unwrap?: boolean;
+        timeout?: number;
     }): Promise<T>;
 }