POCLI
EN ES

Engineered for Speed, Control & Grounding

POCLI rejects monolithic prompt bloat. Every specialist runs in an isolated Linux process with role-bounded tools, deterministic SDLC governance, and sub-second Time-To-First-Token.

Capabilities

Minimal Harness & Token Efficiency

Inspired by Pi (pi-mono) and empirical findings from Harness Engineering (arXiv:2609.00006), POCLI replaces monolithic 15,000+ ...

3-Tier Context & SQLite DAG

Built on Node.js Native SQLite (node:sqlite) in WAL + FTS5 mode, POCLI stores the entire engineering history in $HOME/.pocli/po...

Autonomous QA & Robot Framework

Following the strict “No Self-Review” engineering principle, the Senior Developer never validates their own code. Once unit tes...

PM Agent & 100% HTML Reports

The Project Manager (PM) provides unified visibility across all virtual engineering specialists without ever interfering with t...

Knowledge Notebooks & Hybrid RAG

POCLI adapts grounded citation research (arXiv:2311.09533) and the NotebookLM / Open Notebook paradigm directly onto your local...

Linux Sandboxing & Multi-Model Router

Every virtual specialist executes in an independent Linux child process communicating via newline-delimited JSON-RPC 2.0 over s...

AI Harness Engineering

AI Agent Harness Reference Matrix & POCLI Coverage

Consolidated architectural taxonomy of the 9 essential capabilities of an AI Agent Harness, why raw LLM API calls fall short, and the exact implementation status in POCLI.

9 Consolidated Pillars 7 Implemented in POCLI 2 Partial (Roadmap)
Pillar / Core Capability What It Is (Definition) Problem Solved Key Components / Concepts Priority Level POCLI Status & Technical Implementation
01 Operational Loop & Execution Control

Orchestrates the master cycle (prompt -> inference -> tool dispatch -> observation), streaming progress to the UI and enforcing strict iteration bounds and timeouts.

Raw API calls cannot self-correct when code or tests fail, risk infinite retry loops, block user interfaces, or hang indefinitely on stalled requests.
  • State-driven turn loop
  • JSON-RPC streaming (agent.streamChunk)
  • Bounded cycles (MAX_QA_CORRECTION_CYCLES = 3)
  • Turn timeouts (120s)
  • Stuck-loop detection
 Core (MVP)
Implemented
How it works in POCLI: PoCliOrchestrator drives agent turns over JSON-RPC 2.0 stdio workers (PersistentAgentRuntime), streams incremental updates via agent.streamChunk to CommandCenterApp, bounds autonomous DEV<->QA rework with MAX_QA_CORRECTION_CYCLES = 3, and enforces 120s per-turn worker timeouts.
Pending: Semantic stuck-loop detector (aborting repeated identical failures) and native HTTP SSE token-by-token streaming across every provider adapter.
02 Model Gateway & Smart Routing

Unified multi-provider LLM abstraction that normalizes payloads, tracks sliding-window rate limits, scores candidates, and executes automatic failover.

Hardcoding a single LLM vendor exposes workflows to HTTP 429/503 outages, latency spikes, provider lock-in, and fragile credential handling.
  • Multi-provider gateway
  • Bandit routing (auto:smart / fast / reliable)
  • RPM / RPD / TPM / TPD sliding windows
  • Cooldown & cascade failover
  • Reasoning tag sanitizer
 Core (MVP)
Implemented
How it works in POCLI: LLMGateway and LLMRouter (llm-router.ts) unify OpenRouter, Groq, Cerebras, Gemini, Pollinations, Ollama, Anthropic, and OpenAI with routing presets, sliding-window quota tracking, cooldown timers, automatic HTTP 429/503/timeout cascade failover, and cleanModelOutput() sanitization.
Pending: Per-error exponential backoff with jitter prior to failover and automated shadow/canary routing evaluations.
03 Typed Tooling & Schema Dispatch

Deterministic registry and execution layer exposing workspace, test, and artifact actions per agent role with structured contracts and controlled loading.

Unconstrained free-text parsing breaks automation, exposes host paths outside the project, and wastes prompt tokens by injecting unused tools upfront.
  • Native tool_calls & structured blocks
  • Role allowlists (allowedTools)
  • Zod schemas
  • Scoped fs/test execution
  • JIT / deferred tool loading
 Core (MVP)
Implemented
How it works in POCLI: harnesses.ts enforces strict per-role allowedTools (architect, developer, qa, pm), while PoCliOrchestrator.executeAgentToolCalls() dispatches typed artifact, source, test (run_unit_tests), QA provisioning (install_qa_tool, run_qa_suite), and handoff calls. LLMGateway merges native choiceMsg.tool_calls with extractToolCalls() backed by Zod schemas.
Pending: Passing full JSON Schema tools[] definitions natively in HTTP payloads for all providers and Just-In-Time (JIT) deferred tool loading for large catalogs.
04 Context Engineering & Layered Memory

Deterministic context assembler combining cache-friendly normative prefixes, tiered memory, lossless compaction checkpoints, and local hybrid RAG retrieval.

Unbounded chat histories cause context rot (lost in the middle), forget architectural decisions, and inflate token spend on every turn.
  • 3-Tier Context Window
  • 4-Layer Memory (CONVERSATIONAL / WORKING / PROJECT / AGENT)
  • Lossless compaction (/compact)
  • Hybrid RAG (SHA-256 + FTS5 + vectors)
 Core (MVP)
Implemented
How it works in POCLI: PoCliDatabase.assembleAgentContextWindow() builds 3-tier prompts: (T1) cacheable normative artifacts prefix, (T2) 4-layer memory + latest context_compactions checkpoint via /compact (marking compacted_into_id without deleting history), and (T3) active uncompacted turns. NotebookRagEngine indexes workspace notebooks via SHA-256 + SQLite FTS5 + vector similarity.
Pending: Automatic provider-threshold compaction triggered transparently before context saturation without requiring manual /compact.
05 Governance, Authority & Sandboxing

Hard policy-as-code rules, single-writer state integrity, Human-in-the-Loop gates, and OS namespace isolation constraining what agents can mutate or execute.

Without deterministic guardrails, agents can overwrite peer artifacts, skip verification gates, corrupt shared state, or run unsafe commands directly on the host.
  • 8-Phase SDLC state machine
  • AuthorityGuard
  • Sole Write Owner + optimistic concurrency
  • HITL (/approve, /accept)
  • Linux bwrap & Podman OCI
 Core (MVP)
Implemented
How it works in POCLI: AuthorityGuard (workflow.ts) validates every SDLC phase transition and artifact permission; PoCliCoordinator serializes SQLite writes as Sole Write Owner with idempotency (requestId), optimistic concurrency (expectedVersion), and coordinator_audit_log; LinuxAgentProcessRunner isolates workers via Bubblewrap (/usr/bin/bwrap --unshare-pid) or Podman OCI containers, while /approve and /accept enforce Product Owner gates.
Pending: Mandatory default seccomp and fine-grained per-tool network-deny policies even when running in lightweight local mode.
06 Persistence, Checkpoints & Durability

ACID transactional storage of sessions, artifacts, layered memory, and compaction checkpoints enabling crash recovery, inspection, and reproducible state history.

In-memory agent state vanishes on process crashes or restarts, breaking multi-session engineering work and making post-mortem audits impossible.
  • SQLite WAL (node:sqlite)
  • Session message history
  • Compaction checkpoints
  • Built-in SQL REPL (pocli db)
  • Step-by-step time-travel replay
 Core (MVP)
Implemented
How it works in POCLI: PoCliDatabase (database.ts) persists projects, messages, versioned artifacts, 4-layer memory entries, compaction checkpoints, and coordinator audit entries inside $HOME/.pocli/pocli.sqlite using Node.js native WAL SQLite. Includes pocli db interactive REPL and JSON/SQL inspection CLI.
Pending: Deterministic step-by-step session replay (time-travel debugging) and turn branching/rewind from immutable state snapshots.
07 Multi-Agent Orchestration & Handoffs

Coordinated execution of isolated specialist agents across separate OS processes using zero-context-bloat assembly and structured inter-agent handoffs.

A single generalist agent grades its own code, mixes incompatible personas, and pollutes reasoning context with irrelevant cross-role noise.
  • Persistent per-role workers
  • JSON-RPC 2.0 bus
  • Typed handoffs ([ARQ->DEV], [DEV->QA], [QA->ARQ])
  • Isolated .venv QA + Mutation Testing
 Advanced / Production
Implemented
How it works in POCLI: PersistentAgentRuntime spawns isolated workers per (projectId, role) across architect, developer, qa, and pm. Each specialist receives only its assembled context window and RAG citations (zero cross-chat bloat). PoCliOrchestrator automates [ARQ->DEV], [DEV->QA], bidirectional DEV<->QA defect loops, and external Robot Framework + TC-MUT-001 validation.
Pending: Concurrent fan-out / fan-in parallel execution of multiple developer subagents across disjoint modules.
08 Extensibility: MCP, Plugins & Skills

Standardized interfaces to attach external tool servers, packaged extensions, custom role behaviors, and reusable skills without modifying the core runtime.

Hardcoding custom integrations for every database, tracker, or API turns the harness into a brittle monolith that cannot adapt across teams.
  • MCP JSON-RPC stdio client (McpRegistry)
  • Per-role MCP ACLs
  • Prompt overrides (~/.pocli/behavior/)
  • Declarative plugins & skills
 Advanced / Production
Partial
How it works in POCLI: McpRegistry (mcp-client.ts) discovers and invokes external Model Context Protocol servers over JSON-RPC 2.0 stdio with strict per-role allowlists (allowedRoles), and harnesses.ts supports user behavior overrides in $HOME/.pocli/behavior/system/.md.
Pending: Declarative plugin package loader, dynamic skill registry (SKILL.md / lifecycle hooks), and remote HTTP/SSE MCP server transport.
09 Telemetry, Cost & Harness Evals

Quantitative observability of latency, token budgets, structured audit logs, executive reporting, and automated end-to-end evaluations verifying harness behavior.

Without telemetry and reproducible harness evals, regressions from model swaps or prompt edits go undetected and runtime costs spiral unnoticed.
  • Rotating logs (pocli logs)
  • Token & compaction tracking
  • PM HTML reports (deliveries/)
  • Headless E2E & Virtual TUI evals (pocli e2e, tui-test)
  • Exact TTFT, USD cost & OTLP
 Advanced / Production
Partial
How it works in POCLI: Logger writes ring-buffered rotating logs ($HOME/.pocli/logs/pocli.log); LLMRouter tracks per-provider latencyMs; PoCliDatabase computes active/saved tokens; PmReporter generates 100% HTML reports in deliveries/; and pocli e2e / pocli tui-test plus Vitest + Mutation Testing validate full harness execution.
Pending: Granular Time-To-First-Token (TTFT) TUI telemetry, per-model USD cost accounting ledger, and OpenTelemetry (OTLP) span export.
POCLI GitHub