Tool Nodes

Tool nodes execute external binaries safely through typed operations. There is no raw shell execution — all commands are constructed from validated, typed configurations.

Principles

• No raw shell execution as a public primitive
• Tools map to typed semantic operations
• Command construction is validated and safe
• stdout/stderr captured and truncated (4KB limit)
• Timeouts enforced via kill_on_drop

Supported Tools

ffmpeg

Operation	Description
media.transcode	Transcode video (codec configurable)
media.extract_audio	Extract audio track to WAV
media.thumbnail	Generate thumbnail at timestamp

yt-dlp

Operation	Description
source.youtube_download	Download video from URL

Example

NodeDefinition::tool("thumb", "media.thumbnail", "ffmpeg")
    .input("input_file", "$context.video.path")
    .output("thumbnail", "$context.images.thumb", MergePolicy::Replace)
    .requires("tool.ffmpeg")

Security

Concern	Policy
Binary resolution	Resolved from PATH (production should use allowlist)
Arguments	No arbitrary arguments — commands built from typed configs
Working directory	Isolation (planned)
Process lifecycle	Killed on timeout via kill_on_drop
Output capture	stdout/stderr truncated to 4KB to prevent memory exhaustion

How It Works

1. The tool runtime executor receives the ToolRuntimeConfig from the node definition
2. It resolves the binary path and constructs a Command from the typed operation
3. The command is executed as a child process with timeout enforcement
4. stdout/stderr are captured (truncated to 4KB)
5. The result is normalized into a NodeExecutionResult

No shell is involved — Command directly invokes the binary with arguments derived from the typed config.