openapi.yaml

openapi: 3.0.3
info:
  title: CodeForge API
  description: Remote AI code task runner. Submit code tasks, monitor progress via SSE, and create pull requests.
  version: 1.0.0
  contact:
    name: CodeForge
servers:
  - url: http://localhost:8080
    description: Local development

security:
  - BearerAuth: []

paths:
  /health:
    get:
      summary: Health check
      operationId: health
      security: []
      tags: [System]
      responses:
        "200":
          description: Service health status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                    example: "1.0.0"
                  redis:
                    type: string
                    example: connected
                  sqlite:
                    type: string
                    example: connected
                  workspace_disk_usage_mb:
                    type: number
                    example: 123.45

  /ready:
    get:
      summary: Readiness probe
      operationId: ready
      security: []
      tags: [System]
      responses:
        "200":
          description: Service is ready
          content:
            application/json:
              schema:
                type: object
                properties:
                  ready:
                    type: boolean
        "503":
          description: Service is not ready

  /metrics:
    get:
      summary: Prometheus metrics
      operationId: metrics
      security: []
      tags: [System]
      responses:
        "200":
          description: Prometheus text format metrics
          content:
            text/plain:
              schema:
                type: string

  /api/v1/auth/verify:
    get:
      summary: Verify authentication token
      operationId: verifyAuth
      tags: [Auth]
      description: |
        Returns 200 if the provided Bearer token is valid.
        Returns 401 if the token is missing or invalid.
        Use this endpoint to validate API tokens from your UI before making other API calls.
      responses:
        "200":
          description: Token is valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: authenticated
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/tasks:
    post:
      summary: Create a new task
      operationId: createTask
      tags: [Tasks]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTaskRequest"
      responses:
        "201":
          description: Task created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    example: pending
                  created_at:
                    type: string
                    format: date-time
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"

  /api/v1/tasks/{taskID}:
    get:
      summary: Get task status and result
      operationId: getTask
      tags: [Tasks]
      parameters:
        - name: taskID
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: include
          in: query
          description: Include additional data (e.g., "iterations")
          schema:
            type: string
            enum: [iterations]
      responses:
        "200":
          description: Task details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/tasks/{taskID}/instruct:
    post:
      summary: Send follow-up instruction to a completed task
      operationId: instructTask
      tags: [Tasks]
      parameters:
        - name: taskID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt:
                  type: string
                  description: Follow-up instruction
      responses:
        "200":
          description: Instruction accepted, new iteration started
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                  iteration:
                    type: integer
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

  /api/v1/tasks/{taskID}/cancel:
    post:
      summary: Cancel a running task
      operationId: cancelTask
      description: |
        Requests cancellation of a running or cloning task. Returns a transient
        "canceling" status indicating the request was accepted. The task will
        transition to "failed" once cancellation completes. Poll GET /tasks/{taskID}
        to observe the final state.
      tags: [Tasks]
      parameters:
        - name: taskID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Cancellation requested
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

  /api/v1/tasks/{taskID}/create-pr:
    post:
      summary: Create a pull request from task changes
      operationId: createPR
      tags: [Tasks]
      parameters:
        - name: taskID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePRRequest"
      responses:
        "200":
          description: PR created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatePRResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

  /api/v1/tasks/{taskID}/review:
    post:
      summary: Run code review on a completed task
      operationId: reviewTask
      tags: [Tasks]
      description: |
        Enqueues a code review of the task's workspace for async worker execution.
        The task must be in completed or awaiting_instruction status.
        Returns 202 immediately — review runs in the worker pool with SSE streaming.
        Transitions: completed/awaiting_instruction → reviewing → completed (with review_result).
        Monitor progress via GET /tasks/{taskID}/stream (SSE events: review_started, review_completed).
      parameters:
        - name: taskID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cli:
                  type: string
                  description: CLI tool override for review (e.g., "codex", "claude-code")
                model:
                  type: string
                  description: AI model override for the review
      responses:
        "202":
          description: Review enqueued for worker execution
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    example: reviewing
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

  /api/v1/tasks/{taskID}/post-review:
    post:
      summary: Post review comments to PR/MR
      operationId: postReviewComments
      tags: [Tasks]
      description: |
        Posts the task's ReviewResult as comments to the associated GitHub PR or GitLab MR.
        Task must have a review_result (run a review first).
        Token is resolved from the task's provider_key or access_token.
      parameters:
        - name: taskID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                pr_number:
                  type: integer
                  description: Override PR/MR number (defaults to task config or task field)
      responses:
        "200":
          description: Review comments posted
          content:
            application/json:
              schema:
                type: object
                properties:
                  review_url:
                    type: string
                    description: URL to the posted review on GitHub/GitLab
                  comments_posted:
                    type: integer
                    description: Number of line-level comments posted
                  pr_number:
                    type: integer
                    description: The PR/MR number used
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/webhooks/github:
    post:
      summary: GitHub webhook receiver for PR reviews
      operationId: githubWebhook
      security: []
      tags: [Webhooks]
      description: |
        Receives GitHub pull_request webhook events and automatically creates pr_review tasks.
        Verified via HMAC-SHA256 signature (X-Hub-Signature-256 header).
        Handles actions: opened, synchronize, reopened. Skips drafts unless configured.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: GitHub pull_request webhook payload
      responses:
        "201":
          description: Review task created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: created
                  task_id:
                    type: string
                    format: uuid
        "200":
          description: Event ignored (not a handled action or draft)
        "401":
          description: Invalid webhook signature

  /api/v1/webhooks/gitlab:
    post:
      summary: GitLab webhook receiver for MR reviews
      operationId: gitlabWebhook
      security: []
      tags: [Webhooks]
      description: |
        Receives GitLab Merge Request Hook events and automatically creates pr_review tasks.
        Verified via X-Gitlab-Token header constant-time comparison.
        Handles actions: open, update, reopen. Skips draft/WIP unless configured.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: GitLab merge_request webhook payload
      responses:
        "201":
          description: Review task created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: created
                  task_id:
                    type: string
                    format: uuid
        "200":
          description: Event ignored (not a handled action or draft/WIP)
        "401":
          description: Invalid webhook token

  /api/v1/tasks/{taskID}/stream:
    get:
      summary: Stream task events via SSE
      operationId: streamTask
      tags: [Tasks]
      description: |
        Opens a Server-Sent Events (SSE) connection to stream real-time task progress.

        **Event types:**
        - `connected` — Initial event with task ID and current status.
        - `data` (unnamed) — Stream events from Redis history and live Pub/Sub.
          Each event is a JSON object: `{ type, event, data, ts }`.
          Types: `system`, `git`, `cli`, `stream`, `result`.
        - `done` — Task finished (completed/failed). Connection closes after this.
        - `timeout` — Connection closed after 10 minutes.

        **Behavior:**
        1. Replays all historical events from Redis.
        2. Subscribes to live events via Redis Pub/Sub.
        3. Sends keepalive comments (`: keepalive`) every 15 seconds.
        4. For terminal tasks (completed/failed/pr_created), sends history + done immediately.

        **Client example (fetch + ReadableStream):**
        ```javascript
        // Browser EventSource does NOT support custom headers.
        // Use fetch with a ReadableStream instead:
        const resp = await fetch('/api/v1/tasks/abc/stream', {
          headers: { Authorization: 'Bearer TOKEN' },
        });
        const reader = resp.body.getReader();
        const decoder = new TextDecoder();
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          const text = decoder.decode(value);
          // Parse SSE frames: lines starting with "data: "
          for (const line of text.split('\n')) {
            if (line.startsWith('data: ')) {
              console.log(JSON.parse(line.slice(6)));
            }
          }
        }
        ```

        **Alternative — token via query parameter:**
        ```javascript
        // If the server supports ?token= auth, EventSource works:
        const es = new EventSource('/api/v1/tasks/abc/stream?token=TOKEN');
        es.onmessage = (e) => console.log(JSON.parse(e.data));
        es.addEventListener('done', () => es.close());
        ```
      parameters:
        - name: taskID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: SSE event stream
          content:
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/keys:
    post:
      summary: Register a provider access key
      operationId: createKey
      tags: [Keys]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, provider, token]
              properties:
                name:
                  type: string
                  description: Unique key name
                  example: my-github-key
                provider:
                  type: string
                  description: Provider type
                  enum: [github, gitlab, sentry]
                  example: github
                token:
                  type: string
                  description: Access token (stored encrypted)
                scope:
                  type: string
                  description: Optional scope restriction
      responses:
        "201":
          description: Key registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  provider:
                    type: string
                  message:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
    get:
      summary: List registered keys (tokens redacted)
      operationId: listKeys
      tags: [Keys]
      responses:
        "200":
          description: List of keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        provider:
                          type: string
                        scope:
                          type: string
                        created_at:
                          type: string
                          format: date-time

  /api/v1/keys/{name}/verify:
    get:
      summary: Verify a stored provider token
      operationId: verifyKey
      tags: [Keys]
      description: |
        Decrypts the stored token and validates it against the provider API (GitHub/GitLab/Sentry).
        Returns token validity, associated username, email, and scopes.
        Use this to show a green/red status indicator in the UI after adding a key.
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Token is valid
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KeyVerifyResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: Token is invalid or expired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KeyVerifyResponse"

  /api/v1/keys/{name}:
    delete:
      summary: Delete a registered key
      operationId: deleteKey
      tags: [Keys]
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Key deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/mcp/servers:
    post:
      summary: Register a global MCP server
      operationId: createMCPServer
      tags: [MCP]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  description: Unique server name
                  example: context7
                transport:
                  type: string
                  enum: [stdio, http]
                  default: stdio
                  description: Transport type (stdio for local process, http for remote)
                package:
                  type: string
                  description: NPM package or binary path (required for stdio transport)
                  example: "@anthropic-ai/context7"
                command:
                  type: string
                  description: Command to run (e.g. npx, uvx) — stdio transport only
                args:
                  type: array
                  items:
                    type: string
                  description: Command arguments — stdio transport only
                env:
                  type: object
                  additionalProperties:
                    type: string
                  description: Environment variables — stdio transport only
                url:
                  type: string
                  format: uri
                  description: Server URL (required for http transport)
                  example: "https://mcp.context7.com/mcp"
                headers:
                  type: object
                  additionalProperties:
                    type: string
                  description: HTTP headers — http transport only
      responses:
        "201":
          description: MCP server registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
    get:
      summary: List global MCP servers
      operationId: listMCPServers
      tags: [MCP]
      responses:
        "200":
          description: List of MCP servers
          content:
            application/json:
              schema:
                type: object
                properties:
                  servers:
                    type: array
                    items:
                      $ref: "#/components/schemas/MCPServer"

  /api/v1/mcp/servers/{name}:
    delete:
      summary: Delete a global MCP server
      operationId: deleteMCPServer
      tags: [MCP]
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: MCP server deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/repositories:
    get:
      summary: List repositories accessible with a provider token
      operationId: listRepositories
      tags: [Repositories]
      description: |
        Lists repositories from GitHub or GitLab. Supports two auth modes:
        1. `provider_key` — uses a stored key from the key registry
        2. `provider` + `X-Provider-Token` header — inline token
      parameters:
        - name: provider_key
          in: query
          description: Name of a registered key to use
          schema:
            type: string
        - name: provider
          in: query
          description: Git provider (github, gitlab). Required when using X-Provider-Token.
          schema:
            type: string
            enum: [github, gitlab]
        - name: X-Provider-Token
          in: header
          description: Inline provider access token
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 30
            maximum: 100
      responses:
        "200":
          description: Repository list
          content:
            application/json:
              schema:
                type: object
                properties:
                  repositories:
                    type: array
                    items:
                      $ref: "#/components/schemas/Repository"
                  count:
                    type: integer
                  provider:
                    type: string
                  page:
                    type: integer
                  per_page:
                    type: integer
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          description: Provider API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/sentry/organizations:
    get:
      summary: List Sentry organizations
      operationId: listSentryOrganizations
      tags: [Sentry]
      description: Proxies request to Sentry API using a stored auth token.
      parameters:
        - name: key_name
          in: query
          required: true
          description: Name of the stored Sentry key
          schema:
            type: string
      responses:
        "200":
          description: List of Sentry organizations
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        slug:
                          type: string
                        name:
                          type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "502":
          description: Sentry API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/sentry/projects:
    get:
      summary: List Sentry projects in an organization
      operationId: listSentryProjects
      tags: [Sentry]
      parameters:
        - name: key_name
          in: query
          required: true
          schema:
            type: string
        - name: org
          in: query
          required: true
          description: Sentry organization slug
          schema:
            type: string
      responses:
        "200":
          description: List of Sentry projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        slug:
                          type: string
                        name:
                          type: string
                        platform:
                          type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "502":
          description: Sentry API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/sentry/issues:
    get:
      summary: List Sentry issues for a project
      operationId: listSentryIssues
      tags: [Sentry]
      parameters:
        - name: key_name
          in: query
          required: true
          schema:
            type: string
        - name: org
          in: query
          required: true
          description: Sentry organization slug
          schema:
            type: string
        - name: project
          in: query
          required: true
          description: Sentry project slug
          schema:
            type: string
        - name: query
          in: query
          description: Sentry search query (default "is:unresolved")
          schema:
            type: string
        - name: sort
          in: query
          description: Sort order (e.g. freq, date, priority)
          schema:
            type: string
        - name: limit
          in: query
          description: Max results (default 50)
          schema:
            type: string
      responses:
        "200":
          description: List of Sentry issues (raw Sentry format)
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
        "400":
          $ref: "#/components/responses/BadRequest"
        "502":
          description: Sentry API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/sentry/issues/{issueID}:
    get:
      summary: Get a Sentry issue detail
      operationId: getSentryIssue
      tags: [Sentry]
      parameters:
        - name: issueID
          in: path
          required: true
          schema:
            type: string
        - name: key_name
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Sentry issue detail (raw Sentry format)
          content:
            application/json:
              schema:
                type: object
        "400":
          $ref: "#/components/responses/BadRequest"
        "502":
          description: Sentry API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/sentry/issues/{issueID}/latest-event:
    get:
      summary: Get latest event for a Sentry issue
      operationId: getSentryIssueLatestEvent
      tags: [Sentry]
      description: Returns the latest event with full stack trace, breadcrumbs, and context.
      parameters:
        - name: issueID
          in: path
          required: true
          schema:
            type: string
        - name: key_name
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Latest event (raw Sentry format)
          content:
            application/json:
              schema:
                type: object
        "400":
          $ref: "#/components/responses/BadRequest"
        "502":
          description: Sentry API error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/workflows:
    post:
      summary: Create a workflow definition
      operationId: createWorkflow
      tags: [Workflows]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkflowDefinition"
      responses:
        "201":
          description: Workflow created
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
    get:
      summary: List workflow definitions
      operationId: listWorkflows
      tags: [Workflows]
      responses:
        "200":
          description: List of workflows
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflows:
                    type: array
                    items:
                      $ref: "#/components/schemas/WorkflowDefinition"

  /api/v1/workflows/{name}:
    get:
      summary: Get a workflow definition
      operationId: getWorkflow
      tags: [Workflows]
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Workflow definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowDefinition"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      summary: Delete a workflow definition
      operationId: deleteWorkflow
      tags: [Workflows]
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Workflow deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

  /api/v1/workflows/{name}/run:
    post:
      summary: Run a workflow
      operationId: runWorkflow
      tags: [Workflows]
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunWorkflowRequest"
      responses:
        "201":
          description: Workflow run created
          content:
            application/json:
              schema:
                type: object
                properties:
                  run_id:
                    type: string
                    format: uuid
                  workflow_name:
                    type: string
                  status:
                    type: string
                    example: pending
                  created_at:
                    type: string
                    format: date-time
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/workflow-runs:
    get:
      summary: List workflow runs
      operationId: listWorkflowRuns
      tags: [Workflows]
      parameters:
        - name: workflow
          in: query
          description: Filter by workflow name
          schema:
            type: string
      responses:
        "200":
          description: List of runs
          content:
            application/json:
              schema:
                type: object
                properties:
                  runs:
                    type: array
                    items:
                      $ref: "#/components/schemas/WorkflowRun"

  /api/v1/workflow-runs/{runID}:
    get:
      summary: Get workflow run details
      operationId: getWorkflowRun
      tags: [Workflows]
      parameters:
        - name: runID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Workflow run with steps
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/workflow-runs/{runID}/stream:
    get:
      summary: Stream workflow run events via SSE
      operationId: streamWorkflowRun
      tags: [Workflows]
      parameters:
        - name: runID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: SSE event stream
          content:
            text/event-stream:
              schema:
                type: string
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/task-types:
    get:
      summary: List available task types
      operationId: listTaskTypes
      tags: [Tasks]
      description: |
        Returns the list of available task types with their descriptions.
        Use this to populate task type selectors in the UI.
      responses:
        "200":
          description: List of task types
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_types:
                    type: array
                    items:
                      $ref: "#/components/schemas/TaskTypeInfo"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/cli:
    get:
      summary: List registered CLI tools
      operationId: listCLI
      tags: [CLI]
      responses:
        "200":
          description: List of CLI tools
          content:
            application/json:
              schema:
                type: object
                properties:
                  cli:
                    type: array
                    items:
                      $ref: "#/components/schemas/CLIEntry"

  /api/v1/cli/health:
    get:
      summary: Check default CLI availability
      operationId: cliHealth
      tags: [CLI]
      responses:
        "200":
          description: CLI is available
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  cli:
                    type: string
                    example: claude-code
                  binary:
                    type: string
                    example: /usr/local/bin/claude
        "503":
          description: CLI is unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: unavailable
                  cli:
                    type: string
                  binary:
                    type: string
                  message:
                    type: string

  /api/v1/tools:
    post:
      summary: Register a tool definition
      operationId: createTool
      tags: [Tools]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateToolRequest"
      responses:
        "201":
          description: Tool registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
    get:
      summary: List all registered tools
      operationId: listTools
      tags: [Tools]
      responses:
        "200":
          description: List of tools
          content:
            application/json:
              schema:
                type: object
                properties:
                  tools:
                    type: array
                    items:
                      $ref: "#/components/schemas/ToolDefinition"

  /api/v1/tools/catalog:
    get:
      summary: List built-in tool catalog
      operationId: toolCatalog
      tags: [Tools]
      responses:
        "200":
          description: Built-in tools
          content:
            application/json:
              schema:
                type: object
                properties:
                  tools:
                    type: array
                    items:
                      $ref: "#/components/schemas/ToolDefinition"

  /api/v1/tools/{name}:
    get:
      summary: Get a tool by name
      operationId: getTool
      tags: [Tools]
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Tool definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolDefinition"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      summary: Delete a tool
      operationId: deleteTool
      tags: [Tools]
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Tool deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/workspaces:
    get:
      summary: List active workspaces
      operationId: listWorkspaces
      tags: [Workspaces]
      responses:
        "200":
          description: Workspace list
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspaces:
                    type: array
                    items:
                      $ref: "#/components/schemas/WorkspaceInfo"
                  total_size_mb:
                    type: number
                  total_count:
                    type: integer

  /api/v1/workspaces/{taskID}:
    delete:
      summary: Delete a workspace
      operationId: deleteWorkspace
      tags: [Workspaces]
      parameters:
        - name: taskID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Workspace deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Missing or invalid auth token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Conflict:
      description: Operation conflicts with current state
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        fields:
          type: object
          additionalProperties:
            type: string

    CreateTaskRequest:
      type: object
      required: [repo_url, prompt]
      properties:
        repo_url:
          type: string
          format: uri
          description: Git repository URL
          example: "https://github.com/user/repo.git"
        provider_key:
          type: string
          description: Name of a registered key to use for git auth
        access_token:
          type: string
          description: Inline access token for git auth
        prompt:
          type: string
          description: Task instruction for the AI
          maxLength: 102400
          example: "Fix the failing tests in the auth module"
        task_type:
          type: string
          description: "Type of task: code (default), plan, or review"
          enum: [code, plan, review, pr_review]
          default: code
        callback_url:
          type: string
          format: uri
          description: Webhook URL for completion notification
        config:
          $ref: "#/components/schemas/TaskConfig"

    TaskConfig:
      type: object
      properties:
        timeout_seconds:
          type: integer
          description: Task timeout in seconds
        cli:
          type: string
          description: CLI tool to use (e.g., "claude-code")
          default: claude-code
        ai_model:
          type: string
          description: AI model override
        ai_api_key:
          type: string
          description: API key for the AI provider
        max_turns:
          type: integer
          description: Maximum conversation turns
        source_branch:
          type: string
          description: Branch to clone/checkout (defaults to target_branch for backward compat)
        target_branch:
          type: string
          description: Base branch for PR creation
        max_budget_usd:
          type: number
          description: Maximum spend in USD
        workspace_task_id:
          type: string
          description: Reuse workspace from another task
        mcp_servers:
          type: array
          items:
            $ref: "#/components/schemas/TaskMCPServer"
        tools:
          type: array
          description: Per-task tool requests
          items:
            type: object
            required: [name]
            properties:
              name:
                type: string
              config:
                type: object
                additionalProperties:
                  type: string
        pr_number:
          type: integer
          description: PR/MR number (required for pr_review tasks)
        output_mode:
          type: string
          description: Output mode for pr_review tasks
          enum: [api_only, post_comments]
          default: api_only

    TaskMCPServer:
      type: object
      required: [name]
      properties:
        name:
          type: string
        transport:
          type: string
          enum: [stdio, http]
        package:
          type: string
          description: NPM package or binary path — stdio transport
        command:
          type: string
          description: Command to run (npx, uvx, docker) — stdio transport
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
          description: Environment variables — stdio transport
        url:
          type: string
          format: uri
          description: Server URL — http transport
        headers:
          type: object
          additionalProperties:
            type: string
          description: HTTP headers — http transport

    TaskTypeInfo:
      type: object
      properties:
        name:
          type: string
          description: Task type identifier
          example: plan
        label:
          type: string
          description: Human-readable label
          example: Plan
        description:
          type: string
          description: What this task type does
          example: "Analyze the codebase and create an implementation plan without modifying files"

    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, cloning, running, reviewing, completed, failed, awaiting_instruction, creating_pr, pr_created]
        repo_url:
          type: string
        provider_key:
          type: string
          description: Name of the registered key used for git auth
        prompt:
          type: string
        task_type:
          type: string
          description: "Type of task: code, plan, or review"
          enum: [code, plan, review, pr_review]
        callback_url:
          type: string
        config:
          $ref: "#/components/schemas/TaskConfig"
        result:
          type: string
        error:
          type: string
        changes_summary:
          $ref: "#/components/schemas/ChangesSummary"
        usage:
          $ref: "#/components/schemas/UsageInfo"
        review_result:
          $ref: "#/components/schemas/ReviewResult"
        iteration:
          type: integer
        current_prompt:
          type: string
        iterations:
          type: array
          items:
            $ref: "#/components/schemas/Iteration"
        branch:
          type: string
        pr_number:
          type: integer
        pr_url:
          type: string
        trace_id:
          type: string
          description: OpenTelemetry trace ID for distributed tracing
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time

    ChangesSummary:
      type: object
      description: Git diff statistics after CLI execution
      properties:
        files_modified:
          type: integer
          description: Number of modified files
        files_created:
          type: integer
          description: Number of newly created files
        files_deleted:
          type: integer
          description: Number of deleted files
        diff_stats:
          type: string
          description: "Short diff summary, e.g. \"+142 -38\""
          example: "+142 -38"

    UsageInfo:
      type: object
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        duration_seconds:
          type: integer

    Iteration:
      type: object
      properties:
        number:
          type: integer
        prompt:
          type: string
        result:
          type: string
        error:
          type: string
        status:
          type: string
        changes:
          $ref: "#/components/schemas/ChangesSummary"
        usage:
          $ref: "#/components/schemas/UsageInfo"
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time

    CreatePRRequest:
      type: object
      properties:
        title:
          type: string
          description: PR title (auto-generated if empty)
        description:
          type: string
          description: PR description (auto-generated if empty)
        target_branch:
          type: string
          description: Target branch (defaults to main/master)

    CreatePRResponse:
      type: object
      properties:
        pr_url:
          type: string
        pr_number:
          type: integer
        branch:
          type: string

    MCPServer:
      type: object
      properties:
        name:
          type: string
        transport:
          type: string
          enum: [stdio, http]
        package:
          type: string
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        url:
          type: string
          format: uri
        headers:
          type: object
          additionalProperties:
            type: string

    StreamEvent:
      type: object
      description: A single event from the task's real-time stream
      properties:
        type:
          type: string
          enum: [system, git, cli, stream, result]
          description: Event category
        event:
          type: string
          description: Event name (e.g., status_change, output, clone_start)
        data:
          description: Event-specific payload (varies by type)
        ts:
          type: string
          format: date-time
          description: ISO 8601 timestamp

    CancelResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          description: >
            Transient response status "canceling" — NOT a stored TaskStatus
            enum value. It indicates the cancellation request was accepted.
            Poll GET /tasks/{id} to observe the final state (will be "failed").
          example: canceling
        message:
          type: string
          example: cancellation requested

    KeyVerifyResponse:
      type: object
      properties:
        name:
          type: string
          example: my-github-key
        provider:
          type: string
          example: github
        valid:
          type: boolean
          example: true
        username:
          type: string
          example: octocat
        email:
          type: string
          example: octocat@github.com
        scopes:
          type: string
          description: Comma-separated OAuth scopes (GitHub only)
          example: "repo, read:org"
        error:
          type: string
          description: Error message when token is invalid

    Repository:
      type: object
      properties:
        name:
          type: string
          example: my-repo
        full_name:
          type: string
          example: owner/my-repo
        clone_url:
          type: string
          format: uri
          example: "https://github.com/owner/my-repo.git"
        default_branch:
          type: string
          example: main
        private:
          type: boolean
        description:
          type: string
        updated_at:
          type: string
          format: date-time

    WorkspaceInfo:
      type: object
      properties:
        task_id:
          type: string
        size_mb:
          type: number
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        task_status:
          type: string

    WorkflowDefinition:
      type: object
      required: [name]
      properties:
        name:
          type: string
          example: sentry-fixer
        description:
          type: string
        builtin:
          type: boolean
        steps:
          type: array
          items:
            $ref: "#/components/schemas/StepDefinition"
        parameters:
          type: array
          items:
            $ref: "#/components/schemas/ParameterDefinition"
        created_at:
          type: string
          format: date-time

    StepDefinition:
      type: object
      required: [name, type, config]
      properties:
        name:
          type: string
        type:
          type: string
          enum: [fetch, task, action]
        config:
          type: object
          description: Step-type-specific configuration

    ParameterDefinition:
      type: object
      required: [name]
      properties:
        name:
          type: string
        required:
          type: boolean
        default:
          type: string

    RunWorkflowRequest:
      type: object
      properties:
        params:
          type: object
          additionalProperties:
            type: string
          description: Workflow input parameters

    WorkflowRun:
      type: object
      properties:
        id:
          type: string
          format: uuid
        workflow_name:
          type: string
        status:
          type: string
          enum: [pending, running, completed, failed]
        params:
          type: object
          additionalProperties:
            type: string
        error:
          type: string
        steps:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowRunStep"
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time

    WorkflowRunStep:
      type: object
      properties:
        run_id:
          type: string
        step_name:
          type: string
        step_type:
          type: string
          enum: [fetch, task, action]
        status:
          type: string
          enum: [pending, running, completed, failed, skipped]
        result:
          type: object
          additionalProperties:
            type: string
        task_id:
          type: string
        error:
          type: string
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time

    CLIEntry:
      type: object
      properties:
        name:
          type: string
          example: claude-code
        binary_path:
          type: string
          example: /usr/local/bin/claude
        default_model:
          type: string
        available:
          type: boolean
        is_default:
          type: boolean

    ToolDefinition:
      type: object
      properties:
        name:
          type: string
          example: sentry
        type:
          type: string
          enum: [mcp, builtin, custom]
        description:
          type: string
        version:
          type: string
        mcp_transport:
          type: string
          enum: [stdio, http]
          description: Transport type (omitted = stdio default)
        mcp_url:
          type: string
          format: uri
          description: URL for http transport tools
        mcp_package:
          type: string
        mcp_command:
          type: string
        mcp_args:
          type: array
          items:
            type: string
        required_config:
          type: array
          items:
            $ref: "#/components/schemas/ConfigField"
        optional_config:
          type: array
          items:
            $ref: "#/components/schemas/ConfigField"
        capabilities:
          type: array
          items:
            type: string
        builtin:
          type: boolean
        created_at:
          type: string
          format: date-time

    ConfigField:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        type:
          type: string
        env_var:
          type: string
        sensitive:
          type: boolean

    CreateToolRequest:
      type: object
      required: [name, type]
      properties:
        name:
          type: string
        type:
          type: string
          enum: [mcp, builtin, custom]
        description:
          type: string
        version:
          type: string
        mcp_transport:
          type: string
          enum: [stdio, http]
          description: Transport type (default stdio)
        mcp_url:
          type: string
          format: uri
          description: URL for http transport
        mcp_package:
          type: string
        mcp_command:
          type: string
        mcp_args:
          type: array
          items:
            type: string
        required_config:
          type: array
          items:
            $ref: "#/components/schemas/ConfigField"
        optional_config:
          type: array
          items:
            $ref: "#/components/schemas/ConfigField"
        capabilities:
          type: array
          items:
            type: string

    ReviewResult:
      type: object
      description: Structured output from code review
      properties:
        verdict:
          type: string
          enum: [approve, request_changes, comment]
        score:
          type: integer
          minimum: 1
          maximum: 10
        summary:
          type: string
        issues:
          type: array
          items:
            $ref: "#/components/schemas/ReviewIssue"
        auto_fixable:
          type: boolean
        reviewed_by:
          type: string
          description: "CLI and model used for review (e.g. claude-code:claude-sonnet-4-6)"
        duration_seconds:
          type: number

    ReviewIssue:
      type: object
      properties:
        severity:
          type: string
          enum: [critical, major, minor, suggestion]
        file:
          type: string
        line:
          type: integer
        description:
          type: string
        suggestion:
          type: string