Crate agent_first_data 

Agent-First Data (AFDATA) output formatting and protocol templates.

Public APIs, grouped by concern (see each item’s own docs for details; the full symbol list is the crate root’s own rustdoc index, not repeated here — it drifts out of sync with a hand-maintained count otherwise):

• Protocol v1 builders: json_result, json_error, json_progress, json_log (each returns a builder; call .build())
• Protocol reader: decode_protocol_event parses and strict-validates one protocol line into a typed DecodedEvent
• Redaction: redacted_value / Redactor::value (JSON values), redact_url_secrets / Redactor::url (URL strings), redact_argv / Redactor::argv (command lines) — Redactor carries custom secret_names/policy
• Output rendering: render — the single value × format × options → String entry point for JSON, YAML, and plain (logfmt) output
• Parse utilities: normalize_utc_offset, is_valid_rfc3339_date, is_valid_rfc3339_time, is_valid_rfc3339, is_valid_bcp47
• Closed-world CLI compiler: CliSpec, CommandSpec, ArgSpec, Combination, and OutputSpec generate parsing, typed ResolvedInvocation values, output plans, and help-v2 from one registry.
• Established CLI utilities: cli_parse_output, cli_parse_log_filters (returns LogFilters), and CliEmitter.
• (feature skill): skill::validate_skill / skill::validate_skill_named — strict Agent Skills SKILL.md front-matter validation
• (feature skill-admin): skill::run_skill_admin — install/uninstall/status a spore’s embedded Agent Skill across Codex, Claude Code, opencode, and Hermes; returns a typed skill::SkillReport
• (feature tracing): afdata_tracing::try_init initializes an AFDATA stdout logging layer with configurable format and redaction; also afdata_tracing::LogFormat

The shared cross-language contract (which of these exist, under what name, in each of Rust/Python/TypeScript/Go) is tracked in spec/api-surface.json and cross-checked by scripts/validate_api_surface.py.

Modules

afdata_tracing

AFDATA-compliant tracing layer.

document

Format-independent document values (dot-path access, typed coercion, and pluggable JSON/TOML/YAML/dotenv/INI backends). Format-independent document values: dot-path get/set/add/remove, type-directed CLI-string coercion, keyed-list (slug-addressed array) helpers, and typed serde adapters, backed by pluggable JSON/TOML/YAML/dotenv/INI format readers and writers.

skill

Agent Skills SKILL.md front-matter validation.

stream_redirect

Optional process stdout/stderr file redirection.

Structs

ArgSpec

One command-local application argument.

BoundCliSpec

A built registry with exactly one handler per action.

BuiltCliSpec

Validated registry used for resolution and help generation.

CliEmitter

Stateful emitter for structured CLI executions.

CliError

Structured CLI-resolution error. It never contains raw argument values.

CliHelpV2

Agent-first help-v2 payload.

CliShape

One legal shape of a call.

CliSpec

Serializable version-one closed-world CLI registry.

CliSpecError

Stable build-time registry error.

Combination

One named legal application invocation shape.

CommandSpec

One exact command path in a CLI registry.

DecodedError

Decoded kind:"error" event.

DecodedLog

Decoded kind:"log" event.

DecodedProgress

Decoded kind:"progress" event.

DecodedResult

Decoded kind:"result" event.

ErrorBuilder

Builder for error events.

Event

A typed, strict-valid AFDATA protocol v1 event.

LogBuilder

Builder for log events.

LogFilters

Parsed and normalized log filters (trimmed, lowercased, deduplicated).

OutputOptions

Output options combining redaction and rendering style.

ProgressBuilder

Builder for progress events.

ProtocolViolation

A single protocol-validation violation: a stable machine-readable rule slug, a JSON pointer to the offending location ("" = the whole event), and a human-readable message.

Redactor

Configurable redaction builder for secrets and legacy field names.

ResolvedDocs

The registry asked to describe itself in full.

ResolvedHelp

Resolved help response plus its lifecycle output plan.

ResolvedInvocation

One legal invocation, projected onto the shape that matched it.

ResolvedVersion

Resolved version response plus its lifecycle output plan.

ResultBuilder

Builder for result events.

SyntheticInvocation

Type-correct argv generated from a registered shape.

Enums

ArgSyntax

An argument’s exact command-local spelling.

ArgValueType

Closed portable value type used by CLI specs and resolved invocations.

BuildError

Error type for builder failures.

CliEmitterError

Error returned by CliEmitter.

CliErrorRule

Stable closed set of invocation-error rules.

CliOutcome

What an argv resolved to.

CliValue

A typed value produced by a built CLI registry.

DecodedEvent

A decoded, strict-valid AFDATA protocol v1 event, typed by kind.

EventDecodeError

Error returned by decode_protocol_event.

FixedValue

A finite fixed enum constraint.

LogLevel

Log level enumeration (serialized as lowercase).

OutputFormat

Output format for CLI and pipe/MCP modes.

OutputLifecycle

Protocol output lifecycle.

OutputPlan

Where a resolved call’s output goes, and in what form.

OutputSpec

Closed output contract for one combination.

OutputTo

Where a CliEmitter sends its events, selected by --output-to.

PlainStyle

Rendering style for plain (logfmt) output only. JSON and YAML are always structure-preserving and ignore this.

RedactionPolicy

Which fields a Redactor scrubs. The default is RedactionPolicy::All.

Functions

build_afdata_cli

Build a registry under AFDATA’s naming conventions.

build_cli_error

Build a CLI error event with optional hint.

build_cli_version

Build a standard CLI version event: a kind:"result" event whose payload is { "code": "version", "name": <name>, "version": <version> }, plus "display_name"/"build" when given. name is the short/bin identity (e.g. "afdata"); display_name is an optional human-facing product name (e.g. "Agent-First Data"); build is an opaque caller-supplied identifier (a git commit SHA, for example) — its meaning is entirely up to the caller. Both are None when unavailable, and simply absent from the payload.

cli_error_event

Wrap a CLI-resolution failure in an event whose code names the failure.

cli_help_event

Wrap a resolved help response in a cli-help-v2 result event.

cli_parse_log_filters

Normalize --log flag entries: trim, lowercase, deduplicate, remove empty.

cli_parse_output

Parse --output flag value into OutputFormat.

cli_render_version

Render a CLI version response as a protocol-v1 event in format.

cli_version_event

Wrap a resolved version response in a protocol result event.

decode_protocol_event

Parse one protocol v1 line, strict-validate it, and return a typed decoded event.

is_valid_bcp47

Return true when s is a structurally well-formed BCP 47 (RFC 5646) language tag.

is_valid_rfc3339

Return true when s is a complete RFC 3339 date-time, such as 2026-02-14T10:30:00Z or 2026-02-14T10:30:00.5+08:00.

is_valid_rfc3339_date

Return true when s is an RFC 3339 full-date (YYYY-MM-DD).

is_valid_rfc3339_time

Return true when s is an RFC 3339 partial-time (HH:MM:SS[.fraction]).

json_error

Fluent builder: start building an error event.

json_log

Fluent builder: start building a log event.

json_progress

Fluent builder: start building a progress event.

json_result

Fluent builder: start building a result event.

normalize_utc_offset

Normalize a fixed UTC offset string to AFDATA canonical form.

redact_argv

Redact secret values out of a command line, using default options.

redact_url_secrets

Redact secret components of a single URL string, using default options.

redacted_value

Return a JSON value copy with default _secret redaction applied.

render

Render a value as a string in the given format with the given options.

render_cli_reference

Render an offline Markdown reference for a whole registry.

validate_protocol_event

Validate one protocol v1 event envelope.

validate_protocol_stream

Validate a finite structured CLI event stream: (log | progress)* -> exactly one (result | error) -> end.