Document model pricing, the agent's per-session spend caps, and final cancels

[DavidCockerill]

⊙ Problem

agent: carry per-call token usage onto the session and enforce a budget (HarperFast/harper#3040) makes the agent's maxCostUsd real, adds agent.maxSessionTokens, records per-session usage, lets a models.generative entry declare its pricing, makes a cancel final, and validates maxTurns. The reference still calls maxCostUsd "not enforced" with a 5.00 default, and documents none of the rest.

Refs HarperFast/harper#3040. Companion to Cap the agent's spend per session by tokens or priced cost, record its model usage, and make a cancel final (HarperFast/harper#3177).

❓ Your call: requirement. These are user-facing config keys, an operations response field, status and 409 behavior that pollers key on, and a change to what cancel_agent_run does, so the docs are needed whenever the core PR merges. Dated v5.4.0 to match the core milestone.

💡 Solution

• Model pricing. A new Pricing subsection under models Configuration, the pricing shared-field row, costUsd on GenerateResult, streamed calls being unpriced, and maxCostUsd among the toolMode: 'auto' options, with the reserved-options note no longer listing it.
• Agent spend caps. The maxTurns, maxSessionTokens and maxCostUsd bullets, the set_agent_config key list, and a new Agent spend caps subsection: what a cap counts, when it is checked, how a stop leaves the transcript, what an unmeasurable cap does, and how to leave a stuck session.
• Operations. error now covering cap stops and a capped final answer ending completed; agent_prompt's 409s while a cancelled run finishes or when a cancel races the prompt; usage on get_agent_session and list_agent_sessions; cancel_agent_run answering pending approvals; and set_agent_config validating the caps and maxTurns.
• Release notes. A 5.4 section for pricing and the spend caps, with the upgrade note for an existing agent.maxCostUsd, and for agent cancellation and limits.

❓ Your call: naming. This documents agent.maxSessionTokens; Document agent.maxTokens, and that a cut-off or empty agent reply ends the run error (#712) documents agent.maxTokens as the per-reply output limit from End agent runs cut off by the output-token limit as errors, and add agent.maxTokens (HarperFast/harper#3064). Both keys can coexist; whichever PR lands second rebases the set_agent_config key list.

The api.md and tool-calling.md hunks also re-align their tables, which Prettier does when a wider row is added.

✅ Verification

Every statement was checked against the core branch by review rounds (Codex graded leg, Gemini, Harper domain adjudication); the last round left only nits. npm run format:check passes. The core behavior these pages describe is exercised by the core PR's integrationTests/server/agent-budget.test.ts and its agent unit suites.

_{🤖 Generated by Claude Code (Anthropic Claude Opus 5.5); posted via @DavidCockerill.}

Related PRs: #568 independent, #671 independent, #676 independent, #683 independent, #691 independent, #709 independent, #712 overlaps (documents agent.maxTokens, the per-reply limit, beside agent.maxSessionTokens; the set_agent_config key list and the 5.4 agent notes conflict), #714 independent, #717 overlaps (agent.configScope in the same agent options and set_agent_config text, and the 5.4 agent notes), #720 overlaps (agent.maxToolResultBytes in the same agent options and set_agent_config text, and the 5.4 agent notes), #722 independent, #724 independent, #725 independent, #715 independent, #713 independent, #697 independent, #710 independent, #707 independent
Complexity: medium

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; blocked=cursor-composer(not-installed); declined=cursor-grok,cursor-kimi,cursor-muse; rounds=8; full=2 @ 5c38284}

_{Review-Attention: skim ~2m (decisions: auto-loop-unpriced-fails-open, failed-calls-uncounted, legacy-sessions-unmeasured, maxcostusd-default-removed, auto-costusd-final-round, cancel-refuses-approved-actions, cancel-finishing-409, maxturns-null-split) @ 5c38284}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

[gemini-code-assist]

Code Review

This pull request updates the documentation for version 5.4.0, introducing model pricing, per-call cost tracking, and spend caps (maxSessionTokens and maxCostUsd) for the built-in agent. It also details updates to the operations API regarding session status, usage reporting, and cancellation behavior. The review feedback suggests using a VersionBadge to highlight the new costUsd field in the API documentation, and recommends splitting combined sentences in the tool-calling and operations guides to make fallback behaviors more distinct and readable.

[gemini-code-assist]

When documenting behavior changes to an existing API surface (such as adding the new costUsd field to the GenerateResult response), we should use the <VersionBadge type="changed" version="v5.4.0" /> component to clearly highlight the change.

Suggested change

	| `costUsd` | `number` | From v5.4.0, the call's cost from the serving entry's [pricing](./overview#pricing); absent when that entry is unpriced or usage is incomplete. With `toolMode: 'auto'`, the final round's only, like `usage` |
	| `costUsd` | `number` | <VersionBadge type="changed" version="v5.4.0" /> The call's cost from the serving entry's [pricing](./overview#pricing); absent when that entry is unpriced or usage is incomplete. With `toolMode: 'auto'`, the final round's only, like `usage` |

References

1. When documenting behavior changes to an existing API surface (e.g., adding new fields to a response), use .

[gemini-code-assist]

The fallback behavior for unpriced rounds is combined with another concept and buried behind a semicolon. To ensure operators can easily find and understand this fallback behavior, please present it in separate, distinct sentences.

Suggested change

| `maxCostUsd` | `number` | — | From v5.4.0, cumulative USD cap across rounds, from the [pricing](./overview#pricing) of the entry that served each round. If a round is unpriced, Harper warns once and `maxToolIterations` remains the bound; a cap of `0` still stops after the first round. This is the opposite of the built-in agent's `maxCostUsd`, which stops rather than run unpriced. Not supported on `generateStream()` (throws) |

| `maxCostUsd` | `number` | — | From v5.4.0, cumulative USD cap across rounds, from the [pricing](./overview#pricing) of the entry that served each round. If a round is unpriced, Harper warns once and `maxToolIterations` remains the bound. A cap of `0` still stops after the first round. This is the opposite of the built-in agent's `maxCostUsd`, which stops rather than run unpriced. Not supported on `generateStream()` (throws) |

References

1. Ensure critical security warnings, such as unauthorized access risks or fallback behaviors, are presented in separate, distinct sentences rather than being combined with other concepts or buried behind semicolons, so that readers scanning the documentation can easily find them.

[gemini-code-assist]

The fallback behavior for a run caught mid-step during cancellation is combined with other concepts and buried behind a colon and semicolons. Please present this critical fallback behavior in separate, distinct sentences so that readers scanning the documentation can easily find it.

Suggested change

From v5.4.0 the cancel also answers every pending approval, decided or not, with a `cancelled_by_operator` result, in the same write that marks the session `aborted`. An approved action that has not started by then never runs, neither in the cancelled run nor when you next prompt the session, and nothing is left awaiting a decision. One already running finishes, and its result is recorded. A cancel between a turn's tool calls answers the rest of that turn `cancelled_by_operator`. The session stays `aborted`: a run caught mid-step finishes that step without marking the session `completed`, `error` or `awaiting_approval`, a tool call it then asks to have approved is answered `cancelled_by_operator` instead, and it makes no further model call.

From v5.4.0 the cancel also answers every pending approval, decided or not, with a `cancelled_by_operator` result, in the same write that marks the session `aborted`. An approved action that has not started by then never runs, neither in the cancelled run nor when you next prompt the session, and nothing is left awaiting a decision. One already running finishes, and its result is recorded. A cancel between a turn's tool calls answers the rest of that turn `cancelled_by_operator`. The session stays `aborted`. A run caught mid-step finishes that step without marking the session `completed`, `error`, or `awaiting_approval`. A tool call it then asks to have approved is answered `cancelled_by_operator` instead, and it makes no further model call.

References

1. Ensure critical security warnings, such as unauthorized access risks or fallback behaviors, are presented in separate, distinct sentences rather than being combined with other concepts or buried behind semicolons, so that readers scanning the documentation can easily find them.