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/threads/{threadId}/pins,
  #   /v1/items/{itemId},
  #   /v1/model-catalog,
  #   /v1/runners (GET only), /v1/agents, /v1/runs (GET/POST),
  #   /v1/runs/{runId} (GET), /v1/runs/{runId}:cancel,
  #   /v1/runs/{runId}/diff (GET), /v1/artifacts (GET),
  #   /v1/artifacts/{artifactId} (GET), /v1/previews (GET),
  #   /v1/previews/{previewId} (GET), /v1/previews/{previewId}:stop,
  #   /v1/metrics, /v1/agent-instances (GET only), /v1/agent-instances/{id},
  #   /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}: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/POST /v1/approvals and nested,
  #   POST /v1/artifacts and nested content/apply/discard,
  #   POST /v1/previews and preview runner/process management,
  #   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"
    delete:
      tags: [IMProject]
      operationId: deleteThread
      summary: Delete thread and associated local run/item records.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      responses:
        "204":
          description: Deleted.

  /v1/threads/{threadId}:archive:
    post:
      tags: [IMProject]
      operationId: archiveThread
      summary: Archive thread.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      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}/pins:
    get:
      tags: [IMProject]
      operationId: listThreadPins
      summary: List pinned thread items.
      description: Returns Edge-local thread pin metadata with each pinned item hydrated when the item still exists.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      responses:
        "200":
          description: Pinned items list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThreadPinListResponse"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags: [IMProject]
      operationId: pinThreadItem
      summary: Pin an item in a 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/PinThreadItemRequest"
      responses:
        "201":
          description: Thread item pin created or updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThreadPinResponse"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    delete:
      tags: [IMProject]
      operationId: deleteThreadPin
      summary: Remove a pinned item from a thread.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/ThreadId"
        - name: itemId
          in: query
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Thread item pin removed.
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /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.
      description: "Read-only Edge-local diff snapshot for a persisted run. Empty runs return `{ runId, files: [] }`."
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Run diff snapshot.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunDiffResponse"
        "404":
          $ref: "#/components/responses/Error"

  /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.
      description: Read-only Edge-local artifact index. Artifact content, apply and discard remain planned.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - name: runId
          in: query
          required: false
          schema:
            type: string
          description: Optional Edge run id filter.
      responses:
        "200":
          description: Artifact list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactListResponse"

  /v1/artifacts/{artifactId}:
    get:
      tags: [ExecutionRunner]
      operationId: getArtifact
      summary: Get artifact metadata.
      description: Read-only Edge-local artifact metadata lookup. Artifact content, apply and discard remain planned.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      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.
      description: Planned. Current Edge artifact metadata may include safe contentSource metadata, but this route still lacks an approved workspace resolver, blob key, MIME type, checksum, size cap, and read policy.
      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.
      description: Read-only Edge-local preview index. Starting previews remains planned; stopped previews are retained as terminal metadata.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - name: runId
          in: query
          required: false
          schema:
            type: string
          description: Optional Edge run id filter.
      responses:
        "200":
          description: Preview list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewListResponse"
    post:
      tags: [ExecutionRunner]
      operationId: createPreview
      summary: Start preview.
      description: Fake-runner contract only. Creates Edge-local `starting` preview metadata for a run without launching a dev server, OS process, or browser; fake runner tests may later mark the preview ready or stopped.
      x-agenthub-phase: P0
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePreviewRequest"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/previews/{previewId}:
    get:
      tags: [ExecutionRunner]
      operationId: getPreview
      summary: Get preview.
      description: Read-only Edge-local preview metadata lookup. Starting previews remains planned; stopped previews are retained as terminal metadata.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      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: implemented
      x-agenthub-owner: Edge
      description: Contract-only local metadata transition. This marks an existing Edge preview as stopped and clears the ready URL; it does not stop an OS process or browser.
      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/model-catalog:
    get:
      tags: [ExecutionRunner]
      operationId: getModelCatalog
      summary: List runtime model catalog entries discovered from local provider configuration.
      description: Returns model/catalog metadata only; provider API keys and secret material are redacted by the Edge implementation.
      x-agenthub-phase: P0
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      responses:
        "200":
          description: Model catalog.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelCatalogResponse"

  /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-phase: P1
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/agent-instances/{id}:
    get:
      tags: [ExecutionRunner]
      operationId: getAgentInstance
      summary: Get one orchestrator sub-agent instance.
      x-agenthub-phase: P1
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "404":
          $ref: "#/components/responses/Error"

  /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: >
        Main Hub WebSocket route. The production route validates a Hub-issued
        HS256 access token during HTTP upgrade, using either `access_token` query
        auth for browser clients or `Authorization: Bearer <token>` for native
        clients. TokenDance ID RS256 bearer tokens and TokenDance API keys are
        not Hub WebSocket credentials. The legacy first-frame `auth` event is
        only for tests and compatibility entries that do not install
        WSAuthMiddleware. See api/events.md for Hub event types.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security:
        - hubWebSocketQueryToken: []
        - bearerAuth: []
      parameters:
        - name: access_token
          in: query
          required: false
          schema: { type: string }
          description: Hub-issued HS256 access token for browser WebSocket upgrade authentication.
      responses:
        "101":
          description: Switching Protocols.
        "401":
          $ref: "#/components/responses/Error"

  /web/agent-tasks:
    x-agenthub-device-type: web
    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 local_edge ExecutionTarget id. Hub validates owner, local_edge 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/relay targets are rejected on this Web dispatch route until their relay/provisioning paths are product-complete.
      responses:
        "200":
          description: Task dispatched.

  /web/agent-tasks/{id}/events:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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"

  /web/agent-tasks/{id}/summary:
    x-agenthub-device-type: web
    get:
      tags: [HubSyncRelay]
      operationId: hubGetTaskRunEventSummaryAlias
      summary: Summarize typed runtime event history for an agent task.
      description: Compatibility alias for `/web/agent-tasks/{id}/events/summary`; returns the same owner-scoped runtime history summary.
      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"

  /web/agent-tasks/{id}/approvals:
    x-agenthub-device-type: web
    get:
      tags: [HubSyncRelay]
      operationId: hubListTaskApprovals
      summary: List projected approval requests and decisions for one agent task.
      description: Owner-scoped metadata projection from AgentRunEvent permission request and decision events. It does not mutate Edge state.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Approval projection for the task.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  data:
                    $ref: "#/components/schemas/AgentTaskApprovalList"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /web/agent-tasks/{id}/approvals/{approvalId}/decide:
    x-agenthub-device-type: web
    post:
      tags: [HubSyncRelay]
      operationId: hubDecideTaskApproval
      summary: Decide a pending approval for one agent task.
      description: Records a run.agent.permission_decided event, returns the projected approval, and pushes or queues an agent.control permission.decide frame to the exact Desktop/Edge device that owns the task. This route does not execute real CLI/model work by itself.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: approvalId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TaskApprovalDecisionRequest"
      responses:
        "200":
          description: Approval decision recorded and control payload delivered or queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  data:
                    $ref: "#/components/schemas/AgentTaskApproval"
        "400":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /web/agent-tasks/{id}/artifacts:
    x-agenthub-device-type: web
    get:
      tags: [HubSyncRelay]
      operationId: hubListTaskArtifacts
      summary: List artifact metadata projected for one agent task.
      description: Metadata/list-only projection from run.agent.file_change and artifact.created events. It does not expose content, apply, or discard actions.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Artifact metadata projection for the task.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  data:
                    $ref: "#/components/schemas/AgentTaskArtifactList"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /edge/agent-tasks/{id}/ack:
    x-agenthub-device-type: desktop
    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:
    x-agenthub-device-type: desktop
    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:
    x-agenthub-device-type: desktop
    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:
    x-agenthub-device-type: desktop
    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:
    get:
      tags: [HubSyncRelay]
      operationId: hubOidcCallbackPage
      summary: Render the browser OIDC callback result page.
      description: >
        Browser redirect endpoint for TokenDance ID Authorization Code callbacks.
        It reads `code` and `state` from the query string and renders localized
        HTML for Desktop/Web handoff. It does not exchange the code or mint Hub
        session tokens; clients still call POST /client/auth/oidc/callback for
        the server-side exchange.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: []
      parameters:
        - name: code
          in: query
          required: true
          schema: { type: string }
        - name: state
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Localized HTML success page.
          content:
            text/html:
              schema: { type: string }
        "400":
          description: Localized HTML missing-parameter page.
          content:
            text/html:
              schema: { type: string }
    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:
    x-agenthub-device-type: web
    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:
        "200":
          $ref: "#/components/responses/Ok"

  /web/custom-agents:
    x-agenthub-device-type: web
    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}:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: desktop
    post:
      tags: [HubSyncRelay]
      operationId: hubRegisterDevice
      summary: Register a device with the Hub. Device type is taken from the JWT claim.
      description: >
        Desktop registration may create or refresh an owner-scoped local_edge
        ExecutionTarget bound to the registered Desktop device. After a
        successful registration, clients should refresh `/web/execution-targets`
        before dispatch target selection. The generated target `is_online` and
        `health_state` reflect desktop check-in freshness from this registration,
        not an active WebSocket route proof.
      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"

  /cloud/edge/register:
    post:
      tags: [HubSyncRelay]
      operationId: hubRegisterCloudEdge
      summary: Register a cloud Edge device and mint its Edge API JWT.
      description: >
        Authenticated Hub session route without the desktop device-type
        restriction used by /edge/devices/register. The request device_id must
        be a UUID for the cloud Edge being registered. Hub registers the device
        as `cloud_edge` under the authenticated Hub user and returns an
        Edge-scoped JWT with `iss=agenthub-hub`, `aud=agenthub-edge`,
        `purpose=edge-api`, `device_type=edge`, and the registered `device_id`
        for Edge API authentication.
      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: Stable cloud Edge device UUID to register under the authenticated Hub user.
                name:
                  type: string
                host:
                  type: string
                port:
                  type: integer
                app_version:
                  type: string
                capabilities:
                  type: array
                  items: { type: string }
      responses:
        "200":
          description: Cloud Edge registered and JWT issued.
          content:
            application/json:
              schema:
                type: object
                required: [code, data]
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    type: object
                    required: [device_id, device_type, jwt]
                    properties:
                      device_id: { type: string, format: uuid }
                      device_type: { type: string, enum: [cloud_edge] }
                      jwt:
                        type: string
                        description: Edge-scoped JWT for Edge API auth.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Error"

  /web/agent-tasks/{id}/cancel:
    x-agenthub-device-type: web
    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 instance to a Hub 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_type, display_name]
              properties:
                agent_type:
                  type: string
                  description: Agent Runtime adapter id such as codex, claude-code, or opencode.
                custom_agent_id:
                  type: string
                  description: Optional legacy CustomAgent id when dispatching a CustomAgent-backed instance.
                display_name:
                  type: string
                  description: User-visible name for this session agent instance.
      responses:
        "200":
          description: Created session agent instance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: ok
                  data:
                    $ref: "#/components/schemas/AgentInstance"

  /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}:
    put:
      tags: [HubSyncRelay]
      operationId: hubEditMessageDirect
      summary: Edit a message.
      description: Sender-only edit for user messages within the Hub edit window.
      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: [content_type, content]
              properties:
                content_type: { type: string }
                content: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /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}/reactions:
    get:
      tags: [HubSyncRelay]
      operationId: hubListMessageReactionsDirect
      summary: List reaction summaries for a message.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: session_id
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Grouped message reaction summaries.
          content:
            application/json:
              schema:
                type: object
                required: [code, data]
                properties:
                  code:
                    type: string
                    enum: [OK]
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MessageReactionResponse"
    post:
      tags: [HubSyncRelay]
      operationId: hubAddMessageReactionDirect
      summary: Add a reaction to a message.
      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/MessageReactionRequest"
      responses:
        "200":
          description: Message reaction summary.
          content:
            application/json:
              schema:
                type: object
                required: [code, data]
                properties:
                  code:
                    type: string
                    enum: [OK]
                  data:
                    $ref: "#/components/schemas/MessageReactionResponse"
    delete:
      tags: [HubSyncRelay]
      operationId: hubRemoveMessageReactionDirect
      summary: Remove a reaction from a message.
      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/MessageReactionRequest"
      responses:
        "200":
          description: Message reaction summary.
          content:
            application/json:
              schema:
                type: object
                required: [code, data]
                properties:
                  code:
                    type: string
                    enum: [OK]
                  data:
                    $ref: "#/components/schemas/MessageReactionResponse"

  /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:
    x-agenthub-device-type: web
    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}:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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"

  # ── Projects backed by Hub workspaces ──

  /web/projects:
    x-agenthub-device-type: web
    get:
      tags: [HubSyncRelay]
      operationId: hubListProjects
      summary: List Hub projects backed by owner-scoped workspaces.
      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: Case-insensitive search over project name and description.
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateProject
      summary: Create a Hub project workspace.
      description: Current behavior returns a 200 OK Hub envelope; status-code migration is intentionally out of scope for this slice.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceProjectRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"

  /web/projects/{id}:
    x-agenthub-device-type: web
    get:
      tags: [HubSyncRelay]
      operationId: hubGetProject
      summary: Get a Hub project workspace.
      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"
    patch:
      tags: [HubSyncRelay]
      operationId: hubUpdateProject
      summary: Update a Hub project workspace.
      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:
              $ref: "#/components/schemas/UpdateWorkspaceProjectRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /web/projects/{id}/threads:
    x-agenthub-device-type: web
    get:
      tags: [HubSyncRelay]
      operationId: hubListProjectThreads
      summary: List Hub project group threads.
      description: Returns owner-scoped Hub group sessions bound to the project workspace through sessions.workspace_id.
      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/List"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateProjectThread
      summary: Create a Hub project group thread.
      description: Creates a group session owned by the current Hub user and binds it to the project workspace.
      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:
              $ref: "#/components/schemas/CreateWorkspaceThreadRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /web/projects/{id}/threads/{threadId}/messages:
    x-agenthub-device-type: web
    get:
      tags: [HubSyncRelay]
      operationId: hubListProjectThreadMessages
      summary: List messages in a Hub project group thread.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: threadId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 100 }
      responses:
        "200":
          $ref: "#/components/responses/List"
        "404":
          $ref: "#/components/responses/Error"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateProjectThreadMessage
      summary: Send a message in a Hub project group thread.
      description: Text content may be raw text or a JSON object with text plus optional metadata for project group, @Agent mention and orchestrator queue fixtures. This route only records the message; real runtime dispatch still uses /web/agent-tasks with trigger_message_id.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: threadId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendWorkspaceThreadMessageRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  # ── Audit Events ──

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

  # ── Relay Commands (web) ──

  /web/relay/commands:
    x-agenthub-device-type: web
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateWebRelayCommand
      summary: Create a relay command.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      x-agenthub-role: admin
      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}:
    x-agenthub-device-type: web
    get:
      tags: [HubSyncRelay]
      operationId: hubGetWebRelayCommand
      summary: Get a relay command status.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      x-agenthub-role: admin
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"

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

  # ── Devices (web) ──

  /web/devices:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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}:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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}:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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
                target_id:
                  type: string
                  format: uuid
                  description: Optional owner-scoped ExecutionTarget id used for exact Desktop/Edge routing of the TeamRun supervisor and assignment tasks.
      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}:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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}:
    x-agenthub-device-type: web
    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:
        "200":
          $ref: "#/components/responses/Ok"

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

  /web/skills/{id}/unpublish:
    x-agenthub-device-type: web
    post:
      tags: [HubSyncRelay]
      operationId: hubUnpublishSkill
      summary: Unpublish a skill from the marketplace (admin only).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      x-agenthub-role: admin
      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:
    x-agenthub-device-type: web
    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}:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    post:
      tags: [HubSyncRelay]
      operationId: hubPublishMCPServer
      summary: Publish an MCP server to the marketplace (admin only).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      x-agenthub-role: admin
      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:
    x-agenthub-device-type: web
    post:
      tags: [HubSyncRelay]
      operationId: hubUnpublishMCPServer
      summary: Unpublish an MCP server from the marketplace (admin only).
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      x-agenthub-role: admin
      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:
    x-agenthub-device-type: web
    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}:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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}:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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:
    x-agenthub-device-type: web
    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.
    hubWebSocketQueryToken:
      type: apiKey
      in: query
      name: access_token
      description: >
        Hub-issued HS256 access token used by browser clients during /client/ws
        HTTP upgrade. TokenDance ID bearer tokens and TokenDance API keys are
        not accepted.
  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
    RunDiffFile:
      type: object
      required: [path, diff, status]
      properties:
        path:
          type: string
          description: Workspace-relative path or an already-sanitized outside-workspace marker.
        diff:
          type: string
          description: Unified diff text for this file. Empty when no diff body is available yet.
        status:
          type: string
          enum: [added, modified, deleted]
    RunDiff:
      type: object
      required: [runId, files]
      properties:
        runId:
          type: string
        files:
          type: array
          items:
            $ref: "#/components/schemas/RunDiffFile"
    RunDiffResponse:
      type: object
      required: [code, data]
      properties:
        code:
          type: string
          enum: [OK]
        data:
          $ref: "#/components/schemas/RunDiff"
    ModelCatalogResponse:
      type: object
      required: [code, data]
      properties:
        code:
          type: string
          enum: [OK]
        data:
          $ref: "#/components/schemas/ModelCatalog"
    ModelCatalog:
      type: object
      required: [items, sources]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ModelCatalogItem"
        sources:
          type: array
          items:
            $ref: "#/components/schemas/ModelCatalogSource"
    ModelCatalogItem:
      type: object
      required: [id, value, label, sourceId, sourceLabel, status]
      properties:
        id:
          type: string
        value:
          type: string
        label:
          type: string
        provider:
          type: string
        runtimeId:
          type: string
        resolvedModel:
          type: string
        sourceId:
          type: string
        sourceLabel:
          type: string
        status:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        reasoningEfforts:
          type: array
          items:
            type: string
        default:
          type: boolean
    ModelCatalogSource:
      type: object
      required: [id, label, status]
      properties:
        id:
          type: string
        label:
          type: string
        status:
          type: string
        detail:
          type: string
    Artifact:
      type: object
      required: [id, runId, threadId, kind, path, sizeBytes, createdAt]
      properties:
        id:
          type: string
        runId:
          type: string
        threadId:
          type: string
        kind:
          type: string
          description: Artifact category such as patch, file, image, document, or web.
        path:
          type: string
          description: Workspace-relative artifact path or logical artifact name. Absolute private paths are never exposed.
        sizeBytes:
          type: integer
          format: int64
        contentSource:
          $ref: "#/components/schemas/ArtifactContentSource"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ArtifactContentSource:
      type: object
      description: Safe metadata for future artifact content reads. The path is either workspace-relative or basename-only; absolute private paths are never stored or returned.
      required: [kind, path, readable]
      properties:
        kind:
          type: string
          enum: [workspace_relative, basename]
        path:
          type: string
          description: Workspace-relative source path when readable, otherwise basename-only fallback.
        readable:
          type: boolean
          description: Whether a future content route may resolve the source from an approved workspace root.
    ArtifactList:
      type: object
      required: [items, page]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Artifact"
        page:
          $ref: "#/components/schemas/PageInfo"
    ArtifactListResponse:
      type: object
      required: [code, data]
      properties:
        code:
          type: string
          enum: [OK]
        data:
          $ref: "#/components/schemas/ArtifactList"
    Preview:
      type: object
      required: [id, runId, threadId, status, createdAt]
      properties:
        id:
          type: string
        runId:
          type: string
        threadId:
          type: string
        url:
          type: string
          format: uri
          description: Local preview URL when a preview is already ready.
        status:
          type: string
          enum: [starting, ready, stopped]
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreatePreviewRequest:
      type: object
      required: [runId]
      properties:
        previewId:
          type: string
          description: Optional caller-supplied preview id; omitted values are generated by Edge.
        runId:
          type: string
          description: Existing Edge run id that owns the preview metadata.
        threadId:
          type: string
          description: Optional thread guard; when supplied it must match the run thread.
    PreviewList:
      type: object
      required: [items, page]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Preview"
        page:
          $ref: "#/components/schemas/PageInfo"
    PreviewListResponse:
      type: object
      required: [code, data]
      properties:
        code:
          type: string
          enum: [OK]
        data:
          $ref: "#/components/schemas/PreviewList"
    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.
    HubWebSocketFrame:
      type: object
      required: [type, payload]
      description: Hub WebSocket frame envelope. Event-specific payload contracts are documented in api/events.md.
      properties:
        type:
          type: string
          enum:
            - message.new
            - message.edited
            - message.reaction_added
            - message.reaction_removed
            - device.online
            - device.offline
            - session.created
            - session.member_joined
            - session.member_left
            - session.info_updated
            - agent.dispatch
            - agent.stream
            - agent.done
            - agent.failed
            - agent.cancel
            - agent.control
            - team.run.started
            - team.event
            - team.assignment.done
            - team.assignment.failed
            - notification.new
            - friend.request
            - friend.accepted
        payload:
          type: object
          additionalProperties: true
    HubDevicePresencePayload:
      type: object
      required: [user_id]
      description: User-level Hub presence payload for device.online and device.offline WebSocket frames. Hub broadcasts presence by user and does not expose device_id or device_type in this payload.
      properties:
        user_id:
          type: string
      additionalProperties: false
    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
    TaskApprovalDecisionRequest:
      type: object
      required: [decision]
      properties:
        decision:
          type: string
          enum: [allow, deny]
        reason:
          type: string
    AgentTaskApprovalList:
      type: object
      properties:
        task_id:
          type: string
        edge_run_id:
          type: string
          maxLength: 128
        session_id:
          type: string
        approvals:
          type: array
          items:
            $ref: "#/components/schemas/AgentTaskApproval"
        pending:
          type: array
          items:
            $ref: "#/components/schemas/AgentTaskApproval"
        decided:
          type: array
          items:
            $ref: "#/components/schemas/AgentTaskApproval"
        last_event_seq:
          type: integer
          format: int64
    AgentTaskApproval:
      type: object
      properties:
        approval_id:
          type: string
        task_id:
          type: string
        edge_run_id:
          type: string
          maxLength: 128
        session_id:
          type: string
        source_event_id:
          type: string
        event_seq:
          type: integer
          format: int64
        request_id:
          type: string
        tool_name:
          type: string
        tool_use_id:
          type: string
        status:
          type: string
        reason:
          type: string
        decided_by:
          type: string
        created_at:
          type: string
          format: date-time
        decided_at:
          type: string
          format: date-time
        edge_control:
          $ref: "#/components/schemas/TeamApprovalEdgeControl"
    AgentTaskArtifactList:
      type: object
      properties:
        task_id:
          type: string
        edge_run_id:
          type: string
          maxLength: 128
        session_id:
          type: string
        artifacts:
          type: array
          items:
            $ref: "#/components/schemas/AgentTaskArtifact"
        last_event_seq:
          type: integer
          format: int64
    AgentTaskArtifact:
      type: object
      properties:
        task_id:
          type: string
        edge_run_id:
          type: string
          maxLength: 128
        session_id:
          type: string
        source_event_id:
          type: string
        event_seq:
          type: integer
          format: int64
        path:
          type: string
        action:
          type: string
        tool_name:
          type: string
        status:
          type: string
        diff:
          type: string
          description: Optional unified diff or patch snippet projected from run.agent.file_change.
        edit_id:
          type: string
          description: Optional runtime edit identifier projected from run.agent.file_change.
        hash:
          type: string
          description: Optional SHA-256 or runtime-provided hash for a diff proposal or artifact.
        review_status:
          type: string
          description: Optional review state projected from run.agent.file_change for inspector UI.
        can_apply:
          type: boolean
          description: Review/export-only capability projection. Current Hub responses clamp unguarded runtime apply capability to false and do not expose a real apply action.
        can_revert:
          type: boolean
          description: Review/export-only capability projection. Current Hub responses clamp unguarded runtime revert capability to false and do not expose a real revert action.
        artifact_id:
          type: string
        name:
          type: string
        mime_type:
          type: string
        size_bytes:
          type: integer
          format: int64
        created_at:
          type: string
          format: date-time
    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.).
    AgentInstance:
      type: object
      required: [id, agent_type, session_id, inviter_user_id, display_name]
      properties:
        id:
          type: string
          format: uuid
          description: Exact Hub AgentInstance id used by /web/agent-tasks agent_instance_id dispatch.
        agent_type:
          type: string
          description: Agent Runtime adapter id such as codex, claude-code, or opencode.
        custom_agent_id:
          type: string
          format: uuid
          description: Optional legacy CustomAgent id.
        session_id:
          type: string
          format: uuid
        inviter_user_id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
        display_name:
          type: string
        created_at:
          type: string
          format: date-time
    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, online, degraded, offline, mismatch, stale]
          readOnly: true
          description: System-managed health proof state. `online` is the current dispatchable state; `healthy` is accepted for compatibility with older clients. `offline`, `mismatch`, and `stale` are not dispatchable. Clients cannot set this through create/update requests.
        auth_method:
          type: string
          enum: [none, ssh_tunnel, tailscale_mtls, hub_jwt]
          description: Public authentication strategy only; not a credential or bearer token.
        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
    WorkspaceProject:
      type: object
      required: [id, name, owner_id, created_at, updated_at]
      description: Web-owned Hub project projection backed by the current workspaces table.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        owner_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateWorkspaceProjectRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string
    UpdateWorkspaceProjectRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    WorkspaceThread:
      type: object
      required: [id, project_id, type, name, member_count, created_at]
      description: Web project-facing projection of a Hub group session.
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        type:
          type: string
          enum: [group]
        name:
          type: string
        owner_user_id:
          type: string
          format: uuid
        role:
          type: string
        member_count:
          type: integer
          format: int64
        last_message_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateWorkspaceThreadRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
    SendWorkspaceThreadMessageRequest:
      type: object
      required: [content]
      properties:
        client_msg_id:
          type: string
          format: uuid
        content_type:
          type: string
          enum: [text, code, diff, image, file, link_card, deploy_card]
          default: text
        content:
          type: string
          description: Raw text, or JSON text payload with optional metadata for im_kind, mentions and orchestrator_queue.
    WorkspaceThreadMessage:
      type: object
      required: [id, project_id, thread_id, seq_id, client_msg_id, sender_type, sender_id, content_type, content, created_at]
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        thread_id:
          type: string
          format: uuid
        seq_id:
          type: integer
          format: int64
        client_msg_id:
          type: string
          format: uuid
        sender_type:
          type: string
          enum: [user, agent]
        sender_id:
          type: string
        content_type:
          type: string
        content:
          type: string
          description: "Normalized JSON string. Text messages are persisted as text-only JSON or text plus metadata JSON."
        created_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:
          oneOf:
            - type: array
              items:
                type: string
            - type: string
              description: Hub-compatible JSON string array.
          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
          enum: [none, ssh_tunnel, tailscale_mtls, hub_jwt]
          description: Public authentication strategy only; not a credential or bearer token.
        device_id:
          type: string
          format: uuid
        capabilities:
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
              description: Hub-compatible JSON string object.
          description: Runtime capability metadata. Hub responses keep this field encoded as a JSON string.
        metadata:
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
              description: Hub-compatible JSON string object.
          description: Target metadata. Hub responses keep this field encoded as a JSON string.
    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:
          oneOf:
            - type: array
              items:
                type: string
            - type: string
              description: Hub-compatible JSON string array.
          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
          enum: [none, ssh_tunnel, tailscale_mtls, hub_jwt]
          description: Public authentication strategy only; not a credential or bearer token.
        device_id:
          type: string
          format: uuid
        capabilities:
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
              description: Hub-compatible JSON string object.
          description: Runtime capability metadata. Empty object clears the target-local capabilities. Hub responses keep this field encoded as a JSON string.
        metadata:
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
              description: Hub-compatible JSON string object.
          description: Target metadata. Empty object clears the target-local metadata. Hub responses keep this field encoded as a JSON string.
    AgentProfile:
      type: object
      required: [id, name, runtime_id]
      description: >
        Current implemented Hub AgentProfile response. See AgentHubAgentSpec
        for an experimental component-only contract draft; no current endpoint
        accepts or returns that full draft shape.
      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.
        memory_policy:
          type: string
          description: >
            Optional forward-compatible JSON object for AgentHub memory
            policy projection. It may be absent until the Hub DB migration is
            assigned; clients must treat absence as partial capability
            readiness, not as an enabled memory policy.
        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
    AgentHubAgentSpec:
      type: object
      x-agenthub-status: contract-draft
      x-agenthub-contract: experimental
      description: >
        Experimental AgentHub-owned agent contract draft for docs and fixtures.
        This component is not wired to any implemented request or response.
        Hub owns orchestration/API and product identity; Edge owns runtime/SDK
        adapters; Web/Desktop consume AgentHub-owned fields only; Tauri never
        owns SDK objects. Live SDK/model execution remains approval-gated.
      required:
        - identity
        - display
        - role
        - runtime
        - target
        - tools
        - mcpServers
        - approval
        - memory
        - evidence
        - handoff
        - sdkOptions
      properties:
        identity:
          type: object
          required: [specId, ownerScope, visibility, source]
          description: Hub-owned product identity, not a provider SDK Agent object.
          properties:
            specId:
              type: string
              maxLength: 128
              description: Stable draft spec id or AgentProfile projection id.
            ownerScope:
              type: string
              enum: [hub-user, hub-org, team-fixture]
            visibility:
              type: string
              enum: [private, team, marketplace, fixture]
            source:
              type: string
              enum: [hub-agent-profile, marketplace-draft, fixture]
        display:
          type: object
          required: [name, description]
          description: User-visible AgentHub profile display fields.
          properties:
            name:
              type: string
              maxLength: 120
            description:
              type: string
              maxLength: 1000
            avatarRef:
              type: string
              maxLength: 256
              description: Optional AgentHub asset ref, never a provider secret.
        role:
          type: object
          required: [teamRole, instructions]
          description: Durable product role used by Hub TeamRun assignment.
          properties:
            teamRole:
              type: string
              enum: [supervisor, worker, reviewer, observer]
            instructions:
              type: string
              maxLength: 20000
            responsibility:
              type: string
              maxLength: 1000
        runtime:
          type: object
          required: [preferredRuntime, adapterMode]
          description: Runtime/provider hint consumed below the Edge adapter boundary.
          properties:
            preferredRuntime:
              type: string
              enum: [codex, claude-code, opencode, openai-agents-sdk, claude-sdk]
            modelHint:
              type: string
              maxLength: 256
              description: Policy hint only; not a public claim that a model is configured.
            reasoning:
              type: string
              maxLength: 128
            adapterMode:
              type: string
              enum: [cli, sdk, daemon, fixture]
        target:
          type: object
          required: [preferences, workspacePolicy]
          description: AgentHub ExecutionTarget preference, not SDK runtime identity.
          properties:
            preferences:
              type: array
              items:
                type: string
                enum: [local-edge, remote-edge, cloud-edge, hub-relay, fixture]
            workspacePolicy:
              type: string
              enum: [explicit-allowlist, project-bound, read-only-fixture, blocked]
        tools:
          type: object
          required: [allowlist]
          description: AgentHub-owned tool policy projected to adapters.
          properties:
            allowlist:
              type: array
              items:
                type: string
                maxLength: 128
            deniedByDefault:
              type: boolean
              default: true
        mcpServers:
          type: array
          description: AgentHub-owned MCP server refs, not raw secret config.
          items:
            type: object
            required: [serverId, ownerScope, exposure]
            properties:
              serverId:
                type: string
                maxLength: 128
              ownerScope:
                type: string
                enum: [hub, edge, fixture]
              exposure:
                type: string
                enum: [tool-provider, context-provider, blocked-in-fixture]
        approval:
          type: object
          required: [mode, riskRules]
          description: Product approval policy mapped into Edge/Hub approval events.
          properties:
            mode:
              type: string
              enum: [read-only, workspace-write, approval-required, blocked]
            riskRules:
              type: array
              items:
                type: object
                required: [match, decision]
                properties:
                  match:
                    type: string
                    maxLength: 256
                  decision:
                    type: string
                    enum: [allow, require-approval, deny]
        memory:
          type: object
          required: [sources, retention]
          description: AgentHub-owned memory/context policy, not SDK session state.
          properties:
            sources:
              type: array
              items:
                type: string
                enum: [agents-md, project-memory, thread-context, artifact-summary, fixture]
            retention:
              type: string
              enum: [thread-only, project-policy, no-persist-fixture]
        evidence:
          type: object
          required: [required, redaction]
          description: Normalized evidence required for review/demo replay.
          properties:
            required:
              type: array
              items:
                type: string
                enum:
                  - run-events
                  - tool-calls
                  - file-changes
                  - artifacts
                  - approvals
                  - route-decisions
                  - handoff-summary
            redaction:
              type: string
              enum: [no-secrets, workspace-relative-paths, fixture-only]
        handoff:
          type: object
          required: [accepts, emits]
          description: TeamRun handoff contract; SDK handoffs are adapter signals only.
          properties:
            accepts:
              type: array
              items:
                type: string
                enum: [teamrun-assignment, approval-decision, fixture-event]
            emits:
              type: array
              items:
                type: string
                enum: [route-decision, result-summary, evidence-refs]
        sdkOptions:
          type: object
          required: [provider, adapterExperiment, liveModelExecution, rawSdkObjectPolicy]
          description: Provider-specific adapter options constrained below Edge.
          properties:
            provider:
              type: string
              enum: [none, claude-sdk, openai-agents-sdk]
            adapterExperiment:
              type: string
              enum: [read-only-fixture, sandbox-fixture, event-mapper, teamrun-fixture-e2e, live-approved]
            liveModelExecution:
              type: string
              enum: [blocked, approval-required]
            rawSdkObjectPolicy:
              type: string
              enum: [never-exposed-above-edge-adapter]
    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.
    MessageReactionRequest:
      type: object
      required: [session_id, reaction]
      properties:
        session_id:
          type: string
        reaction:
          type: string
          minLength: 1
          maxLength: 64
    MessageReactionResponse:
      type: object
      required: [message_id, session_id, reaction, count, reacted_by_me]
      properties:
        message_id:
          type: string
        session_id:
          type: string
        reaction:
          type: string
          maxLength: 64
        count:
          type: integer
          minimum: 0
        reacted_by_me:
          type: boolean
    PinThreadItemRequest:
      type: object
      required: [itemId]
      properties:
        itemId:
          type: string
          minLength: 1
          description: Thread item id to pin. The item must belong to the target thread.
        pinnedBy:
          type: string
          description: Optional local actor label for audit display.
    ThreadPin:
      type: object
      required: [threadId, itemId, pinnedAt, createdAt, updatedAt]
      properties:
        threadId:
          type: string
        itemId:
          type: string
        pinnedBy:
          type: string
        pinnedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ThreadPinResponse:
      type: object
      required: [code, data]
      properties:
        code:
          type: string
          enum: [OK]
        data:
          $ref: "#/components/schemas/ThreadPin"
    ThreadPinListResponse:
      type: object
      required: [code, data]
      properties:
        code:
          type: string
          enum: [OK]
        data:
          type: object
          required: [items, page]
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/ThreadPinWithItem"
            page:
              $ref: "#/components/schemas/PageInfo"
    ThreadPinWithItem:
      allOf:
        - $ref: "#/components/schemas/ThreadPin"
        - type: object
          required: [item]
          properties:
            item:
              $ref: "#/components/schemas/Item"
    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"
        route_audit_log:
          type: array
          items:
            $ref: "#/components/schemas/TeamRouteAuditState"
        budget:
          $ref: "#/components/schemas/TeamBudget"
        terminal_reason:
          type: string

    TeamRouteAuditState:
      type: object
      properties:
        status:
          type: string
          enum: [accepted, rejected]
        action:
          type: string
          enum: [delegate, review, approve, finish]
        subtask_id: { type: string, format: uuid }
        parent_task_id: { type: string, format: uuid }
        agent_id: { type: string }
        reason: { type: string }
        correlation_id: { type: string }
        created_at: { type: string, format: date-time }

    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 }
        accepted: { type: boolean }
        subtask_id:
          type: string
          description: Hub queued TeamTask id for accepted route decisions.
        parent_task_id:
          type: string
          description: Optional parent TeamTask id for subtask replay.
        agent_id:
          type: string
          description: Target agent/member id recorded for audit and rejected-route replay.
        reason:
          type: string
          description: Accepted or rejected route audit reason.
        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:
          description: Accepts a JSON object or the current Hub-compatible JSON object string.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
        skills:
          description: Accepts a string array or the current Hub-compatible JSON array string.
          oneOf:
            - type: array
              items:
                type: string
                format: uuid
            - type: string
        mcp_servers:
          description: Accepts a string array or the current Hub-compatible JSON array string.
          oneOf:
            - type: array
              items:
                type: string
                format: uuid
            - type: string
        tool_allowlist:
          description: Accepts a string array or the current Hub-compatible JSON array string.
          oneOf:
            - type: array
              items:
                type: string
            - type: string
        approval_policy:
          description: Accepts a JSON object or the current Hub-compatible JSON object string.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
        target_preferences:
          description: Accepts a JSON object or the current Hub-compatible JSON object string.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
        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:
          description: Accepts a JSON object or the current Hub-compatible JSON object string.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
        skills:
          description: Accepts a string array or the current Hub-compatible JSON array string.
          oneOf:
            - type: array
              items:
                type: string
                format: uuid
            - type: string
        mcp_servers:
          description: Accepts a string array or the current Hub-compatible JSON array string.
          oneOf:
            - type: array
              items:
                type: string
                format: uuid
            - type: string
        tool_allowlist:
          description: Accepts a string array or the current Hub-compatible JSON array string.
          oneOf:
            - type: array
              items:
                type: string
            - type: string
        approval_policy:
          description: Accepts a JSON object or the current Hub-compatible JSON object string.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
        target_preferences:
          description: Accepts a JSON object or the current Hub-compatible JSON object string.
          oneOf:
            - type: object
              additionalProperties: true
            - type: string
        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
      required: [id, provider, is_available, quota_used, quota_limit, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        provider: { type: string }
        binding_name: { type: string }
        base_url: { type: string }
        is_available: { type: boolean }
        quota_used:
          type: integer
          format: int64
        quota_limit:
          type: integer
          format: int64
        last_checked:
          type: string
          format: date-time
          nullable: true
        metadata:
          type: string
          description: JSON object metadata encoded by the current Hub provider binding handler.
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    CreateProviderBindingRequest:
      type: object
      required: [provider]
      properties:
        provider:
          type: string
        binding_name:
          type: string
        base_url:
          type: string
        is_available:
          type: boolean
        quota_limit:
          type: integer
          format: int64
        metadata:
          type: string
          description: JSON object metadata encoded by the current Hub provider binding handler.

    UpdateProviderBindingRequest:
      type: object
      properties:
        provider:
          type: string
        binding_name:
          type: string
        base_url:
          type: string
        is_available:
          type: boolean
        quota_used:
          type: integer
          format: int64
        quota_limit:
          type: integer
          format: int64
        last_checked:
          type: string
          format: date-time
          nullable: true
        metadata:
          type: string
          description: JSON object metadata encoded by the current Hub provider binding handler.

    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"