Architecture

System Shape

Oblive is one local-first business runner with one organization operator, one always-running chat profile, optional Growth, Engineering, and Support profiles, and ephemeral workers for task execution.

The agent application depends on a provider-neutral harness interface. Codex is the first adapter, not a type system that should leak through shared domain contracts.

Closed Loops

Chat

durable user message + pending assistant message
→ live wakeup
→ claimed chat execution
→ revision-fenced updates
→ PostgreSQL projection
→ SSE to the browser

Chat may recover from missed live signals. Only chat may resume a stored harness session.

Tasks

task + run request in PostgreSQL
→ stream wakeup
→ worker revalidation
→ immutable attempt
→ heartbeat + workspace sync
→ task, dependency, and outcome finalization

Workers create attempts. Scheduler and runbeat create or requeue run requests; they do not create attempts directly.

Human Handoff

active run stages typed blocker
→ finalization opens Human Inbox item
→ task waits
→ human response advances task version
→ fresh run request

Do not continue a stale process after a human response.

Managed Integration Authorization

organization chooses access mode
→ backend creates one-use namespaced OAuth state
→ MCP SDK discovers metadata, registers, and performs PKCE
→ callback discovers policy-eligible tools
→ encrypted organization credential + selected tools
→ execution-scoped backend gateway capability

OAuth client information, refresh tokens, and cached discovery state remain backend-side. Automatic token rotation uses a compare-and-swap credential write and does not advance the authorization epoch. Human connect, reconnect, and disconnect operations use the normal invalidating transition. Agents receive neither API keys nor OAuth tokens.

Component Boundaries

Backend

Owns authentication, validation, canonical transitions, repositories, Context construction, agent-pack publication and provisioning, OpenAPI, scheduling, repair, and external action policy.

Agent Application

Owns chat and worker loops, backend-client calls, context hydration, workspace synchronization, harness invocation, event normalization, heartbeat scheduling, and shutdown.

Shared Packages

• @oblive/types: domain, transport, persistence, manifest, and integration contracts.
• @oblive/caching: connection-injected Redis primitives and canonical names.
• @oblive/objectstore: guarded object operations, keys, URIs, and workspace lifecycle.
• @oblive/agent-packs: catalog validation, composition, discovery, and deterministic revisions.
• @oblive/oblivectl: snapshot-scoped control-plane HTTP mechanics.

Packages own reusable mechanics, not app-specific policy.

Non-negotiable Invariants

• Scope applicable state by organization.
• Keep chat general; route departments when durable work is created.
• Keep run_requests as mutable task-only intent and runs as immutable attempt history.
• Make stale writes and duplicate wakeups harmless through durable revalidation.
• Route task dependencies through one cycle-checking service.
• Route consequential effects through typed actions.
• Synchronize validated output before success.
• Keep provider credentials out of agents and workspaces.
• Keep oblivectl as the authenticated mutation boundary and contextctl local/read-only.
• Persist useful summaries and evidence, never hidden reasoning.

Before Changing Architecture

1. Name the workflow and failure mode.
2. Identify canonical ownership.
3. Trace current behavior through contracts and tests.
4. Check accepted and rejected decisions.
5. Reuse records and transitions.
6. Update contracts, migrations, tests, OpenAPI, CLI, and knowledge-base surfaces together.