docs: sync agent-api-openapi.yaml from warp-server - #613

Summary

Regenerates developers/agent-api-openapi.yaml (the file Scalar renders at docs.warp.dev/api) from the canonical spec in warp-server/public_api/openapi.yaml, and fixes a filter gap in the sync script that let a private component leak into the published copy.

Found by the missing_docs drift-watch audit, which flagged two new /factory routes in warp-server; triaging them surfaced the accumulated spec drift below.

Source commit: warp-server@8b41081c4 (develop).

Changes

developers/agent-api-openapi.yaml (regenerated)

Schemas added:

• ChargedUsageDetail, InferenceCostBreakdownUsd, InferenceUsageDetail, TokenCountBreakdown — the per-category token and dollar-cost breakdown now returned with run usage.

Schemas modified:

• AgentResponse, AmbientAgentConfig, FileArtifactData, FileArtifactResponseData, Harness, RequestUsage, RunExecutionLocation.
• Notable content changes: RequestUsage gains total_tokens, inference_cost_breakdown_usd, and usage_by_category; cost fields now describe conversion at the owning team's current credit price rather than a fixed rate; AmbientAgentConfig gains computer_use_model_id; AgentResponse.available is redescribed as "whether the agent is currently enabled."

Top-level info updated: title Oz Agent API → Warp Agent API, plus several Oz → Warp wording changes in descriptions. These all come from upstream.

Removed:

• components.responses.FactoryAccessDenied — see below.

.agents/skills/sync-openapi-spec/scripts/sync_openapi.py

The script pruned components.schemas down to entries reachable from the surviving paths, but copied every other component section verbatim. FactoryAccessDenied — a shared response referenced only by the private /factory/* operations that this policy excludes — therefore shipped in the published spec as an orphan definition naming a private surface.

• Added PRUNABLE_COMPONENT_SECTIONS, mirroring unusedComponents in warp-server/public_api/public-openapi-filter.yaml (schemas, parameters, examples, headers, requestBodies, responses, mediaTypes). Sections outside the set (securitySchemes) are still copied verbatim, since nothing $refs them.
• Generalized $ref walking from schema names to (section, name) pairs so reachability follows cross-section edges (a shared response pulls in the schemas it references). _transitive_schemas became _reachable_components.
• --mode diff now reports added/removed/modified entries for every pruned section, not just schemas. A stale components.responses entry in the target previously reported as "in sync."
• Extended the self-test to cover both directions: a shared response referenced by a surviving operation is kept (along with the schema only it references), and one referenced solely by a dropped path is pruned.

.agents/skills/sync-openapi-spec/references/sync-policy.md

Documents the new pruning rule and the leak it closes.

Validation

• --mode self-test → OK
• --mode diff after apply → In sync. No changes needed.
• npm run build → exit 0 (only the repo's pre-existing chunk-size and /404 route warnings)
• Leak check on the regenerated file: no /factory, /memory*, or /harness-support paths, and no x-* implementation extensions

Reviewers

scripts/suggest_reviewers.py resolved no owner for warp-server:public_api/openapi.yaml, router/handlers/public_api/factories.go, or router/handlers/public_api/factory_automations.go — neither .github/CODEOWNERS nor .github/STAKEHOLDERS has a rule covering public_api/ or router/handlers/public_api/. Recent history on those files is almost entirely automation commits, so no reviewer was auto-assigned; please route manually.

Worth considering separately: adding a /public_api/ and /router/handlers/public_api/ rule to warp-server's .github/STAKEHOLDERS so future spec syncs route themselves.

Unverified claims

None — this PR adds no prose. Every schema and description is copied verbatim from the canonical warp-server spec.

Co-Authored-By: Oz oz-agent@warp.dev
Co-Authored-By: Warp agent@warp.dev

Deferred findings

This PR resolves every API-category finding from the 2026-08-24 missing_docs drift-watch run. The run's remaining 23 findings are all low-severity terminology matches deferred to style_lint, and they are listed with per-term rationale in the companion bookkeeping PR #614 under "Deferred findings". Nothing from the run was dropped without a recorded decision.