Backplane.AgentRuntime.ToolEffects behaviour (backplane_agent_runtime v1.10.52)

Tool effects and cancellation boundary for Backplane agent runtime.

Summary

Functions

cancel(adapter, invocation)

execute(adapter, invocation, context)

present(operation, result, decision)

Preserves an actual native result while selecting durable consumer presentation.

reject(operation, error)

Rejects an invocation before dispatching any tool or external effect.

settlement(arg1, arg2)

Classifies an observed backend result using its admitted descriptor safety.

validate_output(output, opts \\ [])

Types

adapter()

@type adapter() :: module()

result()

@type result() ::
  {:ok, map()}
  | {:error, Backplane.AgentRuntime.Error.t()}
  | {:rejected, Backplane.AgentRuntime.ToolEffects.Rejection.t()}
  | {:presented, Backplane.AgentRuntime.ToolEffects.Presentation.t()}

Callbacks

cancel(map)

@callback cancel(map()) ::
  :ok
  | {:ok,
     Backplane.AgentRuntime.ToolEffects.Cancellation.t()
     | Backplane.AgentRuntime.ToolEffects.AggregateCancellation.t()
     | Backplane.AgentRuntime.ToolEffects.EventsCancellation.t()
     | Backplane.AgentRuntime.ToolEffects.ClockCancellation.t()
     | Backplane.AgentRuntime.ToolEffects.Retirement.t()}
  | {:error, Backplane.AgentRuntime.Error.t()}

execute(map)

@callback execute(map()) :: result()

Functions

cancel(adapter, invocation)

@spec cancel(adapter(), map()) ::
  :ok
  | {:ok,
     Backplane.AgentRuntime.ToolEffects.Cancellation.t()
     | Backplane.AgentRuntime.ToolEffects.AggregateCancellation.t()
     | Backplane.AgentRuntime.ToolEffects.EventsCancellation.t()
     | Backplane.AgentRuntime.ToolEffects.ClockCancellation.t()
     | Backplane.AgentRuntime.ToolEffects.Retirement.t()}
  | {:error, Backplane.AgentRuntime.Error.t()}

execute(adapter, invocation, context)

@spec execute(adapter(), map(), map()) ::
  {:ok, map()} | {:error, Backplane.AgentRuntime.Error.t()}

present(operation, result, decision)

Preserves an actual native result while selecting durable consumer presentation.

A trusted backend calls this after native completion. %{type: :block, text: ...} returns a consumer error (including to Code Mode); :stopped replaces model output while nested Code Mode retains the original value. Additional context is independently delivered through append_feedback. This is never non-dispatch evidence. The Runtime validates exact identity and persists both values before replying. Unacknowledged Store settlement remains uncertain and is not replayed.

reject(operation, error)

@spec reject(map(), Backplane.AgentRuntime.Error.t()) ::
  {:rejected, Backplane.AgentRuntime.ToolEffects.Rejection.t()}
  | {:error, Backplane.AgentRuntime.Error.t()}

Rejects an invocation before dispatching any tool or external effect.

Only the registered, trusted backend may make this assertion, after its host approval/catalog checks and before dispatch. It is not a reconciliation receipt for work that was started. Generic errors and error details do not prove non-execution. An unknown outcome cannot be turned into a rejection.

The rejection binds the runtime operation identity and exact arguments; the execution boundary validates it before publishing a structured tool error.

settlement(arg1, arg2)

@spec settlement(term(), map()) :: :settled | :uncertain

Classifies an observed backend result using its admitted descriptor safety.

validate_output(output, opts \\ [])

@spec validate_output(map(), keyword()) ::
  {:ok, map()} | {:error, Backplane.AgentRuntime.Error.t()}