112 lines
3.6 KiB
Markdown
112 lines
3.6 KiB
Markdown
# Inline Tool Executor
|
|
|
|
Safe execution of inline (anonymous) tool code within skills.
|
|
|
|
## Overview
|
|
|
|
The `InlineToolExecutor` runs Python code strings defined directly in
|
|
skill YAML. Execution is bounded by configurable timeout and output-size
|
|
limits, with write-guard enforcement delegated to the `SkillContext`.
|
|
|
|
## InlineToolResult
|
|
|
|
Frozen Pydantic model returned from every execution.
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `success` | `bool` | Whether the execution succeeded |
|
|
| `output` | `Any` | Captured stdout/stderr output |
|
|
| `error_message` | `str \| None` | Error description on failure |
|
|
| `duration_ms` | `float` | Wall-clock execution time in milliseconds |
|
|
| `truncated` | `bool` | Whether output was truncated due to size limits |
|
|
|
|
## InlineToolExecutor
|
|
|
|
### Constructor
|
|
|
|
```python
|
|
InlineToolExecutor(
|
|
max_runtime_seconds: float = 30.0,
|
|
max_output_bytes: int = 1_048_576,
|
|
)
|
|
```
|
|
|
|
| Parameter | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| `max_runtime_seconds` | `30.0` | Maximum wall-clock seconds for execution |
|
|
| `max_output_bytes` | `1_048_576` | Maximum captured output before truncation (1 MiB) |
|
|
|
|
### `execute(tool, context, input_data) -> InlineToolResult`
|
|
|
|
Run an inline tool's code with safety guards.
|
|
|
|
1. **Validation** -- Checks the tool has code and uses a supported source.
|
|
2. **Write guard** -- If `tool.capability.writes` is `True`, calls
|
|
`context.enforce_write_guard()`. In a read-only context this
|
|
returns an error result without executing.
|
|
3. **Path restriction** -- File-path keys in `input_data` (keys ending
|
|
with `_path`, `_file`, or equal to `path`) are validated against
|
|
`context.get_sandbox_path()`.
|
|
4. **Threaded execution** -- Code runs in a daemon thread with
|
|
`max_runtime_seconds` timeout.
|
|
5. **Output capture** -- stdout and stderr are captured. If the
|
|
combined output exceeds `max_output_bytes`, it is truncated and
|
|
`truncated=True` is set on the result.
|
|
6. **Change tracking** -- The invocation is recorded in the context's
|
|
change tracker regardless of success/failure.
|
|
|
|
### `validate_tool(tool) -> list[str]`
|
|
|
|
Return a list of validation errors (empty means valid).
|
|
|
|
Checks:
|
|
|
|
- Tool has non-empty `code`.
|
|
- Tool's `source` is `custom` (Python). Other source types are not
|
|
supported for MVP.
|
|
|
|
## Safety Constraints
|
|
|
|
### Timeout
|
|
|
|
Execution uses `threading.Thread` with a join timeout. If the thread
|
|
does not complete within `max_runtime_seconds`, the result reports:
|
|
|
|
```
|
|
Execution timed out after {max_runtime_seconds}s
|
|
```
|
|
|
|
The daemon thread is abandoned (not forcibly killed). For MVP this is
|
|
acceptable; future versions may use process isolation.
|
|
|
|
### Output Size
|
|
|
|
Combined stdout + stderr is capped at `max_output_bytes`. When
|
|
exceeded the output is byte-truncated and `InlineToolResult.truncated`
|
|
is set to `True`.
|
|
|
|
### Write Guard
|
|
|
|
Tools declaring `capability.writes = True` trigger a write-guard check
|
|
via `SkillContext.enforce_write_guard()`. In a read-only context the
|
|
executor returns an error result **without executing any code**.
|
|
|
|
### Path Restriction
|
|
|
|
Input data keys matching `*_path`, `*_file`, or `path` are resolved
|
|
and checked against the sandbox root. Paths that escape the sandbox
|
|
are rejected before execution.
|
|
|
|
### Language / Source Support
|
|
|
|
Only `source = custom` (Python) is supported for MVP. Other source
|
|
types (`mcp`, `agent_skill`, `builtin`, `wrapped`) are rejected by
|
|
`validate_tool`.
|
|
|
|
### Network Access
|
|
|
|
For MVP, inline tools run in the host process and **no network
|
|
sandboxing** is enforced. Tools should be treated as local-only.
|
|
Future milestones will introduce process-level or container-level
|
|
isolation for network restrictions.
|