openapi: 3.1.0
info:
  title: AIOS Orchestrator Decision Callback
  version: 1.0.0
servers:
  - url: https://REPLACE_WITH_ACTIONS_HOST
paths:
  /v1/orchestrator/decisions:
    post:
      operationId: submit_orchestration_decision
      summary: Submit one strict orchestration decision for a triggered event
      description: >-
        The 18890 Actions API validates the decision strictly and forwards it
        to the loopback Gateway with a callback credential resolved only from
        an approved SecretRef. This operation cannot perform arbitrary GitOps
        mutations.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Decision'
      responses:
        '202':
          description: Accepted
        '409':
          description: Contract mismatch or stale state version
        '422':
          description: Schema validation failed
        '401':
          description: Missing or invalid Actions API bearer credential
        '403':
          description: Credential lacks orchestrator:decision scope
        '502':
          description: Metadata-only Gateway forwarding failure
        '503':
          description: SecretRef provider or callback configuration unavailable
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    WorkUnit:
      type: object
      additionalProperties: false
      required:
        - id
        - track_id
        - gate_id
        - primary_agent
        - fallback_agent
        - clean_base_commit
        - allowed_paths
        - required_checks
        - forbidden_operations
        - instruction
      properties:
        id: {type: string}
        track_id: {type: string}
        gate_id: {type: string}
        primary_agent:
          type: string
          enum: [openclaw, codex]
        fallback_agent:
          type: string
          enum: [openclaw, codex]
        clean_base_commit:
          type: string
          pattern: '^[0-9a-f]{40}$'
        allowed_paths:
          type: array
          items: {type: string}
        required_checks:
          type: array
          items: {type: string}
        forbidden_operations:
          type: array
          items: {type: string}
        instruction: {type: string}
    Decision:
      type: object
      additionalProperties: false
      required:
        - schema_version
        - project_key
        - contract_commit
        - event_id
        - expected_state_version
        - verdict
        - state_updates
        - next_work_units
        - requires_human_input
        - stop_reason
      properties:
        schema_version:
          type: integer
          const: 1
        project_key: {type: string}
        contract_commit:
          type: string
          pattern: '^[0-9a-f]{40}$'
        event_id: {type: string}
        expected_state_version:
          type: integer
          minimum: 0
        verdict:
          type: string
          enum: [DISPATCH, BLOCKED, COMPLETE, NOOP]
        state_updates:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [key, value]
            properties:
              key: {type: string}
              value: {type: string}
        next_work_units:
          type: array
          items:
            $ref: '#/components/schemas/WorkUnit'
        requires_human_input: {type: boolean}
        stop_reason:
          type: [string, 'null']