View Source Jido.Runner.Chain (Jido v1.0.0)

A runner that executes instructions sequentially with support for result chaining, directive-based interruption, and syscall handling.

Chain Execution

Instructions are executed in sequence with the output of each instruction becoming the input for the next instruction in the chain. This enables data flow between instructions while maintaining state consistency.

Directive Handling

The chain supports directive-based flow control:

  • Directives can interrupt chain execution (default)
  • Directives can be collected while continuing execution
  • State changes and directives can be mixed in the chain

Syscall Handling

  • Syscalls are special instructions that affect server behavior
  • Syscalls are validated before execution
  • Syscalls can be mixed with regular instructions
  • Chain execution continues after syscall handling

State Management

  • Initial state flows through the chain
  • Each instruction can modify or extend the state
  • Final state reflects accumulated changes
  • Directive interrupts preserve current state

Summary

Types

chain_opts()
chain_result()

Functions

dbug(_, _ \\ [], _ \\ [])
error(_, _ \\ [], _ \\ [])
run(agent, opts \\ [])

Executes a chain of instructions, handling directives, syscalls and state transitions.

Types

chain_opts()

@type chain_opts() :: [{:continue_on_directive, boolean()}]

chain_result()

@type chain_result() ::
  {:ok, Jido.Runner.Result.t()} | {:error, Jido.Error.t() | String.t()}

Functions

dbug(_, _ \\ [], _ \\ [])

(macro)

error(_, _ \\ [], _ \\ [])

(macro)

run(agent, opts \\ [])

@spec run(Jido.Agent.t(), chain_opts()) :: chain_result()

Executes a chain of instructions, handling directives, syscalls and state transitions.

Execution Flow

  1. Instructions are executed in sequence
  2. Results from each instruction feed into the next
  3. Directives can interrupt or continue the chain
  4. Syscalls are validated and handled
  5. State changes are accumulated through the chain

Parameters

  • agent: The agent struct containing pending instructions
  • opts: Optional keyword list of execution options:
    • :continue_on_directive - boolean, continues chain execution after directive (default: false)
    • :merge_results - boolean, merges map results into subsequent instruction params (default: true)

Returns

  • {:ok, %Result{}} - Chain completed successfully
    • result_state: Final accumulated state
    • directives: List of encountered directives
    • syscalls: List of executed syscalls
    • status: Final execution status
  • {:error, term()} - Chain execution failed
    • Contains error details and partial results

Examples 

# Basic chain execution
{:ok, result} = Chain.run(agent)

# Continue after directives
{:ok, result} = Chain.run(agent, continue_on_directive: true)

# Handle execution error
{:error, error} = Chain.run(agent_with_failing_instruction)