acontext 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

acontext/agent/text_editor.py

@@ -0,0 +1,436 @@
+"""Text editor file operations for sandbox environments."""
+
+import base64
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .sandbox import AsyncSandboxContext, SandboxContext
+
+
+def escape_for_shell(s: str) -> str:
+    """Escape a string for safe use in shell commands."""
+    # Use single quotes and escape any single quotes in the string
+    return "'" + s.replace("'", "'\"'\"'") + "'"
+
+
+# ============================================================================
+# Sync Operations
+# ============================================================================
+
+
+def view_file(
+    ctx: "SandboxContext", path: str, view_range: list | None, timeout: float | None
+) -> dict:
+    """View file content with line numbers.
+
+    Args:
+        ctx: The sandbox context.
+        path: The file path to view.
+        view_range: Optional [start_line, end_line] to view specific lines.
+        timeout: Optional timeout for command execution.
+
+    Returns:
+        A dict with file content and metadata, or error information.
+    """
+    # First check if file exists and get total lines
+    check_cmd = f"wc -l < {escape_for_shell(path)} 2>/dev/null || echo 'FILE_NOT_FOUND'"
+    result = ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=check_cmd,
+        timeout=timeout,
+    )
+
+    if "FILE_NOT_FOUND" in result.stdout or result.exit_code != 0:
+        return {
+            "error": f"File not found: {path}",
+            "stderr": result.stderr,
+        }
+
+    total_lines = int(result.stdout.strip()) if result.stdout.strip().isdigit() else 0
+
+    # Build the view command with line numbers
+    if view_range and len(view_range) == 2:
+        start_line, end_line = view_range
+        cmd = f"sed -n '{start_line},{end_line}p' {escape_for_shell(path)} | nl -ba -v {start_line}"
+    else:
+        cmd = f"nl -ba {escape_for_shell(path)}"
+        start_line = 1
+
+    result = ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=cmd,
+        timeout=timeout,
+    )
+
+    if result.exit_code != 0:
+        return {
+            "error": f"Failed to view file: {path}",
+            "stderr": result.stderr,
+        }
+
+    # Count lines in output
+    content_lines = (
+        result.stdout.rstrip("\n").split("\n") if result.stdout.strip() else []
+    )
+    num_lines = len(content_lines)
+
+    return {
+        "file_type": "text",
+        "content": result.stdout,
+        "numLines": num_lines,
+        "startLine": start_line if view_range else 1,
+        "totalLines": total_lines + 1,  # wc -l doesn't count last line without newline
+    }
+
+
+def create_file(
+    ctx: "SandboxContext", path: str, file_text: str, timeout: float | None
+) -> dict:
+    """Create a new file with content.
+
+    Args:
+        ctx: The sandbox context.
+        path: The file path to create.
+        file_text: The content to write to the file.
+        timeout: Optional timeout for command execution.
+
+    Returns:
+        A dict with creation status or error information.
+    """
+    # Check if file already exists
+    check_cmd = f"test -f {escape_for_shell(path)} && echo 'EXISTS' || echo 'NEW'"
+    check_result = ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=check_cmd,
+        timeout=timeout,
+    )
+    is_update = "EXISTS" in check_result.stdout
+
+    # Create directory if needed
+    dir_path = "/".join(path.split("/")[:-1])
+    if dir_path:
+        mkdir_cmd = f"mkdir -p {escape_for_shell(dir_path)}"
+        ctx.client.sandboxes.exec_command(
+            sandbox_id=ctx.sandbox_id,
+            command=mkdir_cmd,
+            timeout=timeout,
+        )
+
+    # Write file using base64 encoding to safely transfer content
+    encoded_content = base64.b64encode(file_text.encode()).decode()
+    write_cmd = f"echo {escape_for_shell(encoded_content)} | base64 -d > {escape_for_shell(path)}"
+
+    result = ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=write_cmd,
+        timeout=timeout,
+    )
+
+    if result.exit_code != 0:
+        return {
+            "error": f"Failed to create file: {path}",
+            "stderr": result.stderr,
+        }
+
+    return {
+        "is_file_update": is_update,
+        "message": f"File {'updated' if is_update else 'created'}: {path}",
+    }
+
+
+def str_replace(
+    ctx: "SandboxContext", path: str, old_str: str, new_str: str, timeout: float | None
+) -> dict:
+    """Replace a string in a file.
+
+    Args:
+        ctx: The sandbox context.
+        path: The file path to modify.
+        old_str: The exact string to find and replace.
+        new_str: The string to replace old_str with.
+        timeout: Optional timeout for command execution.
+
+    Returns:
+        A dict with diff information or error details.
+    """
+    # First read the file content
+    read_cmd = f"cat {escape_for_shell(path)}"
+    result = ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=read_cmd,
+        timeout=timeout,
+    )
+
+    if result.exit_code != 0:
+        return {
+            "error": f"File not found: {path}",
+            "stderr": result.stderr,
+        }
+
+    original_content = result.stdout
+
+    # Check if old_str exists in the file
+    if old_str not in original_content:
+        return {
+            "error": f"String not found in file: {old_str[:50]}...",
+        }
+
+    # Count occurrences
+    occurrences = original_content.count(old_str)
+    if occurrences > 1:
+        return {
+            "error": f"Multiple occurrences ({occurrences}) of the string found. Please provide more context to make the match unique.",
+        }
+
+    # Perform the replacement
+    new_content = original_content.replace(old_str, new_str, 1)
+
+    # Find the line numbers affected
+    old_lines = original_content.split("\n")
+    new_lines = new_content.split("\n")
+
+    # Find where the change starts
+    old_start = 1
+    for i, (old_line, new_line) in enumerate(zip(old_lines, new_lines)):
+        if old_line != new_line:
+            old_start = i + 1
+            break
+
+    # Write the new content
+    encoded_content = base64.b64encode(new_content.encode()).decode()
+    write_cmd = f"echo {escape_for_shell(encoded_content)} | base64 -d > {escape_for_shell(path)}"
+
+    result = ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=write_cmd,
+        timeout=timeout,
+    )
+
+    if result.exit_code != 0:
+        return {
+            "error": f"Failed to write file: {path}",
+            "stderr": result.stderr,
+        }
+
+    # Calculate diff info
+    old_str_lines = old_str.count("\n") + 1
+    new_str_lines = new_str.count("\n") + 1
+
+    # Build diff lines
+    diff_lines = []
+    for line in old_str.split("\n"):
+        diff_lines.append(f"-{line}")
+    for line in new_str.split("\n"):
+        diff_lines.append(f"+{line}")
+
+    return {
+        "oldStart": old_start,
+        "oldLines": old_str_lines,
+        "newStart": old_start,
+        "newLines": new_str_lines,
+        "lines": diff_lines,
+    }
+
+
+# ============================================================================
+# Async Operations
+# ============================================================================
+
+
+async def async_view_file(
+    ctx: "AsyncSandboxContext", path: str, view_range: list | None, timeout: float | None
+) -> dict:
+    """View file content with line numbers (async).
+
+    Args:
+        ctx: The async sandbox context.
+        path: The file path to view.
+        view_range: Optional [start_line, end_line] to view specific lines.
+        timeout: Optional timeout for command execution.
+
+    Returns:
+        A dict with file content and metadata, or error information.
+    """
+    check_cmd = f"wc -l < {escape_for_shell(path)} 2>/dev/null || echo 'FILE_NOT_FOUND'"
+    result = await ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=check_cmd,
+        timeout=timeout,
+    )
+
+    if "FILE_NOT_FOUND" in result.stdout or result.exit_code != 0:
+        return {
+            "error": f"File not found: {path}",
+            "stderr": result.stderr,
+        }
+
+    total_lines = int(result.stdout.strip()) if result.stdout.strip().isdigit() else 0
+
+    if view_range and len(view_range) == 2:
+        start_line, end_line = view_range
+        cmd = f"sed -n '{start_line},{end_line}p' {escape_for_shell(path)} | nl -ba -v {start_line}"
+    else:
+        cmd = f"nl -ba {escape_for_shell(path)}"
+        start_line = 1
+
+    result = await ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=cmd,
+        timeout=timeout,
+    )
+
+    if result.exit_code != 0:
+        return {
+            "error": f"Failed to view file: {path}",
+            "stderr": result.stderr,
+        }
+
+    content_lines = (
+        result.stdout.rstrip("\n").split("\n") if result.stdout.strip() else []
+    )
+    num_lines = len(content_lines)
+
+    return {
+        "file_type": "text",
+        "content": result.stdout,
+        "numLines": num_lines,
+        "startLine": start_line if view_range else 1,
+        "totalLines": total_lines + 1,
+    }
+
+
+async def async_create_file(
+    ctx: "AsyncSandboxContext", path: str, file_text: str, timeout: float | None
+) -> dict:
+    """Create a new file with content (async).
+
+    Args:
+        ctx: The async sandbox context.
+        path: The file path to create.
+        file_text: The content to write to the file.
+        timeout: Optional timeout for command execution.
+
+    Returns:
+        A dict with creation status or error information.
+    """
+    check_cmd = f"test -f {escape_for_shell(path)} && echo 'EXISTS' || echo 'NEW'"
+    check_result = await ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=check_cmd,
+        timeout=timeout,
+    )
+    is_update = "EXISTS" in check_result.stdout
+
+    dir_path = "/".join(path.split("/")[:-1])
+    if dir_path:
+        mkdir_cmd = f"mkdir -p {escape_for_shell(dir_path)}"
+        await ctx.client.sandboxes.exec_command(
+            sandbox_id=ctx.sandbox_id,
+            command=mkdir_cmd,
+            timeout=timeout,
+        )
+
+    encoded_content = base64.b64encode(file_text.encode()).decode()
+    write_cmd = f"echo {escape_for_shell(encoded_content)} | base64 -d > {escape_for_shell(path)}"
+
+    result = await ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=write_cmd,
+        timeout=timeout,
+    )
+
+    if result.exit_code != 0:
+        return {
+            "error": f"Failed to create file: {path}",
+            "stderr": result.stderr,
+        }
+
+    return {
+        "is_file_update": is_update,
+        "message": f"File {'updated' if is_update else 'created'}: {path}",
+    }
+
+
+async def async_str_replace(
+    ctx: "AsyncSandboxContext", path: str, old_str: str, new_str: str, timeout: float | None
+) -> dict:
+    """Replace a string in a file (async).
+
+    Args:
+        ctx: The async sandbox context.
+        path: The file path to modify.
+        old_str: The exact string to find and replace.
+        new_str: The string to replace old_str with.
+        timeout: Optional timeout for command execution.
+
+    Returns:
+        A dict with diff information or error details.
+    """
+    read_cmd = f"cat {escape_for_shell(path)}"
+    result = await ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=read_cmd,
+        timeout=timeout,
+    )
+
+    if result.exit_code != 0:
+        return {
+            "error": f"File not found: {path}",
+            "stderr": result.stderr,
+        }
+
+    original_content = result.stdout
+
+    if old_str not in original_content:
+        return {
+            "error": f"String not found in file: {old_str[:50]}...",
+        }
+
+    occurrences = original_content.count(old_str)
+    if occurrences > 1:
+        return {
+            "error": f"Multiple occurrences ({occurrences}) of the string found. Please provide more context to make the match unique.",
+        }
+
+    new_content = original_content.replace(old_str, new_str, 1)
+
+    old_lines = original_content.split("\n")
+    new_lines = new_content.split("\n")
+
+    old_start = 1
+    for i, (old_line, new_line) in enumerate(zip(old_lines, new_lines)):
+        if old_line != new_line:
+            old_start = i + 1
+            break
+
+    encoded_content = base64.b64encode(new_content.encode()).decode()
+    write_cmd = f"echo {escape_for_shell(encoded_content)} | base64 -d > {escape_for_shell(path)}"
+
+    result = await ctx.client.sandboxes.exec_command(
+        sandbox_id=ctx.sandbox_id,
+        command=write_cmd,
+        timeout=timeout,
+    )
+
+    if result.exit_code != 0:
+        return {
+            "error": f"Failed to write file: {path}",
+            "stderr": result.stderr,
+        }
+
+    old_str_lines = old_str.count("\n") + 1
+    new_str_lines = new_str.count("\n") + 1
+
+    diff_lines = []
+    for line in old_str.split("\n"):
+        diff_lines.append(f"-{line}")
+    for line in new_str.split("\n"):
+        diff_lines.append(f"+{line}")
+
+    return {
+        "oldStart": old_start,
+        "oldLines": old_str_lines,
+        "newStart": old_start,
+        "newLines": new_str_lines,
+        "lines": diff_lines,
+    }

acontext/async_client.py

@@ -13,9 +13,8 @@ from .errors import APIError, TransportError
 from .messages import MessagePart as MessagePart
 from .uploads import FileUpload as FileUpload
 from .resources.async_disks import AsyncDisksAPI as AsyncDisksAPI
-from .resources.async_blocks import AsyncBlocksAPI as AsyncBlocksAPI
+from .resources.async_sandboxes import AsyncSandboxesAPI as AsyncSandboxesAPI
 from .resources.async_sessions import AsyncSessionsAPI as AsyncSessionsAPI
-from .resources.async_spaces import AsyncSpacesAPI as AsyncSpacesAPI
 from .resources.async_tools import AsyncToolsAPI as AsyncToolsAPI
 from .resources.async_skills import AsyncSkillsAPI as AsyncSkillsAPI
 from .resources.async_users import AsyncUsersAPI as AsyncUsersAPI
@@ -105,14 +104,13 @@ class AcontextAsyncClient:
 
         self._timeout = actual_timeout
 
-        self.spaces = AsyncSpacesAPI(self)
         self.sessions = AsyncSessionsAPI(self)
         self.disks = AsyncDisksAPI(self)
         self.artifacts = self.disks.artifacts
-        self.blocks = AsyncBlocksAPI(self)
         self.tools = AsyncToolsAPI(self)
         self.skills = AsyncSkillsAPI(self)
         self.users = AsyncUsersAPI(self)
+        self.sandboxes = AsyncSandboxesAPI(self)
 
     @property
     def base_url(self) -> str:
@@ -158,7 +156,10 @@ class AcontextAsyncClient:
         data: Mapping[str, Any] | None = None,
         files: Mapping[str, tuple[str, BinaryIO, str | None]] | None = None,
         unwrap: bool = True,
+        timeout: float | None = None,
     ) -> Any:
+        # Use per-request timeout if provided, otherwise use client default
+        effective_timeout = timeout if timeout is not None else self._timeout
         try:
             response = await self._client.request(
                 method=method,
@@ -167,7 +168,7 @@ class AcontextAsyncClient:
                 json=json_data,
                 data=data,
                 files=files,
-                timeout=self._timeout,
+                timeout=effective_timeout,
             )
         except httpx.HTTPError as exc:  # pragma: no cover - passthrough to caller
             raise TransportError(str(exc)) from exc

acontext/client.py

@@ -13,9 +13,8 @@ from .errors import APIError, TransportError
 from .messages import MessagePart as MessagePart
 from .uploads import FileUpload as FileUpload
 from .resources.disks import DisksAPI as DisksAPI
-from .resources.blocks import BlocksAPI as BlocksAPI
+from .resources.sandboxes import SandboxesAPI as SandboxesAPI
 from .resources.sessions import SessionsAPI as SessionsAPI
-from .resources.spaces import SpacesAPI as SpacesAPI
 from .resources.tools import ToolsAPI as ToolsAPI
 from .resources.skills import SkillsAPI as SkillsAPI
 from .resources.users import UsersAPI as UsersAPI
@@ -105,14 +104,13 @@ class AcontextClient:
 
         self._timeout = actual_timeout
 
-        self.spaces = SpacesAPI(self)
         self.sessions = SessionsAPI(self)
         self.disks = DisksAPI(self)
         self.artifacts = self.disks.artifacts
-        self.blocks = BlocksAPI(self)
         self.tools = ToolsAPI(self)
         self.skills = SkillsAPI(self)
         self.users = UsersAPI(self)
+        self.sandboxes = SandboxesAPI(self)
 
     @property
     def base_url(self) -> str:
@@ -157,7 +155,10 @@ class AcontextClient:
         data: Mapping[str, Any] | None = None,
         files: Mapping[str, tuple[str, BinaryIO, str | None]] | None = None,
         unwrap: bool = True,
+        timeout: float | None = None,
     ) -> Any:
+        # Use per-request timeout if provided, otherwise use client default
+        effective_timeout = timeout if timeout is not None else self._timeout
         try:
             response = self._client.request(
                 method=method,
@@ -166,7 +167,7 @@ class AcontextClient:
                 json=json_data,
                 data=data,
                 files=files,
-                timeout=self._timeout,
+                timeout=effective_timeout,
             )
         except httpx.HTTPError as exc:  # pragma: no cover - passthrough to caller
             raise TransportError(str(exc)) from exc

acontext/client_types.py

@@ -17,6 +17,7 @@ class RequesterProtocol(Protocol):
         data: Mapping[str, Any] | None = None,
         files: Mapping[str, tuple[str, BinaryIO, str | None]] | None = None,
         unwrap: bool = True,
+        timeout: float | None = None,
     ) -> Any:
         ...
 
@@ -32,5 +33,6 @@ class AsyncRequesterProtocol(Protocol):
         data: Mapping[str, Any] | None = None,
         files: Mapping[str, tuple[str, BinaryIO, str | None]] | None = None,
         unwrap: bool = True,
+        timeout: float | None = None,
     ) -> Awaitable[Any]:
         ...

acontext/resources/__init__.py

@@ -1,16 +1,14 @@
 """Resource-specific API helpers for the Acontext client."""
 
-from .async_blocks import AsyncBlocksAPI
 from .async_disks import AsyncDisksAPI, AsyncDiskArtifactsAPI
+from .async_sandboxes import AsyncSandboxesAPI
 from .async_sessions import AsyncSessionsAPI
-from .async_spaces import AsyncSpacesAPI
 from .async_tools import AsyncToolsAPI
 from .async_skills import AsyncSkillsAPI
 from .async_users import AsyncUsersAPI
-from .blocks import BlocksAPI
 from .disks import DisksAPI, DiskArtifactsAPI
+from .sandboxes import SandboxesAPI
 from .sessions import SessionsAPI
-from .spaces import SpacesAPI
 from .tools import ToolsAPI
 from .skills import SkillsAPI
 from .users import UsersAPI
@@ -18,17 +16,15 @@ from .users import UsersAPI
 __all__ = [
     "DisksAPI",
     "DiskArtifactsAPI",
-    "BlocksAPI",
+    "SandboxesAPI",
     "SessionsAPI",
-    "SpacesAPI",
     "ToolsAPI",
     "SkillsAPI",
     "UsersAPI",
     "AsyncDisksAPI",
     "AsyncDiskArtifactsAPI",
-    "AsyncBlocksAPI",
+    "AsyncSandboxesAPI",
     "AsyncSessionsAPI",
-    "AsyncSpacesAPI",
     "AsyncToolsAPI",
     "AsyncSkillsAPI",
     "AsyncUsersAPI",

acontext/resources/async_disks.py

@@ -287,3 +287,95 @@ class AsyncDiskArtifactsAPI:
             "GET", f"/disk/{disk_id}/artifact/glob", params=params
         )
         return [Artifact.model_validate(item) for item in data]
+
+    async def download_to_sandbox(
+        self,
+        disk_id: str,
+        *,
+        file_path: str,
+        filename: str,
+        sandbox_id: str,
+        sandbox_path: str,
+    ) -> bool:
+        """Download an artifact from disk storage to a sandbox environment.
+
+        Args:
+            disk_id: The UUID of the disk containing the artifact.
+            file_path: Directory path of the artifact (not including filename).
+            filename: The filename of the artifact.
+            sandbox_id: The UUID of the target sandbox.
+            sandbox_path: Destination directory in the sandbox.
+
+        Returns:
+            True if the download was successful.
+
+        Example:
+        ```python
+            success = await client.disks.artifacts.download_to_sandbox(
+                disk_id="disk-uuid",
+                file_path="/documents/",
+                filename="report.pdf",
+                sandbox_id="sandbox-uuid",
+                sandbox_path="/home/user/"
+            )
+            print(f"Success: {success}")
+        ```
+        """
+        payload = {
+            "file_path": file_path,
+            "filename": filename,
+            "sandbox_id": sandbox_id,
+            "sandbox_path": sandbox_path,
+        }
+        data = await self._requester.request(
+            "POST",
+            f"/disk/{disk_id}/artifact/download_to_sandbox",
+            json_data=payload,
+        )
+        return bool(data.get("success", False))
+
+    async def upload_from_sandbox(
+        self,
+        disk_id: str,
+        *,
+        sandbox_id: str,
+        sandbox_path: str,
+        sandbox_filename: str,
+        file_path: str,
+    ) -> Artifact:
+        """Upload a file from a sandbox environment to disk storage as an artifact.
+
+        Args:
+            disk_id: The UUID of the target disk.
+            sandbox_id: The UUID of the source sandbox.
+            sandbox_path: Source directory in the sandbox (not including filename).
+            sandbox_filename: Filename in the sandbox.
+            file_path: Destination directory path on the disk.
+
+        Returns:
+            Artifact containing the created artifact information.
+
+        Example:
+        ```python
+            artifact = await client.disks.artifacts.upload_from_sandbox(
+                disk_id="disk-uuid",
+                sandbox_id="sandbox-uuid",
+                sandbox_path="/home/user/",
+                sandbox_filename="output.txt",
+                file_path="/results/"
+            )
+            print(f"Created: {artifact.path}{artifact.filename}")
+        ```
+        """
+        payload = {
+            "sandbox_id": sandbox_id,
+            "sandbox_path": sandbox_path,
+            "sandbox_filename": sandbox_filename,
+            "file_path": file_path,
+        }
+        data = await self._requester.request(
+            "POST",
+            f"/disk/{disk_id}/artifact/upload_from_sandbox",
+            json_data=payload,
+        )
+        return Artifact.model_validate(data)