Runtime Module

Tool runtime module.

class atloop.runtime.ToolRuntime(sandbox: SandboxAdapter, skill_loader=None)

Bases: object

Tool runtime for executing tools in sandbox.

This is a legacy compatibility layer. New code should use ToolRegistry directly.

__init__(sandbox: SandboxAdapter, skill_loader=None)

Initialize tool runtime.

Parameters:

• sandbox – Sandbox adapter instance

• skill_loader – Optional skill loader instance for read_skill_file tool

apply_patch(patch: str) → ToolResult

Apply patch (legacy method - use ToolRegistry.execute(“run”, {“cmd”: “git apply”}) instead).

Parameters:

patch – Patch content

Returns:

ToolResult

git_diff() → ToolResult

Get git diff (legacy method - use ToolRegistry.execute(“run”, {“cmd”: “git diff”}) instead).

Returns:

ToolResult with git diff output

list_tree(max_depth: int = 4, ignore_patterns: List[str] | None = None) → ToolResult

List file tree.

Parameters:

• max_depth – Maximum depth to traverse

• ignore_patterns – Patterns to ignore (e.g., [“node_modules”, “.git”])

Returns:

ToolResult with file tree

read_file(path: str, start_line: int = 1, end_line: int | None = None, offset: int | None = None, limit: int | None = None) → ToolResult

Read file lines (legacy method - use ToolRegistry.execute(“read_file”, …) instead).

Parameters:

• path – File path

• start_line – Start line number (1-indexed) - legacy parameter

• end_line – End line number (1-indexed) - legacy parameter

• offset – Line number to start reading from (1-indexed) - new parameter

• limit – Number of lines to read - new parameter

Returns:

ToolResult with file content

run(cmd: str, timeout_sec: int = 600) → ToolResult

Execute shell command.

Parameters:

• cmd – Shell command to execute

• timeout_sec – Command timeout in seconds

Returns:

ToolResult instance

search(query: str, glob: str | None = None, max_results: int = 50) → ToolResult

Search using grep.

Parameters:

• query – Search query (treated as regex pattern)

• glob – Glob pattern to filter files (e.g., “.py”, “*/*.js”)

• max_results – Maximum number of results

Returns:

ToolResult with search results

write_file(path: str, content: str) → ToolResult

Write file (legacy method - use ToolRegistry.execute(“write_file”, …) instead).

Parameters:

• path – File path

• content – File content

Returns:

ToolResult

class atloop.runtime.ToolResult(ok: bool, stdout: str, stderr: str, meta: Dict[str, Any])

Bases: object

Result of tool execution.

__init__(ok: bool, stdout: str, stderr: str, meta: Dict[str, Any]) → None

__repr__() → str

String representation.

ok: bool

stdout: str

stderr: str

meta: Dict[str, Any]

class atloop.runtime.SandboxAdapter(config: SandboxConfig, session_id: str)

Bases: object

Adapter for noxrunner sandbox execution.

__init__(config: SandboxConfig, session_id: str)

Initialize sandbox adapter.

Parameters:

• config – Sandbox configuration

• session_id – Unique session identifier

download_workspace(workspace_path: str) → bool

Download workspace from sandbox to local directory.

This method delegates to noxrunner’s download_workspace method, which handles all the details of downloading and extracting files regardless of the backend type (local or remote).

Parameters:

workspace_path – Local workspace path to download to

Returns:

True if successful

exec(cmd: List[str], workdir: str = '/workspace', env: Dict[str, str] | None = None, timeout_seconds: int = 30) → Dict

Execute a command in the sandbox (using exec, not exec_shell). This returns the correct exit code from the command itself, not from sh.

Parameters:

• cmd – Command to execute (list of strings)

• workdir – Working directory

• env – Environment variables

• timeout_seconds – Command timeout

Returns:

Dict with exitCode, stdout, stderr, durationMs

exec_shell(command: str, workdir: str = '/workspace', env: Dict[str, str] | None = None, timeout_seconds: int = 30) → Dict

Execute shell command in sandbox.

Parameters:

• command – Shell command to execute

• workdir – Working directory

• env – Environment variables

• timeout_seconds – Command timeout

Returns:

Dict with exitCode, stdout, stderr, durationMs

initialize() → bool

Initialize sandbox (create if needed).

Returns:

True if successful

initialize_git() → bool

Initialize git repository in sandbox if not exists.

Returns:

True if successful

upload_workspace(workspace_path: str) → bool

Upload workspace to sandbox.

Parameters:

workspace_path – Local workspace path

Returns:

True if successful

SandboxAdapter

class atloop.runtime.sandbox_adapter.SandboxAdapter(config: SandboxConfig, session_id: str)

Bases: object

Adapter for noxrunner sandbox execution.

__init__(config: SandboxConfig, session_id: str)

Initialize sandbox adapter.

Parameters:

• config – Sandbox configuration

• session_id – Unique session identifier

initialize() → bool

Initialize sandbox (create if needed).

Returns:

True if successful

upload_workspace(workspace_path: str) → bool

Upload workspace to sandbox.

Parameters:

workspace_path – Local workspace path

Returns:

True if successful

initialize_git() → bool

Initialize git repository in sandbox if not exists.

Returns:

True if successful

exec_shell(command: str, workdir: str = '/workspace', env: Dict[str, str] | None = None, timeout_seconds: int = 30) → Dict

Execute shell command in sandbox.

Parameters:

• command – Shell command to execute

• workdir – Working directory

• env – Environment variables

• timeout_seconds – Command timeout

Returns:

Dict with exitCode, stdout, stderr, durationMs

exec(cmd: List[str], workdir: str = '/workspace', env: Dict[str, str] | None = None, timeout_seconds: int = 30) → Dict

Execute a command in the sandbox (using exec, not exec_shell). This returns the correct exit code from the command itself, not from sh.

Parameters:

• cmd – Command to execute (list of strings)

• workdir – Working directory

• env – Environment variables

• timeout_seconds – Command timeout

Returns:

Dict with exitCode, stdout, stderr, durationMs

download_workspace(workspace_path: str) → bool

Download workspace from sandbox to local directory.

This method delegates to noxrunner’s download_workspace method, which handles all the details of downloading and extracting files regardless of the backend type (local or remote).

Parameters:

workspace_path – Local workspace path to download to

Returns:

True if successful

ToolRuntime

class atloop.runtime.tool_runtime.ToolRuntime(sandbox: SandboxAdapter, skill_loader=None)

Bases: object

Tool runtime for executing tools in sandbox.

This is a legacy compatibility layer. New code should use ToolRegistry directly.

__init__(sandbox: SandboxAdapter, skill_loader=None)

Initialize tool runtime.

Parameters:

• sandbox – Sandbox adapter instance

• skill_loader – Optional skill loader instance for read_skill_file tool

run(cmd: str, timeout_sec: int = 600) → ToolResult

Execute shell command.

Parameters:

• cmd – Shell command to execute

• timeout_sec – Command timeout in seconds

Returns:

ToolResult instance

list_tree(max_depth: int = 4, ignore_patterns: List[str] | None = None) → ToolResult

List file tree.

Parameters:

• max_depth – Maximum depth to traverse

• ignore_patterns – Patterns to ignore (e.g., [“node_modules”, “.git”])

Returns:

ToolResult with file tree

search(query: str, glob: str | None = None, max_results: int = 50) → ToolResult

Search using grep.

Parameters:

• query – Search query (treated as regex pattern)

• glob – Glob pattern to filter files (e.g., “.py”, “*/*.js”)

• max_results – Maximum number of results

Returns:

ToolResult with search results

read_file(path: str, start_line: int = 1, end_line: int | None = None, offset: int | None = None, limit: int | None = None) → ToolResult

Read file lines (legacy method - use ToolRegistry.execute(“read_file”, …) instead).

Parameters:

• path – File path

• start_line – Start line number (1-indexed) - legacy parameter

• end_line – End line number (1-indexed) - legacy parameter

• offset – Line number to start reading from (1-indexed) - new parameter

• limit – Number of lines to read - new parameter

Returns:

ToolResult with file content

write_file(path: str, content: str) → ToolResult

Write file (legacy method - use ToolRegistry.execute(“write_file”, …) instead).

Parameters:

• path – File path

• content – File content

Returns:

ToolResult

git_diff() → ToolResult

Get git diff (legacy method - use ToolRegistry.execute(“run”, {“cmd”: “git diff”}) instead).

Returns:

ToolResult with git diff output

apply_patch(patch: str) → ToolResult

Apply patch (legacy method - use ToolRegistry.execute(“run”, {“cmd”: “git apply”}) instead).

Parameters:

patch – Patch content

Returns:

ToolResult