Repository navigation
Add Hosted Agents /v2/agents OpenAPI (full harness surface) - #1233
Open
SSharma-10 wants to merge 13 commits into
Open
SSharma-10 wants to merge 13 commits into
SSharma-10 wants to merge 13 commits into
Conversation
Document all 38 OHS public endpoints (configs, sessions, checkpoints, fork, workspace transfers, and templates) for client generation and docs. Co-authored-by: Cursor <cursoragent@cursor.com>
Expose a single requestBody media type so Autorest can generate agents_create_session, while documenting YAML/JSON dual forms via description and x-content-schemas to match harness swagger. Co-authored-by: Cursor <cursoragent@cursor.com>
anup-deka
reviewed
Sep 24, 2026
anup-deka
reviewed
Sep 24, 2026
anup-deka
reviewed
Sep 24, 2026
anup-deka
reviewed
Sep 25, 2026
anup-deka
reviewed
Sep 25, 2026
anup-deka
previously approved these changes
Sep 25, 2026
Merged
4 tasks done
sdharavath
added a commit
to sdharavath/openapi
that referenced
this pull request
Oct 8, 2026
… OpenAPI Adds the 15 operations missing from digitalocean#1233 (point 3 of the API Engineering review): - Triggers Config API (13 ops): CRUD + pause/resume on /v2/agents/triggers, webhook secret rotation, execution history + cancel, by-session lookup, reusable-session picker, the webhook-providers registry, and the HMAC-authenticated webhook ingress endpoint. Mirrored from harness-trigger/contracts/trigger.swagger.json. - Session event stream: GET /v2/agents/sessions/{session_id}/events (Server-Sent Events), mirrored from contracts/mars-dataplane-sse.openapi.yaml. Documents the shipping params (replay_only, replay_from, cursor, device_id, Last-Event-ID, X-Device-UUID). - Port-forward: GET /v2/agents/sessions/{session_id}/port-forward/{port}, the WebSocket tunnel to a guest TCP port (documented as the 101 upgrade handshake). The webhook ingress body is modeled as application/octet-stream (binary), not '*/*': the latter crashes the autorest/modelerfour pre-namer ('Name cannot be empty') that the pydo client-gen CI runs. Validation: make lint 0 errors; make bundle ok; autorest --python generate exits 0. Co-authored-by: Cursor <cursoragent@cursor.com>
anup-deka
approved these changes
Oct 8, 2026
Contributor
|
Latest PR - #1255 supersede this one |
Merged
2 of 4 tasks
SSharma-10
added a commit
that referenced
this pull request
Oct 13, 2026
…rward; supersedes #1233) (#1255) * Add Hosted Agents /v2/agents OpenAPI surface from harness swagger. Document all 38 OHS public endpoints (configs, sessions, checkpoints, fork, workspace transfers, and templates) for client generation and docs. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix Hosted Agents OpenAPI gaps vs harness swagger. * Rename Hosted Agents OpenAPI copy to Environment terminology * Align Harness Runtime OpenAPI tag with product docs * Make CreateSession/ValidatePolicy codegen-safe for pydo. Expose a single requestBody media type so Autorest can generate agents_create_session, while documenting YAML/JSON dual forms via description and x-content-schemas to match harness swagger. Co-authored-by: Cursor <cursoragent@cursor.com> * emove x-content-schemas refs that break bundled Spectral lint * Rename Harness Runtime operationIds to harness_* for pydo codegen * addressed comments * Fix Hosted Agents scopes and Insights fields * Update sandbox_size structure (#1237) * OAR-15627: add triggers, event stream, and port-forward to /v2/agents OpenAPI Adds the 15 operations missing from #1233 (point 3 of the API Engineering review): - Triggers Config API (13 ops): CRUD + pause/resume on /v2/agents/triggers, webhook secret rotation, execution history + cancel, by-session lookup, reusable-session picker, the webhook-providers registry, and the HMAC-authenticated webhook ingress endpoint. Mirrored from harness-trigger/contracts/trigger.swagger.json. - Session event stream: GET /v2/agents/sessions/{session_id}/events (Server-Sent Events), mirrored from contracts/mars-dataplane-sse.openapi.yaml. Documents the shipping params (replay_only, replay_from, cursor, device_id, Last-Event-ID, X-Device-UUID). - Port-forward: GET /v2/agents/sessions/{session_id}/port-forward/{port}, the WebSocket tunnel to a guest TCP port (documented as the 101 upgrade handshake). The webhook ingress body is modeled as application/octet-stream (binary), not '*/*': the latter crashes the autorest/modelerfour pre-namer ('Name cannot be empty') that the pydo client-gen CI runs. Validation: make lint 0 errors; make bundle ok; autorest --python generate exits 0. Co-authored-by: Cursor <cursoragent@cursor.com> * OAR-15627: use shared DO error model {id,message,request_id} for all /v2/agents errors Anup Deka (API Eng) asked for the standard envelope; cthulhu#179553 (merged) makes harness-api emit it and the Oceanus edge already returns it. Point the agents error schema at shared/models/error.yml so all 128 error responses across the 53 ops use {id, message, request_id} instead of the old nested {error:{code,message}}, removing the split where only 401/404/429/500 used the standard shape. make lint 0 errors; make bundle ok (old nested shape gone); autorest --python exits 0. Co-authored-by: Cursor <cursoragent@cursor.com> * OAR-15627: address API review of #1255 (findings 1-9) - #1: events-stream errors are text/plain (OHP, not JSON) for 404/429/500/503; drop the 400; keep 401 JSON (edge). OHP moves to JSON under MARSOHS-2065. - #2: add 402 to the 16 billing-gated operations (cthulhu#179578). - #3: add GET /v2/agents/sessions/{id}/ingress (publicly routed; replaces the port-forward bridge for browser clients). - #4: trigger create/update return 422 (trigger limit) and 503 (upstream check); webhook ingress returns 400 (body too large/unreadable). - #5: add stream.state to the stream_event type enum + a stream_state schema. - #6: trigger reads return 404 not 403 for another team's trigger; create can return 403 (config permission denied). - #7: correct the port-forward description (ingress replaced it for browsers; paused sessions are woken and served) and document the handshake 400. - #8: webhook body lists concrete content types (json/form/octet-stream). - #9: drop the ignored Content-Type response header on the events 200. Deferred (cosmetic): renaming the 53 Go-method summaries to DO reference style. make lint 0 errors; make bundle ok; autorest --python exits 0. Co-authored-by: Cursor <cursoragent@cursor.com> * OAR-15627: document events-stream errors as the DO-standard JSON envelope Matches OHP after cthulhu#179797 (MARSOHS-2065): OHP routes its refusals through common/httpapi.WriteError + httpapi.RequestID and emits {id, message, request_id} on 404/429/500/503 (the 401 is the edge). GATED ON #179797's DEPLOY: until it is rolled out to the OHP instance behind api.digitalocean.com the live stream still returns text/plain, so #1255 must merge only after #179797 is deployed. make lint 0 errors; make bundle ok. Co-authored-by: Cursor <cursoragent@cursor.com> * OAR-15627: address minor review follow-ups - create and update trigger document 502 (config service error); update also documents 403 (config permission denied) - both via writeConfigErr's default and PermissionDenied branches (handlers.go:1244/1248). - webhook ingress application/json body is type: object (additionalProperties: true) so real JSON deliveries validate under a contract check; form and octet-stream stay strings. make lint 0 errors; make bundle ok; autorest --python exits 0. Co-authored-by: Cursor <cursoragent@cursor.com> * Make trigger webhook body codegen-safe for Autorest --------- Co-authored-by: SSharma-10 <shivanisharma@digitalocean.com> Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: Damanpreet Singh <damanpreetsingh@digitalocean.com> Co-authored-by: anup-deka <adeka@digitalocean.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/v2/agents/*, mirrored from harness-apiharness.swagger.json(38 operations).main.Test plan
make bundlesucceedsnpm run lint -- specification/DigitalOcean-public.v2.yaml→ 0 errorsMade with Cursor