openapi.yaml

openapi: 3.1.0
info:
  title: AgentHub REST API
  version: v1
  description: >
    AgentHub REST JSON API for commands and queries. Realtime state, logs,
    message deltas, approvals and artifact notifications are delivered through
    WebSocket typed events documented in api/events.md.

    ## Implementation Status (2026-05-29)

    **Edge Server**: Core endpoints (health/runs/threads/projects/agents/events/permissions)
    are implemented. `/v1/runners` remains a compatibility surface for runtime/
    target health; new architecture language should use Agent Runtime, Agent
    Profile, and Execution Target.

    **Hub Server**: Hub entries marked `x-agenthub-status: implemented` mirror
    the current Gin router paths in `hub-server/internal/router/router.go`,
    including `/client/auth`, `/client/contacts`, `/client/sessions`,
    `/client/messages`, `/client/attachments`, `/client/notifications`,
    `/edge/*`, and `/web/*`. Deprecated or legacy Hub shapes are retained only
    when marked `planned`; they are not callable routes.
    The legacy `/v1/auth`, `/v1/users`, `/v1/contacts` paths are planned for future
    migration and not currently implemented.

    ## Status tags
    - `x-agenthub-status: implemented` — 已实现，可直接调用
    - `x-agenthub-status: planned` — 远期规划，尚未实现
servers:
  - url: http://127.0.0.1:3210
    description: Local Edge Server
  - url: http://localhost:8080
    description: Local Hub Server
  - url: http://api.hub.vectorcontrol.tech
    description: Production Hub Server
tags:
  - name: Foundation
    description: Health, capability and event stream handshake.
  - name: IMProject
    description: Project, conversation, thread, message and item APIs.
  - name: ExecutionRunner
    description: Agent Runtime, compatibility runner health, AgentRun, approval, artifact, preview and workspace APIs.
  - name: HubSyncRelay
    description: Auth, user, contact, group, device, edge, sync, relay and cloud APIs.

paths:
  # ═══════════════════════════════════════════════════════════
  # Edge Server — Implementation Status
  #
  # IMPLEMENTED: /v1/health, /v1/events, /v1/projects (GET/POST),
  #   /v1/projects/{projectId} (GET only), /v1/threads (GET/POST),
  #   /v1/threads/{threadId} (GET/PATCH/DELETE), /v1/threads/{threadId}/items,
  #   /v1/threads/{threadId}/messages, /v1/items/{itemId},
  #   /v1/runners (GET only), /v1/agents, /v1/runs (GET/POST),
  #   /v1/runs/{runId} (GET), /v1/runs/{runId}:cancel,
  #   /v1/metrics, /v1/agent-instances (GET only),
  #   /v1/permissions/decide
  #
  # PLANNED (documented but not yet implemented):
  #   PATCH/DELETE /v1/projects/{projectId},
  #   GET/PATCH /v1/projects/{projectId}/memory,
  #   GET/POST /v1/conversations,
  #   GET/PATCH /v1/conversations/{conversationId},
  #   POST /v1/conversations/{conversationId}:archive,
  #   GET/POST /v1/conversations/{conversationId}/members,
  #   DELETE /v1/conversations/{conversationId}/members/{memberId},
  #   POST /v1/threads/{threadId}:archive,
  #   POST /v1/threads/{threadId}:fork,
  #   GET /v1/runners/{runnerId},
  #   POST /v1/runners/{runnerId}:ping,
  #   POST /v1/runners/{runnerId}:drain,
  #   POST /v1/runs/{runId}:interrupt,
  #   POST /v1/runs/{runId}:resume,
  #   POST /v1/runs/{runId}:retry,
  #   GET /v1/runs/{runId}/items,
  #   GET /v1/runs/{runId}/logs,
  #   GET /v1/runs/{runId}/diff,
  #   GET/POST /v1/approvals and nested,
  #   GET/POST /v1/artifacts and nested,
  #   GET/POST /v1/previews and nested,
  #   GET /v1/workspaces/{workspaceId} and nested,
  #   POST /v1/agent-instances
  # ═══════════════════════════════════════════════════════════

  /v1/health:
    get:
      tags: [Foundation]
      operationId: getHealth
      summary: Health check.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/events:
    get:
      tags: [Foundation]
      operationId: openEventStream
      summary: Open WebSocket event stream.
      description: >
        Local Edge WebSocket handshake surface. Event envelope and event types are
        documented in api/events.md. When local Edge auth is enabled, browser
        clients use `access_token` query auth; native clients may use the same
        local Edge token through Authorization or X-AgentHub-Edge-Token.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeWebSocketQueryToken: []
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "101":
          description: Switching Protocols.
        "401":
          $ref: "#/components/responses/Error"

  /v1/projects:
    get:
      tags: [IMProject]
      operationId: listProjects
      summary: List projects.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [IMProject]
      operationId: createProject
      summary: Create or register a project.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/projects/{projectId}:
    get:
      tags: [IMProject]
      operationId: getProject
      summary: Get project.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "404":
          $ref: "#/components/responses/Error"
    patch:
      tags: [IMProject]
      operationId: updateProject
      summary: Update project.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [IMProject]
      operationId: deleteProject
      summary: Delete or unregister project.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "204":
          description: Deleted.

  /v1/projects/{projectId}/memory:
    get:
      tags: [IMProject]
      operationId: getProjectMemory
      summary: Get project memory metadata.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [IMProject]
      operationId: updateProjectMemory
      summary: Update project memory metadata.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/conversations:
    get:
      tags: [IMProject]
      operationId: listConversations
      summary: List conversations.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [IMProject]
      operationId: createConversation
      summary: Create conversation.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/conversations/{conversationId}:
    get:
      tags: [IMProject]
      operationId: getConversation
      summary: Get conversation.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/ConversationId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [IMProject]
      operationId: updateConversation
      summary: Update conversation.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/ConversationId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/conversations/{conversationId}:archive:
    post:
      tags: [IMProject]
      operationId: archiveConversation
      summary: Archive conversation.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/ConversationId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/conversations/{conversationId}/members:
    get:
      tags: [IMProject]
      operationId: listConversationMembers
      summary: List conversation members.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/ConversationId"
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [IMProject]
      operationId: addConversationMember
      summary: Add conversation member.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/ConversationId"
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/conversations/{conversationId}/members/{memberId}:
    delete:
      tags: [IMProject]
      operationId: removeConversationMember
      summary: Remove conversation member.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/ConversationId"
        - $ref: "#/components/parameters/MemberId"
      responses:
        "204":
          description: Removed.

  /v1/threads:
    get:
      tags: [IMProject]
      operationId: listThreads
      summary: List threads.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ProjectIdQuery"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [IMProject]
      operationId: createThread
      summary: Create thread.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/threads/{threadId}:
    get:
      tags: [IMProject]
      operationId: getThread
      summary: Get thread.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [IMProject]
      operationId: updateThread
      summary: Update thread.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/threads/{threadId}:archive:
    post:
      tags: [IMProject]
      operationId: archiveThread
      summary: Archive thread.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/threads/{threadId}:fork:
    post:
      tags: [IMProject]
      operationId: forkThread
      summary: Fork thread.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/threads/{threadId}/items:
    get:
      tags: [IMProject]
      operationId: listThreadItems
      summary: List thread items.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ThreadId"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/threads/{threadId}/messages:
    post:
      tags: [IMProject]
      operationId: createThreadMessage
      summary: Create user message in thread.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateThreadMessageRequest"
      responses:
        "201":
          description: Message item created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Item"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /v1/items/{itemId}:
    get:
      tags: [IMProject]
      operationId: getItem
      summary: Get item.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ItemId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/runners:
    get:
      tags: [ExecutionRunner]
      operationId: listRunners
      summary: List runners.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      responses:
        "200":
          description: Runner list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListResponse"

  /v1/agents:
    get:
      tags: [ExecutionRunner]
      operationId: listAgents
      summary: List available agent adapters.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      responses:
        "200":
          description: Agent adapter list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListResponse"

  /v1/runners/{runnerId}:
    get:
      tags: [ExecutionRunner]
      operationId: getRunner
      summary: Get runner.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunnerId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/runners/{runnerId}:ping:
    post:
      tags: [ExecutionRunner]
      operationId: pingRunner
      summary: Ping runner.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunnerId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/runners/{runnerId}:drain:
    post:
      tags: [ExecutionRunner]
      operationId: drainRunner
      summary: Stop assigning new runs to runner.
      x-agenthub-phase: P2
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunnerId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/runs:
    get:
      tags: [ExecutionRunner]
      operationId: listRuns
      summary: List AgentRuns.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/ThreadIdQuery"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [ExecutionRunner]
      operationId: startRun
      summary: Start AgentRun.
      description: >
        Starts a local AgentRun. P0 accepts an empty body for Desktop Shell
        compatibility and falls back to the default local project/thread.
        New callers should pass projectId and threadId explicitly. If the Edge
        process is started with a workspace allowlist, workDir must resolve
        inside one of the allowed roots or the request is rejected before run
        creation.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartRunRequest"
      responses:
        "202":
          description: Run accepted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        "403":
          $ref: "#/components/responses/Error"

  /v1/runs/{runId}:
    get:
      tags: [ExecutionRunner]
      operationId: getRun
      summary: Get AgentRun.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/runs/{runId}:cancel:
    post:
      tags: [ExecutionRunner]
      operationId: cancelRun
      summary: Cancel AgentRun.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/runs/{runId}:interrupt:
    post:
      tags: [ExecutionRunner]
      operationId: interruptRun
      summary: Interrupt AgentRun.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/runs/{runId}:resume:
    post:
      tags: [ExecutionRunner]
      operationId: resumeRun
      summary: Resume AgentRun.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/runs/{runId}:retry:
    post:
      tags: [ExecutionRunner]
      operationId: retryRun
      summary: Retry AgentRun.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/runs/{runId}/items:
    get:
      tags: [ExecutionRunner]
      operationId: listRunItems
      summary: List run items.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/runs/{runId}/logs:
    get:
      tags: [ExecutionRunner]
      operationId: getRunLogs
      summary: Get run logs snapshot.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/runs/{runId}/diff:
    get:
      tags: [ExecutionRunner]
      operationId: getRunDiff
      summary: Get run diff snapshot.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/approvals:
    get:
      tags: [ExecutionRunner]
      operationId: listApprovals
      summary: List approval requests.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/approvals/{approvalId}:
    get:
      tags: [ExecutionRunner]
      operationId: getApproval
      summary: Get approval request.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ApprovalId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/approvals/{approvalId}:decide:
    post:
      tags: [ExecutionRunner]
      operationId: decideApproval
      summary: Decide approval request.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ApprovalId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/artifacts:
    get:
      tags: [ExecutionRunner]
      operationId: listArtifacts
      summary: List artifacts.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/artifacts/{artifactId}:
    get:
      tags: [ExecutionRunner]
      operationId: getArtifact
      summary: Get artifact metadata.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ArtifactId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/artifacts/{artifactId}/content:
    get:
      tags: [ExecutionRunner]
      operationId: getArtifactContent
      summary: Get artifact content or redirect.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ArtifactId"
      responses:
        "200":
          description: Artifact content.
        "302":
          description: Redirect to signed artifact URL.

  /v1/artifacts/{artifactId}:apply:
    post:
      tags: [ExecutionRunner]
      operationId: applyArtifact
      summary: Apply artifact to target workspace.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ArtifactId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/artifacts/{artifactId}:discard:
    post:
      tags: [ExecutionRunner]
      operationId: discardArtifact
      summary: Discard artifact.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ArtifactId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/previews:
    get:
      tags: [ExecutionRunner]
      operationId: listPreviews
      summary: List previews.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [ExecutionRunner]
      operationId: createPreview
      summary: Start preview.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/previews/{previewId}:
    get:
      tags: [ExecutionRunner]
      operationId: getPreview
      summary: Get preview.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/PreviewId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/previews/{previewId}:stop:
    post:
      tags: [ExecutionRunner]
      operationId: stopPreview
      summary: Stop preview.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/PreviewId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/workspaces/{workspaceId}:
    get:
      tags: [ExecutionRunner]
      operationId: getWorkspace
      summary: Get workspace.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Runner
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/workspaces/{workspaceId}/files:
    get:
      tags: [ExecutionRunner]
      operationId: listWorkspaceFiles
      summary: List workspace files.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Runner
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/workspaces/{workspaceId}/files:read:
    post:
      tags: [ExecutionRunner]
      operationId: readWorkspaceFile
      summary: Read workspace file by path.
      description: File path is passed in the JSON body so slash-containing paths do not become ambiguous URL segments.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Runner
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/workspaces/{workspaceId}/files:search:
    post:
      tags: [ExecutionRunner]
      operationId: searchWorkspaceFiles
      summary: Search workspace files.
      x-agenthub-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Runner
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          $ref: "#/components/responses/List"

  # ── Missing from original spec ──────────────────────────────

  /v1/metrics:
    get:
      tags: [Foundation]
      operationId: getMetrics
      summary: Prometheus metrics.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      responses:
        "200":
          description: Prometheus text format.

  /v1/agent-instances:
    get:
      tags: [ExecutionRunner]
      operationId: listAgentInstances
      summary: List orchestrator sub-agent instances.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - name: runId
          in: query
          schema: { type: string }
        - name: parentId
          in: query
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [ExecutionRunner]
      operationId: createAgentInstance
      summary: Register a sub-agent instance.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/permissions/decide:
    post:
      tags: [ExecutionRunner]
      operationId: decidePermission
      summary: Approve or deny a pending permission request.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [runId, requestId, decision]
              properties:
                runId: { type: string }
                requestId: { type: string }
                decision: { type: string, enum: [allow, deny] }
                reason: { type: string }
      responses:
        "200":
          description: Decision recorded.
        "400":
          description: Invalid decision payload.
        "404":
          description: Pending permission request not found.

  # ═══════════════════════════════════════════════════════════
  # Hub Server Routes (prefix: /client, /edge, /web, /api/public)
  # ═══════════════════════════════════════════════════════════

  /health:
    get:
      tags: [HubSyncRelay]
      operationId: hubHealth
      summary: Hub health check (DB + Redis + migrations).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /api/public/stats:
    get:
      tags: [HubSyncRelay]
      operationId: publicStats
      summary: Public statistics for official website.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      responses:
        "200":
          description: Public stats.

  /client/auth/me:
    get:
      tags: [HubSyncRelay]
      operationId: hubMe
      summary: Get current user profile.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: User profile.

  /client/contacts:
    get:
      tags: [HubSyncRelay]
      operationId: hubContacts
      summary: List contacts.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  /client/sessions:
    get:
      tags: [HubSyncRelay]
      operationId: hubSessions
      summary: List user sessions (private + group).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  /client/sessions/private:
    post:
      tags: [HubSyncRelay]
      operationId: hubCreatePrivate
      summary: Create a private (1-on-1) chat session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "201":
          description: Session created.

  /client/sessions/group:
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateGroup
      summary: Create a group chat session.
      description: "`member_ids` may be an empty array when a browser workspace needs an owner-only group session that can invite an Agent before dispatch."
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "201":
          description: Group created.

  /client/sessions/{id}/messages:
    get:
      tags: [HubSyncRelay]
      operationId: hubGetMessages
      summary: Get paginated messages for a session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: hubSendMessage
      summary: Send a message to a session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "201":
          description: Message sent.

  /client/ws:
    get:
      tags: [HubSyncRelay]
      operationId: hubWebSocket
      summary: Hub WebSocket — real-time IM + agent dispatch.
      description: First frame must be auth handshake. See api/events.md for Hub event types.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      responses:
        "101":
          description: Switching Protocols.

  /web/agent-tasks:
    post:
      tags: [HubSyncRelay]
      operationId: hubTriggerTask
      summary: Trigger an agent task from web client.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [trigger_message_id]
              properties:
                trigger_message_id:
                  type: string
                agent_instance_id:
                  type: string
                  description: Optional exact AgentInstance id to dispatch. When provided, Hub must not fall back to another agent.
                agent_type:
                  type: string
                  description: Optional Edge Runtime adapter id such as codex, claude-code, or opencode.
                custom_agent_id:
                  type: string
                  description: Optional CustomAgent id to dispatch. When provided, Hub must not fall back to another custom agent.
                model_params:
                  type: string
                  description: Optional JSON string with model/provider/reasoning hints copied into the agent.dispatch payload.
                target_id:
                  type: string
                  format: uuid
                  description: Optional owner-scoped ExecutionTarget id. Hub validates owner, dispatchable target type, and bound desktop device, persists target_id and edge_device_id on the pending task, routes agent.dispatch only to that device, and queues offline work in a target/device queue without falling back to another desktop. Remote/cloud targets still require future relay/provisioning work before they are product-complete.
      responses:
        "200":
          description: Task dispatched.

  /web/agent-tasks/{id}/events:
    get:
      tags: [HubSyncRelay]
      operationId: hubListTaskRunEvents
      summary: List typed runtime events persisted for an agent task.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: event_type
          in: query
          required: false
          schema: { type: string }
          description: Optional exact runtime event type filter.
        - name: after_seq
          in: query
          required: false
          schema: { type: integer, format: int64, minimum: 0 }
          description: Return only events with event_seq greater than this value.
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 0, maximum: 500 }
          description: Optional maximum number of events. Values above 500 are clamped by Hub.
      responses:
        "200":
          description: Ordered runtime events for replay.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/AgentRunEvent"

  /web/agent-tasks/{id}/events/summary:
    get:
      tags: [HubSyncRelay]
      operationId: hubGetTaskRunEventSummary
      summary: Summarize typed runtime event history for an agent task.
      description: Owner-scoped runtime history summary with task status, event counts, tokens, elapsed time, approval, artifact, output and tool-call aggregates.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Runtime event summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  data:
                    $ref: "#/components/schemas/AgentRunEventSummary"

  /edge/agent-tasks/{id}/ack:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [HubSyncRelay]
      operationId: hubTaskAck
      summary: Edge acknowledges an agent task and may attach the Edge run id.
      description: Optional run_id/edge_run_id is capped at 128 characters before Hub persists it.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HubTaskAckRequest"
      responses:
        "200":
          description: Task marked running.

  /edge/agent-tasks/{id}/stream:
    post:
      tags: [HubSyncRelay]
      operationId: hubTaskStream
      summary: Edge reports agent output stream chunk to Hub.
      description: Hub normalizes content/chunk or event_type + payload into an AgentRunEvent and chat projection. The persisted runtime payload and projected message content are each capped at 1 MiB after normalization. Optional run_id/edge_run_id is capped at 128 characters before Hub persists or matches it.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HubTaskStreamRequest"
      responses:
        "200":
          description: Chunk recorded.

  /edge/agent-tasks/{id}/done:
    post:
      tags: [HubSyncRelay]
      operationId: hubTaskDone
      summary: Edge reports agent task completed.
      description: Optional run_id/edge_run_id is capped at 128 characters; final_content is capped at the 1 MiB callback payload budget.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HubTaskDoneRequest"
      responses:
        "200":
          description: Task marked done.

  /edge/agent-tasks/{id}/fail:
    post:
      tags: [HubSyncRelay]
      operationId: hubTaskFail
      summary: Edge reports agent task failure.
      description: Optional run_id/edge_run_id is capped at 128 characters; error is capped at the 1 MiB callback payload budget.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HubTaskFailRequest"
      responses:
        "200":
          description: Task marked failed.

  # ═══════════════════════════════════════════════════════════
  # Hub Server — additional implemented routes
  # ═══════════════════════════════════════════════════════════

  # ── Auth ──

  /client/auth/oidc/authorize:
    post:
      tags: [HubSyncRelay]
      operationId: hubOidcAuthorize
      summary: Generate TokenDance ID OIDC PKCE authorization URL.
      description: >
        Public login-start endpoint. The client generates a PKCE verifier/challenge,
        sends the S256 challenge plus its Hub device proof, then opens the returned
        TokenDance ID authorization URL in a browser. This endpoint does not accept
        third-party provider tokens and does not require an existing Hub bearer token.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HubOIDCAuthorizeRequest"
      responses:
        "200":
          description: Hub state and TokenDance ID authorization URL.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HubOIDCAuthorizeResponse"
        "400":
          $ref: "#/components/responses/Error"

  /client/auth/oidc/callback:
    post:
      tags: [HubSyncRelay]
      operationId: hubOidcCallback
      summary: Exchange TokenDance ID OIDC code for a Hub session.
      description: >
        Public Hub session exchange endpoint. The client posts the browser callback
        code/state, its PKCE verifier, and the same Hub device proof used at authorize
        time. Hub exchanges the code with TokenDance ID, validates the ID token through
        RS256/JWKS plus issuer/audience/expiration checks, maps TokenDance ID sub to a
        Hub user, then returns Hub-local access and refresh tokens. Raw TokenDance ID
        bearer tokens are not used as Hub sessions.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HubOIDCCallbackRequest"
      responses:
        "200":
          description: Hub-local session tokens and mapped Hub user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HubOIDCCallbackResponse"
        "400":
          $ref: "#/components/responses/Error"

  # ── Contacts ──

  /client/contacts/{userId}:
    delete:
      tags: [HubSyncRelay]
      operationId: hubRemoveContact
      summary: Remove a contact.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "204":
          description: Removed.

  /client/contacts/{userId}/block:
    post:
      tags: [HubSyncRelay]
      operationId: hubBlockContact
      summary: Block a user.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/contacts/{userId}/unblock:
    post:
      tags: [HubSyncRelay]
      operationId: hubUnblockContact
      summary: Unblock a user.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/contacts/{userId}/remark:
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateRemark
      summary: Update contact remark.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [remark]
              properties:
                remark: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Friend Requests ──

  /client/friend-requests:
    get:
      tags: [HubSyncRelay]
      operationId: hubListFriendRequests
      summary: Legacy friend-request listing shape.
      x-deprecated: true
      description: No corresponding Hub router path exists. Use `GET /client/contacts/friend-requests`.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  /client/friend-requests/sent:
    get:
      tags: [HubSyncRelay]
      operationId: hubListSentFriendRequests
      summary: Legacy sent friend-request listing shape.
      x-deprecated: true
      description: No corresponding Hub router path exists.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  # ── Session Members ──

  /client/sessions/{id}/members:
    get:
      tags: [HubSyncRelay]
      operationId: hubListSessionMembers
      summary: List session members.
      x-deprecated: true
      description: No corresponding Hub router path exists.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: hubAddSessionMembers
      summary: Add members to a session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [members]
              properties:
                members:
                  type: array
                  items:
                    type: string
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /client/sessions/{id}/members/{user_id}:
    delete:
      tags: [HubSyncRelay]
      operationId: hubRemoveSessionMember
      summary: Remove a member from a session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: user_id
          in: path
          required: true
          schema: { type: string }
      responses:
        "204":
          description: Removed.

  /client/sessions/{id}/leave:
    post:
      tags: [HubSyncRelay]
      operationId: hubLeaveSession
      summary: Leave a session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Session Management ──

  /client/sessions/{id}/dissolve:
    post:
      tags: [HubSyncRelay]
      operationId: hubDissolveGroup
      summary: Dissolve a group session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/sessions/{id}/transfer-owner:
    post:
      tags: [HubSyncRelay]
      operationId: hubTransferOwner
      summary: Transfer session ownership.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [new_owner_user_id]
              properties:
                new_owner_user_id: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/sessions/{id}/settings:
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateMemberSettings
      summary: Update the current user's session settings.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pinned: { type: boolean }
                muted: { type: boolean }
                archived: { type: boolean }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/sessions/{id}/member-settings:
    patch:
      tags: [HubSyncRelay]
      operationId: hubUpdateMemberSettingsLegacy
      summary: Legacy member settings shape.
      x-deprecated: true
      description: No corresponding Hub router path exists. Use `PUT /client/sessions/{id}/settings`.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pinned: { type: boolean }
                muted: { type: boolean }
                archived: { type: boolean }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Message Operations ──

  /client/sessions/{id}/messages/search:
    get:
      tags: [HubSyncRelay]
      operationId: hubSearchSessionMessages
      summary: Search messages within a session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: q
          in: query
          required: true
          schema: { type: string }
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"

  /client/messages/search:
    get:
      tags: [HubSyncRelay]
      operationId: hubSearchMessages
      summary: Search messages across all sessions.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"

  /client/sessions/{id}/messages/{msgId}:recall:
    post:
      tags: [HubSyncRelay]
      operationId: hubRecallMessage
      summary: Recall (delete) a message.
      x-deprecated: true
      description: Deprecated session-scoped path. Use `POST /client/messages/{id}/recall` instead.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - $ref: "#/components/parameters/MsgId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/sessions/{id}/messages/{msgId}:pin:
    post:
      tags: [HubSyncRelay]
      operationId: hubPinMessage
      summary: Pin a message.
      x-deprecated: true
      description: Deprecated session-scoped path. Use `POST /client/messages/{id}/pin` instead.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - $ref: "#/components/parameters/MsgId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/sessions/{id}/messages/{msgId}:unpin:
    post:
      tags: [HubSyncRelay]
      operationId: hubUnpinMessage
      summary: Unpin a message.
      x-deprecated: true
      description: Deprecated session-scoped path. Use `DELETE /client/messages/{id}/pin` instead.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - $ref: "#/components/parameters/MsgId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/sessions/{id}/messages/{msgId}:read:
    post:
      tags: [HubSyncRelay]
      operationId: hubMarkMessageRead
      summary: Mark a message as read.
      x-deprecated: true
      description: Deprecated. No corresponding route exists in Hub router.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - $ref: "#/components/parameters/MsgId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/sessions/{id}/pins:
    get:
      tags: [HubSyncRelay]
      operationId: hubListPins
      summary: List pinned messages in a session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"

  /client/messages:forward:
    post:
      tags: [HubSyncRelay]
      operationId: hubForwardMessages
      summary: Legacy batch-forward shape.
      x-deprecated: true
      description: No corresponding Hub router path exists. Use `POST /client/messages/{id}/forward`.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message_ids, target_session_id]
              properties:
                message_ids:
                  type: array
                  items:
                    type: string
                target_session_id: { type: string }
      responses:
        "201":
          $ref: "#/components/responses/Created"

  # ── Attachments ──

  /client/attachments/probe:
    post:
      tags: [HubSyncRelay]
      operationId: hubProbeAttachment
      summary: Check if an attachment exists by hash.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [hash]
              properties:
                hash: { type: string }
      responses:
        "200":
          description: Attachment metadata if present; null if absent.

  /client/attachments:
    post:
      tags: [HubSyncRelay]
      operationId: hubUploadAttachment
      summary: Upload an attachment.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /client/attachments/{id}:
    get:
      tags: [HubSyncRelay]
      operationId: hubDownloadAttachment
      summary: Download an attachment.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Attachment file (binary).
        "404":
          $ref: "#/components/responses/Error"

  # ── Notifications ──

  /client/notifications:
    get:
      tags: [HubSyncRelay]
      operationId: hubListNotifications
      summary: List notifications.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: unread_only
          in: query
          required: false
          schema: { type: boolean }
        - name: limit
          in: query
          required: false
          schema: { type: integer }
        - name: offset
          in: query
          required: false
          schema: { type: integer }
      responses:
        "200":
          $ref: "#/components/responses/List"

  /client/notifications/{id}/read:
    post:
      tags: [HubSyncRelay]
      operationId: hubMarkNotificationRead
      summary: Mark a notification as read.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/notifications/read-all:
    post:
      tags: [HubSyncRelay]
      operationId: hubReadAllNotifications
      summary: Mark all notifications as read.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Custom Agents ──

  /web/agent-profiles:
    get:
      tags: [HubSyncRelay]
      operationId: hubListAgentProfiles
      summary: List Hub-owned Agent Profiles for the signed-in user.
      description: >
        Returns user-managed Agent Profiles from Hub. Web clients use this
        endpoint after TokenDance ID -> Hub session exchange; it is not an
        Edge runtime inventory endpoint and must not be used with raw
        TokenDance ID bearer tokens.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
        - name: runtime_id
          in: query
          required: false
          schema: { type: string }
          description: Filter profiles by Agent Runtime id, such as codex, claude-code, or opencode.
        - name: q
          in: query
          required: false
          schema: { type: string }
          description: Search profile names/descriptions.
      responses:
        "200":
          description: Hub response envelope containing a paginated Agent Profile list.
          content:
            application/json:
              schema:
                type: object
                required: [code, data]
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    type: object
                    required: [items, page]
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/AgentProfile"
                      page:
                        $ref: "#/components/schemas/PageInfo"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateAgentProfile
      summary: Create a new Agent Profile.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAgentProfileRequest"
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /web/custom-agents:
    get:
      tags: [HubSyncRelay]
      operationId: hubListCustomAgents
      summary: List custom agents.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateCustomAgent
      summary: Create a custom agent.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, agent_type, system_prompt]
              properties:
                name: { type: string }
                agent_type: { type: string }
                system_prompt: { type: string }
                capability_tags:
                  type: array
                  items:
                    type: string
                tool_whitelist:
                  type: array
                  items:
                    type: string
                model_params:
                  type: object
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /web/custom-agents/{id}:
    get:
      tags: [HubSyncRelay]
      operationId: hubGetCustomAgent
      summary: Legacy custom-agent detail shape.
      x-deprecated: true
      description: No corresponding Hub router path exists.
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateCustomAgent
      summary: Update a custom agent.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                agent_type: { type: string }
                system_prompt: { type: string }
                capability_tags:
                  type: array
                  items:
                    type: string
                tool_whitelist:
                  type: array
                  items:
                    type: string
                model_params:
                  type: object
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteCustomAgent
      summary: Delete a custom agent.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "204":
          description: Deleted.

  # ── Edge / Web ──

  /edge/devices/register:
    post:
      tags: [HubSyncRelay]
      operationId: hubRegisterDevice
      summary: Register a device with the Hub. Device type is taken from the JWT claim.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [device_id]
              properties:
                device_id:
                  type: string
                  format: uuid
                  description: UUID of the physical device (must match JWT device_id claim).
                app_version:
                  type: string
                  description: Optional client application version.
                capabilities:
                  type: array
                  items: { type: string }
                  description: Device capability tags (e.g. ["desktop", "edge"]).
      responses:
        "200":
          description: Device registered.
          content:
            application/json:
              schema:
                type: object
                required: [code, data]
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    $ref: "#/components/schemas/Device"
        "400":
          $ref: "#/components/responses/BadRequest"

  /web/agent-tasks/{id}/cancel:
    post:
      tags: [HubSyncRelay]
      operationId: hubCancelTask
      summary: Cancel an agent task.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Auth (routes from router.go not yet documented) ──

  /client/auth/refresh:
    post:
      tags: [HubSyncRelay]
      operationId: hubRefresh
      summary: Refresh JWT access token using refresh token.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refresh_token]
              properties:
                refresh_token: { type: string }
      responses:
        "200":
          description: New JWT token pair.

  /client/auth/logout:
    post:
      tags: [HubSyncRelay]
      operationId: hubLogout
      summary: Logout and invalidate tokens.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/auth/profile:
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateProfile
      summary: Update user profile (nickname, avatar, etc.).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nickname: { type: string }
                avatar_url: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Contacts (routes from router.go not yet documented) ──

  /client/contacts/search:
    get:
      tags: [HubSyncRelay]
      operationId: hubSearchContacts
      summary: Search contacts by keyword.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"

  /client/contacts/friend-requests:
    get:
      tags: [HubSyncRelay]
      operationId: hubListContactFriendRequests
      summary: List received friend requests.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: hubSendFriendRequest
      summary: Send a friend request.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [friend_id]
              properties:
                friend_id: { type: string }
                message: { type: string }
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /client/contacts/friend-requests/{id}/accept:
    post:
      tags: [HubSyncRelay]
      operationId: hubAcceptFriendRequest
      summary: Accept a friend request.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/contacts/friend-requests/{id}/reject:
    post:
      tags: [HubSyncRelay]
      operationId: hubRejectFriendRequest
      summary: Reject a friend request.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Sessions (routes from router.go not yet documented) ──

  /client/sessions/{id}/info:
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateGroupInfo
      summary: Update group session info (name, avatar, announcement).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                avatar_url: { type: string }
                announcement: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/sessions/{id}:
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteSession
      summary: Delete session for current user (soft-delete).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "204":
          description: Deleted.

  /client/sessions/{id}/messages/sync:
    get:
      tags: [HubSyncRelay]
      operationId: hubSyncMessages
      summary: Get incremental messages after a cursor (sync).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: cursor
          in: query
          required: false
          schema: { type: string }
        - name: limit
          in: query
          required: false
          schema: { type: integer }
      responses:
        "200":
          description: Incremental message batch.

  /client/sessions/{id}/read:
    post:
      tags: [HubSyncRelay]
      operationId: hubMarkSessionRead
      summary: Mark all messages in a session as read.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/sessions/{id}/agents:
    post:
      tags: [HubSyncRelay]
      operationId: hubAddAgentToSession
      summary: Add an agent to a session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [agent_id]
              properties:
                agent_id: { type: string }
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /client/sessions/search:
    get:
      tags: [HubSyncRelay]
      operationId: hubSearchSessions
      summary: Search sessions by keyword.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"

  # ── Messages (individual operations — code paths) ──

  /client/messages/{id}/recall:
    post:
      tags: [HubSyncRelay]
      operationId: hubRecallMessageDirect
      summary: Recall (delete) a message.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/messages/{id}/pin:
    post:
      tags: [HubSyncRelay]
      operationId: hubPinMessageDirect
      summary: Pin a message.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [HubSyncRelay]
      operationId: hubUnpinMessageDirect
      summary: Unpin a message.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /client/messages/{id}/forward:
    post:
      tags: [HubSyncRelay]
      operationId: hubForwardSingleMessage
      summary: Forward a single message to another session.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [target_session_id]
              properties:
                target_session_id: { type: string }
      responses:
        "201":
          $ref: "#/components/responses/Created"

  # ── Execution Targets ──

  /web/execution-targets:
    get:
      tags: [HubSyncRelay]
      operationId: hubListExecutionTargets
      summary: List execution targets.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateExecutionTarget
      summary: Create an execution target.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateExecutionTargetRequest"
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /web/execution-targets/{id}:
    get:
      tags: [HubSyncRelay]
      operationId: hubGetExecutionTarget
      summary: Get an execution target.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [HubSyncRelay]
      operationId: hubUpdateExecutionTarget
      summary: Update an execution target.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateExecutionTargetRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteExecutionTarget
      summary: Delete an execution target.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "204":
          description: Deleted.

  /web/execution-targets/{id}/ping:
    post:
      tags: [HubSyncRelay]
      operationId: hubPingExecutionTarget
      summary: Ping an execution target to test connectivity.
      description: Current Hub proof only marks local_edge targets healthy. Remote SSH, Tailscale, Cloud Edge, and Hub Relay targets return TARGET_NOT_ROUTABLE until their live health proof paths are implemented, and Hub does not mark them online from this manual ping.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "409":
          $ref: "#/components/responses/Error"

  # ── Audit Events ──

  /web/audit-events:
    get:
      tags: [HubSyncRelay]
      operationId: hubListAuditEvents
      summary: List audit events.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"

  # ── Relay Commands (web) ──

  /web/relay/commands:
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateWebRelayCommand
      summary: Create a relay command.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [command_type, payload]
              description: Provide target_edge_id. The legacy target_id alias is accepted for clients generated from the earlier web relay schema.
              properties:
                target_edge_id:
                  type: string
                  description: Target Edge connection/user id that should receive the relay command.
                target_id:
                  type: string
                  deprecated: true
                  description: Backward-compatible alias for target_edge_id.
                command_type:
                  type: string
                  description: Relay command type, for example run.cancel.
                payload:
                  type: object
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/relay/commands/{id}:
    get:
      tags: [HubSyncRelay]
      operationId: hubGetWebRelayCommand
      summary: Get a relay command status.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/relay/commands/{id}/ack:
    post:
      tags: [HubSyncRelay]
      operationId: hubAckWebRelayCommand
      summary: Acknowledge a relay command.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Devices (web) ──

  /web/devices:
    get:
      tags: [HubSyncRelay]
      operationId: hubListDevices
      summary: List user devices.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  # ── Agent Teams (web) ──

  /web/agent-teams:
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateAgentTeam
      summary: Create an agent team.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  maxLength: 100
                description:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    get:
      tags: [HubSyncRelay]
      operationId: hubListAgentTeams
      summary: List agent teams owned by the current user.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  /web/agent-teams/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [HubSyncRelay]
      operationId: hubGetAgentTeam
      summary: Get agent team detail with members.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateAgentTeam
      summary: Update agent team name and description.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
                description:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteAgentTeam
      summary: Delete an agent team.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/members:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    post:
      tags: [HubSyncRelay]
      operationId: hubAddTeamMember
      summary: Add an agent profile to a team.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [agent_profile_id]
              properties:
                agent_profile_id:
                  type: string
                  format: uuid
                role:
                  type: string
                  enum: [supervisor, executor, reviewer]
                  default: executor
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/members/{member_id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: member_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    delete:
      tags: [HubSyncRelay]
      operationId: hubRemoveTeamMember
      summary: Remove a member from a team.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/runs:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    post:
      tags: [HubSyncRelay]
      operationId: hubStartTeamRun
      summary: Start a team run with a trigger message.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [trigger_message]
              properties:
                trigger_message:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    get:
      tags: [HubSyncRelay]
      operationId: hubListTeamRuns
      summary: List runs for a team.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  /web/agent-teams/{id}/runs/{run_id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [HubSyncRelay]
      operationId: hubGetTeamRun
      summary: Get a team run detail.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/runs/{run_id}/state:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [HubSyncRelay]
      operationId: hubGetTeamRunState
      summary: Replay a team run state from TeamEvent and assignment data.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/runs/{run_id}/events:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [HubSyncRelay]
      operationId: hubListTeamEvents
      summary: List append-only TeamEvent entries for a team run.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  /web/agent-teams/{id}/runs/{run_id}/tasks:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [HubSyncRelay]
      operationId: hubListTeamTasks
      summary: List first-class TeamTask rows for a team run.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  /web/agent-teams/{id}/runs/{run_id}/route-decisions:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    post:
      tags: [HubSyncRelay]
      operationId: hubHandleTeamRouteDecision
      summary: Consume a typed supervisor route decision and record accepted or rejected TeamEvent audit entries.
      description: Applies schema validation plus task-count, active-subagent, and repeated-route guardrails before creating TeamAssignment and TeamTask rows.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CoordinatorRouteDecision"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/runs/{run_id}/approvals/{approval_id}/decide:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: approval_id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [HubSyncRelay]
      operationId: hubDecideTeamApproval
      summary: Record a TeamRun approval decision and deliver the Edge control payload.
      description: Validates that the approval is still pending and tied to an exact Edge device, appends a team.approval.decided TeamEvent, returns the Edge control payload, and pushes or queues an agent.control permission.decide frame for the owning Desktop/Edge device. Hub rejects decisions that cannot be mapped to a recorded edge_device_id so approvals cannot silently fall back to another desktop.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TeamApprovalDecisionRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/runs/{run_id}/conflicts/{conflict_id}/resolve:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: conflict_id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [HubSyncRelay]
      operationId: hubResolveTeamConflict
      summary: Resolve a projected TeamRun file conflict and append an auditable TeamEvent.
      description: Validates that the conflict still exists in the replayed TeamRunState, records the human decision as team.conflict.resolved, and marks the conflict resolved on subsequent state replay.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TeamConflictResolveRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/runs/{run_id}/assignments:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateTeamAssignment
      summary: Create a team assignment (delegation) from a supervisor to an executor.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [from_member_id, to_member_id, task_prompt]
              properties:
                from_member_id:
                  type: string
                  format: uuid
                to_member_id:
                  type: string
                  format: uuid
                type:
                  type: string
                  enum: [delegate, review, approve, notify]
                  default: delegate
                task_prompt:
                  type: string
                context:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    get:
      tags: [HubSyncRelay]
      operationId: hubListTeamAssignments
      summary: List all assignments for a team run.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/List"

  /web/agent-teams/{id}/runs/{run_id}/assignments/{assignment_id}/dispatch:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: assignment_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    post:
      tags: [HubSyncRelay]
      operationId: hubDispatchTeamAssignment
      summary: Dispatch a pending assignment through Hub agent task routing and bind TeamTask state.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/runs/{run_id}/assignments/{assignment_id}/complete:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: assignment_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    post:
      tags: [HubSyncRelay]
      operationId: hubCompleteTeamAssignment
      summary: Mark a running assignment as completed with result.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [result]
              properties:
                result:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-teams/{id}/runs/{run_id}/assignments/{assignment_id}/fail:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: run_id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - name: assignment_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    post:
      tags: [HubSyncRelay]
      operationId: hubFailTeamAssignment
      summary: Mark an assignment as failed with a reason.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Legacy / Planned (not yet implemented) ──────────────────

  /v1/auth/login:
    post:
      tags: [HubSyncRelay]
      operationId: login
      summary: Login.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/auth/logout:
    post:
      tags: [HubSyncRelay]
      operationId: logout
      summary: Logout.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "204":
          description: Logged out.

  /v1/users/me:
    get:
      tags: [HubSyncRelay]
      operationId: getMe
      summary: Get current user.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [HubSyncRelay]
      operationId: updateMe
      summary: Update current user.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/contacts:
    get:
      tags: [HubSyncRelay]
      operationId: listContacts
      summary: List contacts.
      x-agenthub-phase: P4
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/contacts:request:
    post:
      tags: [HubSyncRelay]
      operationId: requestContact
      summary: Send contact request.
      x-agenthub-phase: P4
      x-agenthub-owner: Hub
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/contacts/{userId}:accept:
    post:
      tags: [HubSyncRelay]
      operationId: acceptContact
      summary: Accept contact request.
      x-agenthub-phase: P4
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/contacts/{userId}:
    delete:
      tags: [HubSyncRelay]
      operationId: deleteContact
      summary: Delete contact.
      x-agenthub-phase: P4
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "204":
          description: Deleted.

  /v1/groups:
    get:
      tags: [HubSyncRelay]
      operationId: listGroups
      summary: List groups.
      x-agenthub-phase: P4
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: createGroup
      summary: Create group.
      x-agenthub-phase: P4
      x-agenthub-owner: Hub
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/groups/{groupId}:
    get:
      tags: [HubSyncRelay]
      operationId: getGroup
      summary: Get group.
      x-agenthub-phase: P4
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/GroupId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [HubSyncRelay]
      operationId: updateGroup
      summary: Update group.
      x-agenthub-phase: P4
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/GroupId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/devices:
    get:
      tags: [HubSyncRelay]
      operationId: listDevices
      summary: List devices.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/devices:register:
    post:
      tags: [HubSyncRelay]
      operationId: registerDevice
      summary: Register device.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/devices/{deviceId}:
    delete:
      tags: [HubSyncRelay]
      operationId: deleteDevice
      summary: Delete device.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/DeviceId"
      responses:
        "204":
          description: Deleted.

  /v1/edges:
    get:
      tags: [HubSyncRelay]
      operationId: listEdges
      summary: List Edge nodes.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/edges:register:
    post:
      tags: [HubSyncRelay]
      operationId: registerEdge
      summary: Register Edge node.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/edges/{edgeId}:
    get:
      tags: [HubSyncRelay]
      operationId: getEdge
      summary: Get Edge node.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/EdgeId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [HubSyncRelay]
      operationId: updateEdge
      summary: Update Edge node.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/EdgeId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/edges/{edgeId}:heartbeat:
    post:
      tags: [HubSyncRelay]
      operationId: heartbeatEdge
      summary: Send Edge heartbeat.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/EdgeId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/sync/events:upload:
    post:
      tags: [HubSyncRelay]
      operationId: uploadSyncEvents
      summary: Upload Edge events.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/sync/events:
    get:
      tags: [HubSyncRelay]
      operationId: listSyncEvents
      summary: List sync events.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/sync/ack:
    post:
      tags: [HubSyncRelay]
      operationId: ackSync
      summary: Acknowledge sync cursor.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/sync/state:
    get:
      tags: [HubSyncRelay]
      operationId: getSyncState
      summary: Get sync state.
      x-agenthub-phase: P2
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/relay/commands:
    post:
      tags: [HubSyncRelay]
      operationId: createRelayCommand
      summary: Create relay command.
      x-agenthub-phase: P3
      x-agenthub-owner: Hub
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/relay/commands/{commandId}:
    get:
      tags: [HubSyncRelay]
      operationId: getRelayCommand
      summary: Get relay command.
      x-agenthub-phase: P3
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/CommandId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/relay/commands/{commandId}:ack:
    post:
      tags: [HubSyncRelay]
      operationId: ackRelayCommand
      summary: Acknowledge relay command.
      x-agenthub-phase: P3
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/CommandId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/relay/edges/{edgeId}:
    get:
      tags: [HubSyncRelay]
      operationId: openEdgeRelay
      summary: Open reverse WebSocket relay for Edge.
      x-agenthub-phase: P3
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/EdgeId"
      responses:
        "101":
          description: Switching Protocols.

  /v1/cloud/edges:
    get:
      tags: [HubSyncRelay]
      operationId: listCloudEdges
      summary: List Cloud Edge nodes.
      x-agenthub-phase: P3
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: createCloudEdge
      summary: Create Cloud Edge node.
      x-agenthub-phase: P3
      x-agenthub-owner: Hub
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/cloud/runners:allocate:
    post:
      tags: [HubSyncRelay]
      operationId: allocateCloudRunner
      summary: Allocate Cloud Runner.
      x-agenthub-phase: P3
      x-agenthub-owner: Hub
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/cloud/runners/{runnerId}:release:
    post:
      tags: [HubSyncRelay]
      operationId: releaseCloudRunner
      summary: Release Cloud Runner.
      x-agenthub-phase: P3
      x-agenthub-owner: Hub
      parameters:
        - $ref: "#/components/parameters/RunnerId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  # ═══════════════════════════════════════════════════════════
  # Hub Server — additional /web routes (Phase 2–6)
  # ═══════════════════════════════════════════════════════════

  # ── Agent Profiles (CRUD beyond GET list) ──

  /web/agent-profiles/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [HubSyncRelay]
      operationId: hubGetAgentProfile
      summary: Get an owner-scoped Agent Profile by id.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "403":
          $ref: "#/components/responses/Error"
    patch:
      tags: [HubSyncRelay]
      operationId: hubUpdateAgentProfile
      summary: Update an Agent Profile.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAgentProfileRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteAgentProfile
      summary: Delete an Agent Profile.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "204":
          description: Deleted.

  /web/agent-profiles/{id}/publish:
    post:
      tags: [HubSyncRelay]
      operationId: hubPublishAgentProfile
      summary: Publish an Agent Profile to the marketplace (admin only).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/agent-profiles/{id}/install:
    post:
      tags: [HubSyncRelay]
      operationId: hubInstallAgentProfile
      summary: Install an Agent Profile from the marketplace.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Skills ──

  /web/skills:
    get:
      tags: [HubSyncRelay]
      operationId: hubListSkills
      summary: List skills owned by the current user.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateSkill
      summary: Create a skill.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSkillRequest"
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /web/skills/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [HubSyncRelay]
      operationId: hubGetSkill
      summary: Get an owner-scoped skill.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "403":
          $ref: "#/components/responses/Error"
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateSkill
      summary: Update a skill.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSkillRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteSkill
      summary: Delete a skill.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "204":
          description: Deleted.

  /web/skills/{id}/publish:
    post:
      tags: [HubSyncRelay]
      operationId: hubPublishSkill
      summary: Publish a skill to the marketplace (admin only).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/skills/{id}/unpublish:
    post:
      tags: [HubSyncRelay]
      operationId: hubUnpublishSkill
      summary: Unpublish a skill from the marketplace (admin only).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── MCP Servers ──

  /web/mcp-servers:
    get:
      tags: [HubSyncRelay]
      operationId: hubListMCPServers
      summary: List MCP servers owned by the current user.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateMCPServer
      summary: Create an MCP server.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateMCPServerRequest"
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /web/mcp-servers/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [HubSyncRelay]
      operationId: hubGetMCPServer
      summary: Get an owner-scoped MCP server.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "403":
          $ref: "#/components/responses/Error"
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateMCPServer
      summary: Update an MCP server.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateMCPServerRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteMCPServer
      summary: Delete an MCP server.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "204":
          description: Deleted.

  /web/mcp-servers/{id}/publish:
    post:
      tags: [HubSyncRelay]
      operationId: hubPublishMCPServer
      summary: Publish an MCP server to the marketplace (admin only).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/mcp-servers/{id}/unpublish:
    post:
      tags: [HubSyncRelay]
      operationId: hubUnpublishMCPServer
      summary: Unpublish an MCP server from the marketplace (admin only).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  # ── Provider Bindings ──

  /web/provider-bindings:
    get:
      tags: [HubSyncRelay]
      operationId: hubListProviderBindings
      summary: List provider bindings.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateProviderBinding
      summary: Create a provider binding.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProviderBindingRequest"
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /web/provider-bindings/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateProviderBinding
      summary: Update a provider binding.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProviderBindingRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteProviderBinding
      summary: Delete a provider binding.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "204":
          description: Deleted.

  # ── Market ──

  /web/market/profiles:
    get:
      tags: [HubSyncRelay]
      operationId: hubSearchMarketProfiles
      summary: Search published Agent Profiles in the marketplace.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
        - name: q
          in: query
          required: false
          schema: { type: string }
          description: Search keyword for profile name or description.
      responses:
        "200":
          $ref: "#/components/responses/List"

  /web/market/profiles/{id}:
    get:
      tags: [HubSyncRelay]
      operationId: hubGetMarketProfile
      summary: Get a published marketplace profile; private profiles return 404.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "404":
          $ref: "#/components/responses/Error"

  /web/market/profiles/{id}/install:
    post:
      tags: [HubSyncRelay]
      operationId: hubInstallMarketProfile
      summary: Install a marketplace profile.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /web/market/profiles/{id}/rate:
    post:
      tags: [HubSyncRelay]
      operationId: hubRateMarketProfile
      summary: Rate a marketplace profile.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rating]
              properties:
                rating:
                  type: integer
                  minimum: 1
                  maximum: 5
      responses:
        "200":
          $ref: "#/components/responses/Ok"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Hub HS256 access token
      description: >
        Hub-issued access token minted by Hub Server after password login or
        TokenDance ID OIDC exchange. Do not send a raw TokenDance ID RS256
        bearer token or a Relay API key to Hub REST/WebSocket endpoints.
    edgeBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Local Edge token
      description: >
        Optional Local Edge token configured by AGENTHUB_EDGE_AUTH_TOKEN or
        --local-auth-token. This is only the loopback Edge process boundary and
        is not a Hub session, TokenDance ID token, or Relay API key.
    edgeLocalToken:
      type: apiKey
      in: header
      name: X-AgentHub-Edge-Token
      description: >
        Header alternative for the optional Local Edge token when Authorization
        is already owned by another caller context.
    edgeWebSocketQueryToken:
      type: apiKey
      in: query
      name: access_token
      description: >
        Browser WebSocket transport for the optional Local Edge token on
        /v1/events. Hub WebSocket uses Hub-issued access tokens separately.
  parameters:
    PageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    PageCursor:
      name: pageCursor
      in: query
      required: false
      schema:
        type: string
    ProjectIdQuery:
      name: projectId
      in: query
      required: false
      schema:
        type: string
    ThreadIdQuery:
      name: threadId
      in: query
      required: false
      schema:
        type: string
    ProjectId:
      name: projectId
      in: path
      required: true
      schema:
        type: string
    ConversationId:
      name: conversationId
      in: path
      required: true
      schema:
        type: string
    MemberId:
      name: memberId
      in: path
      required: true
      schema:
        type: string
    MsgId:
      name: msgId
      in: path
      required: true
      schema:
        type: string
    ThreadId:
      name: threadId
      in: path
      required: true
      schema:
        type: string
    ItemId:
      name: itemId
      in: path
      required: true
      schema:
        type: string
    RunnerId:
      name: runnerId
      in: path
      required: true
      schema:
        type: string
    RunId:
      name: runId
      in: path
      required: true
      schema:
        type: string
    ApprovalId:
      name: approvalId
      in: path
      required: true
      schema:
        type: string
    ArtifactId:
      name: artifactId
      in: path
      required: true
      schema:
        type: string
    PreviewId:
      name: previewId
      in: path
      required: true
      schema:
        type: string
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      schema:
        type: string
    UserId:
      name: userId
      in: path
      required: true
      schema:
        type: string
    GroupId:
      name: groupId
      in: path
      required: true
      schema:
        type: string
    DeviceId:
      name: deviceId
      in: path
      required: true
      schema:
        type: string
    EdgeId:
      name: edgeId
      in: path
      required: true
      schema:
        type: string
    CommandId:
      name: commandId
      in: path
      required: true
      schema:
        type: string
  schemas:
    Resource:
      type: object
      additionalProperties: true
    ListResponse:
      type: object
      required: [items, page]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Resource"
        page:
          $ref: "#/components/schemas/PageInfo"
    PageInfo:
      type: object
      required: [hasMore]
      properties:
        nextCursor:
          type: string
        hasMore:
          type: boolean
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
            traceId:
              type: string
            details:
              type: object
              additionalProperties: true
    HubOIDCAuthorizeRequest:
      type: object
      required: [code_challenge, device_type, device_id]
      properties:
        code_challenge:
          type: string
          description: PKCE S256 code challenge generated by the client.
        code_challenge_method:
          type: string
          enum: [S256]
          default: S256
          description: Hub accepts only S256; omitted values default to S256.
        device_type:
          type: string
          enum: [desktop, web, cli]
          description: Hub device class for the resulting local session.
        device_id:
          type: string
          format: uuid
          description: Stable Hub device UUID; must match the callback request. Current target-bound dispatch requires an owner-owned desktop device; remote/cloud routing remains future work.
        redirect_uri:
          type: string
          format: uri
          description: Optional browser redirect URI for this PKCE round trip. When omitted, Hub uses its configured TokenDance ID redirect URI.
    HubOIDCAuthorizeResponse:
      type: object
      required: [code, data]
      properties:
        code:
          type: string
          enum: [OK]
        message:
          type: string
        data:
          type: object
          required: [state, authorization_url]
          properties:
            state:
              type: string
              description: One-time Hub state value bound to PKCE and device proof.
            authorization_url:
              type: string
              format: uri
              description: TokenDance ID /oidc/authorize URL to open in the browser.
    HubOIDCCallbackRequest:
      type: object
      required: [code, state, code_verifier, device_type, device_id]
      properties:
        code:
          type: string
          description: Authorization code returned by TokenDance ID.
        state:
          type: string
          description: Hub state returned from /client/auth/oidc/authorize.
        code_verifier:
          type: string
          description: Original PKCE verifier corresponding to the S256 challenge.
        device_type:
          type: string
          enum: [desktop, web, cli]
        device_id:
          type: string
          format: uuid
          description: Same stable Hub device UUID used in the authorize request.
        redirect_uri:
          type: string
          format: uri
          description: Same redirect URI used in the authorize request. Optional for legacy desktop clients that use the configured Hub redirect URI.
    HubOIDCCallbackResponse:
      type: object
      required: [code, data]
      properties:
        code:
          type: string
          enum: [OK]
        message:
          type: string
        data:
          type: object
          required: [access_token, refresh_token, expires_in, user]
          properties:
            access_token:
              type: string
              description: Hub-local HS256 access token for REST and WebSocket auth.
            refresh_token:
              type: string
              description: Hub-local refresh token; not a TokenDance ID refresh token.
            expires_in:
              type: integer
              format: int64
              description: Hub access token lifetime in seconds.
            user:
              type: object
              required: [id, username, nickname]
              properties:
                id:
                  type: string
                  format: uuid
                username:
                  type: string
                nickname:
                  type: string
                avatar_url:
                  type: string
                tokendance_sub:
                  type: string
                  description: TokenDance ID subject mapped to this Hub user.
    HubTaskAckRequest:
      type: object
      properties:
        run_id:
          type: string
          maxLength: 128
          description: Edge run id returned by POST /v1/runs.
        edge_run_id:
          type: string
          maxLength: 128
          description: Alias for run_id for explicit Hub persistence.
    HubTaskStreamRequest:
      type: object
      anyOf:
        - required: [content]
        - required: [chunk]
        - required: [payload]
      properties:
        content:
          type: string
          maxLength: 1048576
          description: 'Legacy stream content. If not valid JSON, Hub wraps it as {"content": "..."} for jsonb storage. Normalized payload/message content must stay within the 1 MiB per-event budget.'
        chunk:
          type: string
          maxLength: 1048576
          description: Legacy alias for content. Normalized payload/message content must stay within the 1 MiB per-event budget.
        event_type:
          type: string
          maxLength: 96
          description: Typed AgentHub runtime event name, for example run.output.batch or run.agent.tool_call.
        payload:
          type: object
          additionalProperties: true
          description: Typed runtime payload persisted as jsonb and broadcast as agent.stream. The encoded JSON payload must stay within the 1 MiB per-event budget.
        client_msg_id:
          type: string
          format: uuid
          description: Client-generated message id for idempotent stream dedup.
        run_id:
          type: string
          maxLength: 128
          description: Edge run id.
        edge_run_id:
          type: string
          maxLength: 128
          description: Alias for run_id.
    AgentRunEvent:
      type: object
      properties:
        id:
          type: string
        task_id:
          type: string
        edge_run_id:
          type: string
          maxLength: 128
        session_id:
          type: string
        agent_instance_id:
          type: string
        event_seq:
          type: integer
          format: int64
        event_type:
          type: string
        payload:
          type: object
          additionalProperties: true
          description: Runtime payload persisted by Hub. Encoded JSON is capped at 1 MiB on stream ingest.
        created_at:
          type: string
          format: date-time
    AgentRunEventSummary:
      type: object
      properties:
        task_id:
          type: string
        edge_run_id:
          type: string
          maxLength: 128
        status:
          type: string
          description: Current Hub pending task status.
        total_events:
          type: integer
        last_event_seq:
          type: integer
          format: int64
        event_type_counts:
          type: object
          additionalProperties:
            type: integer
        tool_call_count:
          type: integer
        step_count:
          type: integer
        artifact_count:
          type: integer
        approval_count:
          type: integer
        pending_approvals:
          type: integer
        decided_approvals:
          type: integer
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        output_bytes:
          type: integer
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        elapsed_ms:
          type: integer
          format: int64
    HubTaskDoneRequest:
      type: object
      properties:
        run_id:
          type: string
          maxLength: 128
          description: Edge run id.
        edge_run_id:
          type: string
          maxLength: 128
          description: Alias for run_id.
        final_content:
          type: string
          maxLength: 1048576
          description: Optional final agent output or summary inserted as the final chat projection. Hub rejects values above the 1 MiB callback payload budget.
    HubTaskFailRequest:
      type: object
      required: [error]
      properties:
        run_id:
          type: string
          maxLength: 128
          description: Edge run id.
        edge_run_id:
          type: string
          maxLength: 128
          description: Alias for run_id.
        error:
          type: string
          maxLength: 1048576
          description: Failure reason persisted on the task and broadcast as agent.failed. Hub rejects values above the 1 MiB callback payload budget.
    StartRunRequest:
      type: object
      properties:
        projectId:
          type: string
          description: Project to bind the run to. Defaults to the local project in P0 compatibility mode.
        threadId:
          type: string
          description: Thread to bind the run to. Defaults to the local thread in P0 compatibility mode.
        prompt:
          type: string
          description: User message or task description passed to the agent.
        agentId:
          type: string
          description: Agent adapter ID (claude-code, codex, opencode, orchestrator). Defaults to the server's --agent-default.
        model:
          type: string
          description: Model override for this run (e.g. claude-sonnet-4-6).
        sessionId:
          type: string
          description: Resume a specific session by ID (Claude Code --resume, OpenCode --session).
        continue:
          type: boolean
          description: Continue the most recent session (Claude Code --continue, OpenCode --continue).
        fork:
          type: boolean
          description: Fork session before continuing (Claude Code --fork-session, OpenCode --fork).
        reasoningEffort:
          type: string
          description: >
            Reasoning effort level. Claude Code values: low, medium, high, max.
            Codex values: minimal, low, medium, high, xhigh.
            OpenCode: passed as --variant for thinking control.
        thinkingMode:
          type: string
          description: Thinking mode override for runtimes that expose an explicit thinking switch.
        maxThinkingTokens:
          type: integer
          description: Maximum thinking token budget (Claude Code --max-thinking-tokens).
        permissionMode:
          type: string
          description: >
            Claude Code permission mode: default, acceptEdits, bypassPermissions, plan, dontAsk.
            Also mapped to Codex --sandbox level.
        workDir:
          type: string
          description: Working directory override for this run. Defaults to the Edge process profile workdir.
        includePartial:
          type: boolean
          description: Include partial stream_event messages for real-time deltas (Claude Code --include-partial-messages).
        structuredOutputSchema:
          type: string
          description: Optional JSON Schema string passed to runtimes that support structured output, currently Claude Code --json-schema.
        systemPrompt:
          type: string
          description: Runtime system prompt override, usually derived from a Hub CustomAgent/Profile policy.
        appendSystemPrompt:
          type: string
          description: Additional prompt text appended to the runtime default system prompt.
        allowedTools:
          type: array
          items:
            type: string
          description: Tool allowlist passed to runtimes that support tool-scoped execution.
        configOverrides:
          type: object
          additionalProperties:
            type: string
          description: Runtime-specific key/value config overrides, currently consumed by Codex as -c entries.
        ephemeral:
          type: boolean
          description: Request a no-persistent-session run for runtimes that support it.
        hubTaskId:
          type: string
          description: Optional Hub task id for Edge-owned Hub callbacks. Desktop bridge usually streams callbacks itself and should avoid duplicate callback paths.
    AgentInfo:
      type: object
      required: [id, name, status]
      properties:
        id:
          type: string
          description: Agent adapter ID.
        name:
          type: string
          description: Display name.
        description:
          type: string
          description: Human-readable description.
        version:
          type: string
          description: CLI version if detected.
        runtimeId:
          type: string
          description: Normalized Agent Runtime id for Hub AgentProfile-backed entries.
        model:
          type: string
          description: Model hint for a Hub AgentProfile-backed entry.
        provider:
          type: string
          description: Provider hint for a Hub AgentProfile-backed entry.
        reasoningEffort:
          type: string
          description: Reasoning effort hint for a Hub AgentProfile-backed entry.
        permissionMode:
          type: string
          description: Runtime permission policy hint for a Hub AgentProfile-backed entry.
        toolAllowlist:
          type: array
          items:
            type: string
          description: Tool allowlist projected from Hub AgentProfile tool_allowlist.
        targetPreferences:
          type: object
          additionalProperties: true
          description: Execution target hints projected from Hub AgentProfile target_preferences.
        status:
          type: string
          description: '"available" if the agent CLI is configured and reachable.'
        capabilities:
          type: object
          additionalProperties: true
          description: Capability flags (streaming, toolCalls, fileChanges, etc.).
    ExecutionTarget:
      type: object
      required: [id, owner_id, name, target_type, is_online]
      properties:
        id:
          type: string
          format: uuid
        owner_id:
          type: string
          format: uuid
        device_id:
          type: string
          format: uuid
        name:
          type: string
        target_type:
          type: string
          enum: [local_edge, remote_ssh, tailscale, cloud_edge, hub_relay]
        host:
          type: string
        port:
          type: integer
        workspace_root:
          type: string
        workspace_allowlist:
          type: string
          description: JSON string array encoded by the current Hub model.
        trust_level:
          type: string
          enum: [local, remote, cloud, relay]
        health_state:
          type: string
          enum: [unknown, healthy, degraded, offline]
          readOnly: true
          description: System-managed health proof state. Clients cannot set this through create/update requests.
        auth_method:
          type: string
        is_online:
          type: boolean
        last_seen_at:
          type: string
          format: date-time
        capabilities:
          type: string
          description: JSON object encoded by the current Hub model.
        metadata:
          type: string
          description: JSON object encoded by the current Hub model.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateExecutionTargetRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        target_type:
          type: string
          enum: [local_edge, remote_ssh, tailscale, cloud_edge, hub_relay]
          default: local_edge
        host:
          type: string
        port:
          type: integer
        workspace_root:
          type: string
        workspace_allowlist:
          type: array
          items:
            type: string
          description: Workspace roots this target may execute inside. Empty keeps the target registered but does not grant remote/cloud workspace routing.
        trust_level:
          type: string
          enum: [local, remote, cloud, relay]
          default: local
        auth_method:
          type: string
        device_id:
          type: string
          format: uuid
        capabilities:
          type: string
          description: JSON object encoded by the current Hub model.
        metadata:
          type: string
          description: JSON object encoded by the current Hub model.
    UpdateExecutionTargetRequest:
      type: object
      properties:
        name:
          type: string
        target_type:
          type: string
          enum: [local_edge, remote_ssh, tailscale, cloud_edge, hub_relay]
        host:
          type: string
        port:
          type: integer
        workspace_root:
          type: string
        workspace_allowlist:
          type: array
          items:
            type: string
          description: Workspace roots this target may execute inside. Empty clears the target-local allowlist.
        trust_level:
          type: string
          enum: [local, remote, cloud, relay]
        auth_method:
          type: string
        device_id:
          type: string
          format: uuid
        capabilities:
          type: string
          description: JSON object encoded by the current Hub model.
        metadata:
          type: string
          description: JSON object encoded by the current Hub model.
    AgentProfile:
      type: object
      required: [id, name, runtime_id]
      properties:
        id:
          type: string
          format: uuid
          description: Hub Agent Profile id.
        owner_id:
          type: string
          format: uuid
          description: Hub user that owns this profile.
        name:
          type: string
          description: User-visible Agent Profile name.
        description:
          type: string
        runtime_id:
          type: string
          description: Agent Runtime id such as codex, claude-code, or opencode.
        model:
          type: string
        provider:
          type: string
        reasoning_effort:
          type: string
        model_mapping:
          type: string
          description: JSON object encoded by current Hub model.
        skills:
          type: string
          description: JSON array encoded by current Hub model.
        mcp_servers:
          type: string
          description: JSON array encoded by current Hub model.
        tool_allowlist:
          type: string
          description: JSON array encoded by current Hub model.
        approval_policy:
          type: string
          description: JSON object encoded by current Hub model.
        permission_mode:
          type: string
        target_preferences:
          type: string
          description: JSON object encoded by current Hub model.
        context_budget_max_tokens:
          type: integer
        is_public:
          type: boolean
        install_count:
          type: integer
        rating_avg:
          type: number
        rating_count:
          type: integer
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateThreadMessageRequest:
      type: object
      required: [content]
      properties:
        content:
          type: string
          minLength: 1
          description: Message body. Whitespace-only content is rejected by the Edge server.
        role:
          type: string
          default: user
          description: Message role. Defaults to user when omitted.
    Item:
      type: object
      required: [itemId, projectId, threadId, type, status, createdAt, updatedAt]
      properties:
        itemId:
          type: string
        projectId:
          type: string
        threadId:
          type: string
        runId:
          type: string
        type:
          type: string
        role:
          type: string
        status:
          type: string
        content:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Run:
      type: object
      required: [runId, projectId, threadId, status, createdAt]
      properties:
        runId:
          type: string
        projectId:
          type: string
        threadId:
          type: string
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time

    HubAuditEvent:
      type: object
      properties:
        id: { type: string, format: uuid }
        user_id: { type: string, format: uuid }
        profile_id: { type: string, format: uuid }
        target_id: { type: string, format: uuid }
        event_type: { type: string }
        severity: { type: string }
        summary: { type: string }
        details: { type: object }
        client_ip: { type: string }
        created_at: { type: string, format: date-time }

    AgentTeam:
      type: object
      properties:
        id: { type: string, format: uuid }
        owner_id: { type: string, format: uuid }
        name: { type: string }
        description: { type: string }
        avatar_url: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    AgentTeamMember:
      type: object
      properties:
        id: { type: string, format: uuid }
        team_id: { type: string, format: uuid }
        agent_profile_id: { type: string, format: uuid }
        role:
          type: string
          enum: [supervisor, executor, reviewer]
        position: { type: integer }
        created_at: { type: string, format: date-time }

    AgentTeamDetail:
      type: object
      properties:
        id: { type: string, format: uuid }
        owner_id: { type: string, format: uuid }
        name: { type: string }
        description: { type: string }
        avatar_url: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        members:
          type: array
          items:
            $ref: "#/components/schemas/AgentTeamMember"

    AgentTeamRun:
      type: object
      properties:
        id: { type: string, format: uuid }
        team_id: { type: string, format: uuid }
        session_id: { type: string, format: uuid }
        trigger_user_id: { type: string, format: uuid }
        trigger_message: { type: string }
        status:
          type: string
          enum: [queued, running, completed, failed, cancelled]
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    AgentTeamAssignment:
      type: object
      properties:
        id: { type: string, format: uuid }
        team_run_id: { type: string, format: uuid }
        from_member_id: { type: string, format: uuid }
        to_member_id: { type: string, format: uuid }
        type:
          type: string
          enum: [delegate, review, approve, notify]
        task_prompt: { type: string }
        context: { type: string }
        status:
          type: string
          enum: [pending, dispatched, running, done, failed, cancelled]
        run_id: { type: string, format: uuid }
        result: { type: string }
        depth: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    AgentTeamTask:
      type: object
      properties:
        id: { type: string, format: uuid }
        team_run_id: { type: string, format: uuid }
        assignment_id: { type: string, format: uuid }
        assignee_member_id: { type: string, format: uuid }
        parent_task_id: { type: string, format: uuid }
        status:
          type: string
          enum: [pending, dispatched, running, done, failed, cancelled]
        objective: { type: string }
        input_refs:
          type: object
          additionalProperties: true
        run_id: { type: string }
        attempt: { type: integer }
        risk_level:
          type: string
          enum: [normal, high]
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    TeamRunState:
      type: object
      properties:
        run_id: { type: string, format: uuid }
        team_id: { type: string, format: uuid }
        status:
          type: string
          enum: [queued, running, completed, failed, cancelled]
        members:
          type: array
          items:
            $ref: "#/components/schemas/TeamMemberState"
        tasks:
          type: array
          items:
            $ref: "#/components/schemas/TeamTaskState"
        dependencies:
          type: array
          items:
            $ref: "#/components/schemas/TeamTaskDependencyState"
        assignments:
          type: array
          items:
            $ref: "#/components/schemas/TeamAssignmentState"
        approvals:
          type: array
          items:
            $ref: "#/components/schemas/TeamApprovalState"
        artifacts:
          type: array
          items:
            $ref: "#/components/schemas/TeamArtifactState"
        conflicts:
          type: array
          items:
            $ref: "#/components/schemas/TeamConflictState"
        run_events:
          type: array
          items:
            $ref: "#/components/schemas/TeamRunEventState"
        route_log:
          type: array
          items:
            $ref: "#/components/schemas/CoordinatorRouteDecision"
        budget:
          $ref: "#/components/schemas/TeamBudget"
        terminal_reason:
          type: string

    TeamMemberState:
      type: object
      properties:
        member_id: { type: string, format: uuid }
        agent_profile_id: { type: string, format: uuid }
        role:
          type: string
          enum: [supervisor, executor, reviewer]
        active_tasks: { type: integer }
        completed_tasks: { type: integer }

    TeamTaskState:
      type: object
      properties:
        task_id: { type: string, format: uuid }
        assignment_id: { type: string, format: uuid }
        assignee_member_id: { type: string, format: uuid }
        parent_task_id: { type: string, format: uuid }
        status:
          type: string
          enum: [pending, dispatched, running, done, failed, cancelled]
        objective: { type: string }
        run_id: { type: string }
        agent_task_id: { type: string, format: uuid }
        edge_run_id: { type: string }
        attempt: { type: integer }
        risk_level:
          type: string
          enum: [normal, high]

    TeamTaskDependencyState:
      type: object
      properties:
        task_id: { type: string, format: uuid }
        depends_on_task_id: { type: string, format: uuid }
        kind: { type: string }

    TeamApprovalState:
      type: object
      properties:
        approval_id: { type: string }
        agent_task_id: { type: string, format: uuid }
        team_task_id: { type: string, format: uuid }
        assignment_id: { type: string, format: uuid }
        member_id: { type: string, format: uuid }
        edge_run_id: { type: string }
        request_id: { type: string }
        tool_name: { type: string }
        tool_use_id: { type: string }
        status: { type: string }
        reason: { type: string }
        decided_by: { type: string, format: uuid }
        created_at: { type: string, format: date-time }
        decided_at: { type: string, format: date-time }
        edge_control:
          $ref: "#/components/schemas/TeamApprovalEdgeControl"

    TeamApprovalDecisionRequest:
      type: object
      required: [decision]
      properties:
        decision:
          type: string
          enum: [allow, deny]
        reason: { type: string }

    TeamApprovalEdgeControl:
      type: object
      required: [runId, requestId, decision]
      properties:
        runId:
          type: string
          description: Local Edge run id to send to Edge /v1/permissions/decide.
        requestId:
          type: string
          description: Edge permission request id.
        decision:
          type: string
          enum: [allow, deny]
        reason: { type: string }

    AgentControlPayload:
      type: object
      required: [kind, edge_device_id]
      properties:
        kind:
          type: string
          enum: [permission.decide]
        agent_task_id: { type: string, format: uuid }
        target_id: { type: string, format: uuid }
        edge_device_id:
          type: string
          description: Exact Desktop/Edge device id that owns the local Edge run.
        team_id: { type: string, format: uuid }
        team_run_id: { type: string, format: uuid }
        team_task_id: { type: string, format: uuid }
        assignment_id: { type: string, format: uuid }
        member_id: { type: string, format: uuid }
        approval_id: { type: string }
        edge_control:
          $ref: "#/components/schemas/TeamApprovalEdgeControl"

    TeamArtifactState:
      type: object
      properties:
        agent_task_id: { type: string, format: uuid }
        team_task_id: { type: string, format: uuid }
        assignment_id: { type: string, format: uuid }
        member_id: { type: string, format: uuid }
        edge_run_id: { type: string }
        source_event_id: { type: string, format: uuid }
        event_seq: { type: integer, format: int64 }
        path: { type: string }
        action: { type: string }
        tool_name: { type: string }
        status: { type: string }
        conflict_id: { type: string }
        created_at: { type: string, format: date-time }

    TeamConflictState:
      type: object
      properties:
        conflict_id: { type: string }
        path: { type: string }
        status:
          type: string
          enum: [pending, resolved]
        agent_task_ids:
          type: array
          items: { type: string, format: uuid }
        team_task_ids:
          type: array
          items: { type: string, format: uuid }
        assignment_ids:
          type: array
          items: { type: string, format: uuid }
        member_ids:
          type: array
          items: { type: string, format: uuid }
        edge_run_ids:
          type: array
          items: { type: string }
        actions:
          type: array
          items: { type: string }
        first_seen_at: { type: string, format: date-time }
        last_seen_at: { type: string, format: date-time }
        resolution:
          type: string
          enum: [accept_agent_task, manual_merge, keep_all, discard_all, blocked]
        resolved_by: { type: string, format: uuid }
        resolved_at: { type: string, format: date-time }
        reason: { type: string }
        selected_agent_task_id: { type: string, format: uuid }

    TeamConflictResolveRequest:
      type: object
      required: [resolution]
      properties:
        path: { type: string }
        resolution:
          type: string
          enum: [accept_agent_task, manual_merge, keep_all, discard_all, blocked]
        selected_agent_task_id:
          type: string
          format: uuid
          description: Required when resolution is accept_agent_task.
        reason: { type: string }

    TeamAssignmentState:
      type: object
      properties:
        assignment_id: { type: string, format: uuid }
        from_member_id: { type: string, format: uuid }
        to_member_id: { type: string, format: uuid }
        type:
          type: string
          enum: [delegate, review, approve, notify]
        status:
          type: string
          enum: [pending, dispatched, running, done, failed, cancelled]
        depth: { type: integer }
        run_id: { type: string, format: uuid }
        agent_task_id: { type: string, format: uuid }
        edge_run_id: { type: string }

    TeamRunEventState:
      type: object
      properties:
        agent_task_id: { type: string, format: uuid }
        edge_run_id: { type: string }
        event_seq: { type: integer }
        event_type: { type: string }
        payload: { type: string }
        created_at: { type: string, format: date-time }

    TeamBudget:
      type: object
      properties:
        total_tokens_used: { type: integer }
        input_tokens: { type: integer }
        output_tokens: { type: integer }
        token_limit: { type: integer }
        remaining_tokens: { type: integer }
        usage_percent: { type: number, format: double }
        run_count: { type: integer }
        context_warnings: { type: integer }
        compactions: { type: integer }

    CoordinatorRouteDecision:
      type: object
      properties:
        action:
          type: string
          enum: [delegate, review, approve, finish]
        next_worker: { type: string }
        instructions: { type: string }
        reasoning: { type: string }
        context: { type: string }
        approved: { type: boolean }
        feedback: { type: string }
        summary: { type: string }
        blocked_reason: { type: string }
        correlation_id: { type: string }

    CreateAgentProfileRequest:
      type: object
      required: [name, runtime_id]
      properties:
        name:
          type: string
        description:
          type: string
        runtime_id:
          type: string
          description: Agent Runtime id such as codex, claude-code, or opencode.
        model:
          type: string
        provider:
          type: string
        reasoning_effort:
          type: string
        permission_mode:
          type: string
        model_mapping:
          type: object
          additionalProperties: true
        skills:
          type: array
          items:
            type: string
            format: uuid
        mcp_servers:
          type: array
          items:
            type: string
            format: uuid
        tool_allowlist:
          type: array
          items:
            type: string
        approval_policy:
          type: object
          additionalProperties: true
        target_preferences:
          type: object
          additionalProperties: true
        context_budget_max_tokens:
          type: integer
        is_public:
          type: boolean

    UpdateAgentProfileRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        runtime_id:
          type: string
        model:
          type: string
        provider:
          type: string
        reasoning_effort:
          type: string
        permission_mode:
          type: string
        model_mapping:
          type: object
          additionalProperties: true
        skills:
          type: array
          items:
            type: string
            format: uuid
        mcp_servers:
          type: array
          items:
            type: string
            format: uuid
        tool_allowlist:
          type: array
          items:
            type: string
        approval_policy:
          type: object
          additionalProperties: true
        target_preferences:
          type: object
          additionalProperties: true
        context_budget_max_tokens:
          type: integer
        is_public:
          type: boolean

    Skill:
      type: object
      properties:
        id: { type: string, format: uuid }
        owner_id: { type: string, format: uuid }
        name: { type: string }
        description: { type: string }
        skill_type: { type: string }
        config: { type: object, additionalProperties: true }
        is_public: { type: boolean }
        install_count: { type: integer }
        version: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    CreateSkillRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          maxLength: 100
        description:
          type: string
        skill_type:
          type: string
        config:
          type: object
          additionalProperties: true
        is_public:
          type: boolean

    UpdateSkillRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
        description:
          type: string
        skill_type:
          type: string
        config:
          type: object
          additionalProperties: true
        is_public:
          type: boolean

    MCPServer:
      type: object
      properties:
        id: { type: string, format: uuid }
        owner_id: { type: string, format: uuid }
        name: { type: string }
        description: { type: string }
        transport: { type: string }
        command: { type: string }
        args: { type: string }
        env: { type: string }
        url: { type: string }
        headers: { type: string }
        is_public: { type: boolean }
        install_count: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    CreateMCPServerRequest:
      type: object
      required: [name, transport]
      properties:
        name:
          type: string
          maxLength: 100
        description:
          type: string
        transport:
          type: string
          enum: [stdio, sse, streamable]
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        is_public:
          type: boolean

    UpdateMCPServerRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
        description:
          type: string
        transport:
          type: string
          enum: [stdio, sse, streamable]
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        url:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        is_public:
          type: boolean

    ProviderBinding:
      type: object
      properties:
        id: { type: string, format: uuid }
        owner_id: { type: string, format: uuid }
        provider: { type: string }
        api_base: { type: string }
        api_key: { type: string }
        models: { type: string }
        is_default: { type: boolean }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    CreateProviderBindingRequest:
      type: object
      required: [provider]
      properties:
        provider:
          type: string
        api_base:
          type: string
        api_key:
          type: string
        models:
          type: array
          items:
            type: string
        is_default:
          type: boolean

    UpdateProviderBindingRequest:
      type: object
      properties:
        provider:
          type: string
        api_base:
          type: string
        api_key:
          type: string
        models:
          type: array
          items:
            type: string
        is_default:
          type: boolean

    Device:
      type: object
      required: [id, user_id, device_type, capabilities, last_active_at, created_at]
      properties:
        id: { type: string, format: uuid }
        user_id: { type: string, format: uuid }
        device_type: { type: string }
        app_version: { type: string }
        capabilities:
          type: array
          items: { type: string }
        last_active_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }

  responses:
    Ok:
      description: OK.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Resource"
    Created:
      description: Created.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Resource"
    Accepted:
      description: Accepted.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Resource"
    List:
      description: List response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListResponse"
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"