openapi: 3.0.3
info:
  title: AgentZ HTTP API
  version: 0.1.0
  description: HTTP API for AgentZ agents, lens, secrets, and sandboxes.
servers:
- url: /
  description: Current origin
security:
- GatewayBearer: []
tags:
- name: agents
  description: Agent lifecycle and status APIs.
- name: tenants
  description: Tenant bootstrap and readiness APIs.
- name: lens
  description: Trace, span, and OS observability APIs.
- name: secrets
  description: Session secret management APIs.
- name: sandboxes
  description: Sandbox resource management APIs.
- name: skills
  description: Immutable skill catalog and attachment APIs.
- name: mcp-connections
  description: MCPConnection resource and credential management APIs.
- name: workflows
  description: Workflow definition management APIs.
- name: workflow-schedules
  description: Workflow schedule management APIs.
- name: workflow-runs
  description: Workflow run browsing and status APIs.
- name: workflow-webhooks
  description: Workflow webhook invocation and trigger listing APIs.

paths:
  /api/tenant:
    get:
      operationId: getTenant
      summary: Get the current tenant bootstrap state.
      tags: [tenants]
      responses:
        '200':
          description: Tenant bootstrap state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: ensureTenant
      summary: Create the current tenant resource when missing.
      description: >
        Ensures a Tenant custom resource exists for the bearer token's active
        Better Auth organization. The request returns immediately with the
        current bootstrap state and does not wait for the tenant to become
        ready.
      tags: [tenants]
      responses:
        '200':
          description: Tenant exists and current bootstrap state is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent:
    get:
      operationId: listAgents
      summary: List paginated agent summaries.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNameFilterQuery'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated agent summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createAgent
      summary: Create an Agent resource.
      description: >
        Creates an agent record and Agent custom resource. The request returns
        after the Agent resource is created and does not wait for the Agent to
        become ready.
      tags: [agents]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '201':
          description: Agent resource created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/{agentName}:
    put:
      operationId: updateAgent
      summary: Update an Agent resource.
      description: >
        Updates mutable Agent fields for an existing Agent. The agent name in
        the path identifies the Agent and is immutable.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: Agent resource updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteAgent
      summary: Delete an Agent resource.
      tags: [agents]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      responses:
        '204':
          description: Agent was deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/agent/watch:
    post:
      operationId: watchAgents
      summary: Watch agent status changes.
      description: >
        Returns an SSE stream. Each event data payload is a JSON object matching
        WatchAgentsEvent. If agent_names is omitted or empty, all known agents
        are watched.
      tags: [agents]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchAgentsRequest'
      responses:
        '200':
          description: Stream of agent status changes.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchAgentsEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/skill:
    get:
      operationId: listSkills
      summary: List immutable Skill resources.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/AgentNameQueryOptional'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated immutable skills.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSkillsResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createSkill
      summary: Create an immutable Skill resource.
      tags: [skills]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSkillRequest'
      responses:
        '201':
          description: Skill created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Skill'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/skill/{skillName}:
    put:
      operationId: updateSkill
      summary: Update an immutable Skill active version and references.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/SkillNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSkillRequest'
      responses:
        '200':
          description: Skill updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Skill'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteSkill
      summary: Delete an immutable Skill resource.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/SkillNamePath'
      responses:
        '204':
          description: Skill deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/skill/{skillName}/references:
    get:
      operationId: getSkillReferences
      summary: List Agents and Sandboxes referencing an immutable Skill.
      tags: [skills]
      parameters:
      - $ref: '#/components/parameters/SkillNamePath'
      responses:
        '200':
          description: Skill references.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillReferences'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/{sessionID}/trace:
    get:
      operationId: listTraceSessions
      summary: List paginated per-session trace summaries.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: sessionID
        in: path
        required: true
        description: Session identifier scoped to an agent.
        schema:
          type: string
          minLength: 1
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/StartedAfterQuery'
      - $ref: '#/components/parameters/StartedBeforeQuery'
      responses:
        '200':
          description: Paginated per-session trace summaries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTraceSessionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/{sessionID}/trace/{traceID}/span:
    get:
      operationId: listSpans
      summary: List paginated spans for a trace.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: sessionID
        in: path
        required: true
        description: Session identifier scoped to an agent.
        schema:
          type: string
          minLength: 1
      - name: traceID
        in: path
        required: true
        description: Trace identifier scoped to a session.
        schema:
          $ref: '#/components/schemas/TraceID'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated spans for a trace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSpansResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/{sessionID}/trace/{traceID}/span/{spanID}:
    get:
      operationId: getSpanDetail
      summary: Get span details and correlated OS observability.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: sessionID
        in: path
        required: true
        description: Session identifier scoped to an agent.
        schema:
          type: string
          minLength: 1
      - name: traceID
        in: path
        required: true
        description: Trace identifier scoped to a session.
        schema:
          $ref: '#/components/schemas/TraceID'
      - name: spanID
        in: path
        required: true
        description: Span identifier scoped to a trace.
        schema:
          $ref: '#/components/schemas/SpanID'
      responses:
        '200':
          description: Span detail with payload and correlated events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanDetailResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/observability/process:
    get:
      operationId: listProcessObservability
      summary: List paginated process observability events.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/EventTimeAfterQuery'
      - $ref: '#/components/parameters/EventTimeBeforeQuery'
      - $ref: '#/components/parameters/ActionQuery'
      - $ref: '#/components/parameters/AggregatedQuery'
      responses:
        '200':
          description: Paginated process observability events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProcessObservabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/observability/file:
    get:
      operationId: listFileObservability
      summary: List paginated file observability events.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/EventTimeAfterQuery'
      - $ref: '#/components/parameters/EventTimeBeforeQuery'
      - $ref: '#/components/parameters/ActionQuery'
      - $ref: '#/components/parameters/AggregatedQuery'
      responses:
        '200':
          description: Paginated file observability events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFileObservabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/observability/network:
    get:
      operationId: listNetworkObservability
      summary: List paginated network observability events.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      - $ref: '#/components/parameters/EventTimeAfterQuery'
      - $ref: '#/components/parameters/EventTimeBeforeQuery'
      - $ref: '#/components/parameters/ActionQuery'
      - $ref: '#/components/parameters/AggregatedQuery'
      responses:
        '200':
          description: Paginated network observability events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNetworkObservabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/lens/{agentName}/mcp/graph:
    get:
      operationId: getMCPGraph
      summary: Get MCP observability graph data for an agent given a date range.
      tags: [lens]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/FromDateQuery'
      - $ref: '#/components/parameters/ToDateQuery'
      responses:
        '200':
          description: Graph-ready MCP observability for an agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPGraphResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/secret/{agentName}:
    get:
      operationId: listSecrets
      summary: List secret keys for an agent.
      description: >
        Returns a paginated list of secret keys with creation timestamps.
        Secret values are never included in the response.
      tags: [secrets]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated secret keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSecretsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: putSecret
      summary: Create a secret for an agent.
      description: >
        Creates a static or OAuth-backed secret for the agent. Secret values
        are stored only in OpenBao. OAuth secrets keep refresh lifecycle state
        in the Secret CRD status.
      tags: [secrets]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/UpdateSandboxQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '201':
          description: Secret created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutSecretsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/secret/{agentName}/watch:
    post:
      operationId: watchSecrets
      summary: Watch secret status changes for an agent.
      description: >
        Returns an SSE stream. Each event data payload is a JSON object matching
        WatchSecretsEvent. If keys is omitted or empty, all known secrets for
        the addressed agent are watched.
      tags: [secrets]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchSecretsRequest'
      responses:
        '200':
          description: Stream of secret updates.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchSecretsEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/secret/{agentName}/delete:
    post:
      operationId: deleteSecret
      summary: Delete secrets for an agent.
      description: >
        Deletes the specified secret keys for the agent. Missing keys are
        ignored.
      tags: [secrets]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteSecretsRequest'
      responses:
        '204':
          description: Secrets deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/sandbox:
    get:
      operationId: listSandboxes
      summary: List paginated Sandbox resources.
      tags: [sandboxes]
      parameters:
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated sandboxes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSandboxesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createSandbox
      summary: Create a Sandbox resource.
      tags: [sandboxes]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxRequest'
      responses:
        '201':
          description: Sandbox created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/sandbox/{sandboxName}:
    put:
      operationId: updateSandbox
      summary: Update a Sandbox resource.
      description: >
        Updates the packages list for an existing Sandbox. The name in the
        path identifies the Sandbox.
      tags: [sandboxes]
      parameters:
      - name: sandboxName
        in: path
        required: true
        description: Sandbox resource name.
        schema:
          $ref: '#/components/schemas/SandboxName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSandboxRequest'
      responses:
        '200':
          description: Sandbox updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteSandbox
      summary: Delete a Sandbox resource.
      tags: [sandboxes]
      parameters:
      - name: sandboxName
        in: path
        required: true
        description: Sandbox resource name.
        schema:
          $ref: '#/components/schemas/SandboxName'
      responses:
        '204':
          description: Sandbox deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/mcp-connection:
    get:
      operationId: listMCPConnections
      summary: List paginated MCPConnection resources.
      tags: [mcp-connections]
      parameters:
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated MCPConnections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMCPConnectionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createMCPConnection
      summary: Create an MCPConnection resource.
      tags: [mcp-connections]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMCPConnectionRequest'
      responses:
        '201':
          description: MCPConnection created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPConnectionDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/mcp-connection/{name}:
    get:
      operationId: getMCPConnection
      summary: Get an MCPConnection resource.
      tags: [mcp-connections]
      parameters:
      - $ref: '#/components/parameters/MCPConnectionNamePath'
      responses:
        '200':
          description: MCPConnection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPConnectionDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteMCPConnection
      summary: Delete an MCPConnection resource.
      tags: [mcp-connections]
      parameters:
      - $ref: '#/components/parameters/MCPConnectionNamePath'
      responses:
        '204':
          description: MCPConnection deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/mcp-connection/watch:
    post:
      operationId: watchMCPConnections
      summary: Watch MCP connection status changes.
      description: >
        Returns an SSE stream. Each event data payload is a JSON object matching
        WatchMCPConnectionsEvent. If names is omitted or empty, all MCP
        connections are watched.
      tags: [mcp-connections]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchMCPConnectionsRequest'
      responses:
        '200':
          description: Stream of MCP connection updates.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchMCPConnectionsEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}:
    get:
      operationId: listWorkflowSummaries
      summary: List workflow summaries.
      description: >
        Lists saved workflow metadata for a single agent without loading the
        full workflow graph.
      tags: [workflows]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      responses:
        '200':
          description: Workflow summaries for an agent.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkflowSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createWorkflow
      summary: Create a workflow definition.
      description: >
        Creates a normalized workflow DAG for a single agent. The workflow
        definition is stored as metadata, nodes, and edges, and later retrieval
        can derive a markdown execution playbook from the structured graph.
      tags: [workflows]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowRequest'
      responses:
        '201':
          description: Workflow created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteWorkflows
      summary: Delete workflow definitions.
      description: >
        Deletes multiple persisted workflow DAGs for an agent in a single
        request. Deletion is strict: if any requested workflow name does not
        exist, the request fails and no workflows are deleted.
      tags: [workflows]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteWorkflowsRequest'
      responses:
        '204':
          description: Workflows deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}:
    get:
      operationId: getWorkflow
      summary: Get a workflow definition.
      description: >
        Retrieves a persisted workflow DAG for a single agent. The response
        preserves the normalized workflow structure so clients can derive a
        detailed execution playbook from the graph.
      tags: [workflows]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      responses:
        '200':
          description: Workflow definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/schedule:
    get:
      operationId: listAgentWorkflowSchedules
      summary: List workflow schedules for an agent.
      description: >
        Lists paginated workflow schedules for an agent across all workflows.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated workflow schedules for an agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowSchedulesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/schedule:
    get:
      operationId: listWorkflowSchedules
      summary: List workflow schedules.
      description: >
        Lists paginated workflow schedules for a workflow definition.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated workflow schedules for a workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowSchedulesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createWorkflowSchedule
      summary: Create a workflow schedule.
      description: >
        Creates a WorkflowSchedule resource for an agent-workflow pair. The
        gateway forwards schedule validation to the existing Kubernetes webhook.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowScheduleRequest'
      responses:
        '201':
          description: Workflow schedule created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowSchedule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/schedule/{scheduleName}:
    put:
      operationId: updateWorkflowSchedule
      summary: Update a workflow schedule.
      description: >
        Replaces all mutable workflow schedule fields for an existing schedule.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: scheduleName
        in: path
        required: true
        description: WorkflowSchedule resource name.
        schema:
          $ref: '#/components/schemas/WorkflowScheduleName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkflowScheduleRequest'
      responses:
        '200':
          description: Workflow schedule updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowSchedule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteWorkflowSchedule
      summary: Delete a workflow schedule.
      description: >
        Deletes a workflow schedule addressed by agent, workflow, and
        schedule name.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: scheduleName
        in: path
        required: true
        description: WorkflowSchedule resource name.
        schema:
          $ref: '#/components/schemas/WorkflowScheduleName'
      responses:
        '204':
          description: Workflow schedule deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/schedule/{scheduleName}/run:
    post:
      operationId: createWorkflowRun
      summary: Trigger a workflow run from a workflow schedule.
      description: >
        Creates a WorkflowRun from the addressed WorkflowSchedule without
        overriding any schedule-derived execution fields.
      tags: [workflow-schedules]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: scheduleName
        in: path
        required: true
        description: WorkflowSchedule resource name.
        schema:
          $ref: '#/components/schemas/WorkflowScheduleName'
      responses:
        '202':
          description: Workflow run accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/webhook:
    post:
      operationId: invokeWorkflowWebhook
      summary: Trigger a workflow run through a webhook API key.
      description: >
        Validates the request body against the saved workflow input contract, then
        creates a direct WorkflowRun for the addressed tenant, agent, and
        workflow. Authentication uses the X-API-Key header.
      security:
      - GatewayAPIKey: []
      tags: [workflow-webhooks]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: timeout_seconds
        in: query
        required: false
        description: Timeout for the created WorkflowRun.
        schema:
          type: integer
          format: int32
          default: 3600
          minimum: 1
          maximum: 604800
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowRunInputs'
      responses:
        '202':
          description: Workflow run accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/webhook:
    get:
      operationId: listWorkflowWebhookTriggers
      summary: List webhook trigger rows for an agent.
      description: >
        Lists the distinct API key and workflow pairs that have produced at
        least a webhook-triggered WorkflowRun for the addressed agent.
      tags: [workflow-webhooks]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated webhook trigger rows for an agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowWebhookTriggersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run:
    get:
      operationId: listWorkflowRuns
      summary: List workflow runs for a workflow.
      description: >
        Lists paginated WorkflowRuns for an agent-workflow pair. Optional
        trigger filters narrow the results to schedule-triggered or
        webhook-triggered runs.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: status
        in: query
        required: false
        description: Optional WorkflowRun phase filter.
        schema:
          $ref: '#/components/schemas/WorkflowRunStatus'
      - name: trigger_type
        in: query
        required: false
        description: Optional workflow trigger type filter.
        schema:
          $ref: '#/components/schemas/WorkflowRunTriggerType'
      - name: schedule_name
        in: query
        required: false
        description: >
          Optional schedule filter. When set, trigger_type must be Schedule.
        schema:
          $ref: '#/components/schemas/WorkflowScheduleName'
      - name: webhook_api_key_id
        in: query
        required: false
        description: >
          Optional webhook API key filter. When set, trigger_type must be
          Webhook.
        schema:
          $ref: '#/components/schemas/APIKeyID'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/PageTokenQuery'
      responses:
        '200':
          description: Paginated workflow runs for a workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowRunsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run/watch:
    post:
      operationId: watchWorkflowRuns
      summary: Watch workflow runs for a workflow.
      description: >
        Returns an SSE stream. Each event data payload is a JSON object matching
        WatchWorkflowRunsEvent. If run_names is omitted or empty, all runs for
        the addressed workflow are watched.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchWorkflowRunsRequest'
      responses:
        '200':
          description: Stream of workflow run updates.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/WatchWorkflowRunsEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run/{runName}:
    get:
      operationId: getWorkflowRun
      summary: Get a workflow run.
      description: >
        Returns all public details for a WorkflowRun owned by the addressed
        agent-workflow pair.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: runName
        in: path
        required: true
        description: WorkflowRun resource name.
        schema:
          $ref: '#/components/schemas/WorkflowRunName'
      responses:
        '200':
          description: Workflow run details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteWorkflowRun
      summary: Delete a workflow run.
      description: >
        Deletes a WorkflowRun owned by the addressed agent-workflow pair and
        waits until controller-driven cleanup completes.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: runName
        in: path
        required: true
        description: WorkflowRun resource name.
        schema:
          $ref: '#/components/schemas/WorkflowRunName'
      responses:
        '204':
          description: Workflow run deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run/{runName}/status:
    patch:
      operationId: patchWorkflowRunStatus
      summary: Set a WorkflowRun terminal status.
      description: >
        Marks a running WorkflowRun as succeeded or failed. The gateway owns
        request validation and state-transition checks, then patches the
        WorkflowRun status in the configured namespace.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: runName
        in: path
        required: true
        description: WorkflowRun resource name.
        schema:
          $ref: '#/components/schemas/WorkflowRunName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchWorkflowRunStatusRequest'
      responses:
        '204':
          description: WorkflowRun status updated.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

  /api/workflow/{agentName}/{workflowName}/run/{runName}/nodes/{nodeName}/status:
    patch:
      operationId: patchWorkflowRunNodeStatus
      summary: Set a WorkflowRun node status.
      description: >
        Records execution progress for one WorkflowRun node. The gateway
        validates node membership and basic state transitions before patching
        the WorkflowRun status in the configured namespace.
      tags: [workflow-runs]
      parameters:
      - $ref: '#/components/parameters/AgentNamePath'
      - name: workflowName
        in: path
        required: true
        description: Workflow name scoped to an agent.
        schema:
          $ref: '#/components/schemas/WorkflowName'
      - name: runName
        in: path
        required: true
        description: WorkflowRun resource name.
        schema:
          $ref: '#/components/schemas/WorkflowRunName'
      - name: nodeName
        in: path
        required: true
        description: Workflow node name.
        schema:
          $ref: '#/components/schemas/WorkflowNodeName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchWorkflowRunNodeStatusRequest'
      responses:
        '204':
          description: WorkflowRun node status updated.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  securitySchemes:
    GatewayBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
    GatewayAPIKey:
      type: apiKey
      in: header
      name: X-API-Key
  parameters:
    AgentNameQuery:
      name: agent_name
      in: query
      required: true
      description: Agent name.
      schema:
        $ref: '#/components/schemas/AgentName'

    AgentNameQueryOptional:
      name: agent_name
      in: query
      required: false
      description: Optional Agent name.
      schema:
        $ref: '#/components/schemas/AgentName'

    AgentNamePath:
      name: agentName
      in: path
      required: true
      description: Agent name.
      schema:
        $ref: '#/components/schemas/AgentName'

    SandboxNamePath:
      name: name
      in: path
      required: true
      description: Sandbox name.
      schema:
        $ref: '#/components/schemas/SandboxName'

    SkillNamePath:
      name: skillName
      in: path
      required: true
      description: Skill name.
      schema:
        $ref: '#/components/schemas/SkillName'

    MCPConnectionNamePath:
      name: name
      in: path
      required: true
      description: MCPConnection name.
      schema:
        $ref: '#/components/schemas/MCPConnectionName'

    AgentNameFilterQuery:
      name: agent_name
      in: query
      required: false
      description: Optional agent name filters. Repeat the query parameter for multiple agents.
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/AgentName'

    LimitQuery:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 200
        default: 50

    PageTokenQuery:
      name: page_token
      in: query
      required: false
      description: Opaque pagination token from a previous response.
      schema:
        type: string
        minLength: 1

    UpdateSandboxQuery:
      name: update_sandbox
      in: query
      required: false
      description: >
        When true, append compatible secret hosts that are missing from the
        agent sandbox allowed host list before creating the secret.
      schema:
        type: boolean
        default: false

    TraceIDQuery:
      name: trace_id
      in: query
      required: true
      description: Lowercase hexadecimal OTLP trace ID.
      schema:
        $ref: '#/components/schemas/TraceID'

    SpanIDQuery:
      name: span_id
      in: query
      required: true
      description: Lowercase hexadecimal OTLP span ID.
      schema:
        $ref: '#/components/schemas/SpanID'

    SessionIDQuery:
      name: session_id
      in: query
      required: false
      description: Optional root session ID.
      schema:
        type: string
        minLength: 1

    StartedAfterQuery:
      name: started_after
      in: query
      required: false
      description: Inclusive lower bound for trace start time.
      schema:
        type: string
        format: date-time

    StartedBeforeQuery:
      name: started_before
      in: query
      required: false
      description: Inclusive upper bound for trace start time.
      schema:
        type: string
        format: date-time

    EventTimeAfterQuery:
      name: event_time_after
      in: query
      required: false
      description: Inclusive lower bound for event time.
      schema:
        type: string
        format: date-time

    EventTimeBeforeQuery:
      name: event_time_before
      in: query
      required: false
      description: Inclusive upper bound for event time.
      schema:
        type: string
        format: date-time

    ActionQuery:
      name: action
      in: query
      required: false
      description: Optional observability action filter.
      schema:
        $ref: '#/components/schemas/ObservabilityAction'

    AggregatedQuery:
      name: aggregated
      in: query
      required: false
      description: When true, returns aggregated events with occurrence counts over the time range.
      schema:
        type: boolean
        default: false

    FromDateQuery:
      name: from
      in: query
      required: true
      description: Inclusive lower bound for MCP tool activity date.
      schema:
        type: string
        format: date

    ToDateQuery:
      name: to
      in: query
      required: true
      description: Inclusive upper bound for MCP tool activity date.
      schema:
        type: string
        format: date

  responses:
    BadRequest:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Request authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: >
        Requested resource was not found. For tenant-gated APIs this can also
        mean the current tenant is not initialized and the error code is
        `tenant_not_found`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >
        Request conflicts with current state. For tenant-gated APIs this can
        also mean the current tenant is still bootstrapping and the error code
        is `tenant_not_ready`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    TraceID:
      type: string
      minLength: 32
      maxLength: 32
      pattern: '^[0-9a-f]{32}$'
      description: Lowercase hexadecimal OTLP trace ID.

    SpanID:
      type: string
      minLength: 16
      maxLength: 16
      pattern: '^[0-9a-f]{16}$'
      description: Lowercase hexadecimal OTLP span ID.

    OptionalSpanID:
      type: string
      maxLength: 16
      pattern: '^([0-9a-f]{16})?$'
      description: Lowercase hexadecimal OTLP span ID, or empty for root spans.

    TenantPhase:
      type: string
      enum: [BOOTSTRAPPING, READY, FAILED]

    TenantCondition:
      type: object
      required: [type, status, reason, message]
      properties:
        type:
          type: string
        status:
          type: string
          enum: ['True', 'False', 'Unknown']
        reason:
          type: string
        message:
          type: string

    Tenant:
      type: object
      required: [tenant_id, user_id, namespace, ready, phase, conditions]
      properties:
        tenant_id:
          type: string
        user_id:
          type: string
        namespace:
          type: string
        ready:
          type: boolean
        phase:
          $ref: '#/components/schemas/TenantPhase'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/TenantCondition'

    ObservabilityAction:
      type: string
      enum: [Allowed, Blocked]

    AgentName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'

    SandboxName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Sandbox resource name.

    SkillName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Immutable Skill resource name.

    MCPConnectionName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: MCPConnection resource name.

    WorkflowName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Workflow name scoped to an agent.

    WorkflowScheduleName:
      type: string
      minLength: 1
      maxLength: 32
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: WorkflowSchedule resource name.

    WorkflowRunName:
      type: string
      minLength: 1
      maxLength: 253
      pattern: '^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$'
      description: WorkflowRun resource name.

    WorkflowNodeName:
      type: string
      minLength: 1
      maxLength: 64
      pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
      description: Stable workflow node identifier.

    Error:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          minLength: 1
        message:
          type: string
          minLength: 1
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
        details:
          $ref: '#/components/schemas/JSONValue'
      required: [code, message]

    FieldError:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          minLength: 1
        message:
          type: string
          minLength: 1
      required: [field, message]

    WorkflowRunTerminalPhase:
      type: string
      enum:
      - Succeeded
      - Failed

    WorkflowRunNodePhase:
      type: string
      enum:
      - Disabled
      - Running
      - Unacked
      - Succeeded
      - Failed

    WorkflowRunNodePatchPhase:
      type: string
      enum:
      - Running
      - Succeeded
      - Failed

    WorkflowRunStatus:
      type: string
      enum:
      - Pending
      - Running
      - Succeeded
      - Failed
      - Unacked

    PatchWorkflowRunStatusRequest:
      type: object
      additionalProperties: false
      properties:
        phase:
          $ref: '#/components/schemas/WorkflowRunTerminalPhase'
        message:
          type: string
          maxLength: 4096
      required: [phase]

    PatchWorkflowRunNodeStatusRequest:
      type: object
      additionalProperties: false
      properties:
        phase:
          $ref: '#/components/schemas/WorkflowRunNodePatchPhase'
        message:
          type: string
          maxLength: 4096
      required: [phase]

    ListAgentsResponse:
      type: object
      additionalProperties: false
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
        next_page_token:
          type: string
      required: [agents, next_page_token]

    ListSkillsResponse:
      type: object
      additionalProperties: false
      properties:
        skills:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
        next_page_token:
          type: string
      required: [skills, next_page_token]

    ListWorkflowSchedulesResponse:
      type: object
      additionalProperties: false
      properties:
        workflow_schedules:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowSchedule'
        next_page_token:
          type: string
      required: [workflow_schedules, next_page_token]

    ListWorkflowRunsResponse:
      type: object
      additionalProperties: false
      properties:
        workflow_runs:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRunSummary'
        next_page_token:
          type: string
      required: [workflow_runs, next_page_token]

    ListWorkflowWebhookTriggersResponse:
      type: object
      additionalProperties: false
      properties:
        webhook_triggers:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowWebhookTrigger'
        next_page_token:
          type: string
      required: [webhook_triggers, next_page_token]

    Agent:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AgentName'
        sandboxName:
          $ref: '#/components/schemas/SandboxName'
        last_activity:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
        home_storage_prefix:
          type: string
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillName'
        status:
          $ref: '#/components/schemas/AgentStatus'
      required:
      - name
      - sandboxName
      - last_activity
      - created_at
      - modified_at
      - home_storage_prefix
      - skills
      - status

    Skill:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SkillName'
        description:
          type: string
          minLength: 1
          maxLength: 1024
        version:
          type: integer
          format: int64
          minimum: 1
        storage_path:
          type: string
          minLength: 1
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentName'
        sandboxes:
          type: array
          items:
            $ref: '#/components/schemas/SandboxName'
        created_at:
          type: string
          format: date-time
      required:
      - name
      - description
      - version
      - storage_path
      - agents
      - sandboxes
      - created_at

    SkillReferences:
      type: object
      additionalProperties: false
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentName'
        sandboxes:
          type: array
          items:
            $ref: '#/components/schemas/SandboxName'
      required: [agents, sandboxes]

    CreateSkillRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SkillName'
        description:
          type: string
          minLength: 1
          maxLength: 1024
        version:
          type: integer
          format: int64
          minimum: 1
        storage_path:
          type: string
          minLength: 1
      required: [name, description, version, storage_path]

    UpdateSkillRequest:
      type: object
      additionalProperties: false
      properties:
        description:
          type: string
          minLength: 1
          maxLength: 1024
        version:
          type: integer
          format: int64
          minimum: 1
        storage_path:
          type: string
          minLength: 1
      required: [version, storage_path]

    AgentStatus:
      type: string
      enum:
      - UNSPECIFIED
      - PROGRESSING
      - DEGRADED
      - DELETED
      - IDLE

    CreateAgentRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AgentName'
        env:
          type: object
          additionalProperties:
            type: string
        sandboxName:
          $ref: '#/components/schemas/SandboxName'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillName'
        opencode:
          $ref: '#/components/schemas/AgentOpencodeConfig'
      required: [name, sandboxName]

    CreateWorkflowRequest:
      type: object
      additionalProperties: false
      properties:
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        title:
          type: string
          minLength: 1
          maxLength: 256
        summary:
          type: string
          minLength: 1
          maxLength: 4096
        inputs:
          $ref: '#/components/schemas/WorkflowInputs'
        arbitrary_json:
          $ref: '#/components/schemas/WorkflowArbitraryJSON'
        nodes:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WorkflowNode'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowEdge'
      required:
      - workflow_name
      - title
      - summary
      - nodes
      - edges

    Workflow:
      type: object
      additionalProperties: false
      properties:
        agent_name:
          $ref: '#/components/schemas/AgentName'
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        title:
          type: string
        summary:
          type: string
        inputs:
          $ref: '#/components/schemas/WorkflowInputs'
        arbitrary_json:
          $ref: '#/components/schemas/WorkflowArbitraryJSON'
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNode'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowEdge'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - agent_name
      - workflow_name
      - title
      - summary
      - nodes
      - edges
      - created_at
      - updated_at

    WorkflowSchedule:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowScheduleName'
        agent_name:
          $ref: '#/components/schemas/AgentName'
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        schedule:
          type: string
          minLength: 1
        time_zone:
          type: string
        inputs:
          $ref: '#/components/schemas/JSONValue'
        timeout_seconds:
          type: integer
          format: int32
          minimum: 1
          maximum: 604800
        suspend:
          type: boolean
        successful_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
        failed_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
        created_at:
          type: string
          format: date-time
      required:
      - name
      - agent_name
      - workflow_name
      - schedule
      - timeout_seconds
      - inputs
      - suspend
      - successful_runs_history_limit
      - failed_runs_history_limit
      - created_at

    APIKeyID:
      type: string
      minLength: 1
      description: Better Auth API key identifier.

    WorkflowRunInputs:
      $ref: '#/components/schemas/JSONValue'
      description: >
        Runtime workflow input values. The gateway validates this value against
        the saved workflow input contract before creating a WorkflowRun.

    WorkflowRunTriggerType:
      type: string
      enum:
      - Schedule
      - Webhook

    WorkflowRunSummary:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowRunName'
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        trigger_type:
          $ref: '#/components/schemas/WorkflowRunTriggerType'
        schedule_name:
          $ref: '#/components/schemas/WorkflowScheduleName'
        status:
          $ref: '#/components/schemas/WorkflowRunStatus'
        reason:
          type: string
        created_at:
          type: string
          format: date-time
        duration_seconds:
          type: integer
          format: int64
          minimum: 0
      required:
      - name
      - workflow_name
      - trigger_type
      - status
      - reason
      - created_at

    WorkflowRunDetail:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowRunName'
        agent_name:
          $ref: '#/components/schemas/AgentName'
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        trigger_type:
          $ref: '#/components/schemas/WorkflowRunTriggerType'
        schedule_name:
          $ref: '#/components/schemas/WorkflowScheduleName'
        inputs:
          $ref: '#/components/schemas/JSONValue'
        timeout_seconds:
          type: integer
          format: int32
          minimum: 1
          maximum: 604800
        status:
          $ref: '#/components/schemas/WorkflowRunStatus'
        reason:
          type: string
        message:
          type: string
        session_id:
          type: string
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        duration_seconds:
          type: integer
          format: int64
          minimum: 0
        node_statuses:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRunNodeStatus'
      required:
      - name
      - agent_name
      - workflow_name
      - trigger_type
      - inputs
      - timeout_seconds
      - status
      - reason
      - message
      - created_at
      - node_statuses

    WorkflowRunNodeStatus:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowNodeName'
        phase:
          $ref: '#/components/schemas/WorkflowRunNodePhase'
        message:
          type: string
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
      required:
      - name
      - phase
      - message

    WorkflowWebhookTrigger:
      type: object
      additionalProperties: false
      properties:
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        api_key_id:
          $ref: '#/components/schemas/APIKeyID'
        last_triggered_at:
          type: string
          format: date-time
      required:
      - workflow_name
      - api_key_id
      - last_triggered_at

    CreateWorkflowScheduleRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowScheduleName'
        schedule:
          type: string
          minLength: 1
        time_zone:
          type: string
        inputs:
          $ref: '#/components/schemas/JSONValue'
        timeout_seconds:
          type: integer
          format: int32
          minimum: 1
          maximum: 604800
        suspend:
          type: boolean
        successful_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
        failed_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
      required:
      - name
      - schedule
      - timeout_seconds

    UpdateWorkflowScheduleRequest:
      type: object
      additionalProperties: false
      properties:
        schedule:
          type: string
          minLength: 1
        time_zone:
          type: string
        inputs:
          $ref: '#/components/schemas/JSONValue'
        timeout_seconds:
          type: integer
          format: int32
          minimum: 1
          maximum: 604800
        suspend:
          type: boolean
        successful_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
        failed_runs_history_limit:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
      required:
      - schedule
      - timeout_seconds

    WorkflowSummary:
      type: object
      additionalProperties: false
      properties:
        workflow_name:
          $ref: '#/components/schemas/WorkflowName'
        title:
          type: string
        summary:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - workflow_name
      - title
      - summary
      - updated_at

    WorkflowNode:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/WorkflowNodeName'
        instructions:
          type: string
          minLength: 1
          maxLength: 16384
        goal:
          type: string
          minLength: 1
          maxLength: 2048
        done_criteria:
          type: string
          minLength: 1
          maxLength: 2048
        preferred_skills:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
            pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
        preferred_tools:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 128
      required:
      - name
      - instructions
      - goal
      - done_criteria

    WorkflowEdge:
      type: object
      additionalProperties: false
      properties:
        source:
          $ref: '#/components/schemas/WorkflowNodeName'
        target:
          $ref: '#/components/schemas/WorkflowNodeName'
        branch_label:
          type: string
          maxLength: 256
        condition_summary:
          type: string
          maxLength: 1024
      required:
      - source
      - target
      - branch_label
      - condition_summary

    WorkflowInputs:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/WorkflowInputSchema'

    WorkflowArbitraryJSON:
      type: object
      additionalProperties: false
      description: >
        Arbitrary JSON workflow input contract. Use this instead of typed
        workflow inputs when a workflow should accept one free-form JSON
        payload.
      properties:
        description:
          type: string
          minLength: 1
        default_payload:
          allOf:
          - $ref: '#/components/schemas/JSONValue'
          x-omitempty: true

    WorkflowInputStringFormat:
      type: string
      enum:
      - email
      - uri
      - uuid
      - date
      - date-time

    WorkflowInputType:
      type: string
      enum:
      - string
      - integer
      - number
      - boolean

    WorkflowInputScalarValue:
      oneOf:
      - type: boolean
      - type: number
        format: double
      - type: string

    WorkflowInputSchema:
      type: object
      additionalProperties: false
      description: |
        Per-input validation schema. Only these keys are accepted: type,
        description, required, default, enum, minLength, maxLength, pattern,
        format, minimum, maximum, exclusiveMinimum, exclusiveMaximum, and
        multipleOf. Extra JSON Schema metadata is not supported.
      properties:
        type:
          $ref: '#/components/schemas/WorkflowInputType'
        description:
          type: string
          minLength: 1
        required:
          type: boolean
        default:
          $ref: '#/components/schemas/WorkflowInputScalarValue'
        enum:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/WorkflowInputScalarValue'
        minLength:
          type: integer
          minimum: 0
        maxLength:
          type: integer
          minimum: 0
        pattern:
          type: string
          minLength: 1
        format:
          $ref: '#/components/schemas/WorkflowInputStringFormat'
        minimum:
          type: number
          format: double
        maximum:
          type: number
          format: double
        exclusiveMinimum:
          type: number
          format: double
        exclusiveMaximum:
          type: number
          format: double
        multipleOf:
          type: number
          format: double
          minimum: 0
          exclusiveMinimum: true
      required:
      - type
      - required

    DeleteWorkflowsRequest:
      type: object
      additionalProperties: false
      properties:
        workflow_names:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WorkflowName'
      required: [workflow_names]

    UpdateAgentRequest:
      type: object
      additionalProperties: false
      properties:
        env:
          type: object
          additionalProperties:
            type: string
        sandboxName:
          $ref: '#/components/schemas/SandboxName'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillName'
        opencode:
          $ref: '#/components/schemas/AgentOpencodeConfig'
      minProperties: 1

    AgentOpencodeConfig:
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
        smallModel:
          type: string
        instruction:
          type: string
          maxLength: 4096
        providers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentOpencodeProviderConfig'

    AgentOpencodeProviderConfig:
      type: object
      additionalProperties: false
      properties:
        env:
          type: array
          items:
            type: string
        baseURL:
          type: string

    ListTracesResponse:
      type: object
      additionalProperties: false
      properties:
        traces:
          type: array
          items:
            $ref: '#/components/schemas/Trace'
        next_page_token:
          type: string
      required: [traces, next_page_token]

    ListTraceSessionsResponse:
      type: object
      additionalProperties: false
      properties:
        trace_sessions:
          type: array
          items:
            $ref: '#/components/schemas/TraceSession'
        next_page_token:
          type: string
      required: [trace_sessions, next_page_token]

    Trace:
      type: object
      additionalProperties: false
      properties:
        trace_id:
          $ref: '#/components/schemas/TraceID'
        agent_name:
          $ref: '#/components/schemas/AgentName'
        root_span_id:
          $ref: '#/components/schemas/OptionalSpanID'
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        duration_ns:
          type: integer
          format: int64
          minimum: 0
        duration_ms:
          type: number
          format: double
          minimum: 0
        span_count:
          type: integer
          format: int64
          minimum: 0
        error_count:
          type: integer
          format: int64
          minimum: 0
        tool_count:
          type: integer
          format: int64
          minimum: 0
        model_count:
          type: integer
          format: int64
          minimum: 0
        input_tokens:
          type: integer
          format: int64
          minimum: 0
        output_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_input_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_write_tokens:
          type: integer
          format: int64
          minimum: 0
        cost_usd:
          type: number
          format: double
          minimum: 0
        status_code:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - trace_id
      - agent_name
      - root_span_id
      - started_at
      - ended_at
      - duration_ns
      - duration_ms
      - span_count
      - error_count
      - tool_count
      - model_count
      - input_tokens
      - output_tokens
      - cached_input_tokens
      - cached_write_tokens
      - cost_usd
      - status_code
      - updated_at

    TraceSession:
      type: object
      additionalProperties: false
      properties:
        trace_id:
          $ref: '#/components/schemas/TraceID'
        session_id:
          type: string
        agent_name:
          $ref: '#/components/schemas/AgentName'
        root_span_id:
          $ref: '#/components/schemas/OptionalSpanID'
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        duration_ns:
          type: integer
          format: int64
          minimum: 0
        duration_ms:
          type: number
          format: double
          minimum: 0
        span_count:
          type: integer
          format: int64
          minimum: 0
        error_count:
          type: integer
          format: int64
          minimum: 0
        tool_count:
          type: integer
          format: int64
          minimum: 0
        model_count:
          type: integer
          format: int64
          minimum: 0
        input_tokens:
          type: integer
          format: int64
          minimum: 0
        output_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_input_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_write_tokens:
          type: integer
          format: int64
          minimum: 0
        cost_usd:
          type: number
          format: double
          minimum: 0
        status_code:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - trace_id
      - session_id
      - agent_name
      - root_span_id
      - started_at
      - ended_at
      - duration_ns
      - duration_ms
      - span_count
      - error_count
      - tool_count
      - model_count
      - input_tokens
      - output_tokens
      - cached_input_tokens
      - cached_write_tokens
      - cost_usd
      - status_code
      - updated_at

    ListSpansResponse:
      type: object
      additionalProperties: false
      properties:
        spans:
          type: array
          items:
            $ref: '#/components/schemas/Span'
        next_page_token:
          type: string
      required: [spans, next_page_token]

    Span:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
        agent_name:
          $ref: '#/components/schemas/AgentName'
        session_id:
          type: string
        trace_id:
          $ref: '#/components/schemas/TraceID'
        span_id:
          $ref: '#/components/schemas/SpanID'
        parent_span_id:
          $ref: '#/components/schemas/OptionalSpanID'
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        duration_ns:
          type: integer
          format: int64
          minimum: 0
        duration_ms:
          type: number
          format: double
          minimum: 0
        name:
          type: string
        span_class:
          type: string
        operation_name:
          type: string
        kind:
          type: string
        status_code:
          type: string
        error_type:
          type: string
        error_message:
          type: string
        model:
          type: string
        tool_name:
          type: string
        input_tokens:
          type: integer
          format: int64
          minimum: 0
        output_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_input_tokens:
          type: integer
          format: int64
          minimum: 0
        cached_write_tokens:
          type: integer
          format: int64
          minimum: 0
        cost_usd:
          type: number
          format: double
          minimum: 0
        llm_finish_reason:
          type: string
        ingested_at:
          type: string
          format: date-time
      required:
      - id
      - agent_name
      - session_id
      - trace_id
      - span_id
      - parent_span_id
      - start_time
      - end_time
      - duration_ns
      - duration_ms
      - name
      - span_class
      - operation_name
      - kind
      - status_code
      - error_type
      - error_message
      - model
      - tool_name
      - input_tokens
      - output_tokens
      - cached_input_tokens
      - cached_write_tokens
      - cost_usd
      - llm_finish_reason
      - ingested_at

    SpanDetail:
      allOf:
      - $ref: '#/components/schemas/Span'
      - type: object
        additionalProperties: false
        properties:
          resource_attributes:
            $ref: '#/components/schemas/JSONValue'
          span_attributes:
            $ref: '#/components/schemas/JSONValue'
        required:
        - resource_attributes
        - span_attributes

    SpanPayload:
      type: object
      additionalProperties: false
      properties:
        input_messages:
          $ref: '#/components/schemas/JSONValue'
        output_messages:
          $ref: '#/components/schemas/JSONValue'
        tool_arguments:
          $ref: '#/components/schemas/JSONValue'
        tool_result:
          $ref: '#/components/schemas/JSONValue'
      required:
      - input_messages
      - output_messages
      - tool_arguments
      - tool_result

    MCPGraphResponse:
      type: object
      additionalProperties: false
      properties:
        agent:
          $ref: '#/components/schemas/MCPGraphAgent'
        connections:
          type: array
          items:
            $ref: '#/components/schemas/MCPGraphConnection'
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPGraphTool'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/MCPGraphEdge'
      required: [agent, connections, tools, edges]

    MCPGraphAgent:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AgentName'
      required: [name]

    MCPGraphConnection:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        server_url:
          type: string
          format: uri
      required: [id, name]

    MCPGraphTool:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        connection_id:
          type: string
        name:
          type: string
      required: [id, connection_id, name]

    MCPGraphEdge:
      type: object
      additionalProperties: false
      properties:
        source:
          type: string
        target:
          type: string
        kind:
          type: string
          enum: [agent_connection, connection_tool]
        avg_latency_ms:
          type: number
          format: double
          minimum: 0
        success_count:
          type: integer
          format: int64
          minimum: 0
        failed_count:
          type: integer
          format: int64
          minimum: 0
        last_called_at:
          type: string
          format: date-time
      required:
      - source
      - target
      - kind

    SpanDetailResponse:
      type: object
      additionalProperties: false
      properties:
        span:
          $ref: '#/components/schemas/SpanDetail'
        payload:
          $ref: '#/components/schemas/SpanPayload'
      required: [span, payload]

    ListProcessObservabilityResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/ProcessObservabilityEvent'
            - $ref: '#/components/schemas/ProcessObservabilityEventAggregated'
        next_page_token:
          type: string
      required: [events, next_page_token]

    ProcessObservabilityEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
        agent_name:
          $ref: '#/components/schemas/AgentName'
        event_time:
          type: string
          format: date-time
        ingested_at:
          type: string
          format: date-time
        pod_namespace:
          type: string
        pod_name:
          type: string
        process:
          type: string
        parent_process:
          type: string
        command_invocation:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
      required:
      - id
      - agent_name
      - event_time
      - ingested_at
      - pod_namespace
      - pod_name
      - process
      - parent_process
      - command_invocation
      - action
      - source

    ProcessObservabilityEventAggregated:
      type: object
      additionalProperties: false
      properties:
        agent_name:
          $ref: '#/components/schemas/AgentName'
        last_seen:
          type: string
          format: date-time
        process:
          type: string
        parent_process:
          type: string
        command_invocation:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
        occurrences:
          type: integer
          format: int64
          minimum: 1
      required:
      - agent_name
      - last_seen
      - process
      - parent_process
      - command_invocation
      - action
      - source
      - occurrences

    ListFileObservabilityResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/FileObservabilityEvent'
            - $ref: '#/components/schemas/FileObservabilityEventAggregated'
        next_page_token:
          type: string
      required: [events, next_page_token]

    FileObservabilityEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
        agent_name:
          $ref: '#/components/schemas/AgentName'
        event_time:
          type: string
          format: date-time
        ingested_at:
          type: string
          format: date-time
        pod_namespace:
          type: string
        pod_name:
          type: string
        file_path_accessed:
          type: string
        process:
          type: string
        command_invocation:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
      required:
      - id
      - agent_name
      - event_time
      - ingested_at
      - pod_namespace
      - pod_name
      - file_path_accessed
      - process
      - command_invocation
      - action
      - source

    FileObservabilityEventAggregated:
      type: object
      additionalProperties: false
      properties:
        agent_name:
          $ref: '#/components/schemas/AgentName'
        last_seen:
          type: string
          format: date-time
        file_path_accessed:
          type: string
        process:
          type: string
        command_invocation:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
        occurrences:
          type: integer
          format: int64
          minimum: 1
      required:
      - agent_name
      - last_seen
      - file_path_accessed
      - process
      - command_invocation
      - action
      - source
      - occurrences

    ListNetworkObservabilityResponse:
      type: object
      additionalProperties: false
      properties:
        events:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/NetworkObservabilityEvent'
            - $ref: '#/components/schemas/NetworkObservabilityEventAggregated'
        next_page_token:
          type: string
      required: [events, next_page_token]

    NetworkObservabilityEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
        agent_name:
          $ref: '#/components/schemas/AgentName'
        event_time:
          type: string
          format: date-time
        ingested_at:
          type: string
          format: date-time
        pod_namespace:
          type: string
        pod_name:
          type: string
        destination_domain:
          type: string
        destination_ip:
          type: string
        destination_port:
          type: integer
          format: int64
          minimum: 0
        protocol:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
      required:
      - id
      - agent_name
      - event_time
      - ingested_at
      - pod_namespace
      - pod_name
      - destination_domain
      - destination_ip
      - destination_port
      - protocol
      - action
      - source

    NetworkObservabilityEventAggregated:
      type: object
      additionalProperties: false
      properties:
        agent_name:
          $ref: '#/components/schemas/AgentName'
        last_seen:
          type: string
          format: date-time
        destination_domain:
          type: string
        destination_ip:
          type: string
        destination_port:
          type: integer
          format: int64
          minimum: 0
        protocol:
          type: string
        action:
          $ref: '#/components/schemas/ObservabilityAction'
        source:
          type: string
        occurrences:
          type: integer
          format: int64
          minimum: 1
      required:
      - agent_name
      - last_seen
      - destination_domain
      - destination_ip
      - destination_port
      - protocol
      - action
      - source
      - occurrences

    WatchAgentsRequest:
      type: object
      additionalProperties: false
      properties:
        agent_names:
          type: array
          items:
            $ref: '#/components/schemas/AgentName'
          uniqueItems: true

    WatchAgentsEvent:
      type: object
      additionalProperties: false
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
      required: [agents]

    WatchWorkflowRunsRequest:
      type: object
      additionalProperties: false
      properties:
        run_names:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRunName'
          uniqueItems: true

    WatchWorkflowRunsEvent:
      type: object
      additionalProperties: false
      properties:
        workflow_runs:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRunDetail'
      required: [workflow_runs]

    JSONValue:
      nullable: true
      oneOf:
      - type: boolean
      - type: number
      - type: string
      - type: array
        items:
          $ref: '#/components/schemas/JSONValue'
      - type: object
        additionalProperties:
          $ref: '#/components/schemas/JSONValue'

    JSONObject:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/JSONValue'

    SecretKey:
      type: string
      minLength: 1
      maxLength: 128
      pattern: '^[A-Za-z_][A-Za-z0-9_]*$'
      description: Secret key name. Must be a valid environment variable name.

    SecretValue:
      type: string
      maxLength: 49152
      description: Secret value. Max 48 KB.

    SecretHost:
      type: string
      minLength: 1
      maxLength: 253
      description: >
        Allowed request host. Use an exact hostname, wildcard hostname with a
        leading "*." or "**.", exact IPv4/IPv6 address, or IPv4/IPv6 CIDR
        range. "*." matches exactly a subdomain label, while "**." matches
        any subdomain depth. Wildcards do not match the apex domain.

    SecretType:
      type: string
      enum: [static, oauth]

    SecretState:
      type: string
      enum: [accepted, ready, degraded]

    SecretOAuthConfig:
      type: object
      additionalProperties: false
      properties:
        provider:
          type: string
        issuer:
          type: string
          format: uri
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        registration_endpoint:
          type: string
          format: uri
        resource:
          type: string
          format: uri
        scopes:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
      required: [token_endpoint, scopes]

    SecretOAuthCredentials:
      type: object
      additionalProperties: false
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        access_token:
          type: string
        refresh_token:
          type: string
        expires_at:
          type: string
          format: date-time
        token_type:
          type: string
        scopes:
          type: array
          items:
            type: string
            minLength: 1
        registration:
          $ref: '#/components/schemas/JSONObject'
        revocation:
          $ref: '#/components/schemas/JSONObject'

    CreateSecretRequest:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/SecretType'
        key:
          $ref: '#/components/schemas/SecretKey'
        hosts:
          type: array
          items:
            $ref: '#/components/schemas/SecretHost'
          minItems: 1
          maxItems: 100
        value:
          $ref: '#/components/schemas/SecretValue'
        oauth:
          allOf:
          - $ref: '#/components/schemas/SecretOAuthConfig'
          - type: object
            additionalProperties: false
            properties:
              credentials:
                $ref: '#/components/schemas/SecretOAuthCredentials'
            required: [credentials]
      required: [type, key, hosts]

    SecretListItem:
      type: object
      additionalProperties: false
      properties:
        key:
          $ref: '#/components/schemas/SecretKey'
        type:
          $ref: '#/components/schemas/SecretType'
        hosts:
          type: array
          items:
            $ref: '#/components/schemas/SecretHost'
        provider:
          type: string
        status:
          $ref: '#/components/schemas/SecretState'
        reason:
          type: string
        message:
          type: string
        created_at:
          type: string
          format: date-time
        last_refresh_time:
          type: string
          format: date-time
        token_expiry_time:
          type: string
          format: date-time
      required: [key, type, hosts, status, reason, message, created_at]

    PutSecretsResponse:
      type: object
      additionalProperties: false
      properties:
        secret:
          $ref: '#/components/schemas/SecretListItem'
      required: [secret]

    DeleteSecretsRequest:
      type: object
      additionalProperties: false
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/SecretKey'
          maxItems: 100
      required: [keys]

    ListSecretsResponse:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SecretListItem'
        next_page_token:
          type: string
      required: [items, next_page_token]

    WatchSecretsRequest:
      type: object
      additionalProperties: false
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/SecretKey'
          uniqueItems: true

    WatchSecretsEvent:
      type: object
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SecretListItem'
      required: [items]

    Sandbox:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SandboxName'
        packages:
          type: array
          items:
            type: string
            minLength: 1
        allowed_hosts:
          type: array
          items:
            type: string
            minLength: 1
        mcp_connection_refs:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionRef'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillName'
        created_at:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: false
          properties:
            package_count:
              type: integer
              format: int32
              minimum: 0
            allowed_host_count:
              type: integer
              format: int32
              minimum: 0
            skill_count:
              type: integer
              format: int32
              minimum: 0
            referenced_by_agent:
              type: boolean
          required: [package_count, allowed_host_count, skill_count, referenced_by_agent]
      required: [name, packages, allowed_hosts, mcp_connection_refs, skills, created_at, metadata]

    ListSandboxesResponse:
      type: object
      additionalProperties: false
      properties:
        sandboxes:
          type: array
          items:
            $ref: '#/components/schemas/Sandbox'
        next_page_token:
          type: string
      required: [sandboxes, next_page_token]

    CreateSandboxRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/SandboxName'
        packages:
          type: array
          items:
            type: string
            minLength: 1
        allowed_hosts:
          type: array
          items:
            type: string
            minLength: 1
        mcp_connection_refs:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionRef'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillName'
      required: [name]

    UpdateSandboxRequest:
      type: object
      additionalProperties: false
      properties:
        packages:
          type: array
          items:
            type: string
            minLength: 1
        allowed_hosts:
          type: array
          items:
            type: string
            minLength: 1
        mcp_connection_refs:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionRef'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillName'
      required: [packages, allowed_hosts, mcp_connection_refs, skills]

    MCPConnectionRef:
      type: object
      additionalProperties: false
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionToolRef'
          minItems: 1
        name:
          $ref: '#/components/schemas/MCPConnectionName'
      required: [name, tools]

    MCPConnectionToolRef:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        require_consent:
          type: boolean
      required: [name, require_consent]

    MCPConnectionTool:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
      required: [name]

    MCPConnectionDetail:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/MCPConnectionName'
        endpoint:
          $ref: '#/components/schemas/MCPConnectionEndpoint'
        auth:
          $ref: '#/components/schemas/MCPConnectionAuth'
        created_at:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/MCPConnectionLifecycle'
        reason:
          $ref: '#/components/schemas/MCPConnectionReason'
        message:
          type: string
        tool_catalog_ready:
          type: boolean
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionTool'
      required: [name, endpoint, auth, created_at, status, reason, message, tool_catalog_ready, tools]

    MCPConnectionSummary:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/MCPConnectionName'
        auth_mode:
          type: string
        endpoint_url:
          type: string
        created_at:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/MCPConnectionLifecycle'
        reason:
          $ref: '#/components/schemas/MCPConnectionReason'
        message:
          type: string
        tool_catalog_ready:
          type: boolean
        tool_count:
          type: integer
          format: int64
          minimum: 0
      required: [name, auth_mode, endpoint_url, created_at, status, reason, message, tool_catalog_ready, tool_count]

    MCPConnectionEndpoint:
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
          minLength: 1
        timeout:
          type: string
          minLength: 1
        insecure_skip_verify:
          type: boolean
        headers:
          type: object
          additionalProperties:
            type: string
      required: [url, insecure_skip_verify, headers]

    MCPConnectionAuth:
      type: object
      additionalProperties: false
      properties:
        bearer:
          $ref: '#/components/schemas/MCPConnectionBearerAuth'
        oauth:
          $ref: '#/components/schemas/MCPConnectionOAuthAuth'

    MCPConnectionBearerAuth:
      type: object
      additionalProperties: false
      properties:
        location:
          $ref: '#/components/schemas/MCPConnectionAuthLocation'

    MCPConnectionOAuthAuth:
      type: object
      additionalProperties: false
      properties:
        issuer:
          type: string
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        registration_endpoint:
          type: string
        resource:
          type: string
        scopes:
          type: array
          items:
            type: string
            minLength: 1
        location:
          $ref: '#/components/schemas/MCPConnectionAuthLocation'

    MCPConnectionAuthLocation:
      type: object
      additionalProperties: false
      properties:
        header:
          $ref: '#/components/schemas/MCPConnectionHeaderLocation'
        query_parameter:
          $ref: '#/components/schemas/MCPConnectionQueryParameterLocation'
        cookie:
          $ref: '#/components/schemas/MCPConnectionCookieLocation'

    MCPConnectionHeaderLocation:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        prefix:
          type: string
          minLength: 1
      required: [name]

    MCPConnectionQueryParameterLocation:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
      required: [name]

    MCPConnectionCookieLocation:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
      required: [name]

    MCPConnectionLifecycle:
      type: string
      enum: [Accepted, Ready, Error]

    MCPConnectionReason:
      type: string
      enum: [Ready, ProbePending, Unreachable, InvalidCredentials, ProtocolError, InternalError]

    ListMCPConnectionsResponse:
      type: object
      additionalProperties: false
      properties:
        mcp_connections:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionSummary'
        next_page_token:
          type: string
      required: [mcp_connections, next_page_token]
    WatchMCPConnectionsRequest:
      type: object
      additionalProperties: false
      properties:
        names:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionName'
    WatchMCPConnectionsEvent:
      type: object
      additionalProperties: false
      properties:
        mcp_connections:
          type: array
          items:
            $ref: '#/components/schemas/MCPConnectionSummary'
      required: [mcp_connections]

    CreateMCPConnectionRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/MCPConnectionName'
        endpoint:
          $ref: '#/components/schemas/MCPConnectionEndpoint'
        auth:
          $ref: '#/components/schemas/MCPConnectionAuth'
        credentials:
          $ref: '#/components/schemas/MCPConnectionCredentials'
      required: [name, endpoint, auth, credentials]

    MCPConnectionCredentials:
      type: object
      additionalProperties: false
      properties:
        bearer:
          $ref: '#/components/schemas/MCPConnectionBearerCredentials'
        oauth:
          $ref: '#/components/schemas/MCPConnectionOAuthCredentials'

    MCPConnectionBearerCredentials:
      type: object
      additionalProperties: false
      properties:
        token:
          type: string
          minLength: 1
      required: [token]

    MCPConnectionOAuthCredentials:
      type: object
      additionalProperties: false
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        refresh_token:
          type: string
        access_token:
          type: string
        expires_at:
          type: string
          format: date-time
        token_type:
          type: string
        scopes:
          type: array
          items:
            type: string
            minLength: 1
        registration:
          $ref: '#/components/schemas/JSONObject'
        revocation:
          $ref: '#/components/schemas/JSONObject'