docs(billing): clarify agent hours per harness on the platform credits page

[hongyi-chen]

Summary

Follow-up to #672, targeting its branch. Incorporates the Slack review of the agent-hours definition: keep it high level, but make it accurate across harnesses.

Two things in the current wording needed adjusting:

• The Warp Agent and third-party harnesses meter differently. With the Warp Agent, the clock only runs while the agent is generating a response; time spent waiting on a command or tool it ran (a five-minute cargo check, a test suite) isn't billed. With Claude Code and Codex, the whole run is billed, including command execution and time waiting on the model provider. The page now says this in two bullets, without naming internals.
• "Or pauses for your input" was carrying too much weight. It's true for the Warp Agent, but cloud runs on third-party harnesses auto-approve, so they aren't usually waiting on anyone. Dropped it from the stop conditions; idle time waiting for a follow-up stays excluded, which holds for every harness.

Also, per the thread on agent hours being the unit Warp Factories are sold on: the section now leads with agent hours as the meter for platform usage, notes that Enterprise contracts set the rate, and says billing views show credits rather than hours (users don't see hours in-product today).

Changes

Mostly src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx. A second pass (below) makes small consistency and register fixes on credits.mdx, pricing-faqs.mdx, and enterprise/support-and-resources/billing.mdx; the sibling pages keep their one-line definition and link here for the full breakdown.

How platform credits are measured now reads:

An agent hour is one hour an agent spends working on a task. Warp meters platform usage in agent hours and bills that usage as platform credits. Partial hours are billed proportionally, not rounded up: a 15-minute run is a quarter of an agent hour. See Warp pricing for current rates. Enterprise rates are set by contract.

A run accrues agent hours from the time the agent starts in its environment, including environment setup, until the run finishes, fails, or is cancelled. Time spent queued before the agent starts isn't billed, and neither is idle time between turns while the run waits for your next message.

Within that period, what's billable depends on the harness:

• Warp Agent - Time the agent spends generating a response. Execution time for commands and tools the agent runs in its environment, such as a five-minute test suite, isn't billable.
• Claude Code and Codex - The entire run, including command execution and time spent waiting on the model provider.

Plus "Usage is shown in credits, not agent hours" in Where platform credits appear.

Second pass over #672

• One phrase for one fact. "billed by the agent hour" now appears everywhere; it replaces "calculated from agent hours" (credits.mdx, pricing-faqs.mdx, the platform credits meta description) and "metered in agent hours" (platform credits intro). The other five mentions already used it.
• Enterprise billing (billing.mdx): the cloud-agent sentence no longer carries the agent-hour definition as a mid-sentence parenthetical; it's its own sentence and notes the rate is set by contract. Also removed the page's last "Warp's platform infrastructure" (line 46), which the revops-factory review flagged.
• Third-party CLI exclusion (platform-credits.mdx): "outside Warp" read as if claude in a Warp terminal pane might be billed. It isn't: a CLI you run yourself never creates a billable run (CliAgentUserQuery in generate_multi_agent_output.go is a Warp Agent input, not the CLI harness being metered). Now reads "yourself, whether in a Warp terminal pane or elsewhere."
• Credits (credits.mdx): "when the conversation is framed around cloud agents versus local agents" → "since only cloud agent runs consume them. Both names refer to the same bucket." Also fixed a pre-existing non-parallel list ("experimenting with different prompts, models, and tracking").

Not changed, worth a follow-up outside this PR: "for Warp's platform infrastructure" still appears on six pages that #672 didn't touch (bring-your-own-api-key.mdx, custom-inference-endpoint.mdx ×2, bring-your-own-llm.mdx, byollm-gemini-enterprise.mdx, team-managed-keys-and-endpoints.mdx), each with a slightly different gloss of what the platform layer includes. A one-line sweep would align them with "platform layer."

Verification against warp-server

• Per-stream segments for the Warp Agent: router/handlers/generate_multi_agent_output.go calls OpenSegmentForStream before the agent loop starts and CloseSegmentForStream when the stream ends. Each stream handles one input (a user query or a single tool-call result); the client executes the tool between streams, so no segment is open while a command runs.
• Whole-run segments for Claude Code and Codex: nothing touches in_progress_since between the driver's IN_PROGRESS report and the terminal transition, so maybeChargeForPlatformUsage in logic/ai/ambient_agents/task_lifecycle.go bills the entire window.
• Environment setup is inside the window for both: the sandbox driver (warp/app/src/ai/agent_sdk/driver.rs) reports IN_PROGRESS before environment setup, and the first Warp Agent stream's EnsureInProgressSegmentStarted is a no-op on an already-open segment.
• Idle between turns is unbilled for both: turn completion is a terminal transition that closes the segment; a follow-up re-enters IN_PROGRESS and opens a new one.
• Enterprise rate is per contract: every enterprise tier YAML under billing/config/tiers/ carries platform_credits_per_minute_override, read via GetPlatformCreditsPerMinuteOverrideFromBillingMetadata in billing/platform.go.
• Exact time, not rounded: ChargeForPlatformUsage multiplies fractional duration.Minutes() by the per-minute rate.

Validation

• style_lint --changed: no findings on any edited line (remaining findings are the same pre-existing ones listed on docs(billing): define agent hours for platform credits and refresh stale language #672).
• check_for_broken_links --internal-only: 0 broken internal links.
• npm run build: passes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 4, 2026 11:20pm UTC

[hongyi-chen]

This PR was generated with Warp.

Comment @warp-agent on this PR to send it follow-up work.

 

[warp-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR updates the platform credits billing page to clarify that platform usage is metered in agent hours and that metering differs between the Warp Agent and third-party harnesses.

Concerns

• The Warp Agent harness bullet conflicts with the preceding setup-window wording by omitting environment setup from the counted time, even though the PR description says setup is billed.

Verdict

Found: 0 critical, 1 important, 0 suggestions

Request changes

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

⚠️ [IMPORTANT] This bullet says the Warp Agent clock runs while generating, but line 20 says environment setup also counts; include setup here so the harness-specific wording does not understate billable time.

Suggested change

	* **Warp Agent** - The clock runs while the agent is generating a response and pauses while a command or tool the agent ran is executing, so a five-minute test suite doesn't add to the run's agent hours.
	* **Warp Agent** - The clock counts environment setup and time spent generating a response, and pauses while a command or tool the agent ran is executing, so a five-minute test suite doesn't add to the run's agent hours.