Module v2 

Configuration schema v2 (RFC 0030) — the agentd 2.0 settings document.

One nested document (YAML or JSON; several files merge in order) whose every path is also AGENTD_<PATH> / AGENT_<PATH> / <PATH> and --<path>. This module holds the typed Settings, its JSON Schema (schema::schema), the load pipeline (files → env → flags → typed → validated), the legacy alias table (--instruction, --intelligence, --model, --mcp, …), the agentd --instruction X sugar, v1/v2 detection, and the reload partition (restart-only paths).

Layering (RFC 0011 §2.1 / RFC 0017 §3.2, unchanged): built-in < files < env < flags. Files compose with JSON-Merge-Patch semantics; env sets a path (lists/maps replaced); flags apply in argument order — a generic --<path> SETS, a named repeatable alias (--mcp, --a2a-peer) ADDS.

The 2.0 runtime consumes Settings; the v1 super::Config keeps serving the v1 runtime until the cut-over (plan §6 P5).

Modules

schema

The JSON Schema (Draft 2020-12) of the v2 settings document (RFC 0030 §3) — hand-written (no schemars, the moat) and kept faithful to super::Settings by the drift tests in super::tests. It is the single source for the path bindings (env AGENTD_<PATH> names, --<path> flags, --help), for --config-schema=2, and for agentctl’s admission validation.

Structs

A2a

A2aPeer

A2aPush

Push notifications: a caller registers a webhook and agentd POSTs its task’s updates there instead of holding a stream open.

A2aTls

AAuth

Agent

AgentTools

Alias

A legacy flag → v2 path alias.

Audit

Auth

A unified per-endpoint authentication provider (RFC 0031 §5). A flat, kind-discriminated record: only the fields relevant to the chosen kind are set; semantic validation (§14) enforces which are required. The provider kinds land incrementally — static/oauth2 first, then aws/spiffe.

AutoContext

Budget

BudgetWindow

Cgroup

Checkpoint

Context

Degrade

Diagnostics

Collected diagnostics: errors fail the load (exit 2); warnings are advisory (logged, printed by --validate-config).

Display

The client-chrome layout (RFC 0032 §12): ordered item lists for the top (header) and bottom (status bar) edges. None ⇒ the built-in default; unknown items are skipped by clients (forward compatibility). The item vocabulary lives in DISPLAY_ITEMS.

Dur

A duration deserialized from "10m" / "500ms" / bare seconds (string or integer). Displays in the same string form.

Durability

Exec

The local command-runner controls (RFC 0028 §exec). agentd’s default posture is no local execution (RFC 0012); this is off unless an operator both builds with --features exec AND sets enabled: true — and even then runs only allow-listed commands, in a confined directory, with a minimal env. The exec tool is otherwise mapping-only (delegate off-box via tools.overrides). It carries the sensitive + egress trifecta tags.

Goal

The self-correcting goal watchdog (RFC 0026). A supervisor-level periodic check of whether the configured statement is achieved (or the agent is stuck), with a configurable disposition. It never blocks the agent loop.

GoalCheck

HeaderMatch

Hmac

HttpOp

Intelligence

Interface

The display-client interface (RFC 0032): the opt-in surface a thin TUI/web-UI client rides — the global SubscribeToEvents feed and the interface.*/debug read ops, served on the existing A2A listener (no new socket). Default-OFF: with enabled: false those methods answer UNSUPPORTED_OPERATION and the core A2A surface is byte-identical. debug additionally exposes internals (conversation transcripts, per-step run detail, the live log ring, audit records on the feed) — operator-grade information; leave it off in production unless you need it. origins lets a hosted web UI (a non-loopback browser origin) through the DNS-rebind guard with CORS; loopback origins are always accepted.

Knowledge

Lifecycle

Limits

Loaded

The result of a v2 load: the typed settings plus the documents they came from (the merged FILE document is kept for secret-provenance validation and for the reload diff).

Mcp

McpOauth

McpServer

Memory

Observability

Otel

Pairing

Pairing-code login (RFC 0032 §13). The code is a 6-digit value derived from a per-process random seed and the current 60-second window — shown only to operators (pairing.code), verified with the previous window’s grace, rate-limited, and exchanged (Pair) for a high-entropy session token that lives in memory until ttl (or restart).

Plan

Pricing

Principal

PrincipalMatch

Quotas

Reserve

RunLimits

Search

Secret

A credential-bearing string: from a FILE it must be a {{secret:…}} / {{secret-file:…}} reference (§5 validation over the file document); from env/flags it may be inline. Debug never shows it.

Security

Settings

The typed v2 settings document. Every object is deny_unknown_fields; every section defaults so a minimal document (agent.instruction alone) is complete.

SkillSource

Skills

Slow

Store

StoreFile

store.file (RFC 0033 §4). The only setting is where the state lives; the adapter needs nothing else, so the block itself is optional — kind: file with no block resolves the root from the environment (file_store_root).

StoreHttp

StoreMcp

StoreOp

SubagentLimits

ToolOverride

Tools

WebhookAuth

A webhook’s inbound authentication. Best practice (and the default guidance) is HMAC over the raw body; a required-header or bearer match are alternatives; none: true is an explicit loopback-only dev opt-out.

Webhooks

The webhook inbound HTTP surface (RFC 0027): a dedicated listener serving the webhook start nodes and wait: {on: webhook} callbacks. Auth is per node (each webhook declares its own verification); a listener-wide default may be set here and is used by nodes that declare no auth.

Enums

AliasKind

How a legacy flag maps onto the document.

Ask

What the loader was asked to do besides loading (short-circuits the CLI handles).

AskHumanFallback

The ask_human fallback disposition (RFC 0032 §16).

AuditSink

AuthKind

The authentication provider family (RFC 0031 §5).

AutoContextOn

BudgetScope

BudgetTactic

Detected

Discover

DurabilityLevel

GoalAction

A goal disposition. Deserialized from a bare string (finish/idle/replan/escalate) or { workflow: <name> }.

OAuthGrant

The OAuth 2.1 grant type (RFC 0031 §7).

OnWorkflowFinished

Preflight

ReserveEstimate

Role

RunUntil

SelectKeyword

StoreKind

StoreOnError

StructuredOutput

ToolSelect

all | none | an explicit list.

WakeEvent

WindowUnit

Constants

ALIASES

The alias table (RFC 0030 §3). Order irrelevant; flags apply in argument order.

DISPLAY_ITEMS

The display items a client knows how to render (RFC 0032 §12).

ENV_ALIASES

Legacy env names → v2 paths (the derived AGENTD_<PATH> names are the primary surface; these keep the quickstart and the 1.x k8s manifests working). Branded (AGENTD_) and neutral (AGENT_) prefixes both apply.

LONG_LIVED_STARTS

Long-lived start-node kinds (RFC 0027 §4) — an instance running one needs a durable store (RFC 0026 §8 lifecycle: run_until: drained).

REMOVED_FLAGS

Flags removed in 2.0 with the migration hint (RFC 0030 §7).

RESTART_ONLY_PATHS

Restart-only path prefixes: a live reload whose effective document differs under any of these is refused (restart_required).

V1_KEYS

v1 (flat) top-level keys.

V2_KEYS

v2-only top-level keys (RFC 0030 §2). limits exists in both schemas (neutral); intelligence is a v1 STRING (the endpoint list) but a v2 OBJECT — decided by shape in detect.

Functions

detect

Decide which schema a merged document speaks.

file_store_root

The file store’s root directory (RFC 0033 §4), first that applies: store.file.path, $AGENTD_STATE_DIR, $XDG_STATE_HOME/agentd/state, $HOME/.local/state/agentd/state, else the OS temp dir.

help_section

The --help section for the v2 paths.

help_text

The v2 --help text: usage, the alias flags, the removed flags, and every config path (flag · env).

load

Load, layer and validate a v2 document from args (excluding the program name) and env. Returns (Loaded, Ask); Ask tells the caller what the invocation wants (--help, --config-schema, --validate-config, …). Errors are ConfigError::Usage (exit 2), before any side effect.

looks_like_resource_uri

scheme://… with no whitespace, and a scheme that is not a bare http(s) URL to a web page… — any <alpha><alnum+.->:// single token counts; the registry decides which server serves it (RFC 0028 §3).

probe

Probe the invocation without side effects: which schema the config files speak (Detected), so main can route to the v2 runtime.

restart_only_diff

The restart-only paths whose values differ between two effective documents.

validate

workflow_is_long_lived

Whether a raw workflow document has a long-lived start node.

workflow_uses_webhook

Whether a raw workflow document uses the inbound webhook surface — a webhook start node, or a wait: {on: webhook} callback (either needs webhooks.listen).