Agentic layer

What this is

OODA cycle

Observe → Orient → Decide → Act. Master-controller's prompt is structured around the four phases. Each cycle ends with one or more fenced action blocks the dispatcher parses and applies.

maybeTriggerOoda  ─┐
                   │  if (idle for > threshold && switchboard.oodaAutoTrigger)
                   ▼
            runOodaCycle
                   │
                   ▼
       buildAgentContext("master-controller")
                   │   datetime, recent decisions, learnings,
                   │   personality, mind-meld profile, recent
                   │   inbox messages, current goals, strategy
                   ▼
        sdkBridge.runStandaloneAgent(master-controller, ...)
                   │
                   ▼
            response text
                   │
                   ▼
        parseOodaResponse(text)
                   │   matches ```<type>\n...\n``` blocks
                   ▼
        executeOodaActions([...])
                   │
                   ├──▶ goal       │ insert into agent_goals
                   ├──▶ decision   │ insert into agent_decisions
                   ├──▶ message    │ insert into agent_messages (inbox)
                   ├──▶ strategy   │ bump agent_strategies version
                   ├──▶ schedule   │ re-fire after delay_minutes
                   ├──▶ persistent_schedule │ insert agent_schedules (cron/interval)
                   ├──▶ learning   │ addLearning() → consolidation later
                   ├──▶ personality│ setPersonalityTrait()
                   ├──▶ tool       │ invoke registered tool
                   ├──▶ tool_sequence │ run tool list in order
                   └──▶ roundtable │ convene specialists on a topic

Action block types

Master-controller emits these as fenced code blocks. The parser is permissive — unknown blocks are ignored, missing required fields skip the action with a debug log.

Cycles can be triggered three ways: automatically (cognitive timer when idle and switchboard.oodaAutoTrigger=true), on user demand (POST /api/cognitive/ooda), or by a registered cron schedule that the previous OODA cycle itself emitted.

Builtin agents

Four agents ship with operad. All start disabled; flip them on per-agent in the Switchboard. You can also define your own agents in ~/.config/operad/operad.toml using [[agent]] blocks (see Configuration).

Self-improvement layer

Every agent response is post-processed by extractAgentActions(), which scans for learning and personality fenced blocks and folds them into the agent's persistent state. On the next run the new state shows up in the agent's context — that's the "self-improvement" mechanism. There's no fine-tuning; there's prompt accretion with decay.

```learning
content: pin sonnet 4.6 for routine
  refactors; opus only for novel
  architecture work
category: routing
confidence: 0.85
```

```personality
trait: communication_style
value: concise, evidence-first
evidence: user repeatedly asked for
  shorter responses with citations
```

What gets injected into an agent's context

buildAgentContext(agentName) →
  current datetime + system memory state
  ┊
  recent decisions  (last 5 from agent_decisions)
  recent learnings  (top by confidence)
  shared insights   (high-confidence learnings from OTHER agents)
  personality       (current trait values)
  recent inbox      (last 5 from agent_messages)
  current goals     (open from agent_goals)
  current strategy  (latest agent_strategies)
  mind-meld profile (your written file, if enabled)
  ┊
  ──→ prepended to user prompt as context block

Memory consolidation

Agents accumulate learnings indefinitely if you let them. The consolidation worker runs when the daemon detects user idle for > threshold and squashes the noise. Four operations:

Daily snapshots of the full agent-state bundle (learnings, personality, goals, decisions, strategies, specializations) write to ~/.local/share/operad/snapshots/ with retention. Lets you roll back if a consolidation pass deletes something useful.

Multi-agent orchestration

Three coordination primitives: message bus, specialization registry, and roundtable protocol.

```message
to: optimizer
type: request
content: weekly token usage spiked 40%
  in cleverkeys. investigate cause and
  recommend mitigations before fri.
```

```roundtable
topic: cleverkeys IME memory leak — what next?
agents: optimizer, ideator, preference-learner
context: profile data shows steady RSS growth
  during long typing sessions; no obvious leak
  in heap snapshot.
```

User control + influence layers

The agentic layer is opt-in and shape-able. You don't just toggle it on — you tell the agents who you are, what you want, and what to ignore. Three layers:

Trust + autonomy

Each agent has an autonomy level. The trust ledger (agent_trust_ledger) records signed deltas — successful scheduled runs add credit, failures and bad outcomes subtract — and produces a recommended autonomy level you can accept or override.

Tools, categories, schedules

Agents act through a tool registry, not free-form Claude Code tools. Each tool is tagged with a category that the autonomy level maps to.

Persistent scheduling

Master-controller can register recurring agent runs via the persistent_schedule block. Stored in agent_schedules; a 30-second poll loop fires due entries. Auto-disables after consecutive failures so a broken schedule doesn't burn quota indefinitely.

```persistent_schedule
name: weekly-quota-review
cron: 0 9 * * MON
prompt: review last week's token usage
  by session. flag the top 3 consumers.
  recommend pruning candidates.
max_budget_usd: 0.50
```

Either cron (5-field expression) or interval_minutes (simple repeating delay) — mutually exclusive.

Custom tools (TOML)

Define your own tools in operad.toml with a [[tool]] block. Tools are shell commands templated with the tool's args; the registry tags them with a category so they slot into the autonomy framework.

Where each layer lives in the dashboard

REST surface

GET    /api/agents                      list configured agents
POST   /api/agents/<name>/run           one-shot run with prompt
POST   /api/agents/<name>/toggle        enable/disable
GET    /api/agents/runs                 paginated runs (preview)
GET    /api/agents/runs/<id>            full prompt/response/thinking
GET    /api/agents/<name>/learnings
GET    /api/agents/<name>/personality
POST   /api/cognitive/ooda              fire OODA on demand
GET    /api/cognitive/goals
GET    /api/cognitive/decisions
GET    /api/cognitive/strategy
GET    /api/cognitive/messages
GET    /api/quota                       weekly quota status
GET    /api/specializations
POST   /api/switchboard                 update toggles

Source of truth lives in src/ — agents.ts, cognitive.ts, agent-engine.ts, consolidation.ts, memory-db.ts, schedule.ts.