Module agent_api 

Agent JSON API emitter (issue #586, port 3 of 5).

Port of the site’s Python-pipeline AgentApiPlugin (~382 LOC): a stable, machine-readable JSON API for AI crawlers and agent toolchains. Complements crate::ai::AiPlugin (llms.txt / llms-full.txt) and the agentic-discovery emitters (agents.txt + ai-plugin.json + mcp.json, issue #552) with a queryable content surface rather than a prose one.

Files emitted (under <site>/api/agents/)

File	Shape
index.json	API descriptor: site identity, entry counts, absolute links to the other three documents
posts.json	Array of {title, url, date, description, tags, locale, wordCount} — one entry per public content page
topics.json	Object mapping each tag / topic-cluster term to the sorted member post URLs
person.json	JSON-LD (schema.org) Person entity for the site author

Data sources

Frontmatter is read from the .meta.json sidecars the compiler emits under <build>/.meta/ (the same convention consumed by crate::taxonomy::TaxonomyPlugin and the MCP auto_resources walker). When the build-dir sidecars are absent (ad-hoc pipelines), *.meta.json files next to the HTML in site_dir are used as a fallback.

wordCount resolution order (per the tracker):

1. the sidecar’s word_count field (stamped by frontmatter::emit_sidecars),
2. a wordCount field lifted from a rendered BlogPosting/Article JSON-LD block in the page HTML,
3. a manual word count over ssg_core::strip_html_tags output.

Default-on and lifecycle

Registered unconditionally by pipeline::register_default_plugins — the same default-on, no ssg.toml knob convention crate::ai::AiPlugin follows (the repo’s other opt-in plugins gate by not being registered, e.g. crate::search_index::VectorSearchPlugin). Programmatic opt-out is available via AgentApiPlugin::disabled. Runs in after_compile and honours ctx.dry_run.

Determinism

Output must be byte-identical across rebuilds (determinism.yml hashes the site): posts are sorted by URL, tag lists are sorted + deduplicated, topics use a BTreeMap, and serde_json’s default BTreeMap-backed object keeps key order canonical. No timestamps are embedded.

Structs

AgentApiPlugin

Plugin that emits /api/agents/{index,posts,topics,person}.json.

PostEntry

One public content page, normalised from its .meta.json sidecar.

Functions

collect_posts

Collects public posts from .meta.json sidecars.

jsonld_word_count

Lifts wordCount from any <script type="application/ld+json"> block in the page (BlogPosting / Article emit it in the Python original this port mirrors).

parse_author

Parses email (Name) and Name <email> author conventions.