Add Hosted Agents /v2/agents/sessions with Origin (MARSOHS-551)

specification/DigitalOcean-public.v2.yaml

@@ -60,6 +60,15 @@ tags:
       The Add-Ons API allows you to manage these resources, including creating, listing, and retrieving
       details about specific add-on resources.
 
+  - name: Agents
+    description: |-
+      Hosted Agents sessions API (`/v2/agents/sessions`). Sessions represent a
+      managed agent + sandbox pair. Product provenance is exposed via
+      `session.origin` (`direct` | `simulation` | `evaluation`). ListSessions
+      omits simulation and evaluation sessions server-side so customer surfaces
+      stay free of product-owned internal runs; GetSession by session_id still
+      returns those sessions for the owning product workflow.
+
   - name: Apps
     description: |-
       App Platform is a Platform-as-a-Service (PaaS) offering from DigitalOcean that allows
@@ -781,6 +790,62 @@ paths:
     patch:
       $ref: "resources/addons/addons_update_plan.yml"
 
+  /v2/agents/sessions:
+    get:
+      $ref: "resources/agents/agents_list_sessions.yml"
+    post:
+      $ref: "resources/agents/agents_create_session.yml"
+  /v2/agents/sessions/policy/validate:
+    post:
+      $ref: "resources/agents/agents_validate_session_policy.yml"
+  /v2/agents/sessions/sandbox/sizes:
+    get:
+      $ref: "resources/agents/agents_list_session_sandbox_sizes.yml"
+  /v2/agents/sessions/{session_id}:
+    delete:
+      $ref: "resources/agents/agents_delete_session.yml"
+    get:
+      $ref: "resources/agents/agents_get_session.yml"
+  /v2/agents/sessions/{session_id}/hitl/{request_id}:
+    post:
+      $ref: "resources/agents/agents_post_session_hitl.yml"
+  /v2/agents/sessions/{session_id}/input:
+    post:
+      $ref: "resources/agents/agents_create_session_input.yml"
+  /v2/agents/sessions/{session_id}/pause:
+    post:
+      $ref: "resources/agents/agents_post_session_pause.yml"
+  /v2/agents/sessions/{session_id}/resume:
+    post:
+      $ref: "resources/agents/agents_post_session_resume.yml"
+  /v2/agents/sessions/{session_id}/sandbox/exec:
+    post:
+      $ref: "resources/agents/agents_post_session_sandbox_exec.yml"
+  /v2/agents/sessions/{session_id}/stream:
+    get:
+      $ref: "resources/agents/agents_get_session_stream.yml"
+  /v2/agents/sessions/{session_id}/workspace/download:
+    get:
+      $ref: "resources/agents/agents_get_session_workspace_download.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers:
+    post:
+      $ref: "resources/agents/agents_create_session_workspace_transfer.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}:
+    get:
+      $ref: "resources/agents/agents_get_session_workspace_transfer.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/cancel:
+    post:
+      $ref: "resources/agents/agents_cancel_session_workspace_transfer.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/commit:
+    post:
+      $ref: "resources/agents/agents_commit_session_workspace_transfer.yml"
+  /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/part-upload-urls:
+    post:
+      $ref: "resources/agents/agents_create_session_workspace_part_upload_urls.yml"
+  /v2/agents/sessions/{session_id}/workspace/upload:
+    post:
+      $ref: "resources/agents/agents_create_session_workspace_upload.yml"
+
   /v2/apps:
     get:
       $ref: "resources/apps/apps_list.yml"

specification/resources/agents/agents_cancel_session_workspace_transfer.yml

@@ -0,0 +1,70 @@
+operationId: agents_cancel_session_workspace_transfer
+summary: Cancel a staged workspace transfer.
+description: 'Aborts an in-flight transfer. Idempotent: cancelling an already-terminal transfer returns
+  `aborted: false` with the current status. The request body is optional.'
+tags:
+- Agents
+parameters:
+- in: path
+  name: session_id
+  required: true
+  description: The session UUID.
+  schema:
+    type: string
+    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+- in: path
+  name: transfer_id
+  required: true
+  description: The workspace transfer identifier.
+  schema:
+    type: string
+    example: tr_example
+  example: tr_example
+requestBody:
+  required: false
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          reason:
+            type: string
+            description: Optional caller-visible audit/debug context.
+            example: example
+responses:
+  '200':
+    description: Cancel processed.
+    headers: &id001
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/workspace_transfer_cancelled
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '404':
+    $ref: ../../shared/responses/not_found.yml
+  '501':
+    description: Cancel is not supported by the active sandbox driver.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '429':
+    $ref: ../../shared/responses/too_many_requests.yml
+  '500':
+    $ref: ../../shared/responses/server_error.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+x-codeSamples:
+- $ref: examples/curl/agents_cancel_session_workspace_transfer.yml
+security:
+- bearer_auth:
+  - agents:create

specification/resources/agents/agents_commit_session_workspace_transfer.yml

@@ -0,0 +1,86 @@
+operationId: agents_commit_session_workspace_transfer
+summary: Finalize a staged upload.
+description: Upload only. Call once, after all parts have been uploaded. Completes the multipart upload
+  and starts the asynchronous import into the workspace. Responds 202; poll the transfer until `completed`
+  or `failed`.
+tags:
+- Agents
+parameters:
+- in: path
+  name: session_id
+  required: true
+  description: The session UUID.
+  schema:
+    type: string
+    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+- in: path
+  name: transfer_id
+  required: true
+  description: The workspace transfer identifier.
+  schema:
+    type: string
+    example: tr_example
+  example: tr_example
+requestBody:
+  required: false
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          sha256:
+            type: string
+            description: Optional lowercase hex SHA-256. Must match the value supplied at create when
+              both are set.
+            example: example
+responses:
+  '202':
+    description: Upload committed; import in progress.
+    headers: &id001
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/workspace_upload_committed
+  '400':
+    description: Missing transfer_id, sha256 mismatch, or invalid JSON.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '404':
+    $ref: ../../shared/responses/not_found.yml
+  '409':
+    description: Transfer is not in a committable state.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '501':
+    description: Staged upload is not supported by the active sandbox driver.
+    headers: *id001
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '429':
+    $ref: ../../shared/responses/too_many_requests.yml
+  '500':
+    $ref: ../../shared/responses/server_error.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+x-codeSamples:
+- $ref: examples/curl/agents_commit_session_workspace_transfer.yml
+security:
+- bearer_auth:
+  - agents:create

specification/resources/agents/agents_create_session.yml

@@ -0,0 +1,128 @@
+operationId: agents_create_session
+summary: CreateSession provisions a sandbox and starts the requested agent.
+description: 'Returns once the session row is allocated. The sandbox boot completes asynchronously; clients
+  observe SESSION_STATUS_PROVISIONING → READY via StreamSession.
+
+
+  Two mutually exclusive request forms are selected by Content-Type. Existing YAML callers send a raw
+  customer `agents.yaml` Agent manifest with `application/x-yaml`, `application/yaml`, `text/yaml`, or
+  `text/x-yaml`; this flow is unchanged. Definition-backed callers send the strict `CreateSessionDefinitionRequest`
+  JSON object with `application/json`. Unknown JSON fields, including team identity, are rejected. An
+  omitted revision_id pins the definition''s current immutable revision.
+
+
+  Definition-backed execution requires an exactly matching credential binding set when the selected revision
+  declares logical secrets. Static values are fetched only by their persisted name/region/version and
+  are never returned or persisted. OAuth bindings currently fail closed with 501.
+
+
+  Every successful create atomically persists value-free execution provenance and an allowlisted agent-spec
+  audit snapshot. The team and user identity are taken from the authenticated principal, never the body.
+  `X-Device-UUID` (if present) is persisted on the session row.'
+tags:
+- Agents
+parameters:
+- in: header
+  name: X-Device-UUID
+  required: false
+  description: Optional hardware device id forwarded by doctl. Persisted on the session row for lifecycle
+    attribution. Values over 128 bytes are ignored.
+  schema:
+    type: string
+    example: device-uuid-example
+  example: device-uuid-example
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema:
+        $ref: models/definitions.yml#/create_session_definition_request
+    application/x-yaml: &id001
+      schema:
+        $ref: models/definitions.yml#/agent_manifest
+    application/yaml: *id001
+    text/yaml: *id001
+    text/x-yaml: *id001
+  description: Either a raw AgentManifest with a YAML Content-Type or CreateSessionDefinitionRequest with
+    application/json. The forms are mutually exclusive by Content-Type.
+responses:
+  '200':
+    description: Session row allocated; sandbox boot continues asynchronously.
+    headers: &id002
+      ratelimit-limit:
+        $ref: ../../shared/headers.yml#/ratelimit-limit
+      ratelimit-remaining:
+        $ref: ../../shared/headers.yml#/ratelimit-remaining
+      ratelimit-reset:
+        $ref: ../../shared/headers.yml#/ratelimit-reset
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/create_session_response
+  '400':
+    description: Invalid manifest/reference JSON, incompatible or missing binding set, env collision,
+      credential limit violation, or invalid session/origin identifier.
+    headers: *id002
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '401':
+    $ref: ../../shared/responses/unauthorized.yml
+  '403':
+    description: Secrets Manager denied access to a pinned credential.
+    headers: *id002
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '409':
+    description: Team is at the active-session quota, a live session name already exists, or the binding
+      set targets another revision.
+    headers: *id002
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '404':
+    $ref: ../../shared/responses/not_found.yml
+  '413':
+    description: JSON reference body exceeds 16 KiB or YAML body exceeds 1 MiB.
+    headers: *id002
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '415':
+    description: Unsupported Content-Type.
+    headers: *id002
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '501':
+    description: The selected binding set contains an OAuth assignment; execution-time OAuth brokering
+      is not available yet.
+    headers: *id002
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '503':
+    description: Secrets Manager is unavailable.
+    headers: *id002
+    content:
+      application/json:
+        schema:
+          $ref: models/definitions.yml#/error
+  '500':
+    $ref: ../../shared/responses/server_error.yml
+  '429':
+    $ref: ../../shared/responses/too_many_requests.yml
+  default:
+    $ref: ../../shared/responses/unexpected_error.yml
+x-codeSamples:
+- $ref: examples/curl/agents_create_session.yml
+security:
+- bearer_auth:
+  - agents:create