AEGIS DOCS

Operator Contracts

Operator contracts are the stable read models for the dashboard. They are defined as Zod schemas in src/shared/contracts.ts and validated in the test suite against real service and HTTP responses.

Runtime response validation is available for the operator endpoints through AGENT_HARNESS_VALIDATE_CONTRACTS=1, or by passing validateContracts: true to createApiServer. It is also enabled automatically when NODE_ENV is development or test. Set AGENT_HARNESS_VALIDATE_CONTRACTS=0 to disable it explicitly.

Command Center

Schema: commandCenterSnapshotSchema

Endpoint:

Purpose: show what needs operator attention across active runs.

Stable fields include active run summaries, task-session counts, blockers, pending approvals, recent failures, and aggregate queue counts.

Coordinator Sessions

Schemas: conversationSessionSchema, conversationDetailsSchema, preRunChecklistSchema

Endpoints:

Purpose: manage durable coordinator chat sessions independently from run execution.

Stable fields include session title/status/origin/active run, event streams, pre-run checklist records, queued-run links, guidance links, and status-report events. PATCH supports rename/archive/active-run switching. Pre-run checklists are durable coordinator events so the operator can inspect what the coordinator planned before work was queued.

Run Workspace

Schema: runWorkspaceSnapshotSchema

Endpoint:

Purpose: inspect one run as coordinated work.

Stable fields include run metadata, run summary, delegation plan, task-session details, approvals, evaluations, latest coordinator report, grouped artifact index, and audit summary counts.

Task Session Inspector

Schema: taskSessionDetailsSchema

Endpoint:

Purpose: inspect one specialist work session.

Stable fields include role/profile context, dispatch metadata, dependency state, dependency rollups, progress rollups, guidance events, event stream, model calls, tool uses, artifacts, evaluations, and trace slices.

Task-session details can include profileRegistryEntry, the durable agent profile record that matched the session role and workflow template. This lets the dashboard show where the runtime profile came from without treating workflow-template JSON as the only source of truth.

Agent Profiles

Schema: agentProfileRecordSchema

Endpoint:

Purpose: inspect coordinator and specialist profile identities before profile editing APIs exist.

Stable fields include id, role, label, description, status, source, version, workflow template ID, provider/model hints, prompt profile, tool allowlist, skill IDs, approval policy class, allowed policy classes, metadata, and timestamps.

Profile editing waits for review and activation policy.

Approval Queue

Schema: approvalQueueSnapshotSchema

Endpoint:

Purpose: review human-owned approval gates with evidence.

Stable fields include approval checkpoint, run context, task session context, evidence artifact references, hash evidence, related trace events, coordinator authority, and recommended action. Approval checkpoint evidence is typed where the runtime knows the shape, including repo-write-patch-bundle and external-write-artifact evidence kinds.

Notification Inbox

Schema: notificationInboxSnapshotSchema

Endpoints:

Purpose: show operator attention items from persisted Aegis state.

Stable fields include notification IDs, category, severity, title/detail, source record IDs, related run/task/session IDs, read/dismissed status, read/dismiss timestamps, unread/read/dismissed counts, and critical count. Notification content is derived from approvals, traces, queue/failure events, and other durable source records; read/dismiss state is stored separately so dismissing inbox items does not mutate approvals, runs, jobs, tasks, or trace events.

Artifact Index

Schema: artifactIndexSnapshotSchema

Endpoint:

Purpose: inspect outputs by purpose rather than raw file path alone.

Stable fields include artifact path, purpose, preview type, label, summary, size, SHA-256, producing task/session references, related approvals, and related evaluations.

Audit View

Schema: auditViewSnapshotSchema

Endpoint:

Purpose: reconstruct the readable run story.

Stable fields include narrative entries, stage timeline, task-session timeline, approval evidence, evaluation summary, risk events, artifact hashes, and integrity warnings. The raw audit export remains available at GET /runs/:id/audit.

System Health

Schema: controlPlaneStatusSchema

Endpoint:

Purpose: understand server, worker, provider, queue, and policy-boundary health.

Stable fields include server config, auth mode, log tail links, worker state, active run summaries, queue totals and per-run queue state, recent failures, provider health, model catalog status, and risk-boundary enforcement.

Headless Agent Client

Schema: headlessAgentClientContractSchema

Endpoint:

Purpose: classify API and CLI access for dashboardless agent use.

Stable fields include version, boundary summary, operation classifications, human-only action classes, blocked capability classes, and the recommended headless flow. The detailed runbook is in docs/architecture/headless-agent-client.md.

Compatibility Rules