stealthwhizz/pcp

Purpose and runtime

PCP is a self-hostable control plane for coding agents: durable task/memory management via MCP plus fleet monitoring via OpenTelemetry. The deployable application is one TypeScript Next.js App Router service rooted at backend/, importing browser UI from frontend/. Main web entry points include backend/app/page.tsx, backend/app/dashboard/page.tsx, and backend/app/developer/page.tsx.

HTTP/API boundary

Next route handlers expose the product API: browser authentication and dashboard reads, agent task/memory operations, MCP, and OTLP ingestion. Representative boundaries are backend/app/api/auth/login/route.ts, backend/app/api/dashboard/route.ts, and backend/app/api/tasks/[taskId]/handoff/route.ts. API handlers should remain thin wrappers around services and enforce organization-scoped access at this edge.

Identity and tenancy

Authentication uses locally managed credentials and signed cookie sessions; API/MCP/telemetry clients authenticate with bearer tokens tied to one organization. Core enforcement and persistence-facing account/token logic live in backend/lib/auth.ts, backend/lib/session.ts, and backend/lib/services/tokens.ts. The tenant boundary is organizationId, intended to scope every domain query and prevent cross-workspace data access.

Domain memory and task lifecycle

The core agent-memory model records tasks, checkpoints, handoffs, recovery state, memories, and explicit memory relationships. Task and memory APIs map to service-layer workflows in backend/lib/services/tasks.ts, backend/lib/services/recovery.ts, and backend/lib/services/memory.ts; routes include backend/app/api/memory/relationships/route.ts and backend/app/api/tasks/[taskId]/checkpoints/route.ts. This is the durable continuity path for agents across sessions.

MCP integration

MCP exposes the same task/memory capabilities to agents through hosted Streamable HTTP and local stdio. HTTP requests enter backend/app/api/mcp/route.ts and are handled through backend/mcp/http.ts; shared tool dispatch is in backend/mcp/handlers.ts. The local-server entry point, backend/mcp/server.ts, can bootstrap project-local .pcp guidance via backend/mcp/bootstrap.ts, while hosted clients operate solely through HTTPS and bearer tokens.

Telemetry and monitoring flow

OTLP logs, metrics, and traces arrive at dedicated endpoints, are normalized/redacted, then persisted as agent telemetry for dashboard aggregation. The pipeline is grounded in backend/app/api/otel/v1/metrics/route.ts, backend/lib/otel/ingest.ts, and backend/lib/otel/normalize.ts. Dashboard-facing portfolio, usage, and activity views are derived through backend/lib/services/dashboard.ts and backend/lib/services/usage.ts, rather than querying ingest payloads directly.

Persistence and deployment

Prisma defines the shared PostgreSQL graph and migration history in backend/prisma/schema.prisma and backend/prisma/migrations/. Database access is centralized in backend/lib/db.ts. Local development uses PostgreSQL via backend/docker-compose.yml; production targets Zerops using backend/zerops.yml, which builds Next.js, applies Prisma migrations, and runs the service with managed Postgres supplied through DATABASE_URL.