# Agent Smith Workflow

## Overview

This document summarizes the implemented runtime workflows.

## 1. Conversation lifecycle

```text
[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

```text
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:

- Tool progress is rendered as transient status output.
- Successful tool content is not printed inline in the terminal.
- Full tool results remain in conversation/model context and are visible through `/pager`.

---

## 3. Request/dispatch flow

```text
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

```text
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.

```text
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:

- **Role-gated** — `/memory` is repository-backed project-memory CRUD, gated on
  the `note` permission for the active role.
- **Pager UI request** — `/prompt` and `/pager` return a pager request the mode
  adapter renders through the shell pager.
- **Builtin handler** — `/scratchpad`, `/config`, `/cmd`, `/load`, `/new`,
  `/usage`, `/clear`, `/history` run their `command.builtin` handlers and return
  a normalized result (e.g. `/usage` prints the session token summary, `/load`
  restores a saved conversation).