Module v2 

The agentd 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 flat alias table (--instruction, --intelligence, --model, --mcp, …), the agentd --instruction X sugar, schema detection, and the reload partition (which paths only a restart can change).

Layering: built-in < files < env < flags. Files compose with JSON-Merge-Patch semantics; env sets a path (lists and maps are replaced, never merged); flags apply in argument order — a generic --<path> SETS, while a named repeatable alias (--mcp, --a2a-peer) ADDS to its list.

Re-exports

pub use crate::engine::model::is_long_lived_start;

Modules

schema

The JSON Schema (Draft 2020-12) of the settings document — hand-written (no schemars, the moat) and held faithful to super::Settings by the tests in super::tests, which walk both shapes object by object. 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, so a section added here reaches all of them at once.

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 named flag → document-path alias.

Audit

Auth

A unified per-endpoint authentication provider. A flat, kind-discriminated record: only the fields relevant to the chosen kind are set, and semantic validation is what enforces which of them are required — the type itself cannot, because every field is optional for some other kind.

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: ordered item lists for the top (header) and bottom (status bar) edges. None ⇒ the built-in default. Clients skip an item they do not recognise instead of erroring, so a newer daemon can name items an older client has never heard of. The vocabulary is 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. agentd’s default posture is no local execution, so this stays off unless an operator both builds with --features exec AND sets enabled: true — two independent switches, so neither a config mistake nor a stock binary can turn it on alone. Even then it runs only allow-listed commands, in a confined directory, with a minimal env. Without the local runner the exec tool is mapping-only: it can be delegated off-box via tools.overrides. It carries the sensitive + egress trifecta tags, so enabling it narrows what else the agent may compose with.

FoundRef

One {{…}} reference found by scan_references.

Goal

The self-correcting goal watchdog. A supervisor-level periodic check of whether the configured statement is achieved (or the agent is stuck), with a configurable disposition. It runs beside the agent loop and never blocks it, so a slow judge cannot stall real work.

GoalCheck

HeaderMatch

Hmac

HttpOp

Identity

InstanceLimits

Intelligence

Interface

The display-client interface: 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

ModelTier

One named model tier.

Observability

Otel

Pairing

Pairing-code login. 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).

ParamSpec

One declared template parameter — the only hole a spawn may fill.

Plan

Policy

One rule: what it matches, and what happens.

PolicyMatch

Pricing

Principal

PrincipalMatch

Quotas

Reserve

Retention

What to keep once a run is over.

RunLimits

RunRetention

RuntimeEvents

Which of the daemon’s own events reach a stream, and at what rate.

Search

Secret

A credential-bearing string. From a FILE it must be a {{secret:…}} / {{secret-file:…}} reference — validation over the file document enforces that, so a config document never carries a live credential — while an env/flag value may be inline. Debug never shows the contents.

Security

Service

A service catalog entry: a named external service this deployment may use — connection settings, one shared credential, authoritative trifecta tags (a floor for any matching endpoint, not just referencing ones), and a tool-surface ceiling consumers can only narrow. The catalog itself dials nothing; mcp.servers entries reference it.

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. 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

StreamCfg

One declared event stream.

StreamRetention

Retention: whichever bound trims first. Neither set = the 10k default — an unbounded stream on a disk the pressure system guards would be a self-inflicted shed.

SubagentDefaults

SubagentLimits

SubagentTemplate

Subagents

The subagents: section: what the model may spawn, and how.

Summarize

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: a dedicated listener serving the webhook start nodes and wait: {on: webhook} callbacks. Auth is per node — each webhook declares its own verification — so one permissive route cannot weaken the others; the listener-wide default set here applies only to nodes that declare no auth of their own.

WorkflowLimits

Ceilings a workflow definition is checked against at load time.

WorkflowSecurity

Whether the agent may rewrite its own workflows.

Enums

AliasKind

How a named flag maps onto the document.

Approval

How much a person wants to be asked.

Ask

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

AskHumanFallback

The ask_human fallback disposition.

AuditSink

AuthKind

The authentication provider family.

AutoContextOn

BudgetScope

BudgetTactic

Detected

Discover

DurabilityLevel

Egress

Whether outbound dials are confined to the service catalog.

GoalAction

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

OAuthGrant

The OAuth 2.1 grant type.

OnWorkflowFinished

PolicyAction

PolicyCaller

Preflight

ReserveEstimate

Role

RunUntil

SelectKeyword

ServiceKind

Which outbound surface a catalog entry describes. Matching is KIND-FILTERED: an MCP dial only matches mcp entries, an http step only http entries, and so on, because one host may legitimately serve several kinds under different trust budgets.

StoreKind

StoreOnError

StructuredOutput

ToolSelect

all | none | an explicit list.

WakeEvent

WindowUnit

WorkDurability

Constants

ALIASES

The alias table. The order of entries is irrelevant — flags take effect in the order they appear on the command line, not the order they are listed here.

DEFAULT_MESSAGE_DEPTH

The default ceiling on chained message deliveries. Deep enough for real delegation — a schedule waking the agent, which runs a workflow, which asks a question back — and shallow enough that a runaway is caught in seconds.

DEFAULT_TAP_QUEUE

The default bound on the runtime-event queue.

DISPLAY_ITEMS

The display items a client knows how to render.

ENV_ALIASES

Short env names → document paths. The derived AGENTD_<PATH> names are the primary surface; these are the shorter spellings a quickstart or a k8s manifest can use instead. Branded (AGENTD_) and neutral (AGENT_) prefixes both apply, as does the bare name.

REMOVED_FLAGS

Flags agentd does not accept, each paired with the hint that replaces it. Naming one fails the load with its hint, so a stale command line is a loud error rather than a flag that is silently ignored.

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

Top-level keys only the settings document has. limits is deliberately absent: it exists in both schemas, so it decides nothing. intelligence is absent for a different reason — it is a STRING (the endpoint list) in the flat schema but an OBJECT here, so detect judges it by shape.

Functions

detect

Decide which schema a merged document speaks.

egress_allows

The dial-time egress check. Open always passes; Closed requires the URL to match a catalog entry of the surface’s kind, so an uncatalogued host cannot be reached even if some other config path names it.

file_store_root

The file store’s root directory, 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).

hmac_algos

Every hmac.algo in a document, with where it sits.

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.

missing_references

The references in value that would NOT resolve right now — secrets against the environment (and any interactively-entered values), secret-files against the filesystem, config.* against vars. One message per missing reference, deduplicated, every location listed.

probe

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

resolve_services

Resolve service: references against the catalog and apply the unconditional tag floor. Mutates mcp.servers in place — after this, every server carries its effective endpoint, auth, headers, admission lists and tag set, so validation, the trifecta gate and the runtime all judge the outcome rather than each re-deriving it. Must therefore run BEFORE validation. Returns the resolution errors, for aggregation with validation’s.

restart_only_diff

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

scan_references

Collect every {{secret:…}}, {{secret-file:…}} and {{config.…}} reference in value, with where each sits.

service_match

Match a URL against the catalog’s entries OF ONE KIND: scheme and authority must be equal (host case-insensitively), and the URL’s path must extend the entry’s path on a segment boundary — so /v1 never matches /v1betaX. Returns the matching entry and refuses nothing; the caller decides what a non-match means (Egress::Closed refuses it).

substitute_config_vars

Substitute {{config.NAME}} tokens in value from vars, appending every unresolved reference to errs (with at naming where it sat).

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).