# Diagrams

Below are exportable ASCII diagrams (copy/paste) covering architecture, runtime flow, context packing, skill flow, tool policy approvals, telemetry, and V2 multi-agent slots.

***

### 1) System overview (modules + boundaries)

```
                 +------------------------------+
                 |      Channels / Inputs       |
                 |  CLI | Telegram | Others     |
                 +--------------+---------------+
                                |
                                v
                    +--------------------------+
                    | openminion-controlplane  |
                    |  adapters + routing      |
                    +------------+-------------+
                                 |
                                 v
+-------------------------------------------------------------------+
|                         openminion-runtime                         |
|   orchestrates turn: session -> context -> llm -> policy -> tool    |
+----+-----------+-----------+------------+------------+-------------+
     |           |           |            |            |
     v           v           v            v            v
+---------+  +---------+  +--------+  +---------+  +--------+
| session |  | context |  |  llm   |  | policy  |  |  tool  |
+----+----+  +----+----+  +---+----+  +----+----+  +---+----+
     |            |           |            |           |
     |            |           |            |           +-------------------+
     |            |           |            |                               |
     |            |           |            |                     +---------v---------+
     |            |           |            |                     | tool plugins      |
     |            |           |            |                     | exec/browser/...  |
     |            |           |            |                     +-------------------+
     |            |
     |            +--------------------+
     |                                 |
     v                                 v
+---------+   +-----------+   +-----------+   +-----------+
| compress|   |  skill    |   |  memory   |   | identity  |
+---------+   +-----------+   +-----------+   +-----------+

(optional sidecar)
+-------------------+
| openminion-telemetry |
+-------------------+
```

***

### 2) Runtime “turn” flow (single turn, potentially multiple packs)

```
User Input
  |
  v
controlplane.receive()
  |
  v
runtime.run_turn(session_id, agent_id)
  |
  +--> session.next_turn_id() -> turn_id
  +--> trace_id = uuid()
  +--> session.append(user.message)
  |
  +--> (optional) identity.get_capsule()
  +--> (optional) memory.retrieve()
  +--> (optional) skill.shortlist()
  +--> (optional) skill.select + skill.expand()
  |
  v
PACK LOOP (pack_id = t{turn_id}-pN)
  |
  +--> context.build_pack(...)
  |       |
  |       +--> (optional) telemetry.emit(context.pack)
  |
  +--> llm.complete(prompt_view)
  |       |
  |       +--> (optional) telemetry.emit(llm.usage)
  |
  +--> if LLM returns TOOL_CALL:
  |       session.append(tool.request)
  |       policy.authorize()
  |         |
  |         +--> NEEDS_APPROVAL --> return PendingAction to controlplane
  |         |
  |         +--> ALLOW --> tool.execute() --> session.append(tool.result) --> loop
  |         |
  |         +--> DENY  --> session.append(tool.result: denied) --> (loop or stop)
  |
  +--> else FINAL_ANSWER:
          session.append(agent.message)
          compress.maybe_summarize()
          telemetry.emit(turn.outcome)
          return response
```

***

### 3) Context packing (how PromptView is assembled under budget)

```
Inputs:
  - identity capsule (small)
  - session summary (small)
  - recent messages (bounded K)
  - memory snippets (bounded top-N)
  - skill cards shortlist (bounded top-N)
  - selected skill excerpt (optional, bounded)
  - tool digest (minimal)

context.build_pack()
  |
  v
[1] establish budgets
    total_budget
    reserved_budget (system + tool overhead)
    available_budget
  |
  v
[2] build sections in priority order
    1 system
    2 identity
    3 task directive (latest user intent)
    4 summary
    5 recent messages
    6 memory snippets
    7 skill cards
    8 selected skill excerpt (if any)
    9 tool digest
  |
  v
[3] enforce caps
    - trim sections by rules
    - drop low priority sections if needed
    - record truncations/drops
  |
  v
PromptView (bounded) -> sent to LLM
  |
  +--> telemetry: ContextPackReport (tokens, drops, truncations, composition)
```

***

### 4) Skill integration flow (many skills → shortlist → one expanded)

```
All skills (many SKILL.md)
  |
  v
openminion-skill.index -> SkillCards (tiny metadata)
  |
  v
skill.shortlist(query=intent, tools_available, N) -> top SkillCards
  |
  v
context.attach_skill_cards(SkillCards)  (bounded)
  |
  v
brain/runtime selects skill_id or NONE
  |
  +--> if selected:
  |       skill.expand(skill_id, goal, max_tokens=M)
  |       context.attach_selected_skill(excerpt) (bounded)
  |       session.append(skill.selected)
  |
  v
LLM uses skill excerpt to plan + call tools reliably
```

***

### 5) Tool execution + policy approvals (approve once / window / forever)

```
LLM TOOL_CALL (tool_name, args)
  |
  v
runtime -> session.append(tool.request)
  |
  v
policy.authorize(tool_name, risk, scopes, args_summary)
  |
  +--> ALLOW
  |      |
  |      v
  |   runtime -> tool.execute()
  |      |
  |      v
  |   session.append(tool.result)
  |      |
  |      v
  |   back to pack loop
  |
  +--> NEEDS_APPROVAL
  |      |
  |      v
  |   return PendingAction:
  |     - approve once
  |     - approve for time window
  |     - approve until revoked
  |     - deny
  |
  +--> DENY
         |
         v
      session.append(tool.result: denied)
      (runtime loops for alternative plan OR stops based on config)
```

***

### 6) Telemetry flow (context-focused, per pack + per turn)

```
context.build_pack(pack_id)
  |
  +--> emit: context.pack
  |      - token budget + usage estimate
  |      - section breakdown
  |      - drops/truncations + reasons
  |
llm.complete(pack_id)
  |
  +--> emit: llm.usage
  |      - actual tokens (if provided)
  |      - latency, model/provider
  |
runtime ends turn
  |
  +--> emit: turn.outcome
         - packs used
         - tool calls count
         - status ok/retry/error/blocked
         - total latency

Sinks:
  - sqlite (default)
  - jsonl (debug)
  - otel (future)
```

***

### 7) Session durability (full history preserved; prompt stays compact)

```
Session Store (SQLite, append-only)
  - stores ALL events forever (or retention policy)
  - user/agent messages
  - tool req/result
  - skill selection refs
  - summaries
  - memory refs

PromptView (context output)
  - only selected subset:
    identity + summary + recent window + top memory + skill card(s) + tool digest
  - bounded by token budget

=> Full history is preserved in session,
   but only compact view is sent to LLM.
```

***

### 8) V2 slots (daemon + registry + local/remote + multi-agent)

```
                  +---------------------+
                  | openminion-registry |
                  | discover agents     |
                  +----------+----------+
                             |
                 +-----------+-----------+
                 |                       |
                 v                       v
      +-------------------+   +-------------------+
      | agent daemon A    |   | agent daemon B    |
      | openminion-runtime|   | openminion-runtime|
      +---------+---------+   +---------+---------+
                |                       |
                +----------+------------+
                           |
                           v
                   openminion-a2a (V2)
                   - local queue (V1)
                   - remote RPC/MCP (V2)
                   - auth/signing (V2)
```