docs: expose precise setup-command operations in agent API OpenAPI (REMOTE-1063) - #376
Conversation
…-1063) Docs-repo spec for REMOTE-1063 (multi-repo: warp, warp-server, docs). Regenerate developers/agent-api-openapi.yaml via the sync-openapi-spec tooling so it mirrors the new precise setup-command operations the warp-server canonical public API commits, with zero-based index semantics, append-at-length insert, index-based duplicate addressing, and a REST-only public contract. Includes sync-policy and cross-repo alignment criteria. Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…up-commands surface (REMOTE-1063)
Rework the proposed endpoint shape to mirror warp-server's committed REST
contract: a multi-verb sub-resource under
/agent/environments/{uid}/setup-commands — GET (list), PUT (replace /
clear-and-rebuild), POST (add; append when index omitted, insert at
0..=len), PATCH /{index} (edit by index), DELETE /{index} (remove by
index), DELETE (clear all). Update error semantics to match the binding
contract (edit/remove out of range -> 404; bad index -> 400) and the
path parameter name to {uid}. Keep the sync-from-server approach
(developers/agent-api-openapi.yaml regenerated from
warp-server/public_api/openapi.yaml via the sync-openapi-spec tooling).
Co-Authored-By: Warp <agent@warp.dev>
…EMOTE-1063)
Mirror warp-server PR #13278's setup-commands sub-resource into the generated
docs OpenAPI (developers/agent-api-openapi.yaml) so the Scalar reference at
docs.warp.dev/api documents the new precise update operations.
Adds (verbatim from the canonical, scoped to the setup-commands surface only):
- GET /agent/environments/{uid}/setup-commands (list)
- PUT /agent/environments/{uid}/setup-commands (replace / clear-and-rebuild)
- POST /agent/environments/{uid}/setup-commands (add; append when index omitted, insert at 0..=len)
- DELETE /agent/environments/{uid}/setup-commands (clear all)
- PATCH /agent/environments/{uid}/setup-commands/{index} (edit one by index)
- DELETE /agent/environments/{uid}/setup-commands/{index} (remove one by index)
- Schemas: SetupCommandsResponse, ReplaceSetupCommandsRequest,
AddSetupCommandRequest, UpdateSetupCommandRequest
- Params: EnvironmentUID, SetupCommandIndex
Index semantics are zero-based, documented verbatim from the canonical: insert
at index == len appends; edit/remove out of range -> 404; bad (non-integer/
negative) index -> 400; duplicate command text allowed and addressed by index.
Scoped additive mirror: the docs file is behind the canonical on several
unrelated public endpoints (factory, memory, messages, events, ...). A full
sync_openapi.py --mode apply would pull all of those in and require triaging
unknown factory/memory tags, which is out of scope for this ticket. This change
adds only the setup-commands surface (390 insertions, 0 removals); the existing
GET /agent/environments operation and CloudEnvironmentConfig schema (with its
setup_commands array field) are unchanged.
Source: warp-server/public_api/openapi.yaml @ 276952ba
(PR #13278, branch factory/remote-1063-setup-command-updates, not yet merged).
Re-sync/confirm once that PR merges.
Co-Authored-By: Oz <oz-agent@warp.dev>
warp-dev-github-integration
Bot
changed the title
|
@warp-dev-github-integration[bot] 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 Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds the setup-commands sub-resource operations and related schemas/parameters to the docs OpenAPI, plus a docs-side spec for REMOTE-1063. The additive OpenAPI shape is mostly consistent with the described endpoint set and security model, and no approved repository spec context was available beyond the attached "No approved or repository spec context" marker.
Concerns
- The generated OpenAPI omits the duplicate-command semantics that the PR/spec says must be exposed: duplicate setup command text is allowed, and callers target a specific occurrence by index. This should be added in the canonical OpenAPI and re-synced so Scalar/API readers see the complete contract.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
![warp-dev-github-integration[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This additive docs PR mirrors the setup-command REST paths, operations, parameters, and schemas from warp-server, and the generated sections match the canonical source structurally. The current head still does not satisfy the committed docs spec's explicit duplicate-command/index contract requirement.
Concerns
developers/agent-api-openapi.yaml never documents that behavior (the existing inline finding at SetupCommandIndex remains unresolved). Update the canonical OpenAPI description first, then regenerate this mirror so Scalar/API readers receive the complete shared contract; do not hand-edit the generated docs file.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Prior concerns still outstanding: duplicate setup-command text must be explicitly documented as addressable by index.
Request changes
Review run
https://oz.staging.warp.dev/runs/019f95b6-7abe-7b6d-9a0c-761633d151ca
…rver c0b5d188 (REMOTE-1063) Address the review finding on PR #376: the generated docs OpenAPI mirror must explicitly document that duplicate setup-command text is allowed and addressed by zero-based index, and advertise the enforced size limits. The canonical source was updated first in warp-server public_api/openapi.yaml (commit c0b5d188 on branch factory/remote-1063-setup-command-updates), which added the duplicate-by-index notes to the list/replace/add/edit/remove operation descriptions and the SetupCommandsResponse/ReplaceSetupCommandsRequest/ AddSetupCommandRequest/UpdateSetupCommandRequest schema descriptions, plus maxItems:100 on the setup_commands arrays and minLength:1/maxLength:4096 on each command string. This re-syncs developers/agent-api-openapi.yaml to match that canonical source verbatim for the setup-command paths and schemas only (the SetupCommandIndex parameter description is unchanged in the canonical). The duplicate-by-index semantics and the schema constraints now appear in the docs mirror that Scalar renders at docs.warp.dev/api. A full sync_openapi.py --mode apply was intentionally NOT run: the canonical source has accumulated unrelated drift (factory, memory_stores, agent events/messages endpoints) whose tags are unclassified under the sync policy and require human triage before inclusion (per the sync-openapi-spec skill, unclassified tags must not be auto-included). That drift is out of scope for this setup-command rework and belongs in a separate full-sync PR. The setup-command sections transplanted here are byte-identical to the canonical c0b5d188 output (verified by loading both YAMLs and comparing the setup-command paths, schemas, and parameter). Validation: - sync_openapi.py --mode self-test: OK - All $refs resolve in the edited mirror (sync_openapi._validate_output) - npm run build prebuild (generate-openapi-json.mjs) parsed the YAML and emitted public/openapi.json with the duplicate notes + constraints - redocly lint: 0 new findings vs original HEAD (2 pre-existing errors + 3 pre-existing warnings in unrelated sections, unchanged by this edit) - astro build fails on an environmental node v25 vs required v20/22/24 SSR/Vercel-adapter rollup config issue, not a content/YAML problem Co-Authored-By: Oz <oz-agent@warp.dev>
There was a problem hiding this comment.
Overview
This rework re-syncs the setup-command paths, parameters, operation descriptions, and request/response schemas in the docs OpenAPI mirror from canonical warp-server commit c0b5d188. The duplicate-by-index contract and shared command/list constraints are now present, and the repository Build, link-check, and audit check passes; the separate Vercel status is a baseline Astro/Vite deployment failure reproducible on the PR base under supported Node 24.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Prior concerns: duplicate setup-command text is explicitly documented as addressable by zero-based index, and maxItems/minLength/maxLength constraints are present in the generated schemas.
Approve
Review run
https://oz.staging.warp.dev/runs/019f9608-8c9a-7df0-9712-be4c26483fa7
|
@pkillianjackson @tnederlof is this from an SE demo? |
2 participants
Summary
Implements the docs-repo deliverable for REMOTE-1063 — Support more precise setup command updates (multi-repo: warp-server, warp, docs; this is the docs child). Mirrors warp-server PR #13278's new setup-commands sub-resource into the generated docs OpenAPI (
developers/agent-api-openapi.yaml) so the Scalar reference atdocs.warp.dev/apiand the rawdocs.warp.dev/openapi.jsondocument the precise update operations.What changed
Scoped, additive mirror of the canonical's setup-commands surface only (390 insertions, 0 removals). Added verbatim from
warp-server/public_api/openapi.yaml:Paths (under
/agent/environments/{uid}/setup-commands):GET— list (listEnvironmentSetupCommands)PUT— replace / clear-and-rebuild (replaceEnvironmentSetupCommands)POST— add; append whenindexomitted, insert at0..=len(addEnvironmentSetupCommand)DELETE— clear all (clearEnvironmentSetupCommands)PATCH /{index}— edit one by index (updateEnvironmentSetupCommand)DELETE /{index}— remove one by index (removeEnvironmentSetupCommand)Schemas:
SetupCommandsResponse,ReplaceSetupCommandsRequest,AddSetupCommandRequest,UpdateSetupCommandRequestParams:
EnvironmentUID,SetupCommandIndexIndex semantics are zero-based, documented verbatim from the canonical: insert at
index == lenappends; edit/remove out of range →404; a bad (non-integer/negative) index →400; duplicate command text is allowed and addressed by index. The existingGET /agent/environmentsoperation andCloudEnvironmentConfigschema (with itssetup_commandsarray field) are unchanged.Why scoped (not a full
--mode apply)The docs file is behind the warp-server canonical on several unrelated public endpoints (factory, memory, messages, events, …). A full
sync_openapi.py --mode applywould pull all of those in and require triaging unknownfactory/memorytags — a product decision outside this ticket's scope. This change adds only the setup-commands surface, which reuses the knownagenttag (no sync-policy change needed) and introduces zero unclassified (!) items. A full re-sync of the remaining public surface is a separate follow-up.Verification
$refresolution: the sync tool's ref validator confirms all$refs resolve in the merged spec (including#/components/parameters/EnvironmentUIDand#/components/parameters/SetupCommandIndex).node scripts/generate-openapi-json.mjsregeneratedpublic/openapi.json(170.4 KB) containing both setup-commands paths, all 6 operationIds, and all 4 schemas.npm run build: theprebuildstep (OpenAPI-JSON generation that consumes this YAML) succeeds. The subsequentastro buildSSR step fails with a pre-existing environment issue (rollupOptions.input should not be an html file when building for SSR— Node v25 in this sandbox vs the repo's required^20.19 || ^22.12 || ^24), identical on the unmodified base, so it is not a regression. CI on the PR (correct Node version) runs the full build.npx @redocly/cli lint): 2 errors + 3 warnings, all pre-existing (identical set on the unmodified base:/agent/identitiesduplicate operationId,UpdateAgentRequestnullable sibling,info/license/url, and two redirect-only ops lacking a 2XX). None are in the setup-commands paths (all of which have proper200/204responses and unique operationIds). This change adds 0 new problems.This is a headless generated-spec change — no UI/computer-use.
Source
warp-server/public_api/openapi.yaml@276952ba— PR #13278 (branchfactory/remote-1063-setup-command-updates, not yet merged). Re-sync/confirm once that PR merges.Originating thread: https://slack.com/archives/C0BDQDW8V5E/p1784910823169449
Conversation: https://staging.warp.dev/conversation/9c6f6eeb-9e52-4081-b912-845459441ee5
Run: https://oz.staging.warp.dev/runs/019f959f-8c09-7b71-9038-cd76432fb2b1
This PR was generated with Oz.