Module ai_tools 

AI-node execution support: exposing bound adapters to a model as callable tools, dispatching the model’s tool calls back to those adapters, and resolving image references for vision calls.

This is the in-node tool-use path - distinct from whole-flow agentic generation. The model emits tool calls, AdapterToolDispatcher runs each through the existing adapter (so the fs/shell sandboxes apply unchanged), and the result is fed back to the model.

Structs

AdapterToolDispatcher

Runs a model tool call by mapping "{adapter}__{actionId}" back to an adapter action: it synthesizes a node from the model’s args (plus the AI node’s workspace as workspaceRoot/cwd) and executes it through the bound adapter, so all existing sandboxing/policy applies.

ProposedEdit

A single filesystem change the agent proposed during a turn, computed but not applied. The IDE renders each as a diff (before → after) the user accepts or rejects.

StagingState

Net staged edits for one agent turn: the per-path result plus first-touch order, so the IDE shows one stable diff per file.

StagingToolDispatcher

Tool dispatcher for a coding-agent turn: filesystem mutations (fs write-file/edit-file/delete-file) are staged into a buffer instead of written to disk, so the turn can be reviewed before it lands. Everything else - fs reads, glob/grep/list-dir, and every shell tool - runs for real through AdapterToolDispatcher. A read-file of a staged path is served from the overlay, so the model sees its own pending edits within the same turn.

ToolObserver

Observes each model tool call so the dispatcher can emit an ExecutionEvent::ToolCall just before the tool runs - giving the UI live per-tool-call granularity during an AI node’s tool loop (the dispatcher otherwise emits nothing per call). Cheap to clone (an Arc + two ids).

Constants

DEFAULT_TOOL_ITERATIONS

Default cap on the in-node tool-use loop (how many times the model may call tools before the run gives up). Overridable per node via maxToolIters (ai_max_tool_iters).

Functions

ai_expect

The node’s natural-language output expectation (expect field) for per-node AI evaluation (roadmap E1). When set, the generate path self-evaluates the output against it and fails the node - engaging the monitor/fix flow - if unmet. None when unset/blank.

ai_labels

Classification labels (trimmed, non-empty) from the node’s labels array.

ai_max_tool_iters

Per-node cap on the in-node tool-use loop, read from the node’s maxToolIters field; falls back to DEFAULT_TOOL_ITERATIONS. Clamped to at least 1 so a 0 can’t silently disable tool use.

ai_output_schema

The structured-output JSON schema (raw text) from the node’s outputSchema field, used by the "structured" task. Stored as a string so it round-trips through the DSL; the model is prompted to produce JSON matching it. None when unset or blank.

ai_reasoning

Per-request reasoning toggle from the node’s thinking flag.

ai_task

The AI node’s dispatch task: "generate" (default), "embedding", or "classify". The inspector stamps it from the bound model’s capability / whether labels are set.

ai_tool_adapters

Adapter names the node exposes to the model as tools (its tools array).

build_tool_specs

Build model tool specs from the descriptors of the bound adapters. Each adapter action becomes one tool "{adapter}__{actionId}"; its required + optional fields become JSON-schema properties.

match_label

Pick the label the model’s output best corresponds to: an exact (case-insensitive) match first, then a label contained in the output, else the first label as a safe default.

parse_json_lenient

Best-effort parse of a model’s text into a JSON value: a direct parse first, else the substring between the first { and last } - tolerates markdown fences or surrounding prose a model adds around structured output.

resolve_image_ref

Resolve an image reference into something a multimodal API accepts: an http(s)/data: URL passes through unchanged; a local path is read and encoded into a data:<mime>;base64,… URL (local inference servers can’t fetch arbitrary URLs). Returns an error string the caller surfaces.

resolve_node_images

Resolve the node’s imageUrl (plus an optional images array) into ready-to-send references (URLs pass through; local paths become data: URLs). Empty when the node carries no images.

Type Aliases

StagedEdits

Shared handle to a turn’s StagingState. FlowApp::run_agent_turn creates one, the executor hands it to the dispatcher, and the caller reads the proposed edits back out after the run.