ProtocolMode

Core Architecture Stateful High Reliability

A strict, state-machine-driven control loop that executes complex workflows via formal protocols with automated referee validation.

⚙️ protocol.json

{
  "initialState": "Analyze",
  "states": [
    {
      "name": "Analyze",
      "instructions": "Identify the bug in the logs",
      "validationCriteria": "If bug found -> 'Fix', else -> 'Search'"
    },
    {
      "name": "Fix",
      "instructions": "Apply the patch",
      "validationCriteria": "If tests pass -> null, else -> 'Fix'"
    }
  ]
}

→

🧠 Execution Transcript

State: Analyze

Executing: ReadLogTask...

Referee: Passed

"Bug identified in line 42. Transitioning to 'Fix'."

State: Fix

Executing: FileModificationTask...

The State Machine Loop

ProtocolMode operates on a deterministic loop designed for high-stakes automation where every step must be verified by a "Referee" agent before proceeding.

Protocol Definition: Can be pre-defined in JSON or dynamically generated by the agent.
State Execution: The agent selects the best tool to satisfy the current state's instructions.
Referee Validation: A separate LLM call evaluates the output against strict criteria to decide the next state.
Variable Substitution: Supports {{mustache}} style variables for reusable templates.

ProtocolModeConfig

Field	Type	Description
`protocolFile`	String?	Path to a JSON file defining the state machine.
`variables`	Map	Key-value pairs to substitute into the protocol JSON.
`maxIterations`	Int	Safety limit on total state transitions (Default: 20).
`maxRetries`	Int	Retries allowed per state on validation failure (Default: 3).

kotlin

// From ProtocolMode.kt
while (currentStateName != null && iteration++ < maxIterations) {
    val currentState = protocol.states.find { it.name == currentStateName }
    
    // 1. Execute Action
    val taskConfig = selectTask(task, currentState, userMessage, history)
    val actionResult = taskImpl.run(...)

    // 2. Validate via Referee
    val validation = validateState(task, currentState, taskConfig, actionResult)
    
    if (validation.passed) {
        currentStateName = validation.nextState
    } else {
        // Handle retry or failure
    }
}