a706e144f8784ac720d8bbfa43a328da6a8217a8
raw

Agent Smith Workflow

Overview

This document summarizes the implemented runtime workflows.

1. Conversation lifecycle

[mode activated]
      |
      v
[runtime.new]
      |
      v
[session created]
      |
      v
[start_session] --> status=running
      |
      v
[process_raw_input]
   |            \
   |             \-> slash command path (/memory..., /prompt, /pager)
   v
 turn path
      |
      v
[turn_completed | turn_cancelled | turn_error]
      |
      v
[persist_turn]
      |
      v
[session stop/fail] -> status=stopped|failed

Step flow:

  1. Mode adapter lazily creates runtime.

  2. Input line routes to command or turn path.

  3. Turn emits events and returns normalized result.

  4. Persistence records messages/usage/turn note.

  5. Session may continue or stop/fail.

2. Tool loop inside a turn

LLM response
   |
   +--> no tool calls --> assistant message -> complete turn
   |
   +--> tool calls detected
            |
            v
     for each tool call (ordered):
       - resolve spec + role policy
       - execute handler
       - append tool result message
            |
            +--> terminal tool success? yes -> stop loop (completed)
            |
            +--> budget/cancel/error? -> stop with reason
            |
            +--> otherwise continue next LLM iteration

Step flow:

  1. Build model messages + request.

  2. Call LLM (stream or non-stream).

  3. Extract tool calls.

  4. Execute calls deterministically with cancel checks.

  5. Continue LLM/tool loop until terminal condition.

Tool-loop display behavior:

3. Request/dispatch flow

Parent role turn
   |
   v
tool:dispatch(role, task, context, files)
   |
   v
dispatch.build_job
  - validate parent->target role matrix
  - validate task/context/files
  - derive child cancel token
   |
   v
dispatch.worker.launch
  - build child execution context
  - run child turn
  - require terminal report
   |
   v
normalize dispatch_result
   |
   v
return to parent as tool result content
   |
   v
parent loop continues for synthesis

Step flow:

  1. Parent calls dispatch (non-terminal).

  2. Runtime validates/constructs dispatch_job.

  3. Child turn runs in isolated context.

  4. Child must terminate via report.

  5. Parent receives normalized dispatch_result and continues answer synthesis.

4. Cancellation flow

User combo (default ctrl-c)
   |
   v
mode.handle_combo
   |
   v
runtime.cancel_current_turn
   - mark cancel_requested
   - emit turn_cancel_requested
   - request turn cancel token
   |
   v
turn loop checks cancel token
   |
   +--> before LLM/tool execution: short-circuit
   +--> during LLM stream: cancel observed between updates
   +--> dispatch child: child token derives from parent token
   |
   v
turn_result.stop_reason = cancelled
turn_result.cancelled = true
error kind = cancelled

Step flow:

  1. Cancel intent is captured by mode combo handling.

  2. Runtime signals cancellation via token + event.

  3. Turn/tool/LLM paths observe token and exit with cancelled result.

  4. Child dispatch cancellations cascade from parent token.

5. Command path (slash commands)

command.router.parse recognizes eleven slash commands: /memory, /scratchpad, /config, /cmd, /load, /prompt, /pager, /new, /usage, /clear, /history. The diagram below shows the three handling shapes; /memory (role-gated) and /prompt / /pager (pager UI request) are the representative cases.

input starts with '/'
   |
   v
command.router.parse
   |
   +--> invalid route -> normalized command error
   |
   +--> memory route
   |      |
   |      v
   |   runtime role gate (note permission)
   |      |
   |      +--> denied -> permission_denied
   |      |
   |      +--> allowed -> command.builtin execute memory ops
   |
   +--> prompt/pager route
   |      |
   |      v
   |   command.builtin returns pager UI request
   |   (mode handles pager display)
   |
   +--> other routes (scratchpad, config, cmd, load, new, usage, clear, history)
          |
          v
       command.builtin handler returns a normalized result
       (text / structured output rendered by the mode adapter)

Handling shapes: