Skip to main content

​
Overview

Polpo follows a supervisor architecture: it manages agent lifecycles, task assignment, assessment, and error recovery. Agents are isolated processes that know nothing about each other — Polpo handles all coordination. Under the hood, Polpo is composed of four layers:
  1. Interface layer — CLI, TUI, Web UI, OpenAI-compatible chat endpoint (/v1/chat/completions), and REST API provide different ways to talk to Polpo
  2. Core — the supervisor loop, task registry, mission executor, system context (.polpo/system-context.md), project memory, and all the managers (assessment, approvals, escalation, scheduling, etc.)
  3. Runner layer — detached subprocesses that host individual agents, communicating with Polpo via the file-based RunStore
  4. Agent layer — the actual AI agents (Claude, GPT, Gemini, etc.) running on the built-in engine
Polpo architecture diagram showing the four layers: Interface, Orchestrator Core, Detached Runners, and Persistence

​
Built-in Engine

All agents run on Polpo’s built-in engine — a multi-provider LLM runtime powered by pi-agent-core. The engine handles agent spawning, tool execution, and activity tracking. Each agent run produces an AgentHandle that Polpo uses to monitor the agent: 
interface AgentHandle {
  agentName: string;
  taskId: string;
  pid: number;              // real process ID
  sessionId?: string;       // optional session ID for transcript access
  activity: AgentActivity;  // live activity data (tools, files, progress)
  done: Promise<TaskResult>; // resolves when agent finishes
  isAlive(): boolean;
  kill(): void;
}

​
Supervisor Loop

Polpo runs a 5-second tick loop that:
  1. Collects results from terminated runners (via RunStore)
  2. Assesses completed tasks using the configured expectations
  3. Retries failed tasks (with fix phase for targeted corrections)
  4. Spawns new agents for pending tasks whose dependencies are met
  5. Enforces health checks — kills stale or timed-out agents
  6. Detects deadlocks — tasks blocked on failed dependencies (Deadlock Resolution)
  7. Recovers orphans — reconnects to live processes after a crash
  8. Checks SLA deadlines — emits warnings or violations when deadlines approach
  9. Evaluates quality gates — blocks mission progression until thresholds are met
  10. Processes approval gates — transitions tasks through awaiting_approval when required

​
Detached Runners

Each agent runs as a detached subprocess (runner.ts), completely independent of Polpo’s main process:
Detached runner communication flow: orchestrator writes config, spawns runner, runner initializes agent, writes results to RunStore
This architecture means:
  • Crash resilience: If Polpo crashes, runners keep working
  • Process isolation: One agent crashing doesn’t affect others
  • Orphan recovery: On restart, Polpo reconnects to live runners

​
Event System

Polpo uses a typed event emitter with 55+ event types organized by category:
CategoryEventsDescription
task:*created, transition, updated, removed, retry, fix, maxRetries, timeout, recovered, question, answeredTask lifecycle
agent:*spawned, finished, activity, staleAgent lifecycle
assessment:*started, progress, complete, correctedTask assessment
orchestrator:*started, tick, deadlock, shutdownSystem events
deadlock:*detected, resolving, resolved, unresolvableDeadlock resolution
mission:*saved, executed, completed, resumed, deletedMission lifecycle
session:*created, message:addedChat sessions
approval:*requested, resolved, timeoutApproval gates
sla:*warning, violated, metSLA monitoring
quality:*gate:passed, gate:failed, threshold:failedQuality gates
schedule:*triggered, created, completedMission scheduling
escalation:*triggered, resolved, humanEscalation chain
notification:*sent, failedNotification delivery
log—General log messages
Events are consumed by the TUI, HTTP/SSE server, and notifications. See Events Reference for full payload details.

​
Persistence

ComponentStoragePurpose
Task RegistryFile-based store (default)Task state with atomic writes
RunStoreFile-based store (default)Runner process tracking
Log StoreFile-based store (default)Persistent event log
Mission StoreFile-based store (default)Mission definitions and status
MemoryFile (.polpo/memory.md)Project context for agents
System ContextFile (.polpo/system-context.md)Standing instructions for Polpo (injected into every conversation)
Runner configsJSON (.polpo/tmp/)Temporary config for detached runners
File-based stores are the default. SQLite and PostgreSQL are available as alternatives via configuration (powered by Drizzle ORM in @polpo-ai/drizzle).
File-based stores use atomic write operations to handle concurrent access from Polpo and multiple runner processes.