Document the built-in agent operations API

[kriszyp]

Documents the built-in Harper agent's Operations API — agent_prompt, get_agent_session, list_agent_sessions, approve_agent_action, cancel_agent_run, and set_agent_config — as a new Agent section in the Operations reference, with the session lifecycle, the approval flow, and the MCP exposure. Adds the agent configuration block to the configuration reference, since the operations do not exist until agent.enabled is set, and a row to the Operations API topic index.

Nothing about the built-in agent was documented before this: neither the operations nor the configuration that turns them on.

For the human reviewer

One open question I could not settle, and did not guess at. Does system.hdb_agent_session replicate to peer nodes? Transcripts durably record prompts and the full output of every tool call, so whether they converge cluster-wide is a data-residency fact, not a detail — and the page currently says nothing either way. If someone can confirm the answer I will add a sentence; I deliberately left it out rather than assert it.

The security section is the part to read hardest. Reviewing this against core turned up a boundary that is narrower than it looks, and the :::warning now says so: agent.user scopes only the operations tools, while the filesystem, http_fetch, followup, and inspector tools are composed unconditionally and run at process privilege. http_fetch blocks only the named cloud-metadata hosts and IPv4 169.254.0.0/16, checks the literal hostname passed, and follows redirects without re-checking. read_file reaches the log and configuration directories and is not gated. Delegating get_agent_session to a restricted role hands it the outputs of operations that ran at the agent's privilege. Each of those is verified against agent/toolset.ts, agent/tools/httpFetchTool.ts, and agent/operations.ts — please push back if any framing is stronger or weaker than the team wants in public docs.

Known rough edges are documented rather than omitted, which is a judgment call worth confirming: list_agent_sessions ordering is not chronological (it walks UUID primary keys in reverse); hitting maxTurns lands in completed with the reason in lastError; set_agent_config's enabled is not a kill switch; changing allowDestructive mid-session orphans scheduled followups so a later cancel_agent_run cannot clear them. If any of these are about to be fixed in core, the corresponding paragraph should come out instead.

provider and maxCostUsd are documented as inert. Both are accepted configuration today, provider never reaches the model call and nothing checks spend against maxCostUsd. The alternative is to omit them until they work; I documented them with the limitation stated, because an operator who sets them deserves to know they do nothing.

One core discrepancy found in passing, not fixed here: the MCP tool description for list_agent_sessions in agent/mcpTools.ts claims "most recent first", which the implementation does not do. The docs follow the code.

Not addressed: the agent shipped in v5.2.0 but release-notes/v5-lincoln/5.2.md has no Agent entry, unlike the other 5.2 features. Adding one retroactively to a released version is a call I did not want to make unilaterally — happy to include it if wanted.

Verification

Every documented parameter, response shape, status value, error code, default, and version claim was traced to harper agent/ on origin/main (v5.2.4) — operations.ts, agent.ts, session.ts, loop.ts, toolset.ts, mcpTools.ts, tools/, and config-root.schema.json. The v5.2.0 badge comes from the first tag containing aaf8b13b0 ("make the built-in agent runnable end-to-end"); the operations were registered as of the v5.1.0 tag but the agent was not runnable then. npm run build is clean — the two broken anchors it reports are pre-existing on main and unrelated — and the rendered page was inspected in build/ to confirm the admonition closes correctly and the new anchors resolve. npx prettier --check is clean.

Complexity: medium

_{Review-Coverage: authored=claude; ran=codex,gemini; declined=cursor-grok,cursor-composer,domain; rounds=5 @ 3094fa5}

_{Human-Review-Need: 4 @ 3094fa5}

[gemini-code-assist]

Code Review

This pull request introduces documentation for the new built-in Harper agent, including its configuration options in options.md and its Operations API endpoints in operations.md. The review feedback suggests formatting improvements to use em dashes (—) instead of hyphens for configuration descriptions to maintain consistency. Additionally, it recommends updating several documented API response fields (such as pendingApprovals and signalledLiveRun) from camelCase to standard snake_case to align with HarperDB's API standards.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-635

This preview will update automatically when you push new commits.