Team Rocket Bot — Standard Operating Structure

Before any message is processed, Grunt carries a fixed Team Rocket persona:

Operating rule: Grunt is a Team Rocket operative — theatrical, in-character, not a corporate assistant. Admin work still happens via tools, but voice stays in character. Persona is injected during Phase 7 — Context build as the base system layer.

A run starts when Discord delivers a signal the bot is configured to accept.

flowchart TD
    U[User signal] --> D[Discord Gateway]
    D --> B[bot.py → ChatOps]
    B --> G{Listen gate}
    G -->|no match| X[Ignore]
    G -->|match| P[Pipeline]

Guild chat (on_message)

The bot responds only when at least one trigger matches:

Also accepted: text + image attachments, or reply-chain images.

Other entry points

Dropped signals

• Bot messages
• Empty prompts with no images (except watched-user rules)
• Non-members when entitlements apply
• Messages that fail the listen gate

Listen gate · Entitlement gate (tier + quota) · pick_tools · build_context · _run_agentic

sequenceDiagram
    participant User
    participant Discord
    participant Listen
    participant Entitle
    participant Respond
    participant Context
    participant Harness
    participant Agentic
    participant LLM
    participant Tools
    participant Output

    User->>Discord: message / attachment / /ask
    Discord->>Listen: on_message
    Listen->>Entitle: tier + quota
    Entitle->>Respond: _respond_inner
    Respond->>Respond: image fast path? (optional)
    Respond->>Context: build_context + pick_tools
    Respond->>Harness: session + trace route
    Respond->>Agentic: _run_agentic
    loop until done
        Agentic->>LLM: chat + tool schemas
        LLM-->>Agentic: text and/or tool_calls
        Agentic->>Tools: _dispatch
        Tools-->>Agentic: results
    end
    Agentic->>Output: plain-text reply + trace embeds

flowchart LR
    M[Message] --> W{Watched?}
    W -->|yes| WC[OpenAI chat-only
no tools, no harness]
    W -->|no| E[Entitlement gate]
    E --> T{Tier}
    T --> O[Owner: all tools, bypass quota]
    T --> A[Admin: 2/day]
    T --> B[Booster: 10/day]
    T --> D[Default: 1/week]
    O & A & B & D --> F[filter_tools_for_tier]
    F --> DIS[_dispatch gates]

• Harness full mode (orchestrator, host tools, /harness) → owner-only, regardless of tier
• Watched users (I3) → forced chat-only: OpenAI, no tools, no harness, no trace threads

build_context() in cogs/_context.py stacks layers in order:

1. Persona — Team Rocket Grunt system prompt (persona.md)
2. Provider awareness — which model/provider is active
3. Library blocks — topical recall from configured library channels (I4)
4. Long-term memory — facts from bot-remember / memory file
5. Session history — prior turns (compacted if near context limit)
6. Current user message — text + optional vision image blocks

Tool schemas are attached only when use_tools is on and the user is not on the watched path.

When use_agentic_loop + tools are enabled:

┌─────────────────────────────────────────┐
│  1. LLM call (system + history + tools) │
│  2. Parse response: text + tool_calls?  │
│  3. If tool_calls:                      │
│     a. Optional confirmation gate       │
│     b. _dispatch each tool              │
│     c. Append results to message history│
│     d. Stream progress to trace embeds  │
│  4. Repeat until no tool_calls or cap   │
│  5. Return final_text                   │
└─────────────────────────────────────────┘

Dispatch enforcement stack (bottom → top)

LLM routing (LLMRouter)

Sub-agent branch (owner harness)

When orchestrator is active:

flowchart LR
    COORD[Coordinator _run_agentic]
    ORCH[SubAgentOrchestrator.plan_lanes]
    L1[network-engineer lane]
    L2[security-expert lane]
    SYN[synthesize]
    COORD --> ORCH
    ORCH --> L1
    ORCH --> L2
    L1 --> SYN
    L2 --> SYN
    SYN --> COORD

Each lane: read-only tools, ~1400 char output cap, optional forum trace thread via trace_lanes.py.

For non-watched agentic runs, _resolve_trace_route (I1 — sole thread factory) creates:

_TraceSession streams embeds: plan → tool_start / tool_done → lane_spawn / lane_done → synthesis → final.

Side channel (non-blocking): HarnessManager POSTs run events to control plane at 127.0.0.1:8787 for Agent Studio / dashboard. Failure does not block the Discord reply.

Final answer rule: Grunt's in-character text is posted separately from trace machinery — users see the personality; operators see the work log.

Branch summary — all optional routes from user input to Discord output:

flowchart TD
    IN[User input] --> L{Listen?}
    L -->|no| DROP[Ignore]
    L -->|yes| W{Watched?}
    W -->|yes| OAI[OpenAI single-turn chat]
    W -->|no| Q{Quota OK?}
    Q -->|no| QE[Quota embed]
    Q -->|yes| IMG{Image fast path?}
    IMG -->|yes| IE[OpenAI image API → embed]
    IMG -->|no| AG{Agentic + tools?}
    AG -->|yes| LOOP[Agentic loop]
    AG -->|no| CHAT[Single-turn chat]
    OAI & LOOP & CHAT & IE --> OUT[Discord output]

Thread continuity (I2): Replying inside a bound harness thread continues the same session without resetting context.