Crate agent_first_data

Expand description

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) — Redactor carries custom secret_names/policy
Output formatters: output_json, output_yaml, output_plain and their _with_options variants
Parse utilities: parse_size, normalize_utc_offset, is_valid_rfc3339_date, is_valid_rfc3339_time
CLI helpers: cli_parse_output, cli_parse_log_filters (returns LogFilters), cli_output, cli_output_with_options, build_cli_error, build_cli_version, cli_render_version, cli_handle_version_or_continue
(feature cli-help): configurable clap help rendering via [cli_render_help_with_options] and [cli_handle_help_or_continue]
(feature cli-help-markdown): [cli_render_help_markdown] — recursive Markdown help
(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.

Structs§

CliEmitter: Stateful emitter for finite structured CLI executions.
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.
Redactor: Configurable redaction builder for secrets and legacy field names.
ResultBuilder: Builder for result events.
VersionConfig: Configuration for pre-parser --version handling.

Enums§

BuildError: Error type for builder failures.
CliEmitterError: Error returned by CliEmitter.
CliProtocolMode: Protocol envelope behavior for early CLI exits such as --version.
DecodedEvent: A decoded, strict-valid AFDATA protocol v1 event, typed by kind.
EventDecodeError: Error returned by decode_protocol_event.
LogLevel: Log level enumeration (serialized as lowercase).
OutputFormat: Output format for CLI and pipe/MCP modes.
OutputStyle: Rendering style for YAML and plain output.
RedactionPolicy: Redaction policy. Convert with .into() to Redactor or OutputOptions.

Functions§

build_cli_error: Build a CLI error event with optional hint.
build_cli_version: Build a standard CLI version event.
cli_handle_version_or_continue: Render version output from raw argv if --version or -V is present.
cli_output: Dispatch output formatting by OutputFormat.
cli_output_with_options: Dispatch output formatting by OutputFormat with configurable output options.
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.
decode_protocol_event: Parse one protocol v1 line, strict-validate it, and return a typed decoded event.
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.
output_json
output_json_with_options: Format as single-line JSON with configurable output options.
output_plain: Format as single-line logfmt. Keys stripped, values formatted, secrets redacted.
output_plain_with_options: Format as single-line logfmt with configurable output options.
output_yaml: Format as multi-line YAML. Keys stripped, values formatted, secrets redacted.
output_yaml_with_options: Format as multi-line YAML with configurable output options.
parse_size
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.
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.