Headless Agent Client Contract

Aegis can be used without the dashboard through the local HTTP API or CLI. The headless contract is narrower than the full operator API: agents may create and inspect work, append steering guidance, and prepare evidence for a human, but they cannot approve high-risk actions or mutate operator-owned configuration.

Machine-readable contract:

• API: GET /agent-client/contract
• CLI: npm run cli -- agent-client-contract

Operation Classes

• agent-readable: safe read paths such as command center, run workspace, task sessions, artifacts, audit view, replay packets, tool/skill/profile catalogs, model catalog, provider health with credential details redacted, and approval queue evidence.
• agent-steering: non-approval work routing such as creating runs, coordinator messages, task guidance, coordinator reports, and retries.
• human-only: approval decisions and authority-changing mutations, including approval checkpoints, agent-profile activation, routing policy changes, and other operations that change future agent authority.
• operator-only: local administration such as secret metadata/status/material, notification read/dismiss state, destructive cleanup, restore checks, service logs, migration, and local machine configuration.
• blocked: future high-risk connector classes and destructive paths that should not be exposed to headless agents.

Headless Flow

1. Read GET /agent-client/contract or run npm run cli -- agent-client-contract.
2. Create work with POST /coordinator/runs or npm run cli -- create-coordinator-run --request "...".
3. Inspect progress with command-center, run-workspace, get-task-session, artifact-index, audit-view, and replay-packet.
4. Steer at execution boundaries with add-task-guidance or coordinator conversation messages.
5. If a human-owned approval appears, inspect approval-queue, summarize typed evidence and hashes for the human, then wait for a human approve or reject decision.

Boundaries

Approval endpoints are authority-scoped. Human decisions use actorType: "human". The model-backed coordinator can use actorType: "coordinator" only for bounded start/internal checkpoints that the executor marks as coordinator-approvable after inspection. Repo-write patch bundles, external side effects, and unsupported high-risk approval classes remain human-owned and require evidence, hash, and policy-class review flags. Headless agent tokens cannot call the approval endpoints.

Bearer-token auth supports AGENT_HARNESS_TOKEN for operator access and optional AGENT_HARNESS_AGENT_TOKEN for headless agent access. The agent token is limited to agent-readable and agent-steering operations; human-only, operator-only, and blocked operations return 403.

Secret metadata is operator-owned. Scoped agent tokens cannot read secret IDs, hashes, redacted previews, status, or provider associations.

Purchases, trades, tax actions, network/device changes, and broad self-extension remain blocked until dedicated connectors, verifier coverage, approval checkpoints, and audit traces exist.