OpenHive is a rules-first agentic system. Behavior lives in markdown rules; infrastructure is minimal TypeScript built on the Vercel AI SDK 6 (ai@^6). Inline AI SDK organization tools act as the control plane, managing a uniform recursive hierarchy of agent teams running as streamText() sessions inside a single Docker container.

Core principle: If behavior can be expressed as a rule, it is a rule -- not code.

• Architecture Overview
• Uniform Recursive Design
• Execution Model
• Organization-Tools -- Control plane: org tree, tools, routing metadata (list_teams), task queue, escalation scenarios
• Team-Configuration -- config.yaml, secrets, provider profiles, rule cascade, skills/subagents
• Memory-System -- Memory: search pipeline, embedding config, per-team isolation
• SDK-Integration -- Session spawning, SDK options, on-demand team spawning
• Isolation-Model -- Cooperative isolation, mechanisms, defense in depth
• Channel-Adapters -- WebSocket protocol, Discord adapters, notification routing
• Triggers -- Trigger engine: types, config, execution flow, circuit breaker, notification routing
• Logging -- Log levels, transports, credential scrubbing
• Durability-Recovery -- Durable state, restart recovery, crash handling, backups
• Data Layout
• Code Inventory
• Design Decisions Summary

graph TB
    subgraph container["Single Docker Container"]
        direction TB

        subgraph process["Main Process (TypeScript)"]
            bootstrap["Bootstrap"]
            channels["Channel Adapters<br/>WebSocket / Discord"]
            trustgate["TrustGate<br/>Sender trust evaluation"]
            classifier["TopicClassifier<br/>(0 topics: skip, 1: agent evaluates,<br/>2+: lightweight LLM)"]
            dashboard["Dashboard<br/>Admin views + limited mutations"]
            orgtools["Organization Tools (Inline)<br/>(Control Plane)"]
            skillrepo["Skill Repo Tool<br/>search_skill_repository"]
            hooks["Tool Guards + withAudit() Wrappers"]
            triggers["Trigger Engine"]
            sqlite["SQLite State Store<br/>(15+ tables incl. topics)"]
            memoryIndex["Memory Index<br/>(embedding + keyword search)"]
        end

        subgraph sessions["Agent Sessions (streamText() calls)"]
            main1["Main Agent Session — Topic 1<br/>cwd: .run/teams/main"]
            main2["Main Agent Session — Topic 2<br/>cwd: .run/teams/main"]

            eng["Engineering Session<br/>cwd: .run/teams/engineering<br/>org tools"]

            ops["Operations Session<br/>cwd: .run/teams/operations<br/>org tools"]

            fe["Frontend Session<br/>cwd: .run/teams/frontend<br/>org tools"]
        end

        bootstrap --> orgtools
        bootstrap --> channels
        bootstrap --> triggers
        bootstrap --> hooks

        channels --> trustgate
        trustgate --> classifier
        classifier --> main1
        classifier --> main2
        orgtools --> main1
        orgtools --> main2
        orgtools --> eng
        orgtools --> ops
        orgtools --> fe
        triggers --> orgtools
        orgtools --> sqlite
        skillrepo --> orgtools
        memoryIndex --> sqlite
        dashboard --> sqlite

        main1 -->|"spawn_team / delegate_task"| eng
        main1 -->|"spawn_team / delegate_task"| ops
        eng -->|"spawn_team / delegate_task"| fe
        eng -->|"escalate"| main1
        fe -->|"escalate"| eng
        ops -->|"escalate"| main1
    end

    users["Users"] --> channels
    schedules["Schedules / Keywords"] --> triggers

Key points:

• Single container -- all teams run as AI SDK streamText() sessions in one process. No Docker-per-team.
• Inline organization tools -- the control plane. Manages hierarchy, messaging, escalation, task queues, routing metadata (list_teams). Defined as AI SDK tool() calls, no HTTP transport.
• Channel adapters -- the only component unique to the main agent. Everything else is uniform.
• Trigger Engine -- fires tasks into the task queue on schedule, message, or keyword events.
• TrustGate -- gates all inbound messages by sender trust level. Untrusted or unknown senders are rejected before reaching the classifier.
• Dashboard -- operational views for admins. Queries SQLite directly. Two mutations only: trigger enable/disable toggle and plugin lifecycle actions (deprecate/remove). See Admin-Dashboard.
• SQLite -- durable workflow state (task queues, org tree, dedup). Sessions are disposable.

Every child team node is structurally identical: a streamText() session with inline organization tools, an orchestrator, subagents, skills, and plugins. The main agent differs from child teams in two ways: (1) it has channel adapters (WebSocket, Discord) attached, and (2) it has no subagents — it routes and delegates only (ADR-40).

graph TD
    main["Main Agent<br/>org-tools + channel adapters<br/>(routes only, no subagents)"]
    teamA["Team A<br/>org-tools"]
    teamB["Team B<br/>org-tools"]

    subgraph ops["Operations Team"]
        orch_ops["Orchestrator"]
        sa1["loggly-monitor<br/>(subagent)"]
        sa2["incident-responder<br/>(subagent)"]
        sk1["get-loggly-log.md"]
        sk2["incident-response.md"]
    end

    fe["Frontend<br/>org-tools"]
    be["Backend<br/>org-tools"]

    main --> teamA
    main --> teamB
    teamA --> orch_ops
    orch_ops -->|"invokes"| sa1
    orch_ops -->|"invokes"| sa2
    sa1 -->|"follows"| sk1
    sa2 -->|"follows"| sk2
    teamB --> fe
    teamB --> be

Each child team node can:

• Delegate down -- send tasks to child teams
• Escalate up -- send issues to its parent
• Spawn children -- create new child teams on demand
• Invoke subagents -- the ONLY way tasks execute within a team. Orchestrators never handle tasks directly (ADR-40).

The main agent can delegate down, escalate to the user, and spawn children — but it has no subagents and performs no direct task execution.

Depth is unlimited. A one-layer deployment (main + workers) and a five-layer deployment use the same code paths.

For a complete walkthrough of how user requests flow through the full hierarchy (Main → Orchestrator → Subagent → Skill → Plugin), see Scenarios#User → Fix Flow.

Each session initialization follows a fixed order to assemble the AI SDK context:

Tool Assembly Order:

1. Built-in tools — Read, Write, Edit, Glob, Grep, Bash (always loaded)
2. Org tools — spawn_team, delegate_task, escalate, etc. (if allowed by allowed_tools)
3. Trigger tools — create_trigger, enable_trigger, etc. (if allowed)
4. Browser tools — browser_navigate, browser_screenshot, etc. (if allowed + Playwright available)
5. Vault tools — vault_set, vault_get, vault_list, vault_delete (if allowed)
6. Plugin tools — Loaded from .run/teams/{name}/plugins/ only if active skill declares them in ## Required Tools

Plugin tool loading flow:

flowchart TD
    A[Session creation] --> B[Load built-in tools]
    B --> C[Load org/trigger/vault tools per allowed_tools]
    C --> D{Active skill exists?}
    D -->|No| E[Generic task: no plugin tools]
    D -->|Yes| F[Parse skill's Required Tools section]
    F --> G["Load declared plugins from .run/teams/{name}/plugins/"]
    G --> H[Verify each tool: typecheck + security scan]
    H --> I{All pass?}
    I -->|Yes| J["Namespace tools: {team}.{tool_name}"]
    I -->|No| K[Reject with error guidance]
    J --> L[Merge into activeTools]
    E --> M[activeTools = built-ins + org tools only]
    L --> N[activeTools includes plugin tools]

Namespace isolation (AC-9):

• Plugin tools are namespaced: {team_name}.{tool_name}
• loadPluginTools(teamName, requiredTools, allowedTools) returns only tools from that team's plugin directory
• Cross-team tool shadowing is impossible

Every team operation is classified as daily-ops (parallel allowed) or org-ops (serialized via a per-team mutex). A team may process up to max_concurrent_daily_ops (default 5) concurrent sessions; org-ops block new daily-ops admission and wait for in-flight daily-ops to drain before running.

Canonical pool + mutex diagram (ADR-41; referenced from ADRs, Organization-Tools, and scenario walkthroughs):

flowchart TD
    Op[Team Operation] --> Class{Classify}
    Class -->|daily-ops| Pool[Concurrent Pool<br/>≤ max_concurrent_daily_ops]
    Class -->|org-ops| Mutex[Per-team Mutex<br/>single-flight]

    Pool --> SA[daily-ops Session A]
    Pool --> SB[daily-ops Session B]
    Pool --> SC[daily-ops Session C]

    Mutex --> SS[org-ops Session<br/>structural change]

    SA -. shared reads / row-level atomic writes .-> DB[(SQLite WAL)]
    SB -. shared reads / row-level atomic writes .-> DB
    SC -. shared reads / row-level atomic writes .-> DB
    SS -. exclusive for this team .-> DB

• Daily-ops (read-heavy, append-only, per-key mutations): parallel up to max_concurrent_daily_ops (default 5).
• Org-ops (structural changes, governance mutations): single-flight per-team mutex.
• Per-key exception: mutable stores like memories use per-subject_key locking so concurrent writes to different keys proceed in parallel while same-key writes serialize.

Org-ops tool set (single-flight per team): spawn_team, shutdown_team, update_team, modify_subagent, memory-schema edits, register_plugin_tool, update_trigger.

Drain policy: an org-op waits for in-flight daily-ops to finish, blocks new daily-ops admission, then runs. No mid-flight abort.

See Architecture-Decisions#ADR-41 Daily-ops vs Org-ops Concurrency for the full rule and Organization-Tools for per-tool class tagging.

Four trigger types fire tasks into the queue. The window trigger (ADR-42) delivers continuous-watch semantics via periodic ticks + memory cursors + no-op returns — no persistent session.

See Triggers for trigger-engine details and Tool-Guidelines#Activation Decision Framework for when to pick each.

The data model uses three tiers with distinct mutability and ownership profiles.

Tier 1 ships the system rules directory (/app/system-rules/) containing core agent patterns, main agent identity, SDK capabilities reference, sender trust framework, task workflow, tool guidelines, and system-level skills (learning and reflection cycles). These are bundled at image build time and cannot be changed without rebuilding.

Tier 2 includes two Docker volume mounts: /data/config/ (read-only, containing providers.yaml and channels.yaml) and /data/rules/ (writable by admin, containing org-level rule markdown files). The config volume cannot be modified by the container.

Tier 3 is the runtime workspace at .run/ (named Docker volume). It contains the SQLite database (openhive.db), shared cross-team data, automated backups, and per-team directories. Each team directory contains: config.yaml (team manifest), org-rules/ (cascading rules), team-rules/ (team-only rules, including team-context.md), skills/ (procedure definitions), plugins/ (team-local TypeScript tool definitions), and subagents/ (agent identity definitions).

See Team-Configuration#Runtime Directory Structure for the per-team layout.

The plugin_tools table tracks lifecycle state and verification results for team-local plugin tools. Each row is keyed by (team_name, tool_name) and stores: lifecycle status (active, deprecated, failed_verification, removed), source path and SHA-256 hash (for change detection), verification results as JSON (TypeScript, interface, and security scan results), and creation/update/verification timestamps.

Initial codebase is estimated at ~2,000-3,000 lines of TypeScript. This is a soft target, not a hard constraint — the codebase will grow as features are added. Everything else is rules (markdown), skills (markdown), config (YAML), and off-the-shelf MCP servers.

The source tree is rooted at src/ with these major areas:

Guards are implemented as inline wrappers inside each tool's execute() function. Shared guard functions in guards.ts enforce hierarchy and capability invariants.