feat(api): add agent environment suspension and expiration

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: 4ec7ddaa-ffa6-4a66-9035-ecb517108372
-openapi_spec_hash: f21b711c644bd7acb83c4a35be5f89b5
-openapi_transformed_spec_hash: 9d23bc992f6c476d92ff2a1768ed1b17
-config_hash: ed29aaecbd1993a4cd3a714b00bc39d2
-codegen_sha: 485e909890c0685a1afe1a48769757c44a75dd1c
-codegen_hash: 08f5227f4a60fb777fcad36dd9097c6c0a1651caaf06bc928d96839fc149ae2e
-public_codegen_sha: a17a5cded92ca8999b02053afcfc5459f01463e5
+generation_id: d507486e-80bb-4c77-ab2f-b280f244a836
+openapi_spec_hash: 633998559d1b899949f8986dd1a58df1
+openapi_transformed_spec_hash: 0bed479bcc4261379749a5fe4e5d6a45
+config_hash: dd5d37ab21844cf4e91a2f181042a9c1
+codegen_sha: b60321b75dee05ffe731751b9d0297a963293f34
+codegen_hash: b6c907773d8159afb1992c0d89354d5ba62e9940e431fc319046dad7c91230ca
+public_codegen_sha: ee22d0fe3f027eb1b02d37b1aa868e41886c37cc

api_reference/openapi.transformed.yml

@@ -36188,6 +36188,36 @@ paths:
               "input_tokens": 11
             }
 webhooks:
+  agent_environment_expired:
+    post:
+      description: |
+        Sent when an agent environment expires and can no longer resume from a snapshot.
+      requestBody:
+        description: The event payload sent by the API.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WebhookAgentEnvironmentExpired'
+      responses:
+        '200':
+          description: |
+            Return a 200 status code to acknowledge receipt of the event. Non-200
+            status codes will be retried.
+  agent_environment_suspended:
+    post:
+      description: |
+        Sent when an agent environment is suspended and can resume from a snapshot.
+      requestBody:
+        description: The event payload sent by the API.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WebhookAgentEnvironmentSuspended'
+      responses:
+        '200':
+          description: |
+            Return a 200 status code to acknowledge receipt of the event. Non-200
+            status codes will be retried.
   agent_environment_failed:
     post:
       description: |
@@ -71424,6 +71454,68 @@ components:
       - type
       - status
       - action
+    WebhookAgentEnvironmentExpired:
+      type: object
+      title: agent.environment.expired
+      description: |
+        Sent when an agent environment expires and can no longer resume from a snapshot.
+      allOf:
+      - $ref: '#/components/schemas/WebhookAgentSessionEnvelope'
+      - type: object
+        required:
+        - type
+        - data
+        properties:
+          type:
+            type: string
+            description: The event type. Always `agent.environment.expired`.
+            enum:
+            - agent.environment.expired
+            x-stainless-const: true
+          data:
+            $ref: '#/components/schemas/AgentEnvironmentEvent'
+      x-oaiMeta:
+        name: agent.environment.expired
+        group: webhook-events
+        example: |
+          {
+            "id": "evt_123",
+            "object": "event",
+            "created_at": 1719168000,
+            "type": "agent.environment.expired",
+            "data": {"id": "ccarenv_123"}
+          }
+    WebhookAgentEnvironmentSuspended:
+      type: object
+      title: agent.environment.suspended
+      description: |
+        Sent when an agent environment is suspended and can resume from a snapshot.
+      allOf:
+      - $ref: '#/components/schemas/WebhookAgentSessionEnvelope'
+      - type: object
+        required:
+        - type
+        - data
+        properties:
+          type:
+            type: string
+            description: The event type. Always `agent.environment.suspended`.
+            enum:
+            - agent.environment.suspended
+            x-stainless-const: true
+          data:
+            $ref: '#/components/schemas/AgentEnvironmentEvent'
+      x-oaiMeta:
+        name: agent.environment.suspended
+        group: webhook-events
+        example: |
+          {
+            "id": "evt_123",
+            "object": "event",
+            "created_at": 1719168000,
+            "type": "agent.environment.suspended",
+            "data": {"id": "ccarenv_123"}
+          }
     WebhookAgentEnvironmentFailed:
       type: object
       title: agent.environment.failed
@@ -81169,13 +81261,15 @@ components:
       - ready
       - connected
       - disconnected
+      - suspended
       - expired
       - failed
       x-enumDescriptions:
       - ''
       - Provisioning succeeded and the environment is available for attachment or use.
       - ''
       - ''
+      - The sandbox is stopped and can be resumed from its private checkpoint.
       - ''
       - ''
       description: The public lifecycle status of an execution environment.
@@ -87103,12 +87197,16 @@ components:
       - ready
       - connected
       - disconnected
+      - suspended
+      - expired
       - failed
       x-enumDescriptions:
       - The environment is being prepared.
       - The environment is ready to connect.
       - The environment is connected.
       - The environment is disconnected.
+      - The environment is stopped and can be resumed from its private checkpoint.
+      - The environment and its private checkpoint have expired.
       - The environment failed to connect.
       description: The connection status of a session environment.
     SessionEnvironmentErrorResource:
@@ -87193,6 +87291,76 @@ components:
       - environment
       additionalProperties: false
       description: Emitted when a hosted session environment is ready to connect.
+    SessionEventAgentSessionEnvironmentSuspended:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+          - agent.session.environment.suspended
+          default: agent.session.environment.suspended
+          x-stainless-const: true
+          description: The type of the object. Always `agent.session.environment.suspended`.
+        event_id:
+          type: string
+          minLength: 0
+          description: The unique ID of the event.
+        session_id:
+          type: string
+          minLength: 0
+          description: The ID of the session associated with the event.
+        turn_id:
+          type:
+          - string
+          - 'null'
+          minLength: 0
+          description: The ID of the turn associated with the event, when applicable.
+        environment:
+          $ref: '#/components/schemas/SessionEnvironmentStateResource'
+          description: The current environment state.
+      required:
+      - type
+      - event_id
+      - session_id
+      - turn_id
+      - environment
+      additionalProperties: false
+      description: Emitted after an idle hosted session environment is checkpointed and stopped.
+    SessionEventAgentSessionEnvironmentExpired:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+          - agent.session.environment.expired
+          default: agent.session.environment.expired
+          x-stainless-const: true
+          description: The type of the object. Always `agent.session.environment.expired`.
+        event_id:
+          type: string
+          minLength: 0
+          description: The unique ID of the event.
+        session_id:
+          type: string
+          minLength: 0
+          description: The ID of the session associated with the event.
+        turn_id:
+          type:
+          - string
+          - 'null'
+          minLength: 0
+          description: The ID of the turn associated with the event, when applicable.
+        environment:
+          $ref: '#/components/schemas/SessionEnvironmentStateResource'
+          description: The current environment state.
+      required:
+      - type
+      - event_id
+      - session_id
+      - turn_id
+      - environment
+      additionalProperties: false
+      description: Emitted after a suspended hosted session environment and its checkpoint expire.
     SessionEventAgentSessionEnvironmentReset:
       type: object
       properties:
@@ -88428,6 +88596,8 @@ components:
         mapping:
           error: '#/components/schemas/SessionEventError'
           agent.session.environment.ready: '#/components/schemas/SessionEventAgentSessionEnvironmentReady'
+          agent.session.environment.suspended: '#/components/schemas/SessionEventAgentSessionEnvironmentSuspended'
+          agent.session.environment.expired: '#/components/schemas/SessionEventAgentSessionEnvironmentExpired'
           agent.session.environment.reset: '#/components/schemas/SessionEventAgentSessionEnvironmentReset'
           agent.output.command_execution_output.delta: '#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta'
           agent.session.created: '#/components/schemas/SessionEventAgentSessionCreated'
@@ -88460,6 +88630,8 @@ components:
       x-oai-discriminator-values:
       - error
       - agent.session.environment.ready
+      - agent.session.environment.suspended
+      - agent.session.environment.expired
       - agent.session.environment.reset
       - agent.output.command_execution_output.delta
       - agent.session.created
@@ -88492,6 +88664,8 @@ components:
       anyOf:
       - $ref: '#/components/schemas/SessionEventError'
       - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReady'
+      - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentSuspended'
+      - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentExpired'
       - $ref: '#/components/schemas/SessionEventAgentSessionEnvironmentReset'
       - $ref: '#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta'
       - $ref: '#/components/schemas/SessionEventAgentSessionCreated'
@@ -90152,6 +90326,8 @@ components:
       - video.failed
       - agent.environment.ready
       - agent.environment.failed
+      - agent.environment.suspended
+      - agent.environment.expired
       - agent.session.created
       - agent.session.action_required
       - agent.session.in_progress

lib/openai.rb

@@ -563,11 +563,13 @@
 require_relative "openai/models/beta/agent_session_deleted"
 require_relative "openai/models/beta/agent_session_environment_connected_event"
 require_relative "openai/models/beta/agent_session_environment_disconnected_event"
+require_relative "openai/models/beta/agent_session_environment_expired_event"
 require_relative "openai/models/beta/agent_session_environment_failed_event"
 require_relative "openai/models/beta/agent_session_environment_pending_event"
 require_relative "openai/models/beta/agent_session_environment_ready_event"
 require_relative "openai/models/beta/agent_session_environment_reset_event"
 require_relative "openai/models/beta/agent_session_environment_state"
+require_relative "openai/models/beta/agent_session_environment_suspended_event"
 require_relative "openai/models/beta/agent_session_error_event"
 require_relative "openai/models/beta/agent_session_event"
 require_relative "openai/models/beta/agent_session_failed_event"
@@ -1448,8 +1450,10 @@
 require_relative "openai/models/video_retrieve_params"
 require_relative "openai/models/video_seconds"
 require_relative "openai/models/video_size"
+require_relative "openai/models/webhooks/agent_environment_expired_webhook_event"
 require_relative "openai/models/webhooks/agent_environment_failed_webhook_event"
 require_relative "openai/models/webhooks/agent_environment_ready_webhook_event"
+require_relative "openai/models/webhooks/agent_environment_suspended_webhook_event"
 require_relative "openai/models/webhooks/agent_session_action_required_webhook_event"
 require_relative "openai/models/webhooks/agent_session_created_webhook_event"
 require_relative "openai/models/webhooks/agent_session_failed_webhook_event"

lib/openai/models/beta/agent_session_environment_expired_event.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Beta
+      class AgentSessionEnvironmentExpiredEvent < OpenAI::Internal::Type::BaseModel
+        # @!attribute environment
+        #   The current environment state.
+        #
+        #   @return [OpenAI::Models::Beta::AgentSessionEnvironmentState]
+        required :environment, -> { OpenAI::Beta::AgentSessionEnvironmentState }
+
+        # @!attribute event_id
+        #   The unique ID of the event.
+        #
+        #   @return [String]
+        required :event_id, String
+
+        # @!attribute session_id
+        #   The ID of the session associated with the event.
+        #
+        #   @return [String]
+        required :session_id, String
+
+        # @!attribute turn_id
+        #   The ID of the turn associated with the event, when applicable.
+        #
+        #   @return [String, nil]
+        required :turn_id, String, nil?: true
+
+        # @!attribute type
+        #   The type of the object. Always `agent.session.environment.expired`.
+        #
+        #   @return [Symbol, :"agent.session.environment.expired"]
+        required :type, const: :"agent.session.environment.expired"
+
+        # @!method initialize(environment:, event_id:, session_id:, turn_id:, type: :"agent.session.environment.expired")
+        #   Emitted after a suspended hosted session environment and its checkpoint expire.
+        #
+        #   @param environment [OpenAI::Models::Beta::AgentSessionEnvironmentState]
+        #     The current environment state.
+        #
+        #   @param event_id [String]
+        #     The unique ID of the event.
+        #
+        #   @param session_id [String]
+        #     The ID of the session associated with the event.
+        #
+        #   @param turn_id [String, nil]
+        #     The ID of the turn associated with the event, when applicable.
+        #
+        #   @param type [Symbol, :"agent.session.environment.expired"]
+        #     The type of the object. Always `agent.session.environment.expired`.
+      end
+    end
+  end
+end

lib/openai/models/beta/agent_session_environment_state.rb

@@ -94,6 +94,12 @@ module Status
           # The environment is disconnected.
           DISCONNECTED = :disconnected
 
+          # The environment is stopped and can be resumed from its private checkpoint.
+          SUSPENDED = :suspended
+
+          # The environment and its private checkpoint have expired.
+          EXPIRED = :expired
+
           # The environment failed to connect.
           FAILED = :failed