Tools

Tools

Edge adaptation of the upstream tool registration, schema, and execution pipeline.

Upstream reference: Tools

What Upstream Provides

ToolRuntime (ctx.tools) is the central tool registry and execution engine. It owns:

• Registration — register() accepts a ToolDefinition built via defineTool(), with typed parameters, output schema, execution function, and UI presentation callbacks.
• Schema generation — schemas() projects model-facing tool definitions through allowlists and restrictions.
• Execution pipeline — a 7-stage waterfall: pre-execute (approval) → monotonic guard → around-dispatch → tool body → post-execute → finalizeContent → result emit. Each stage can allow, deny, replace, or observe.
• Concurrency — tools declare isConcurrencySafe to opt into parallel execution; the agent loop forms barriers and rolling pools accordingly.

Individual tools are separate plugins (ToolFs, ToolGoal, ToolWeb) that call ctx.tools.register() during their apply(). The runtime doesn't know which tools exist — it only provides the registry and pipeline.

What Edge Changed

Direct Reuse ToolRuntime

ToolRuntime is installed as-is. The full execution pipeline — pre-execute waterfalls, guards, post-execute hooks, content finalization, schema projection — runs upstream code unmodified.

Direct Reuse Upstream tool plugins

Three upstream tool plugins are installed directly:

• ToolFs — file read/write/edit/read_image (backed by EdgeFileSystem)
• ToolGoal — create_goal/get_goal/update_goal
• ToolWeb — web search (fetch disabled)

Replacement Edge bash tool

createEdgeBashTool() registers a custom bash tool via the standard ctx.tools.register() API. It uses defineTool() with the same schema vocabulary as upstream tools. The tool executes commands through just-bash (a pure-JS shell) against the Computer VFS, instead of upstream's node:child_process.

The registration goes through ctx.effect() so the tool is tied to the cordis lifecycle and properly cleaned up on disposal.

Direct Reuse Pipeline extensions

SpillPolicy (post-execute output truncation) and TimeoutPolicy (tool call timeout) are installed as-is and participate in the upstream pipeline without Edge-specific code.

What Edge Did NOT Change

• Tool registration API, schema DSL, and validation
• 7-stage execution pipeline and waterfall semantics
• Concurrency scheduling and barrier logic
• UI presentation vocabulary (card types, diff views, terminal views)
• Error handling (ToolArgsError, ToolOutputError, ToolNotFoundError)
• Scoped registration and restriction filtering

Performance Characteristics

Tool registration

All tools register during EdgeSessionStore.initialize(). Registration is synchronous schema compilation — no I/O. The bash tool registers via ctx.effect() which adds one cordis lifecycle entry. Total registration cost: negligible (sub-millisecond for all tools combined).

Execution pipeline overhead

Each tool call traverses the 7-stage pipeline. Edge adds no custom stages — only upstream's SpillPolicy (checks output byte length, conditionally spills to VFS) and TimeoutPolicy (wraps execution in AbortSignal.timeout()). Both are O(1) per call. The pipeline itself is synchronous waterfall dispatch with no I/O between stages.

Bash tool execution

The bash tool's performance is dominated by just-bash command parsing and VFS I/O, not the tool pipeline. See the Bash wiki for detailed bash performance analysis.

Architecture Summary

Component	Category	Edge Code
ToolRuntime	Reuse	One ctx.plugin() call
ToolFs, ToolGoal, ToolWeb	Reuse	Three ctx.plugin() calls
SpillPolicy, TimeoutPolicy	Reuse	Two ctx.plugin() calls
Edge bash tool	Replace	createEdgeBashTool() via defineTool()

Key observation: The tool subsystem is a textbook example of the architecture charter's "maximize upstream leverage" principle. Edge uses the standard defineTool() + ctx.tools.register() API to plug in its custom bash implementation — the same API any upstream tool plugin uses. The runtime, pipeline, schema system, and UI vocabulary are entirely upstream. Edge owns exactly one tool definition.