MingaAgent.Tool.Executor (Minga v0.1.0)

Executes agent tools through the registry with approval checking and Config.Advice integration.

The execution pipeline:

Look up the tool spec in MingaAgent.Tool.Registry
Check the tool's approval level (:auto, :ask, :deny)
If Minga.Config.Advice has advice for the tool name (as an atom), wrap the execution through the advice chain
Execute the tool callback in the calling process (no spawning)
Return {:ok, result} or {:error, reason}

ETS fast-path

The advice check is a single ETS read via Minga.Config.Advice.advised?/1. When no advice is registered (the common case), the wrap is skipped entirely and the callback runs directly.

Approval

Tools with :auto approval execute immediately. Tools with :deny are rejected. Tools with :ask return {:needs_approval, spec} so the caller (typically Agent.Session) can request user confirmation before calling execute_approved/2.

Summary

Types

result()

Result of tool execution.

Functions

execute(name, args)

Executes a tool by name with the given arguments.

execute(name, args, registry_table)

execute_approved(spec, args)

Executes a tool that has already been approved by the user.

Types

result()

@type result() ::
  {:ok, term()}
  | {:error, term()}
  | {:needs_approval, MingaAgent.Tool.Spec.t(), map()}

Result of tool execution.

Functions

execute(name, args)

@spec execute(String.t(), map()) :: result()

Executes a tool by name with the given arguments.

Looks up the spec in the registry, checks approval, optionally wraps through Config.Advice, and runs the callback. Returns {:ok, result}, {:error, reason}, or {:needs_approval, spec, args} for tools that require user confirmation.

The optional third argument is the registry table name (for testing).

execute(name, args, registry_table)

@spec execute(String.t(), map(), atom()) :: result()

execute_approved(spec, args)

@spec execute_approved(MingaAgent.Tool.Spec.t(), map()) ::
  {:ok, term()} | {:error, term()}

Executes a tool that has already been approved by the user.

Skips the approval check and runs the callback directly (with advice wrapping if applicable). Use this after receiving {:needs_approval, spec, args} from execute/2 and getting user confirmation.