Roadmap¶

ProbOS is organized as a starship crew — specialized teams of agents working together to keep the system operational, secure, and evolving. Each team is a dedicated agent pool with distinct responsibilities. The Captain (human operator) approves major decisions through a stage gate.

Crew Structure¶

                        ┌─────────────────────┐
                        │   BRIDGE (Command)   │
                        │   Captain = Human     │
                        │   First Officer =     │
                        │   Architect Agent     │
                        └─────────┬───────────┘
                                  │
        ┌──────────┬──────────┬───┴───┬──────────┬──────────┐
        │          │          │       │          │          │
   ┌────┴───┐ ┌───┴────┐ ┌──┴───┐ ┌─┴──────┐ ┌┴───────┐ ┌┴──────────┐
   │Medical │ │Engineer│ │Science│ │Security│ │  Ops   │ │   Comms   │
   │Sickbay │ │   ing  │ │       │ │Tactical│ │        │ │           │
   └────────┘ └────────┘ └──────┘ └────────┘ └────────┘ └───────────┘

Team	Starfleet Analog	ProbOS Function	Status
Medical	Sickbay (Crusher)	Health monitoring, diagnosis, remediation, post-mortems	Built (AD-290)
Engineering	Main Engineering (Scotty)	Performance optimization, maintenance, builds, infrastructure	Partial (Builder, Architect built)
Science	Science Lab (Spock)	Research, discovery, architectural analysis, codebase knowledge	Built (Architect, CodebaseIndex)
Security	Tactical (Worf)	Threat detection, defense, trust integrity, input validation	Partial
Operations	Ops (Data/O'Brien)	Resource management, scheduling, load balancing, coordination	Partial
Communications	Comms (Uhura)	Channel adapters, federation, external interfaces	Partial
Bridge	Command (Picard)	Strategic decisions, human approval gate, goal planning	Partial

Ship's Computer (Runtime Services)¶

Not a team — shared infrastructure that all teams use:

CodebaseIndex — structural self-awareness, the ship's technical manual (Phase 29c)
Knowledge Store — long-term memory, the ship's library
Episodic Memory + Dreaming — experiential learning, the ship's log. Three-tier dreaming model (AD-288): micro-dreams (continuous, every 10s during active sessions), idle dreams (after 120s idle), and shutdown dreams (final consolidation flush)
Decision Cache — LLM reasoning cache inside CognitiveAgent (AD-272). Identical observations skip LLM re-evaluation. Future: feedback-driven cache eviction, KnowledgeStore persistence for warm boot
Trust Network — reputation system, crew performance records
Intent Bus — internal communications, the ship's intercom
Hebbian Router — navigation, learned routing pathways

Capability Tiers (Crew, Instruments, Knowledge)¶

ProbOS has three tiers of capability, modeled after a starship crew:

Agents  (Crew)        → who decides what    → crew members who think and collaborate
Tools   (Instruments) → what you can do     → tricorder, transporter, phaser
Skills  (Knowledge)   → what you know       → ship's library, reference data

Tier	Star Trek Analog	ProbOS	Governance	Examples
Agent	Crew member (Crusher, Worf)	Intent handler with full lifecycle	Trust, Hebbian, consensus, Shapley	DiagnosticianAgent, SurgeonAgent
Tool	Tricorder, transporter, phaser	Typed callable function, shared across agents	Tool-level trust tracking, no per-call consensus	File read/write, HTTP fetch, API calls, MCP tools
Skill	Ship's library, computer database	Read-only data access attached to agents	None (internal)	`codebase_knowledge`, search indexes

When to use each: - Agent — handles a user intent, needs to decide/reason, should participate in trust and Hebbian routing - Tool — performs a specific action, any authorized agent can use it, doesn't need consensus for each call - Skill — provides data access internally, no behavior, read-only

Tools are the natural mapping target for MCP — external MCP tools become ProbOS tools, and ProbOS tools are exposed as MCP tools to external systems.

The Federation¶

Each ProbOS instance is a ship. Multiple instances form a federation:

Star Trek Concept	ProbOS Equivalent	Status
Starship	Single ProbOS instance	Built
Ship departments	Agent pools (crew teams)	In progress
Ship's computer	Runtime + CodebaseIndex + Knowledge Store	Built
Federation	Federated ProbOS instances	Built (Phase 29)
Diplomatic relations	Trust transitivity between nodes	Roadmap
Shared intelligence	Knowledge federation	Roadmap
Prime Directive	Safety constraints, boundary rules, human gate	Built

Build Phases¶

Phase	Title	Crew Team	Goal
24	Channel Integration	Comms	Discord, Slack, Telegram adapters + external tool connectors
25	Persistent Tasks	Ops	Long-running autonomous tasks with checkpointing, browser automation
25b	Tool Layer	Ship's Computer	Typed callable instruments (tricorders) shared across agents, ToolRegistry, MCP mapping
26	Inter-Agent Deliberation	Bridge	Structured multi-turn agent debates, agent-to-agent messaging, interactive execution
28	Meta-Learning	Science	Workspace ontology, dream cycle abstractions, session context, goal management
29	Federation + Emergence	Comms	Knowledge federation, trust transitivity, MCP adapter, A2A adapter, TC_N measurement
29b	Medical Team	Medical	Vitals monitor, diagnostician, surgeon, pharmacist, pathologist
29c	Codebase Knowledge	Ship's Computer	Structural self-awareness — indexed source map + introspection skill
30	Self-Improvement Pipeline	All Teams	Capability proposals, stage contracts, QA pool, evolution store, human gate
31	Security Team	Security	Formalized threat detection, prompt injection scanner, trust integrity monitoring, secrets management, runtime sandboxing, network egress policy, inference audit, data governance
32	Engineering Team	Engineering	Automated performance optimization, maintenance agents, build agents, LLM resilience, observability export, CI/CD, backup/restore, storage abstraction layers, containerized deployment
33	Operations Team	Ops	Formalized resource management, workload balancing, system coordination, LLM cost tracking

Team Details¶

Medical Team (Phase 29b)¶

"Please state the nature of the medical emergency."

A dedicated pool of specialized agents that monitor, diagnose, and remediate ProbOS health issues. Modeled as a medical team where each agent has a distinct role in the health lifecycle.

Vitals Monitor (Nurse)

HeartbeatAgent subclass, always running at low overhead
Tracks: response latency, trust score trends, pool utilization, error rates, dream consolidation rates, memory usage
Raises structured alerts (severity + metric + threshold + current value) to the Diagnostician
Does not diagnose or act — observes and escalates only

Diagnostician

CognitiveAgent triggered by Vitals Monitor alerts or on a configurable schedule
Runs structured health assessment (extends IntrospectAgent._system_health())
Compares current state to historical baselines stored in episodic memory
Root cause analysis: agent-level, pool-level, or system-level
Produces a structured Diagnosis with severity, affected components, and recommended treatment

Surgeon (Remediation)

CognitiveAgent that takes corrective action based on Diagnostician findings
Actions: recycle degraded agents, trigger emergency dream cycles via force_dream(), rebalance pools via pool_scaler, prune stale episodic memory
Actions are trust-scored via Shapley contribution — did the intervention actually fix the problem?
High-impact actions (pruning agents, config changes) can require human approval via the approval gate

Pharmacist (Tuning)

CognitiveAgent for slow-acting, trend-based configuration adjustments
Analyzes patterns over time: "sessions average 4 minutes, idle dream threshold should be 60s not 120s"
Produces configuration recommendations with justification and expected impact
Changes applied through the existing config system with audit trail

Pathologist (Post-Mortem)

CognitiveAgent triggered by escalation Tier 3 hits, consensus failures, or agent crashes
Produces structured post-mortems stored in episodic memory and (future) evolution store
Identifies recurring failure patterns across sessions
Findings feed into the self-improvement pipeline (Phase 30) as improvement signals

Codebase Knowledge Service (Phase 29c)¶

The ship's technical manual — available to any crew member.

ProbOS already has runtime self-awareness — it knows what agents are doing, their trust scores, and routing patterns. This phase adds structural self-awareness: understanding how ProbOS is built, not just how it's behaving. Access is shared across agents via a skill, like a library that any crew member can visit.

CodebaseIndex (Runtime Service)

Built at startup, cached in memory, read-only during a session
Scans src/probos/ and builds a structured map:
File tree with module-level descriptions
Agent registry: type, tier, pool, capabilities, intent descriptors
Layer organization: substrate, mesh, consensus, cognitive, federation
Key APIs: public methods on Runtime, TrustNetwork, IntentBus, HebbianRouter, etc.
Configuration schema: what's tunable, current values, and where each parameter lives
Indexed by concept, not just filename ("how does trust work?" maps to the relevant files)
No LLM calls — pure AST/inspection-based indexing

codebase_knowledge Skill (Shared Crew Capability)

Any CognitiveAgent can use this skill to query the codebase
Methods: query_architecture(concept), read_source(file, lines), search_code(pattern), get_agent_map(), get_layer_map(), get_config_schema()
Returns structured, context-aware answers rather than raw file contents
Used by: Medical (Pathologist, Diagnostician), Science (Architect, Research), Engineering (Builder), Bridge (IntrospectAgent)

Self-Knowledge Comprehension

"ProbOS's biggest cognitive gap is not knowing what it already knows."

The CodebaseIndex delivers data (source code, doc sections, architecture maps) to the reflection LLM, but the LLM's synthesis is shallow — it gives generic distributed systems advice rather than reasoning about what's actually built. Improving comprehension quality:

Structured reflection prompts — format context with explicit sections ("Source code from X shows...", "Roadmap section Y describes...") instead of dumping raw dicts; guide the LLM to reason about specific evidence
Evidence-grounded responses — reflection prompt instructs LLM to cite specific code/docs when making claims, and to verify claims against provided snippets before stating them
Self-contradiction detection — flag when a response contradicts data in the provided context (e.g., "no episodic memory" when episodic memory source code is in the snippets)

Capability Inventory (ProbOS's MEMORY.md)

Inspired by Claude Code's persistent memory file — a structured self-knowledge baseline.

Claude Code maintains a MEMORY.md with facts about the project it's working on (file counts, architecture layers, key systems). ProbOS should generate equivalent self-knowledge at build time:

Auto-generated at startup — CodebaseIndex produces a compact capability summary alongside its structural index: "ProbOS has: episodic memory (ChromaDB, persistent), dreaming (three-tier: micro/idle/shutdown), trust network (Bayesian Beta distribution), federation (ZeroMQ), 52 agents across 25 pools..."
Injected into every reflection prompt — prepended as system context so the LLM never starts cold. Prevents recommending building things that already exist
Updated on rebuild — when CodebaseIndex rebuilds (new agents, new capabilities), the inventory regenerates automatically
Structured format — organized by crew team and architecture layer, not just a flat list. "Medical team: Vitals Monitor, Diagnostician, Surgeon, Pharmacist, Pathologist (Phase 29b, designed). Security: red team agents (built), SSRF protection (AD-285, built)..."

Tool-Augmented Reflection (Agentic RAG)

Inspired by Claude Code's ability to read files mid-reasoning — the reflection LLM should be able to look things up.

Currently, reflection is a single LLM call with pre-assembled context. If the context is incomplete or the LLM needs to verify a claim, it has no recourse — it guesses or stays generic. Tool-augmented reflection gives the reflection step the ability to query CodebaseIndex during response generation:

Verification tool calls — before stating "X doesn't exist," the reflection LLM can call query("X") to check. If results come back, it corrects itself before responding
Follow-up reads — if the initial context mentions a file but doesn't include enough detail, the reflection LLM can call read_source() or read_doc_sections() to get more
Two-pass reflection — first pass generates a draft response; second pass verifies claims in the draft against CodebaseIndex queries, revises any contradictions, then finalizes
Bounded iteration — max 2-3 tool calls per reflection to keep latency reasonable; not a full agent loop, just targeted verification
Cost-aware — tool-augmented reflection only activates for introspection and analysis queries, not simple command responses

Security Team (Phase 31)¶

"Shields up. Red alert."

Formalize threat detection and defense as a dedicated agent pool. Builds on existing security infrastructure (red team agents, SSRF protection).

Threat Detector — monitors inbound requests for prompt injection, adversarial input, abnormal patterns
Trust Integrity Monitor — detects trust score manipulation, coordinated attacks on consensus, Sybil patterns
Input Validator — rate limiting enforcement, payload size limits, content policy
Red Team Lead — coordinates existing red team agents, schedules adversarial verification campaigns
Existing: Red team agents (built), SSRF protection (AD-285), prompt injection scanner (roadmap)

Secrets Management

Secure credential store — integrate with system keyring, HashiCorp Vault, or AWS KMS for API keys, tokens, and sensitive config values
Runtime injection — secrets resolved at startup and injected into agents/tools that need them, never stored in config files or logs
Rotation support — automatic credential rotation without restart; agents notified when credentials change
Existing: .env file support (basic), config values in system.yaml (not encrypted)

Runtime Sandboxing

Process isolation — imported and self-designed agents execute in sandboxed subprocesses with restricted filesystem, network, and memory access
Capability whitelisting — agents declare required capabilities in their manifest; runtime grants only those capabilities at startup
Resource limits — per-agent CPU time, memory, and network quotas enforced by the sandbox; violations terminate the agent and report to Trust Network
Graduated trust → graduated access — new/untrusted agents get tighter sandboxes; high-trust agents get relaxed constraints
Existing: AST validation for self-mod agents (built), restricted imports whitelist (built), red team source scanning (built)

Network Egress Policy

Inspired by NVIDIA NemoClaw's outbound connection control.

ProbOS has SSRF protection (AD-285) for inbound attack patterns, but no outbound egress control. Agents — especially imported or self-designed ones — should not have unrestricted internet access:

Domain allowlist — per-agent (or per-pool) list of permitted outbound domains. Agents can only reach URLs on their allowlist; all other requests are blocked
Trust-graduated access — new/imported agents start with no network access. As trust increases, domains can be unlocked. High-trust agents get broader access
Real-time approval — when an agent attempts to contact an unlisted domain, surface the request to the Captain via HXI for approve/deny (NemoClaw pattern). Approved domains are added to the allowlist
Hot-reloadable — egress rules can be updated at runtime without restarting agents
Existing: SSRF protection blocks dangerous inbound patterns (AD-285, built). Egress policy blocks unauthorized outbound connections

Inference Audit Layer

Inspired by NemoClaw's inference gateway that intercepts all LLM calls.

ProbOS centralizes LLM calls through the tiered client, but doesn't audit the content of agent-to-LLM communications. An adversarial designed agent could embed sensitive data in its prompts:

Prompt logging — log all LLM requests (prompt content, system prompt, tier, requesting agent) to the event log for audit
Anomaly detection — flag unusual patterns: agents sending base64-encoded data, agents including file contents they shouldn't have access to, sudden prompt size spikes
PII scrubbing — optionally redact detected PII from LLM prompts before they leave the system (complements Data Governance)
Per-agent LLM access control — allow/deny specific agents from using specific LLM tiers (e.g., imported agents restricted to fast tier only)
Existing: Tiered LLM client centralizes all LLM calls (built), decision cache tracks LLM usage (AD-272, built)

Data Governance & Privacy

PII detection — scan agent conversations and episodic memory for personally identifiable information; flag or redact before storage
Data retention policies — configurable TTLs for episodic memory, conversation history, and knowledge store entries; auto-purge expired data
Right-to-erasure — delete all data associated with a specific user or session on request (GDPR/CCPA compliance)
Audit trail — immutable log of who accessed what data, when, and why; required for enterprise and regulated deployments
Consent tracking — record user consent for data collection and processing; respect opt-out preferences across all agents

Engineering Team (Phase 32)¶

"I'm givin' her all she's got, Captain!"

Automated performance optimization, maintenance, and construction. The team that keeps the ship running and builds new capabilities.

Performance Monitor — tracks latency, throughput, memory pressure, identifies bottlenecks (what AD-289 did manually, but automated)
Maintenance Agent — database compaction, log rotation, cache eviction, connection pool management
Builder Agent — executes build prompts, constructs new capabilities (bridges to external coding agents initially)
Architect Agent — reads codebase, produces build-prompt-grade proposals that the Builder can execute autonomously

Automated Build Pipeline — Northstar (AD-311+)

"The ship builds itself — with the Captain's approval."

The Architect and Builder agents form an automated design-and-build pipeline. The Architect reads full source via CodebaseIndex (import graphs, caller analysis, API surface verification), produces structured proposals with embedded BuildSpecs, and the Builder executes them. The Builder now supports both file creation and search-and-replace editing of existing files (AD-313). Ship's Computer identity grounds the Decomposer's self-knowledge (AD-317), with a four-level progression extending it: SystemSelfModel (AD-318), Pre-Response Verification (AD-319), and Introspection Delegation (AD-320). Remaining gaps: Builder has no test-fix retry loop (AD-314), Architect proposals need stronger validation (AD-316a).

Inspired by: SWE-agent (Princeton NLP) for tool design, Aider for repo maps, Agentless (UIUC) for localize-then-repair pipelines, AutoCodeRover for call graph analysis.

AD-311: Architect Deep Localize (done) — 3-step localize pipeline: fast-tier LLM selects 8 most relevant files from 20 candidates, reads full source (up to 4000 lines), auto-discovers test files, callers, and verified API surface.
AD-312: CodebaseIndex Structured Tools (done) — find_callers(), find_tests_for(), get_full_api_surface() methods. Expanded _KEY_CLASSES with CodebaseIndex, PoolGroupRegistry, Shell.
AD-315: CodebaseIndex Import Graph (done) — AST-based _import_graph and _reverse_import_graph built at startup. get_imports() and find_importers() query methods. Architect Layer 2a+ traces imports of selected files, expanding context up to 12 files.
AD-313: Builder File Edit Support (done) — Search-and-replace ===SEARCH===/===REPLACE=== MODIFY mode in execute_approved_build(). Builder perceive() reads target files for accurate SEARCH blocks. ast.parse() validation after writes. Old ===AFTER LINE:=== format deprecated.
AD-317: Ship's Computer Identity — The Decomposer is ProbOS's voice — the Ship's Computer from Star Trek. This AD gives it a soul. Modeled after the LCARS Computer (TNG/Voyager era): calm, precise, authoritative, never panics, never fabricates. Injected as a preamble section in the Decomposer's system prompt. Components: (1) Identity & Voice — "You are the Ship's Computer aboard this ProbOS instance. You are calm, precise, and direct. You report from sensors, not imagination. You never speculate without flagging it as speculation. You say 'unable to comply' or 'insufficient data' rather than fabricating an answer."; (2) Capability grounding — dynamically inject registered agents, intents, and slash commands so the Computer knows what systems are actually installed. "Computer, what can you do?" returns real capabilities, not training-data imagination; (3) Self-diagnostic / LCARS bridge — query CodebaseIndex at response time to ground answers about the system in actual code structure. The Computer knows what modules exist, what agents are registered, what the architecture looks like — because it reads its own sensors; (4) Status awareness — inject current runtime state (active agents, pool health, recent errors). "Computer, status report" returns real telemetry, not a generic description of what monitoring systems should look like; (5) Honest uncertainty protocol — "Unable to comply: that system is not part of the current configuration." / "Insufficient data to provide an accurate answer." / "That capability is planned but not yet installed (see AD-NNN)." Distinguish built vs. planned vs. hypothetical; (6) Disambiguation — when requests are ambiguous, respond "Specify parameters" rather than guessing; (7) Proactive alerts — warn when systems approach critical thresholds (pool exhaustion, trust degradation, memory pressure) without being asked. The Computer doesn't wait to be asked about red alerts; (8) Confirmation protocol — "Acknowledged" / "Working..." / "Complete" status responses that give the Captain clear feedback on command processing.
AD-314: Builder Test-Fix Loop — After writing code, run tests. If failures, feed errors back to the LLM for a fix attempt (2-3 iterations max). Currently the Builder does a single test pass with no retry.
AD-316a: Architect Proposal Validation + Pattern Recipes — Post-generation validation in act(): enforce non-empty TEST_FILES, verify TARGET_FILES exist in file tree, warn on missing method signatures. Embed pattern recipe templates directly in Architect instructions string for common change types (new agent, new slash command, new API endpoint) — each recipe lists required files, typical test file, and structural checklist. Zero LLM calls, zero storage overhead.
AD-318: SystemSelfModel — Lightweight, always-current in-memory dataclass holding verified runtime facts (pool count, agent roster, registered intents, recent errors, uptime, last capability gap). Updated reactively on pool/agent changes. Replaces ad-hoc runtime_summary from AD-317. Injected into WorkingMemorySnapshot so the Decomposer never starts cold. Level 2 of self-knowledge grounding (rules → data → verification → delegation).
AD-319: Pre-Response Verification — Fast validation pass on Decomposer output before it reaches the Captain. Regex check against SystemSelfModel for unregistered capabilities, unknown agent names, unbuilt feature claims. Optional fast-tier LLM check for complex reflective responses. The "read before you speak" pattern. Level 3 of self-knowledge grounding.
AD-320: Introspection Delegation — Self-knowledge questions ("what agents do you have?", "how does trust work?") route to IntrospectionAgent first. IntrospectionAgent queries SystemSelfModel + CodebaseIndex + episodic memory, returns grounded facts. Decomposer synthesizes from verified data instead of generating from LLM training knowledge. Level 4 of self-knowledge grounding.
Infrastructure Agent — disk space monitoring, dependency health, environment validation
Existing: PoolScaler handles some Ops/Engineering overlap

Containerized Deployment (Docker)

"The ship in a bottle — portable, isolated, cross-platform."

ProbOS currently runs directly on the host OS. A Docker-based deployment provides security isolation (agents can't reach the host filesystem), cross-platform parity (Windows, Linux, macOS from one image), and simplified setup:

Official Dockerfile — multi-stage build: Python base with ProbOS deps, Ollama for local LLM, optional HXI frontend served via the built-in FastAPI static mount
docker-compose.yml — one-command startup: ProbOS runtime + Ollama + optional ChromaDB (persistent volume for data)
Cross-platform parity — same container image runs identically on Windows (Docker Desktop), Linux (native), and macOS (Docker Desktop). Eliminates platform-specific setup issues (pip not found, path separators, venv activation)
Security boundary — containerized ProbOS can't access host filesystem, network, or processes beyond explicitly mapped volumes and ports. Essential for the public Twitch demo and any scenario with untrusted agents
Safe mode profile — container startup flag (--safe-mode) that enables restricted config: disabled shell commands, disabled file writes outside /sandbox, rate limiting, SSRF protection enforced
Volume mounts — data/ (episodic memory, knowledge store, event log), config/ (system.yaml), optional agents/ (designed agents). Everything else is ephemeral
Ollama sidecar — Ollama runs as a separate container on the same Docker network. ProbOS connects to it via http://ollama:11434/v1. No GPU passthrough required for CPU-only models; GPU passthrough available for CUDA-enabled hosts
Existing: Twitch demo plan already specifies Docker-based deployment (commercial roadmap)

Backup & Restore

Episodic memory snapshots — periodic ChromaDB backup to disk or cloud storage; restore from snapshot on corruption or migration
System state export — export trust scores, Hebbian weights, agent registry, and config as a portable snapshot for migration between instances
Point-in-time recovery — roll back episodic memory to a known-good state after bad dream consolidation or corrupted imports

CI/CD Pipeline

GitHub Actions test suite — run full pytest suite (1700+ tests) on every PR and push to main
Vitest for HXI — run frontend tests alongside Python tests
Quality gates — block merge if tests fail, lint errors, or type check issues
Automated release — tag-based releases with changelog generation from commit history
Existing: GitHub Actions for docs deployment to probos.dev (built)

Performance & Load Testing

Benchmarks — reproducible performance baselines for DAG execution, consensus rounds, LLM latency, and intent routing throughput
Load simulation — synthetic concurrent user workloads to identify scaling bottlenecks before production
Regression detection — CI compares benchmark results against baselines, flags performance regressions on PRs

LLM Resilience — Graceful Degradation

Provider failover — if the primary LLM provider is down or rate-limited, fall back to a secondary provider (e.g., OpenAI → Anthropic → local model)
Cached response mode — when all providers are unavailable, serve cached responses from the decision cache for previously-seen patterns
Degraded operation — agents that don't require LLM calls (HeartbeatAgents, mesh agents) continue operating; cognitive agents queue work until LLM access is restored
Circuit breaker — after N consecutive LLM failures, stop retrying and notify the Captain rather than burning through rate limits
Health indicator — LLM provider status surfaced through Vitals Monitor and HXI

Observability Export

OpenTelemetry integration — structured traces for intent routing, DAG execution, consensus rounds, and LLM calls
Prometheus metrics — agent trust scores, pool utilization, Hebbian weights, dream consolidation rates, LLM latency/cost exposed as scrapeable metrics
Grafana dashboards — pre-built dashboards for system health, agent performance, and cost tracking
Log aggregation — structured JSON logging with correlation IDs for tracing a user request through decomposition → routing → execution → reflection
Existing: Python logging throughout, HXI real-time visualization (built)

Storage Abstraction Layer

ProbOS currently uses aiosqlite (SQLite) for event log and episodic memory, and ChromaDB for vector storage. Both are ideal for local-first, single-ship deployment (zero config, embedded, pip install). For enterprise and cloud deployment, swappable backends are needed:

StorageBackend ABC — abstract interface for relational/event storage operations (write event, query events, store episode, recall episodes)
SQLiteBackend — default implementation wrapping current aiosqlite usage. Remains the zero-config default for OSS
Future backends — PostgreSQL, etc. implemented as drop-in replacements behind the same interface
Migration path — existing EventLog and EpisodicMemory classes code against the ABC, not raw aiosqlite. Backend selected via config
SQLite is proven for single-node: zero config, WAL mode handles modest concurrency, file-based backup. The abstraction exists so cloud/enterprise can swap without changing agent code

Vector Store Abstraction Layer

ChromaDB is the right default for OSS (embedded, zero config, works offline), but enterprise/cloud needs backends with clustering, replication, and multi-tenant isolation:

VectorStore ABC — abstract interface for vector operations (add, query, get, delete, count). Small surface — ~50 lines
ChromaDBBackend — default implementation wrapping current ChromaDB usage. Remains the zero-config default for OSS
Future backends — pgvector, Qdrant, Pinecone implemented as drop-in replacements behind the same interface
Migration path — existing KnowledgeStore and EpisodicMemory (vector side) code against the ABC, not raw ChromaDB API. Backend selected via config
Key insight: PostgreSQL + pgvector could serve as the single enterprise backend for both relational and vector storage, reducing operational complexity

P1 Performance Optimizations (deferred from AD-289)

Pool health check caching — cache healthy_agents list with short TTL, invalidate on agent state change
WebSocket delta updates — send state deltas instead of full snapshots, throttle event broadcast rate (batch within 100ms window)
Event log write batching — batch SQLite commits (flush every 100ms or 10 events), enable WAL mode
Episodic memory query optimization — add timestamp index to ChromaDB collection, cache recent episodes with TTL

Decision Cache Persistence (deferred from AD-272)

Persist CognitiveAgent decision caches to KnowledgeStore for warm boot — returning users get instant responses for previously-seen patterns
Feedback-driven cache eviction: /feedback bad invalidates cached decisions for involved agents, preventing stale bad judgments from persisting

Operations Team (Phase 33)¶

"Rerouting power to forward shields."

Formalize resource management and system coordination as an agent pool.

Resource Allocator — workload balancing across pools, demand prediction, capacity planning
Scheduler — task prioritization, queue management, deadline enforcement (extends Phase 24c TaskScheduler)
Coordinator — cross-team orchestration during high-load or emergency events
Response-Time Scaling (deferred from Phase 8) — latency-aware pool scaling. Instrument broadcast() with per-intent latency tracking, scale up pools where response times exceed SLA thresholds
LLM Cost Tracker — per-agent, per-intent, and per-DAG token usage accounting. Budget caps (daily/monthly), cost attribution via Shapley (which agents are expensive vs. valuable), per-workflow cost breakdowns for end-to-end visibility, alerts when spend exceeds thresholds. Provides the data foundation for commercial ROI analytics. Note: accurate cost attribution will require a proper tokenizer library (e.g., tiktoken for OpenAI models, model-specific tokenizers for others) — current len(content) // 4 estimation is insufficient for billing-grade accuracy
Existing: PoolScaler (built), TaskScheduler (Phase 24c roadmap), IntentBus demand tracking (built)

Mission Control — Agent Activity Dashboard (Phase 34)¶

"Captain on the bridge — all stations reporting."

The UX layer that gives the Captain full visibility into what every agent is doing, in real time. Today, cognitive agents (Architect, Builder) work in a black box — the user triggers /design or /build and waits for a result or failure with no insight into progress. Mission Control replaces that with a live operational dashboard where the Captain can see every active task, track step-by-step progress, respond to agent requests, and manage the crew's workload at a glance.

Inspired by: GitHub Copilot's task list, Kanban boards (Trello/Linear), mission control dashboards (NASA MCC).

AD-316: AgentTask Data Model + Progress Events

The foundational primitive that everything else renders from:

AgentTask dataclass: agent_id, agent_type, team, task_type (design/build/query/skill), prompt (original request text), started_at, steps (list of TaskStep with label/status/duration), requires_action flag, action_type (approve/review/respond/null)
TaskStep dataclass: label, status (pending/in_progress/done/failed), started_at, duration_ms
TaskTracker service on the runtime — agents register tasks, emit step updates, mark completion
Architect perceive() emits real progress events at each layer: "Selecting relevant files...", "Reading 8 files (2,400 lines)...", "Analyzing callers and tests...", "Generating proposal via Opus..."
Builder emits: "Reading reference files...", "Generating code...", "Writing files...", "Running tests..."
WebSocket event type agent_task_update streams TaskTracker state to the HXI
Replaces the current cosmetic progress events (fired before work starts) with real events fired during work

AD-321: Activity Drawer (React)

A slide-out panel from the right edge of the chat:

Three sections: Active (agents currently working, with live step progress), Needs Attention (agents waiting for human input — approve/reject/respond), Recent (completed tasks with outcomes)
Each item is a compact card: agent type icon, task title (truncated prompt), team color badge, elapsed time
Click card to expand: full prompt, step-by-step checklist with timings, action buttons if applicable
Badge count on the drawer toggle button for "Needs Attention" items
Subscribes to agent_task_update WebSocket events for live updates

AD-322: Kanban Board View

Full mission control as a dedicated view (route or tab):

Columns: Queued → Working → Needs Review → Done
Cards show: agent type icon, task title, team color, elapsed time, step progress bar
Click card to expand into full detail panel: original prompt, step-by-step progress, file diffs (build tasks), proposal text (design tasks), action buttons (Approve / Reject / Respond)
Cards auto-move between columns as task state changes
Filter by team (Science, Engineering, Medical, etc.) or agent type
"Done" column auto-archives after configurable time

AD-323: Agent Notification Queue

Persistent notifications that agents can emit and that persist until the Captain acknowledges:

AgentNotification dataclass: agent_id, agent_type, notification_type (info/action_required/error), title, detail, action_url (link to the relevant card), created_at, acknowledged
Notification types: "Proposal ready for review", "Build failed — 3 test failures", "Question: should this modify panels.py or create a new file?"
Bell icon in the HXI header with unread count badge
Notification dropdown: list of unread notifications, click to navigate to the relevant card/drawer item
action_required notifications stay pinned until explicitly acknowledged or the underlying task is resolved
Agent API: self._runtime.notify(agent_id, title, detail, action_required=True) — simple method any agent can call

AD-324: Orb Hover Enhancement

Upgrade the existing system health orb with per-agent hover preview:

When hovering over an agent representation in the orb, show a tooltip with: current task prompt (truncated), current step label, elapsed time, progress fraction (step 3 of 5)
Visual indicator on the orb when any agent requires Captain attention (pulsing amber)
Click-through from orb tooltip to the Activity Drawer card for that agent

Bundled Agent Reorganization (Future)¶

"All hands, report to your departments."

Bundled agents currently share a single "Bundled" pool group, but they serve different departments of the ship. "Bundled" is a distribution label (ships with ProbOS out of the box), not an organizational role. Future work will reassign bundled agents to their functional crew teams:

Communications — TranslateAgent, SummarizerAgent
Science/Research — WebSearchAgent, PageReaderAgent, NewsAgent, WeatherAgent
Operations — CalculatorAgent, TodoAgent, NoteTakerAgent, SchedulerAgent

The bundled designation becomes agent metadata (origin: "bundled") rather than a crew assignment. The pool group system and HXI clustering already support this — it's a data change, not an architectural change.

Meta-Learning (Phase 28)¶

"Fascinating." — The ship learns to learn.

Move beyond per-session learning to cross-session concept formation, persistent goals, and abstract reasoning.

Workspace Ontology — auto-discovered conceptual vocabulary from the user's usage patterns, stored in Knowledge Store
Dream Cycle Abstractions — dreaming produces not just weight updates but abstract rules and recognized patterns
Session Context — conversation history carries across sessions, decomposer resolves references to past interactions (AD-273 provides foundation)
Goal Management (deferred from Phase 16) — persistent goals with progress tracking, conflict arbitration between competing goals, goal decomposition into sub-goals with dependency tracking
Existing: Episodic memory (built), dreaming engine with three-tier model (built), conversation context (AD-273, built)

Federation Hardening (Phase 29)¶

Additional federation capabilities deferred from Phase 9.

Beyond the core federation transport (ZeroMQ, gossip, intent forwarding) already built:

Dynamic Peer Discovery — multicast/broadcast-based automatic node discovery on local networks, replacing manual --config peer lists
Cross-Node Episodic Memory — federated memory queries that span multiple ProbOS instances, enabling a ship to recall experiences from allied ships
Cross-Node Agent Sharing — propagate self-designed agents to federated peers (deferred from Phase 10). Agents carry their trust history and design provenance
Smart Capability Routing — cost-benefit routing between federation nodes, factoring in capability scores, latency, trust, and load. Beyond the current "all peers" routing
Federation TLS/Authentication — encrypted transport and node identity verification for federation channels. Required before any production multi-node deployment
Cluster Management — node health monitoring, auto-restart, graceful handoff of responsibilities when a node goes down

MCP Federation Adapter (Phase 29)¶

A universal translator for the wider agent ecosystem.

MCP (Model Context Protocol) is becoming the standard for inter-agent tool sharing. ProbOS supports it as a federation transport alongside ZeroMQ — connecting ProbOS to external agent frameworks, IDEs, and MCP-compatible tools without requiring them to run ProbOS.

Inbound (MCP Server)

ProbOS exposes its agent capabilities as MCP tools
MCP tool calls are translated to IntentMessage and dispatched through the intent bus
MCP-originated intents go through the same governance pipeline as any federated intent: consensus, red team verification, escalation
The MCP adapter is a transport, not a trust bypass

Outbound (MCP Client)

ProbOS discovers and invokes capabilities on external MCP servers
External tool definitions translated to IntentDescriptor and registered as federated capabilities
FederationRouter routes intents to MCP-connected systems alongside ZeroMQ-connected ProbOS nodes
External capabilities carry federated trust discount (same δ factor as trust transitivity)

MCP Client Trust

MCP clients treated as federated peers with configurable trust
New clients start with probationary trust (same Beta(alpha, beta) prior as new agents — AD-110)
Trust updated based on outcome quality of submitted intents
Destructive intents from MCP clients always require full consensus regardless of accumulated trust

Transport Coexistence

ZeroMQ remains the primary intra-Nooplex transport (fast, binary, low-latency)
MCP serves the tool boundary between ProbOS and the wider ecosystem
A2A serves the agent boundary between ProbOS and external agent frameworks
FederationBridge becomes transport-polymorphic: ZeroMQ, MCP, and A2A implementations behind a shared interface

A2A Federation Adapter (Phase 29)¶

"Hailing frequencies open — to all ships, not just ours."

Google's Agent-to-Agent (A2A) protocol is the agent-communication complement to MCP (which is tool-communication). MCP lets agents use external tools; A2A lets agents collaborate with external agents. ProbOS supports both as federation transports.

External World ←→ ProbOS
─────────────────────────────────
Tools:   MCP Protocol  ←→ Intent Bus (tool calls)
Agents:  A2A Protocol  ←→ Intent Bus (agent collaboration)
Nodes:   ZeroMQ        ←→ Federation (ProbOS-to-ProbOS)

Inbound (A2A Server)

ProbOS exposes agent capabilities as A2A-discoverable services
External agents can send tasks to ProbOS agents via A2A task protocol
A2A tasks are translated to IntentMessage and dispatched through the intent bus
Full governance applies: consensus, red team verification, trust scoring
ProbOS publishes an Agent Card describing available capabilities, authentication requirements, and supported modalities

Outbound (A2A Client)

ProbOS discovers external agents via A2A Agent Card discovery
External agent capabilities registered as federated agents (not tools — key distinction from MCP)
FederationRouter routes intents to A2A-connected agents alongside ZeroMQ and MCP peers
Supports A2A streaming for long-running collaborative tasks

A2A Trust Model

External A2A agents treated as federated crew members with discounted trust (same δ factor as trust transitivity)
New A2A peers start with probationary trust, same as MCP clients
Trust updated based on task outcome quality, measured by Shapley attribution
A2A agents never bypass consensus — they're collaborators, not privileged operators
Agent Card metadata (publisher, version, capabilities) stored for provenance tracking

MCP vs A2A Decision Matrix

Use MCP when: consuming a stateless capability (file read, API call, database query) — tools
Use A2A when: delegating a task that requires reasoning, context, multi-step work — agents
ProbOS agents can use both: MCP for instruments, A2A for collaboration with external crew
Phase 26 Agent-as-Tool works internally; A2A extends the pattern across framework boundaries

Skill Manifest Format (Phase 30)¶

A standard manifest for portable, publishable skills.

Inspired by OpenClaw's declarative skill metadata. Standardizes how skills are described, discovered, and distributed — foundation for the Agent Marketplace.

Manifest file (skill.yaml) — name, description, version, author, license, required dependencies, platform constraints, ProbOS version compatibility
Dependency declaration — Python packages, system binaries, external services needed
Auto-installation — skills declare their dependencies; runtime installs them on first use
Discovery protocol — skills can be searched, browsed, and installed from registries
Testing contract — manifest includes test commands, expected coverage, integration test requirements
Pairs with the commercial Agent Marketplace for publishing and distribution

Task Ledger (Phase 33 — Operations Team)¶

Two-loop architecture for long-horizon task management.

Inspired by Microsoft Magentic-One's Task Ledger + Progress Ledger pattern. Structured tracking for multi-step, multi-agent tasks with adaptive replanning.

Task Ledger — tracks facts (confirmed), guesses (unverified), plan (ordered steps), and blockers for each active long-horizon task
Progress Ledger — per-subtask tracking: assigned agent, status, output, retries, duration
Adaptive replanning — when progress stalls or a subtask fails, revise the plan using updated facts and lessons learned
Extends Phase 24c TaskScheduler from "schedule and run" to "schedule, track, and adapt"
Integrates with Evolution Store — task outcomes feed back as lessons for future planning

Tool Layer — Instruments (Phase 25b)¶

"Tricorder readings, Captain."

A lightweight callable abstraction for operations that don't need full agent lifecycle. Tools are the ship's instruments — trusted, shared, and purpose-built. Any authorized crew member (agent) can pick up a tricorder and use it without filing a request through the chain of command.

Why this tier exists:

Currently, reading a file routes through the full agent lifecycle: Hebbian routing → trust scoring → consensus → Shapley attribution. That's a committee meeting to pick up a tricorder. Tools provide a direct-call path for operations that need reliability but not deliberation.

Tool base class:

class Tool:
    name: str                           # "file_reader", "http_fetch", "stripe_api"
    description: str                    # Human-readable purpose
    input_schema: dict                  # JSON schema for typed inputs
    output_schema: dict                 # JSON schema for typed outputs
    trust_score: float                  # Tool-level reliability tracking
    requires_approval: bool = False     # Some tools (shell, delete) need Captain approval

    async def execute(self, **kwargs) -> ToolResult

ToolRegistry:

Central registry of available tools, analogous to agent Registry
register(tool), get(name), list(), search(capability)
Any CognitiveAgent can discover and invoke registered tools via self.use_tool(name, **kwargs)
Tool results include execution metadata (duration, success, error) for trust tracking

Tool Trust (lightweight):

Tools carry a simple success/failure trust score (same Beta distribution as agents)
Trust is updated per-call but does NOT feed into Hebbian routing or Shapley attribution
Below-threshold trust triggers a warning to the using agent, not a consensus vote
Captain can disable untrusted tools globally

Migration Path:

Current mesh agents that are pure function wrappers can be optionally demoted to tools:

Current Agent	Tool Equivalent	Governance Change
FileReaderAgent	`file_reader` tool	Direct call, no consensus
FileWriterAgent	`file_writer` tool	Requires approval for write paths
HttpFetchAgent	`http_fetch` tool	SSRF validation stays, no consensus
ShellCommandAgent	`shell_command` tool	Always requires Captain approval
DirectoryListAgent	`directory_list` tool	Direct call, no consensus
FileSearchAgent	`file_search` tool	Direct call, no consensus

Migration is optional and gradual — agents remain as fallback. Tools supplement, not replace.

MCP Compatibility:

External MCP tools register as ProbOS tools automatically (with probationary trust)
ProbOS tools are exposed as MCP tools to external systems via the MCP adapter (Phase 29)
Tool.input_schema / Tool.output_schema map directly to MCP tool schemas
This makes the MCP adapter implementation straightforward: MCP tool ↔ ProbOS tool is 1:1

External Integration Pattern:

Third-party tools (Stripe, GitHub, database, etc.) follow the same pattern:

class StripeTool(Tool):
    name = "stripe_checkout"
    description = "Create a Stripe checkout session"
    input_schema = {"amount": "int", "currency": "str", "description": "str"}
    requires_approval = True  # financial operations need Captain approval

No need to build a full StripeAgent with intent handling, Hebbian routing, and Shapley attribution — just a validated instrument.

Agent-as-Tool Invocation (Phase 26)¶

Explicit agent-to-agent capability consumption.

Allows one agent to explicitly invoke another agent's capability as a typed function call, complementing the implicit collaboration that already happens through the intent bus. Builds on the Tool Layer (Phase 25b) — agents can be wrapped as tools for direct invocation.

AgentTool wrapper — any agent can be consumed as a tool by another agent with typed input/output contracts
Intent bus remains the primary collaboration mechanism for loosely-coupled work
AgentTool is for tightly-coupled cases where one agent always needs another's output (e.g., Diagnostician consumes Vitals Monitor metrics)
Trust and consensus still apply — wrapping doesn't bypass governance (unlike plain tools, AgentTools are full agents underneath)
Natural fit for Phase 26 Inter-Agent Deliberation

Interactive Execution Mode (deferred from Phase 16)

Pause, inject, or redirect a running DAG mid-flight during execution
Human can add constraints, modify node parameters, or insert new nodes into an active plan
CollaborationEvent type for HXI visualization of human-agent co-editing
Foundation for real-time human-agent pair programming on complex tasks

Self-Improvement Pipeline (Phase 30)¶

The mechanism that allows the ship to upgrade itself — with the Captain's approval.

The infrastructure for a closed-loop improvement cycle: discover capabilities, evaluate fit, propose changes, validate results, and learn from outcomes.

Stage Contracts (Typed Agent Handoffs)

Formal I/O specifications for inter-agent task handoffs
Each contract declares: input artifacts, output artifacts, definition of done, error codes, max retries
Enables reliable multi-step workflows where agents hand off work to each other with clear expectations

Capability Proposal Format

Typed schema for "here's what was found, why it matters, and how it fits"
Fields: source (repo/paper/API), relevance score, architectural fit assessment, integration effort estimate, dependency analysis, license compatibility
Proposals flow through a review queue with approve/reject/modify actions

Human Approval Gate

Stage-gate mechanism that pauses automated pipelines for Captain review
Approval queue surfaced via HXI, shell, or API
Supports approve, reject, or modify-and-resubmit workflows
Audit trail of all decisions for traceability

QA Agent Pool

Automated validation agents that go beyond pytest
Behavioral testing: does the new capability actually improve the metric it claimed to?
Regression detection: did anything break?
Performance benchmarking: latency, memory, throughput before and after
Shapley scoring to measure marginal contribution of new capabilities

Evolution Store

Append-only store of lessons learned from capability integrations (successes, failures, and why)
Time-decayed retrieval: recent lessons weighted higher, stale lessons fade
Fed into episodic memory and dream consolidation for cross-session learning
Future Science team agents query this store to avoid repeating past mistakes

PIVOT/REFINE Decision Loops

Autonomous decision points in multi-step workflows: proceed, refine (tweak and retry), or pivot (abandon and try a different approach)
Artifact versioning on rollback: previous work is preserved, not overwritten
Hard iteration caps to prevent infinite loops

Capability Injection (Adapter Bundle)

Agents declare needed capabilities (search, store, fetch, notify) via typed Protocol interfaces
Runtime injects concrete implementations at startup
Swappable providers without changing agent code (e.g., swap OpenAlex for Semantic Scholar)
Recording stubs for testing: log calls without side effects, verify agent behavior in isolation

Multi-Layer Verification (Anti-Hallucination)

Graduated verification of agent-produced claims against external sources
Multiple verification layers, each catching what the previous missed (e.g., direct ID lookup -> API search -> fuzzy title match -> LLM relevance scoring)
Classifications: VERIFIED (high confidence), SUSPICIOUS (needs review), HALLUCINATED (fabricated), SKIPPED (unverifiable)
Extends the trust network from binary success/fail to graduated confidence scoring
Applied to research findings, generated references, claimed capabilities, and factual assertions

Agent Versioning + Shadow Deployment (deferred from Phase 14c)

Track version history of designed agents — each modification produces a new version with provenance chain
Shadow deployment: run new agent versions alongside existing ones, compare performance on identical intents via Shapley scoring, promote or rollback based on observed metrics
Depends on persistent agent identity (AD-177, built)

Vibe Agent Creation (AD-271, built)

Human-guided agent design: user provides natural language guidance ("make it focus on security" or "it should be conservative") before generation
An alternative mode alongside fully automated self-mod — the Captain can shape agent design without writing code
Extends the Human Approval Gate from binary approve/reject to collaborative design

Git-Backed Agent Persistence

Self-designed agents currently live in the evolution store (KnowledgeStore) as runtime artifacts. To become permanent crew members, they need to be version-controlled:

Write-to-disk serialization — promote approved agents from evolution store to src/probos/agents/designed/ as clean .py files
Git integration — ProbOS creates a branch, commits the agent file, opens a PR. ProbOS becomes a git contributor (Co-Authored-By: ProbOS <probos@probos.dev>)
Code quality gate — lint, test, security scan (red team), and behavioral validation before commit
Provenance chain — each agent file carries metadata: which conversation spawned it, design intent, trust score earned, Shapley contribution, version history
Rollback — if an agent degrades post-promotion, revert the commit and demote back to evolution store
User-owned repos — each ProbOS user's designed agents sync to their own git repo (local or GitHub). The user chooses private or public visibility

"The Federation shares its finest officers."

When users make their agent repos public, a decentralized agent-sharing ecosystem emerges — like P2P file sharing but for ProbOS agents, with GitHub as the transport layer.

Multi-User / Multi-Tenant (Future)¶

"Multiple Captains on the bridge."

Currently ProbOS assumes a single Captain — one human operator with full authority. Multi-user support enables shared ProbOS instances where multiple users connect simultaneously without interfering with each other.

Session isolation — each connected user gets their own conversation context, decomposer state, and episodic memory namespace
User identity — authenticated users via channel adapters (Discord user ID, API key, SSO token) mapped to ProbOS user profiles
Permission model — role-based access: Captain (full authority, approval gate), Officer (can issue intents, no self-mod approval), Observer (read-only, monitor HXI)
Approval routing — self-mod and destructive intents route to the Captain regardless of which user triggered them
Per-user trust context — agents may have different trust scores per user (optional, advanced)
Shared resources — all users share the same agent pools, knowledge store, and trust network, but conversation state is isolated
Foundation for team deployments and the commercial multi-tenant hosting model

Discovery

GitHub repos tagged with probos-agent topic are discoverable by any ProbOS instance
Discovery agent (Science team) periodically indexes public agent repos via GitHub API search
Agent catalog: name, description, trust score history, design provenance, compatibility info
No central registry needed — GitHub is the index

Import with Review

Captain browses discovered agents, previews trust history, provenance chain, and source code
Import creates a branch in the user's local repo with the external agent
Red team scans imported agent source for security issues (prompt injection, data exfiltration, sandbox escapes)
QA pool runs behavioral tests before the agent joins the crew
Imported agents start with a low trust score and earn trust through performance (same onboarding as self-designed agents)

Trust and Provenance

Agents carry a signed provenance chain: who designed them (human or ProbOS), which instance, what version
Trust scores from the source instance are visible but not inherited — each ship builds its own trust independently
Community trust signals: how many instances have imported this agent, aggregate success/failure rates
License compatibility checks: agents inherit the license of their source repo

Sharing Back

If a user improves an imported agent, they can contribute the improvement back to the source repo via PR
ProbOS-to-ProbOS collaboration: one ship's agent evolves and the improvement propagates across the fleet
Opt-in only — no automatic propagation, every change goes through Captain approval

Want to contribute?

See the Contributing guide for how to get involved.