100 lines
2.0 KiB
Markdown
100 lines
2.0 KiB
Markdown
# Code Execution User Guide
|
|
|
|
## Overview
|
|
|
|
`execute_code` is the only MCP tool provided by `anvilmcp`. It runs bash scripts in an isolated subprocess sandboxed via landrun. All AnviLLM functionality is accessed through 9P and helper scripts within these subprocesses.
|
|
|
|
## Tool Discovery
|
|
|
|
List available helper scripts:
|
|
|
|
```bash
|
|
9p ls anvillm/tools/
|
|
```
|
|
|
|
Read a script to see its usage:
|
|
|
|
```bash
|
|
9p read anvillm/tools/check_inbox.sh
|
|
```
|
|
|
|
Invoke a script:
|
|
|
|
```bash
|
|
bash <(9p read anvillm/tools/check_inbox.sh)
|
|
```
|
|
|
|
## Common Patterns
|
|
|
|
### Messaging
|
|
|
|
```bash
|
|
# Check inbox
|
|
bash <(9p read anvillm/tools/check_inbox.sh)
|
|
|
|
# Send message
|
|
bash <(9p read anvillm/tools/send_message.sh) \
|
|
--to user --type PROMPT_RESPONSE --subject "Done" --body "Complete"
|
|
```
|
|
|
|
### Session Management
|
|
|
|
```bash
|
|
9p read anvillm/list
|
|
9p read anvillm/$ID/state
|
|
```
|
|
|
|
### Beads
|
|
|
|
```bash
|
|
9p read anvillm/beads/list | jq '[.[] | select(.status == "open")]'
|
|
echo 'new "Task title" "Task description"' | 9p write anvillm/beads/ctl
|
|
```
|
|
|
|
### Polling
|
|
|
|
```bash
|
|
while true; do
|
|
state=$(9p read anvillm/$ID/state)
|
|
[ "$state" = "idle" ] && break
|
|
sleep 5
|
|
done
|
|
```
|
|
|
|
### Filtering
|
|
|
|
Process data in the subprocess — only return summaries to the agent:
|
|
|
|
```bash
|
|
beads=$(9p read anvillm/beads/list)
|
|
count=$(echo "$beads" | jq '[.[] | select(.priority <= 2)] | length')
|
|
echo "Found $count high-priority beads"
|
|
```
|
|
|
|
## Subprocess Restrictions
|
|
|
|
Scripts run in a landrun sandbox with limited permissions:
|
|
|
|
- Read/write to the session's working directory
|
|
- Read from system paths (`/usr`, `/lib`, `/bin`)
|
|
- Access to 9P namespace
|
|
- Standard utilities: `jq`, `grep`, `sed`, `awk`, `9p`
|
|
- Network access per sandbox config
|
|
|
|
## Error Handling
|
|
|
|
```bash
|
|
if output=$(9p read anvillm/beads/list 2>&1); then
|
|
echo "$output" | jq 'length'
|
|
else
|
|
echo "Failed: $output" >&2
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
## Further Reading
|
|
|
|
- [Code Execution Pattern](./code-execution-pattern.md) — design rationale
|
|
- [Security Documentation](./code-execution-security.md) — threat model and sandbox config
|
|
- [Example Workflows](./code-execution-examples.md) — common patterns
|