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

    Each operation carries `x-agenthub-status: implemented|planned`.
    Implemented Hub entries mirror `hub-server/internal/router/router.go`;
    planned entries are not callable routes. New architecture language uses
    Agent Runtime, Agent Profile, and Execution Target.

    ## Hub success envelope code

    Hub Server success responses use `{"code":"ok","data":...}` with lowercase
    `ok` (`hub-server/internal/errcode.OK.Code` via `handler.OK`). This is not
    HTTP status text and is not the Edge success shape (Edge returns bare JSON).
    See `api/conventions.md` for the normative client rule.

    ## 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: https://hub.example.com
    description: Production Hub Server (placeholder)
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/runs/{runId}/checkpoint (GET), /v1/runs/{runId}/checkpoint/file (GET),
  #   /v1/artifacts (GET),
  #   /v1/artifacts/{artifactId} (GET), /v1/previews (GET/POST),
  #   /v1/previews/{previewId} (GET), /v1/previews/{previewId}:stop,
  #   /v1/metrics, /v1/agent-instances (GET only), /v1/agent-instances/{id},
  #   /v1/permissions/decide,
  #   /v1/runs/{runId}/apply (POST), /v1/runs/{runId}/apply-all (POST),
  #   /v1/plans/decide (POST), /v1/plans/pending (GET),
  #   /v1/delivery-journal (GET), /v1/users (GET), /v1/users/current (GET),
  #   /v1/agent-profiles (GET/POST), /v1/agent-profiles/{profileId} (GET/PATCH/DELETE),
  #   /v1/settings (GET/PATCH), /v1/runtime-sessions (GET),
  #   /v1/ccswitch/status (GET), /v1/ccswitch/providers (GET),
  #   /v1/deployments (POST), /v1/memory (GET/POST)
  #
  # 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,
  #   GET /v1/workspaces/{workspaceId} and nested,
  #   POST /v1/agent-instances
  # ═══════════════════════════════════════════════════════════

  /v1/health:
    get:
      tags: [Foundation]
      operationId: getHealth
      summary: Health and run callback capabilities.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      responses:
        "200":
          description: Healthy Edge with explicit callback ownership capabilities.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EdgeHealth"
        "503":
          description: Degraded Edge; health body retains the same schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EdgeHealth"

  /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 send `access_token.<edge-token>` as a WebSocket subprotocol;
        native clients may use Authorization or X-AgentHub-Edge-Token. The
        `access_token` query parameter is rejected to keep tokens out of proxy logs.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeWebSocketProtocol: []
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/PageCursor"
        - name: cursor
          in: query
          required: false
          schema: { type: integer, format: int64 }
          description: >
            Numeric event-sequence cursor for replay. Alias for `pageCursor`;
            `cursor` takes precedence when both are present. The Edge handler
            accepts either name for backwards compatibility.
      responses:
        "101":
          description: Switching Protocols.
        "401":
          $ref: "#/components/responses/Error"

  /v1/projects:
    get:
      tags: [IMProject]
      operationId: listProjects
      summary: List projects.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProjectRequest"
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/projects/{projectId}:
    get:
      tags: [IMProject]
      operationId: getProject
      summary: Get project.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [IMProject]
      operationId: deleteProject
      summary: Delete or unregister project.
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [IMProject]
      operationId: updateProjectMemory
      summary: Update project memory metadata.
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/conversations:
    get:
      tags: [IMProject]
      operationId: listConversations
      summary: List conversations.
      x-agenthub-superseded-by: "GET /client/sessions"
      x-agenthub-status: planned
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [IMProject]
      operationId: createConversation
      summary: Create conversation.
      x-agenthub-superseded-by: "POST /client/sessions"
      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-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-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-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-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-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-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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/ProjectIdQuery"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          description: >
            Thread list. Edge implementation returns {items, page:{hasMore:false}}
            and never sends nextCursor (response_dto.go hardcodes hasMore:false).
            The pageCursor/nextCursor parameters are accepted but ignored by Edge.
          content:
            application/json:
              schema:
                type: object
                required: [items, page]
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Resource"
                  page:
                    type: object
                    required: [hasMore]
                    properties:
                      hasMore:
                        type: boolean
                        description: Always false on Edge (no cursor pagination).
    post:
      tags: [IMProject]
      operationId: createThread
      summary: Create thread.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateThreadRequest"
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/threads/{threadId}:
    get:
      tags: [IMProject]
      operationId: getThread
      summary: Get thread.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [IMProject]
      operationId: updateThread
      summary: Update thread.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateThreadRequest"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    delete:
      tags: [IMProject]
      operationId: deleteThread
      summary: Delete thread and associated local run/item records.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/ThreadId"
      responses:
        "204":
          description: Deleted.

  /v1/threads/{threadId}:archive:
    post:
      tags: [IMProject]
      operationId: archiveThread
      summary: Archive thread.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/ItemId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/runners:
    get:
      tags: [ExecutionRunner]
      operationId: listRunners
      summary: List runners.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/RunnerId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/runs:
    get:
      tags: [ExecutionRunner]
      operationId: listRuns
      summary: List AgentRuns.
      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. An empty body is accepted 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-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. On an accepted replay this returns the original run envelope (data.runId) with additive deduplicated/deliveryId; no new run/timeline/executor is created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        "403":
          # capability_token_invalid: the X-AgentHub-Capability-Token is missing,
          # fails validation, or does not bind this user/device/project/target.
          $ref: "#/components/responses/Error"
        "409":
          # delivery_conflict: delivery_id binds a different Hub task or legacy
          # project/thread scope (#2347); active_run_exists: the thread already has
          # an active run. admission_uncertain requires reconciliation of a retained
          # run without proof of admission; clients must not ACK/FAIL or restart.
          $ref: "#/components/responses/Error"
        "429":
          description: Executor capacity rejected admission before execution; retry the same Hub task later.
          headers:
            Retry-After:
              description: Delay in seconds before retrying admission.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          # not_found: the original run referenced by an accepted receipt was removed.
          $ref: "#/components/responses/Error"
        "503":
          description: >
            not_configured means the Edge cannot validate a Hub identity because
            its Hub credential policy is unconfigured; it fails closed.
            delivery_busy is temporary contention for a pending delivery or
            admission capacity and includes Retry-After. admission_persist_failed
            means admission evidence could not be saved; execution may already
            have been accepted. Retry to reconcile, not to force another start.
            callback_unavailable means a direct callback owner is not configured;
            no new run is created, and device routing is required.
          headers:
            Retry-After:
              description: Delay in seconds, present for delivery_busy and admission_persist_failed responses.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/runs/{runId}:
    get:
      tags: [ExecutionRunner]
      operationId: getRun
      summary: Get AgentRun.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Run is already terminal (finished/failed/cancelled/completed_with_issues); current status returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
        "202":
          $ref: "#/components/responses/Accepted"
        "404":
          $ref: "#/components/responses/Error"

  /v1/runs/{runId}:interrupt:
    post:
      tags: [ExecutionRunner]
      operationId: interruptRun
      summary: Interrupt AgentRun.
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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/runs/{runId}/checkpoint:
    get:
      tags: [ExecutionRunner]
      operationId: getRunCheckpoint
      summary: Get run checkpoint metadata and inventory.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Checkpoint metadata plus file inventory for a persisted run.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "404":
          $ref: "#/components/responses/Error"

  /v1/runs/{runId}/checkpoint/file:
    get:
      tags: [ExecutionRunner]
      operationId: getRunCheckpointFile
      summary: Get a single checkpoint file preview.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Checkpoint file preview.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "404":
          $ref: "#/components/responses/Error"

  /v1/runs/{runId}/apply:
    post:
      tags: [ExecutionRunner]
      operationId: applyRunDiffHunk
      summary: Apply a single run diff hunk to the filesystem.
      description: >
        Applies one accepted hunk decision for a finished run to the workspace
        filesystem. Reads the run's persisted diff, applies the selected hunk,
        and returns the updated diff state. workDir must be within the Edge
        workspace allowlist.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/RunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [file_path, hunk_index, accepted]
              properties:
                file_path:
                  type: string
                  description: Workspace-relative file path whose hunk is being decided.
                hunk_index:
                  type: integer
                  minimum: 0
                  description: Zero-based hunk index within the file's unified diff.
                accepted:
                  type: boolean
                  description: When true the hunk is written to the filesystem; when false it is recorded as rejected without writing.
                workDir:
                  type: string
                  description: Absolute workspace root; must be within the Edge workspace allowlist. Required when accepted is true.
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /v1/runs/{runId}/apply-all:
    post:
      tags: [ExecutionRunner]
      operationId: applyAllRunDiffHunks
      summary: Batch apply multiple run diff hunk decisions.
      description: >
        Applies multiple hunk accept/reject decisions for a finished run in one
        request. Each decision is applied in order; the first failure aborts
        the batch. Returns the per-hunk results and count applied.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - $ref: "#/components/parameters/RunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decisions]
              properties:
                decisions:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required: [file_path, hunk_index, accepted]
                    properties:
                      file_path:
                        type: string
                      hunk_index:
                        type: integer
                        minimum: 0
                      accepted:
                        type: boolean
                workDir:
                  type: string
                  description: Absolute workspace root; must be within the Edge workspace allowlist.
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

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

  /v1/approvals/{approvalId}:
    get:
      tags: [ExecutionRunner]
      operationId: getApproval
      summary: Get approval request.
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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. Previews can be created via POST; stopped previews are retained as terminal metadata.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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. Previews can be created via POST /v1/previews; stopped previews are retained as terminal metadata.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: planned
      x-agenthub-owner: Hub
      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-status: planned
      x-agenthub-owner: Hub
      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-status: planned
      x-agenthub-owner: Hub
      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-status: planned
      x-agenthub-owner: Hub
      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
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - name: runId
          in: query
          schema: { type: string }
        - name: parentId
          in: query
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [ExecutionRunner]
      operationId: createAgentInstance
      summary: Register a sub-agent instance.
      x-agenthub-status: planned
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      responses:
        "201":
          $ref: "#/components/responses/Created"

  /v1/agent-instances/{id}:
    get:
      tags: [ExecutionRunner]
      operationId: getAgentInstance
      summary: Get one orchestrator sub-agent instance.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      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.
      description: >
        Resolves a pending tool-permission request of a run. The legacy form
        (both `controlId` and `hubTaskId` absent) keeps one-shot receiver
        semantics. The modern form supplies both fields and is idempotent: an
        identical retry returns the original applied receipt, a different
        control for the same run/request or a changed payload for the same
        control fails with 409, and a cold/evicted receipt is never invented as
        success. The receipt cache is process-local, bounded, and non-durable;
        capacity pressure returns 429 before applying the decision. Under Hub
        JWT / multi-user mode the run must be owned by the caller and a modern
        request must match the stored `hubTaskId`. A foreign run, nonexistent
        run, wrong task, and missing pending request are reported identically
        (404), so this endpoint is not an existence oracle. A caller without a
        Hub identity fails closed. Local single-tenant mode is unaffected.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [runId, requestId, decision]
              properties:
                controlId:
                  type: string
                  description: Modern idempotency identity; must be supplied with hubTaskId.
                hubTaskId:
                  type: string
                  description: Exact Hub task bound to the Edge run; must be supplied with controlId.
                runId: { type: string }
                requestId: { type: string }
                decision: { type: string, enum: [allow, deny] }
                reason: { type: string }
      responses:
        "200":
          description: >
            Decision applied. Legacy requests return `{status: ok}`; modern
            requests return the applied receipt and set `deduplicated` when the
            request replayed an existing receipt.
          content:
            application/json:
              schema:
                type: object
                required: [code, data]
                properties:
                  code: { type: string }
                  data:
                    type: object
                    required: [status]
                    properties:
                      status: { type: string }
                      controlId: { type: string }
                      hubTaskId: { type: string }
                      runId: { type: string }
                      requestId: { type: string }
                      decision: { type: string, enum: [allow, deny] }
                      applied: { type: boolean }
                      deduplicated: { type: boolean }
        "400":
          description: Invalid decision payload or only one of controlId/hubTaskId supplied.
        "404":
          description: >
            Pending permission request not found. The same response is returned
            when the run belongs to another Hub user or the modern hubTaskId
            does not match, so a foreign/mismatched run and a nonexistent run
            are indistinguishable.
        "409":
          description: The control identity or run/request already has a conflicting decision receipt.
        "429":
          description: The bounded permission decision receipt cache is full; no decision was applied.

  /v1/plans/decide:
    post:
      tags: [ExecutionRunner]
      operationId: decidePlan
      summary: Approve or reject a pending orchestrator plan.
      description: >
        Plan confirmation gate. Resolves a pending plan for the given
        run via the PlanApprovalBroker. The resolved plan_approved /
        plan_rejected event is emitted by the dispatch interceptor once the
        broker decision resolves; this endpoint only records the decision.
        Under Hub JWT / multi-user mode the run must be owned by the caller; a
        run owned by another Hub user and a nonexistent run are reported
        identically (404), so this endpoint is not a runId existence oracle. A
        caller without a Hub identity fails closed. Local single-tenant mode is
        unaffected.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [runId, decision]
              properties:
                runId: { type: string }
                decision:
                  type: string
                  enum: [approve, reject]
                reason: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /v1/plans/pending:
    get:
      tags: [ExecutionRunner]
      operationId: listPendingPlans
      summary: List pending orchestrator plans awaiting approval.
      description: >
        Returns pending plans registered with the PlanApprovalBroker. When no
        broker is configured an empty list is returned. Under Hub JWT /
        multi-user mode, plans are filtered to runs owned by the caller and a
        caller without a Hub identity gets an empty list; local single-tenant
        mode sees all rows.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/delivery-journal:
    get:
      tags: [Foundation]
      operationId: getDeliveryJournal
      summary: Read Edge-to-Hub delivery journal for reconciliation.
      description: >
        Edge-local callback journal snapshot for delivery reconciliation. When
        the Edge CallbackClient is not configured, returns 503. Under Hub JWT /
        multi-user mode, entries are filtered to runs owned by the caller;
        local single-tenant mode sees all rows.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - name: afterSeq
          in: query
          required: false
          schema:
            type: integer
            format: int64
            minimum: 0
            default: 0
          description: Return entries with seq greater than this value.
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
        "503":
          $ref: "#/components/responses/Error"

  /v1/users:
    get:
      tags: [Foundation]
      operationId: listEdgeUsers
      summary: List Edge-local user profiles.
      description: >
        Returns Edge-local user profiles from the Edge store. This is the
        single-tenant local profile surface; Hub-owned users live under Hub
        Server routes.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/users/current:
    get:
      tags: [Foundation]
      operationId: getCurrentEdgeUser
      summary: Get the current Edge-local user profile.
      description: >
        Returns the current Edge-local user profile, or 404 when no current
        user is set.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "404":
          $ref: "#/components/responses/Error"

  /v1/agent-profiles:
    get:
      tags: [ExecutionRunner]
      operationId: listEdgeAgentProfiles
      summary: List Edge-local agent profiles.
      description: >
        Edge-local agent profile index. Profiles have no per-user owner
        binding, so under Hub JWT / multi-user mode this route fails closed;
        local single-tenant mode keeps access. Supports an
        optional adapterId query filter.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - name: adapterId
          in: query
          required: false
          schema:
            type: string
          description: Optional adapter id filter.
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [ExecutionRunner]
      operationId: createEdgeAgentProfile
      summary: Create an Edge-local agent profile.
      description: >
        Creates an Edge-local agent profile. Agent profiles are node-level
        shared configuration with no per-user owner binding, so under Hub JWT /
        multi-user mode this route is not writable and fails closed with 404
        whose body is indistinguishable from a missing resource;
        local single-tenant mode keeps write access.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                description: { type: string }
                adapterId: { type: string }
                model: { type: string }
                provider: { type: string }
                reasoningEffort: { type: string }
                thinkingMode: { type: string }
                maxThinkingTokens: { type: integer }
                permissionMode: { type: string }
                systemPrompt: { type: string }
                allowedTools:
                  type: array
                  items:
                    type: string
                mcpConfig: { type: string }
                skills:
                  type: array
                  items:
                    type: string
                avatarRef: { type: string }
      responses:
        "201":
          $ref: "#/components/responses/Created"
        "400":
          $ref: "#/components/responses/Error"

  /v1/agent-profiles/{profileId}:
    get:
      tags: [ExecutionRunner]
      operationId: getEdgeAgentProfile
      summary: Get an Edge-local agent profile.
      description: >
        Edge-local agent profile lookup. Fails closed under Hub JWT /
        multi-user mode.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - name: profileId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "404":
          $ref: "#/components/responses/Error"
    patch:
      tags: [ExecutionRunner]
      operationId: updateEdgeAgentProfile
      summary: Update an Edge-local agent profile.
      description: >
        Partial update of an Edge-local agent profile by id. Agent profiles are
        node-level shared configuration with no per-user owner binding, so under
        Hub JWT / multi-user mode this route is not writable and fails closed
        with 404 whose body is indistinguishable from a missing resource;
        local single-tenant mode keeps write access.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - name: profileId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: JSON patch map merged into the profile.
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    delete:
      tags: [ExecutionRunner]
      operationId: deleteEdgeAgentProfile
      summary: Delete an Edge-local agent profile.
      description: >
        Deletes an Edge-local agent profile by id. Agent profiles are
        node-level shared configuration with no per-user owner binding, so
        under Hub JWT / multi-user mode this route is not writable and fails
        closed with 404 whose body is indistinguishable from a missing
        resource; local single-tenant mode keeps write access.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - name: profileId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted.
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /v1/settings:
    get:
      tags: [Foundation]
      operationId: getEdgeSettings
      summary: Read Edge-local settings.
      description: >
        Edge-local settings have no per-user owner binding; under Hub JWT /
        multi-user mode this route fails closed. Local
        single-tenant mode keeps access.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [Foundation]
      operationId: updateEdgeSettings
      summary: Upsert Edge-local settings.
      description: >
        Merges a string-keyed patch into Edge-local settings. An empty patch
        is rejected. Persist failures are reported as 500 so callers do not
        mistake them for success. Edge-local settings are node-level shared
        configuration with no per-user owner binding, so under Hub JWT /
        multi-user mode this route is not writable and fails closed with 404
        whose body is indistinguishable from a missing resource;
        local single-tenant mode keeps write access. The gate runs before the
        request body is decoded.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
              minProperties: 1
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /v1/runtime-sessions:
    get:
      tags: [Foundation]
      operationId: listRuntimeSessions
      summary: List observed local Agent Runtime sessions.
      description: >
        Read-only Desktop import discovery surface. Scans the local filesystem
        for recent Agent Runtime session summaries; never mutates third-party
        stores. Shared machine surface: fails closed under Hub JWT / multi-user
        mode.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
        - name: runtime
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated runtime filter list (e.g. claude-code,codex).
      responses:
        "200":
          $ref: "#/components/responses/List"
        "400":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /v1/ccswitch/status:
    get:
      tags: [Foundation]
      operationId: getCCSwitchStatus
      summary: Report cc-switch installation status.
      description: >
        Returns whether cc-switch is installed and whether model routing is
        active on this Edge. When cc-switch is not detected the response
        reports installed=false, routingActive=false.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/ccswitch/providers:
    get:
      tags: [Foundation]
      operationId: listCCSwitchProviders
      summary: List cc-switch providers for an app type.
      description: >
        Reads cc-switch provider entries for the given appType (defaults to
        claude). Returns an empty list when cc-switch is not installed or its
        database is not readable.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - name: appType
          in: query
          required: false
          schema:
            type: string
            default: claude
      responses:
        "200":
          $ref: "#/components/responses/List"
        "500":
          $ref: "#/components/responses/Error"

  /v1/deployments:
    post:
      tags: [ExecutionRunner]
      operationId: createDeployment
      summary: Deploy run artifacts to a static site target.
      description: >
        Collects a finished run's artifacts, archives them, and SCPs the
        archive to the configured deployment target. The slug becomes the
        subdomain of the pages domain. The run must be finished, failed, or
        cancelled — runs that ended with completed_with_issues are refused —
        and have at least one artifact.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [runId, slug]
              properties:
                runId: { type: string }
                slug:
                  type: string
                  description: DNS-safe subdomain slug (lowercase alphanumeric with hyphens, 2-63 chars).
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /v1/memory:
    get:
      tags: [ExecutionRunner]
      operationId: getEdgeMemory
      summary: Read AgentHub memory entries for a workspace.
      description: >
        Reads AgentHub memory entries for the given workDir / threadId /
        agentId. workDir must be within the Edge workspace allowlist when set.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      parameters:
        - name: workDir
          in: query
          required: false
          schema:
            type: string
        - name: threadId
          in: query
          required: false
          schema:
            type: string
        - name: agentId
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "403":
          $ref: "#/components/responses/Error"
    post:
      tags: [ExecutionRunner]
      operationId: writeEdgeMemory
      summary: Write or update an AgentHub memory entry.
      description: >
        Writes a single AgentHub memory entry for the given workDir. workDir is
        required and must be within the Edge workspace allowlist. When id is
        omitted one is generated. An empty content body is rejected.
      x-agenthub-status: implemented
      x-agenthub-owner: Edge
      security:
        - edgeBearerAuth: []
        - edgeLocalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [workDir, content]
              properties:
                workDir: { type: string }
                threadId: { type: string }
                agentId: { type: string }
                id: { type: string }
                content: { type: string }
                source: { type: string }
                tags:
                  type: array
                  items:
                    type: string
                overwrite: { type: boolean }
      responses:
        "201":
          $ref: "#/components/responses/Created"
        "400":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

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

  /health:
    get:
      tags: [HubSyncRelay]
      operationId: hubHealth
      summary: Hub health check (DB + Redis + migrations).
      description: >
        Aggregate health probe. Answers 200 with the component report while the
        health wiring is live, including when a dependency is degraded (the body
        carries status/ready so callers can tell those apart). Answers 503 with
        status "unavailable" and ready false only when no health reporting is
        wired into the process at all, so a probe can never read "ok" from a
        build that verified nothing. The liveness and readiness sub-routes
        (/health/live, /health/ready) are ops probes deliberately kept outside
        this contract, so they have no path entry here; /health/live stays 200
        in both cases.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      responses:
        "200":
          $ref: "#/components/responses/Ok"

        "500":
          $ref: "#/components/responses/Error"

        "503":
          $ref: "#/components/responses/Error"
  /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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"

        "500":
          $ref: "#/components/responses/Error"
  /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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HubUser"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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":
          description: Sessions list. Handler returns a bare JSON array (no {items,page} envelope); openapi aligned to implementation.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Resource"
        "401":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateSession
      summary: Create a session by type (dispatches to private or group creation).
      description: >
        Generic session-create dispatcher. The request body carries a `type`
        field (`private` or `group`); the handler delegates to the same
        private/group creation path used by `POST /client/sessions/private`
        and `POST /client/sessions/group`. Typed variants are preferred for
        new clients; this generic route remains implemented for backwards
        compatibility.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type]
              properties:
                type:
                  type: string
                  enum: [private, group]
                target_user_id:
                  type: string
                  format: uuid
                  description: Required when type is private.
                name:
                  type: string
                  description: Required when type is group.
                member_ids:
                  type: array
                  items: { type: string, format: uuid }
                  description: Member IDs for group sessions.
      responses:
        "200":
          description: Session created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionCreate"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePrivateSessionRequest"
      responses:
        "201":
          description: Session created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionCreate"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGroupSessionRequest"
      responses:
        "201":
          description: Group created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionCreate"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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 }
        - name: before_seq
          in: query
          required: false
          schema: { type: integer, format: int64 }
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1 }
      responses:
        "200":
          description: Messages list (bare array of Message). Handler returns []MessageResponse; openapi aligned to Message schema.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Message"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendSessionMessageRequest"
      responses:
        "201":
          description: Message sent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Message"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /client/ws:
    get:
      tags: [HubSyncRelay]
      operationId: hubWebSocket
      summary: Hub WebSocket — real-time IM + agent dispatch.
      description: >
        Main Hub WebSocket route. AuthMiddleware.WSHandler() validates a Hub-issued HS256
        access token during HTTP upgrade and resolves that token from exactly
        two sources, in priority order: (1) `Authorization: Bearer <token>` for
        native clients that can set headers, (2) the `Sec-WebSocket-Protocol`
        request header for browsers, carried either as
        `agenthub.bearer.v1, <hub-jwt>` (preferred two-token form; only the
        fixed marker is negotiated back so the token is never echoed) or as the
        single-token `access_token.<hub-jwt>` form. The `access_token` query
        parameter is deliberately rejected (fail closed) because query strings
        leak into proxy logs, browser history, and Referer headers — see
        middleware.extractWSToken. Query-string auth is therefore not part of
        this contract. 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
        AuthMiddleware.WSHandler(). See api/events.md for Hub event types.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security:
        - bearerAuth: []
      parameters:
        - name: Sec-WebSocket-Protocol
          in: header
          required: false
          schema: { type: string }
          description: >
            Preferred browser token carriage. Send
            `agenthub.bearer.v1, <hub-jwt>` (Hub negotiates back only the fixed
            `agenthub.bearer.v1` marker) or the single-token form
            `access_token.<hub-jwt>`.
      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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HubPendingAgentTask"
        "409":
          description: Turn in progress — the agent instance already has a non-terminal (queued/dispatched/running) task. The trigger message itself is already persisted and is not rolled back. The web client treats this as a recoverable condition (keep draft / optimistic message, show an info toast) rather than a hard error. Granularity is per `agent_instance_id`, not per session; a different agent instance in the same session is not blocked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                turn_in_progress:
                  value:
                    error:
                      code: turn_in_progress
                      message: agent instance already has an active task

  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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/{approval_id}/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: approval_id
          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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ═══════════════════════════════════════════════════════════
  # 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/{user_id}:
    delete:
      tags: [HubSyncRelay]
      operationId: hubRemoveContact
      summary: Remove a contact.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/ContactUserId"
      responses:
        "204":
          description: Removed.

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /client/contacts/{user_id}/block:
    post:
      tags: [HubSyncRelay]
      operationId: hubBlockContact
      summary: Block a user.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/ContactUserId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /client/contacts/{user_id}/unblock:
    post:
      tags: [HubSyncRelay]
      operationId: hubUnblockContact
      summary: Unblock a user.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - $ref: "#/components/parameters/ContactUserId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"

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

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── Friend Requests ──

  /client/friend-requests:
    get:
      tags: [HubSyncRelay]
      operationId: hubListFriendRequests
      summary: Legacy friend-request listing shape.
      x-deprecated: true
      x-agenthub-superseded-by: "GET /client/contacts/friend-requests"
      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
      x-agenthub-superseded-by: "GET /client/contacts/friend-requests"
      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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /client/sessions/{id}/members/{target_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: target_user_id
          in: path
          required: true
          schema: { type: string }
      responses:
        "204":
          description: Removed.

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /client/sessions/{id}/member-settings:
    patch:
      tags: [HubSyncRelay]
      operationId: hubUpdateMemberSettingsLegacy
      summary: Legacy member settings shape.
      x-deprecated: true
      x-agenthub-superseded-by: "PUT /client/sessions/{id}/settings"
      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 }
        - name: content_type
          in: query
          required: false
          schema: { type: string }
        - name: from
          in: query
          required: false
          schema: { type: string }
        - name: to
          in: query
          required: false
          schema: { type: string }
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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 }
        - name: session_id
          in: query
          required: false
          schema: { type: string }
        - name: content_type
          in: query
          required: false
          schema: { type: string }
        - name: from
          in: query
          required: false
          schema: { type: string }
        - name: to
          in: query
          required: false
          schema: { type: string }
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /client/sessions/{id}/messages/{msgId}:recall:
    post:
      tags: [HubSyncRelay]
      operationId: hubRecallMessage
      summary: Recall (delete) a message.
      x-deprecated: true
      x-agenthub-superseded-by: "POST /client/messages/{id}/recall"
      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
      x-agenthub-superseded-by: "POST /client/messages/{id}/pin"
      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
      x-agenthub-superseded-by: "DELETE /client/messages/{id}/pin"
      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
      x-agenthub-superseded-by: "POST /client/sessions/{id}/read"
      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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /client/messages:forward:
    post:
      tags: [HubSyncRelay]
      operationId: hubForwardMessages
      summary: Legacy batch-forward shape.
      x-deprecated: true
      x-agenthub-superseded-by: "POST /client/messages/{id}/forward"
      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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Attachment"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
              required: [file, hash, original_name]
              properties:
                file:
                  type: string
                  format: binary
                hash:
                  type: string
                  description: SHA-256 content hash of the upload.
                original_name:
                  type: string
                  description: Original file name preserved for display.
      responses:
        "201":
          $ref: "#/components/responses/Created"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "413":
          $ref: "#/components/responses/Error"
        "415":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /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).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Attachment"
        "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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /client/settings:
    get:
      tags: [HubSyncRelay]
      operationId: hubGetSettings
      summary: Get every stored key-value setting for the authenticated user.
      description: Returns a flat string-to-string map. An empty object is returned when the user has no stored settings.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Settings map for the authenticated user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    type: object
                    additionalProperties: { type: string }
        "401":
          $ref: "#/components/responses/Error"
    patch:
      tags: [HubSyncRelay]
      operationId: hubPatchSettings
      summary: Upsert key-value settings for the authenticated user.
      description: Partial upsert — keys present in values are inserted or overwritten, keys omitted are left untouched. Responds with the full settings map after the upsert.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [values]
              properties:
                values:
                  type: object
                  additionalProperties: { type: string }
      responses:
        "200":
          description: Full settings map after the upsert.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    type: object
                    additionalProperties: { type: string }
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"

  # ── 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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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.

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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/Error"
        "429":
          $ref: "#/components/responses/Error"

  /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. Per-user quota: once the authenticated
        user owns AGENTHUB_MAX_CLOUD_EDGE_DEVICES (default 50) cloud_edge
        devices, registering a brand-new device_id fails with 403
        `device_limit_exceeded`; re-registering an already-owned device_id
        (upsert refresh) is not blocked.
      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/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "429":
          $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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /web/agent-tasks/{id}/regenerate:
    x-agenthub-device-type: web
    post:
      tags: [HubSyncRelay]
      operationId: hubRegenerateTask
      summary: Re-dispatch an agent task, producing a new pending task.
      description: Creates and dispatches a fresh PendingAgentTask derived from the referenced task. The original task is left as-is; the response carries the newly created task.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: The newly created pending agent task.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    $ref: "#/components/schemas/HubPendingAgentTask"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"

  # ── 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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthRefreshResponse"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── Contacts (routes from router.go not yet documented) ──

  /client/contacts/search:
    get:
      tags: [HubSyncRelay]
      operationId: hubSearchContacts
      summary: Search contacts by user id.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: query
          required: true
          description: Target user id (implementation and frontend SSOT use id, not q).
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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.

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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: after_seq
          in: query
          required: false
          description: Incremental sync cursor (messages.seq_id, matches api/events.md).
          schema: { type: integer, format: int64 }
        - name: limit
          in: query
          required: false
          schema: { type: integer }
      responses:
        "200":
          description: Incremental message batch.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Message"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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 }
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
      responses:
        "200":
          $ref: "#/components/responses/List"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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. Returns the edit acknowledgment (message_id + edited_at); not a full Message projection.
      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":
          description: Edit acknowledgment.
          content:
            application/json:
              schema:
                type: object
                required: [message_id, edited_at]
                properties:
                  message_id:
                    type: string
                    format: uuid
                  edited_at:
                    type: string
                    format: date-time
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "410":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /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":
          description: Message recalled (null data).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "410":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /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":
          description: Message pinned (null data).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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":
          description: Message unpinned (null data).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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: [] }]
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageCursor"
        - name: target_type
          in: query
          required: false
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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.

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateProject
      summary: Create a Hub project workspace.
      description: Returns HTTP 200 with a Hub envelope.
      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. Handler returns a bare JSON array (no {items,page} envelope); openapi aligned to implementation.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Project threads list (bare array).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkspaceThread"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $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.
      description: Handler returns a bare JSON array (no {items,page} envelope); openapi aligned to implementation.
      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":
          description: Thread messages list (bare array).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkspaceThreadMessage"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $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 ──

  # ── Documents (Docs Hub) ──

  /web/documents:
    x-agenthub-device-type: web
    get:
      tags: [HubSyncRelay]
      operationId: hubListDocuments
      summary: List cloud documents owned by the authenticated user.
      description: Query filters are bound from the query string; unparsable values are ignored rather than rejected. Returns an items array that is an empty list when nothing matches.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      parameters:
        - name: limit
          in: query
          required: false
          schema: { type: integer }
        - name: after
          in: query
          required: false
          schema: { type: string }
          description: Cursor — return documents after this document id.
        - name: source
          in: query
          required: false
          schema: { type: string }
        - name: search
          in: query
          required: false
          schema: { type: string }
      responses:
        "200":
          description: Lightweight document list items (document content is omitted).
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    type: object
                    required: [items]
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/HubDocumentListItem"
        "401":
          $ref: "#/components/responses/Error"
    post:
      tags: [HubSyncRelay]
      operationId: hubCreateDocument
      summary: Create a cloud document.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string }
                type:
                  type: string
                  description: Document format such as md. Hub defaults to md when omitted.
                tag:
                  type: string
                  nullable: true
                location:
                  type: string
                  description: Library/folder label. Hub applies its default library when omitted.
                content:
                  type: string
                  nullable: true
      responses:
        "200":
          description: The created document.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    $ref: "#/components/schemas/HubDocument"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"

  /web/documents/{id}:
    x-agenthub-device-type: web
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [HubSyncRelay]
      operationId: hubGetDocument
      summary: Get one owner-scoped cloud document including its content.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: The requested document.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    $ref: "#/components/schemas/HubDocument"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    patch:
      tags: [HubSyncRelay]
      operationId: hubUpdateDocument
      summary: Partially update a cloud document.
      description: Only the fields present in the body are applied; omitted fields keep their stored value.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title: { type: string, nullable: true }
                type: { type: string, nullable: true }
                tag: { type: string, nullable: true }
                content: { type: string, nullable: true }
      responses:
        "200":
          description: The updated document.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    $ref: "#/components/schemas/HubDocument"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteDocument
      summary: Delete a cloud document.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /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"
        - name: event_type
          in: query
          required: false
          schema: { type: string }
        - name: severity
          in: query
          required: false
          schema: { type: string }
        - name: since
          in: query
          required: false
          schema: { type: string }
        - name: until
          in: query
          required: false
          schema: { type: string }
      responses:
        "200":
          $ref: "#/components/responses/List"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /web/relay/commands/{id}/device-ack:
    x-agenthub-device-type: web
    post:
      tags: [HubSyncRelay]
      operationId: hubDeviceAckWebRelayCommand
      summary: Device-credential acknowledgement of a relay command (session auth; device_id ownership verified server-side).
      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: [device_id]
              properties:
                device_id:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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":
          description: OK.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentTeam"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    get:
      tags: [HubSyncRelay]
      operationId: hubListAgentTeams
      summary: List agent teams owned by the current user.
      description: Handler returns a bare JSON array (no {items,page} envelope); openapi aligned to implementation.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Agent teams list (bare array).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AgentTeam"
        "401":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    put:
      tags: [HubSyncRelay]
      operationId: hubUpdateAgentTeam
      x-agenthub-role: team-owner
      description: |
        Requires team owner; not satisfied by global admin alone.
      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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteAgentTeam
      x-agenthub-role: team-owner
      description: |
        Requires team owner; not satisfied by global admin alone.
      summary: Delete an agent team.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
      x-agenthub-role: team-owner
      description: |
        Requires team owner; not satisfied by global admin alone.
      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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
      x-agenthub-role: team-owner
      description: |
        Requires team owner; not satisfied by global admin alone.
      summary: Remove a member from a team.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          $ref: "#/components/responses/Ok"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    get:
      tags: [HubSyncRelay]
      operationId: hubListTeamRuns
      summary: List runs for a team.
      description: Handler returns a bare JSON array (no {items,page} envelope); openapi aligned to implementation.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Team runs list (bare array).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AgentTeamRun"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "429":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"

  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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 }
      - name: afterSeq
        in: query
        required: false
        schema: { type: integer, minimum: 0, default: 0 }
        description: Return events with run-local seq greater than this cursor.
      - name: pageSize
        in: query
        required: false
        schema: { type: integer, minimum: 1, maximum: 500, default: 50 }
        description: Page size; values above 500 are clamped.
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
      x-agenthub-role: team-owner
      summary: Consume a typed supervisor route decision and record accepted or rejected TeamEvent audit entries.
      description: Requires team owner (not satisfied by global admin alone). 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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
      x-agenthub-role: team-owner
      summary: Record a TeamRun approval decision and deliver the Edge control payload.
      description: Requires team owner (not satisfied by global admin alone). 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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
      x-agenthub-role: team-owner
      summary: Resolve a projected TeamRun file conflict and append an auditable TeamEvent.
      description: Requires team owner (not satisfied by global admin alone). 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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
      x-agenthub-role: team-member
      description: |
        Requires team member (owner or agent-profile owner installed in the team); not satisfied by global admin alone.
      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, compete]
                  default: delegate
                task_prompt:
                  type: string
                context:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
      x-agenthub-role: team-member
      description: |
        Requires team member (owner or agent-profile owner installed in the team); not satisfied by global admin alone.
      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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
      x-agenthub-role: team-member
      description: |
        Requires team member (owner or agent-profile owner installed in the team); not satisfied by global admin alone.
      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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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
      x-agenthub-role: team-member
      description: |
        Requires team member (owner or agent-profile owner installed in the team); not satisfied by global admin alone.
      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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── Team run compete summary / human review gate ──
  # Mounted flat under /web/team-runs (not under /web/agent-teams/{id}/runs).

  /web/team-runs/{id}/compete-summary:
    x-agenthub-device-type: web
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
        description: TeamRun id (not the AgentTeam id).
    get:
      tags: [HubSyncRelay]
      operationId: hubTeamRunCompeteSummary
      summary: Generate the compete-mode comparison summary for a team run.
      description: >
        Aggregates every competing member's assignment result for the run and
        returns an LLM comparison summary. The handler tolerates an optional
        JSON body with a `prompt` string to steer the comparison and falls back
        to an empty request when the body is absent or unparsable, so callers
        that cannot attach a body to GET still work.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Compete comparison summary for the run.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    $ref: "#/components/schemas/HubCompeteSummaryResponse"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

  /web/team-runs/{id}/review-decision:
    x-agenthub-device-type: web
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string, format: uuid }
        description: TeamRun id (not the AgentTeam id).
    post:
      tags: [HubSyncRelay]
      operationId: hubTeamRunReviewDecision
      x-agenthub-role: team-member
      summary: Record a human review decision on a team run DAG plan.
      description: Requires team member (owner or agent-profile owner installed in the team; not satisfied by global admin alone). Applies the reviewer's approve/discuss/modify decision to the pending review gate and returns the recorded review state.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HubHumanReviewDecision"
      responses:
        "200":
          description: The recorded human review state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  data:
                    $ref: "#/components/schemas/HubHumanReviewState"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"

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

  /v1/auth/login:
    post:
      tags: [HubSyncRelay]
      operationId: login
      summary: Login.
      x-agenthub-superseded-by: "GET /client/auth/oidc/authorize"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/auth/logout:
    post:
      tags: [HubSyncRelay]
      operationId: logout
      summary: Logout.
      x-agenthub-superseded-by: "POST /client/auth/logout"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "204":
          description: Logged out.

  /v1/users/me:
    get:
      tags: [HubSyncRelay]
      operationId: getMe
      summary: Get current user.
      x-agenthub-superseded-by: "GET /client/auth/me"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [HubSyncRelay]
      operationId: updateMe
      summary: Update current user.
      x-agenthub-superseded-by: "PUT /client/auth/profile"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "200":
          $ref: "#/components/responses/Ok"

  /v1/contacts:
    get:
      tags: [HubSyncRelay]
      operationId: listContacts
      summary: List contacts.
      x-agenthub-superseded-by: "GET /client/contacts"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "200":
          $ref: "#/components/responses/List"

  /v1/contacts:request:
    post:
      tags: [HubSyncRelay]
      operationId: requestContact
      summary: Send contact request.
      x-agenthub-superseded-by: "POST /client/contacts/friend-requests"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/contacts/{userId}:accept:
    post:
      tags: [HubSyncRelay]
      operationId: acceptContact
      summary: Accept contact request.
      x-agenthub-superseded-by: "POST /client/contacts/friend-requests/{id}/accept"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/contacts/{userId}:
    delete:
      tags: [HubSyncRelay]
      operationId: deleteContact
      summary: Delete contact.
      x-agenthub-superseded-by: "DELETE /client/contacts/{user_id}"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "204":
          description: Deleted.

  /v1/groups:
    get:
      tags: [HubSyncRelay]
      operationId: listGroups
      summary: List groups.
      x-agenthub-superseded-by: "GET /client/sessions"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: createGroup
      summary: Create group.
      x-agenthub-superseded-by: "POST /client/sessions"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "201":
          $ref: "#/components/responses/Created"

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

  /v1/devices:
    get:
      tags: [HubSyncRelay]
      operationId: listDevices
      summary: List devices.
      x-agenthub-superseded-by: "GET /web/devices"
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "200":
          $ref: "#/components/responses/List"

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

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

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

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

  /v1/edges/{edgeId}:
    get:
      tags: [HubSyncRelay]
      operationId: getEdge
      summary: Get Edge node.
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      parameters:
        - $ref: "#/components/parameters/EdgeId"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
    patch:
      tags: [HubSyncRelay]
      operationId: updateEdge
      summary: Update Edge node.
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      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-owner: Hub
      x-agenthub-status: planned
      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-owner: Hub
      x-agenthub-status: planned
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

  /v1/sync/events:
    get:
      tags: [HubSyncRelay]
      operationId: listSyncEvents
      summary: List sync events.
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      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-owner: Hub
      x-agenthub-status: planned
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

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

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

  /v1/relay/commands/{commandId}:
    get:
      tags: [HubSyncRelay]
      operationId: getRelayCommand
      summary: Get relay command.
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      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-owner: Hub
      x-agenthub-status: planned
      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-owner: Hub
      x-agenthub-status: planned
      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-owner: Hub
      x-agenthub-status: planned
      responses:
        "200":
          $ref: "#/components/responses/List"
    post:
      tags: [HubSyncRelay]
      operationId: createCloudEdge
      summary: Create Cloud Edge node.
      x-agenthub-owner: Hub
      x-agenthub-status: planned
      responses:
        "202":
          $ref: "#/components/responses/Accepted"

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

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

  # ═══════════════════════════════════════════════════════════
  # Hub Server — additional /web routes
  # ═══════════════════════════════════════════════════════════

  # ── 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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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"
        - name: q
          in: query
          required: false
          schema: { type: string }
        - name: skill_type
          in: query
          required: false
          schema: { type: string }
        - name: is_public
          in: query
          required: false
          schema: { type: boolean }
      responses:
        "200":
          $ref: "#/components/responses/List"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteSkill
      summary: Delete a skill.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "204":
          description: Deleted.

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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"
        - name: q
          in: query
          required: false
          schema: { type: string }
        - name: transport
          in: query
          required: false
          schema: { type: string }
        - name: is_public
          in: query
          required: false
          schema: { type: boolean }
      responses:
        "200":
          $ref: "#/components/responses/List"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteMCPServer
      summary: Delete an MCP server.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "204":
          description: Deleted.

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"
        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
    delete:
      tags: [HubSyncRelay]
      operationId: hubDeleteProviderBinding
      summary: Delete a provider binding.
      x-agenthub-status: implemented
      x-agenthub-owner: Hub
      security: [{ bearerAuth: [] }]
      responses:
        "204":
          description: Deleted.

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  # ── 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.
        - name: runtime_id
          in: query
          required: false
          schema: { type: string }
        - name: sort_by
          in: query
          required: false
          schema: { type: string, enum: [recent, install_count, rating] }
      responses:
        "200":
          $ref: "#/components/responses/List"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
  /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"

        "400":
          $ref: "#/components/responses/Error"
        "401":
          $ref: "#/components/responses/Error"
        "403":
          $ref: "#/components/responses/Error"
        "404":
          $ref: "#/components/responses/Error"
        "500":
          $ref: "#/components/responses/Error"
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.
    edgeWebSocketProtocol:
      type: apiKey
      in: header
      name: Sec-WebSocket-Protocol
      description: >
        Browser WebSocket transport for the optional Local Edge token on
        /v1/events: one subprotocol entry of the form `access_token.<edge-token>`.
        Hub WebSocket uses Hub-issued access tokens separately.
  parameters:
    PageSize:
      name: pageSize
      in: query
      required: false
      # Over-ceiling is clamped, not rejected: a request above the maximum the
      # endpoint declares comes back with `maximum` items, HTTP 200 and the
      # usual page.nextCursor / page.hasMore, so the rest of the collection is
      # reached by following the cursor (limit/offset endpoints: by advancing
      # offset). It never falls back to `default`, which would shorten the page
      # a second time. See api/conventions.md §Pagination and
      # hub-server/internal/config/paging.go (ADR-031 / #2243).
      description: >-
        Page size. Defaults to 50. Values above the endpoint's declared maximum
        are clamped to that maximum (not rejected, and not reduced to the
        default); follow page.nextCursor to read the rest.
      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
    ContactUserId:
      name: user_id
      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:
    SessionCreate:
      type: object
      required: [session_id, type, created]
      properties:
        session_id: { type: string, format: uuid }
        type:
          type: string
          enum: [private, group]
        created: { type: boolean }

    HubUser:
      type: object
      required: [id, username, nickname, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        username: { type: string }
        nickname: { type: string }
        avatar_url: { type: string }
        tokendance_sub: { type: string, nullable: true }
        tokendance_sub_linked_at: { type: string, format: date-time, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    AuthRefreshResponse:
      type: object
      required: [access_token, refresh_token, expires_in]
      properties:
        access_token: { type: string }
        refresh_token: { type: string }
        expires_in: { type: integer, format: int64 }

    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]
      description: Hub WebSocket frame envelope. Event-specific payload contracts are documented in api/events.md.
      properties:
        type:
          type: string
          enum:
            - auth.ok
            - typing
            - message.new
            - message.recall
            - message.pin
            - message.unpin
            - message.read
            - message.reaction_added
            - message.reaction_removed
            - session.created
            - session.dissolved
            - session.member_joined
            - session.member_left
            - session.info_updated
            - device.online
            - device.offline
            - device.kicked
            - agent.dispatch
            - agent.stream
            - agent.done
            - agent.failed
            - agent.cancel
            - agent.control
            - team.run.started
            - team.event
            - team.assignment.done
            - team.assignment.failed
            - team.subagent.stream
            - notification.new
            - friend.request
            - friend.accepted
        payload:
          type: object
          additionalProperties: true
        seq_id:
          type: integer
          format: int64
          description: Monotonic sequence ID for ordering and gap detection. Every pushed Hub frame carries one, including auth.ok (seq_id 1); data frames follow from 2.
    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: string
          description: JSON-encoded runtime payload persisted by Hub; 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.
    CreateProjectRequest:
      type: object
      properties:
        name:
          type: string
          description: Project display name.
        description:
          type: string
          description: Optional project description.
    CreateThreadRequest:
      type: object
      required: [projectId]
      properties:
        projectId:
          type: string
          description: Owning project id.
        title:
          type: string
          description: Optional thread title.
        metadata:
          type: object
          additionalProperties: true
          description: Optional key/value metadata for the thread.
    UpdateThreadRequest:
      type: object
      properties:
        title:
          type: string
          description: Updated thread title.
        status:
          type: string
          description: Updated thread status.
        metadata:
          type: object
          additionalProperties: true
          description: Optional key/value metadata to merge or replace.
    CreatePrivateSessionRequest:
      type: object
      required: [peer_user_id]
      properties:
        peer_user_id:
          type: string
          description: The other user id for this 1-on-1 session.
    CreateGroupSessionRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Group session name.
        member_ids:
          type: array
          items:
            type: string
          description: Initial member user ids. May be empty for owner-only group sessions that later invite an Agent.
    SendSessionMessageRequest:
      type: object
      required: [content_type, content]
      properties:
        content_type:
          type: string
          description: Message content type, such as text, code, diff, image, or file.
        content:
          type: string
          description: Message content payload. Text messages carry the message body directly.
        client_msg_id:
          type: string
          format: uuid
          description: Client-generated idempotency key.
    EdgeHealth:
      type: object
      required: [status, version, edgeId, capabilities]
      properties:
        status:
          type: string
        http_status:
          type: integer
        version:
          type: string
        edgeId:
          type: string
        checks:
          type: object
          additionalProperties: true
        capabilities:
          type: object
          required: [runCallbackOwnership, directHubCallbacks, permissionDecisionReceipts]
          properties:
            runCallbackOwnership:
              type: boolean
              description: The Edge enforces and persists per-run callback ownership.
            directHubCallbacks:
              type: boolean
              description: Direct callbacks have a configured destination and current credential; no token or live reachability is exposed.
            permissionDecisionReceipts:
              type: boolean
              description: The Edge supports idempotent modern permission decision receipts.
    DispatchContextMessage:
      type: object
      required: [role, content]
      properties:
        role:
          type: string
        content:
          type: string
        timestamp:
          type: string
          format: date-time
    StartRunRequest:
      type: object
      properties:
        projectId:
          type: string
          description: Project to bind the run to. Defaults to the local project.
        threadId:
          type: string
          description: Thread to bind the run to. Defaults to the local thread.
        deliveryId:
          type: string
          description: Hub delivery_id for dual-channel admission dedup. Empty string bypasses dedup (legacy payload).
        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: >
            Runtime permission policy hint. Only the claude adapter honours this
            field (mapped to Claude Code --permission-mode: default, acceptEdits,
            plan, dontAsk). All other adapters ignore it; Codex
            sandbox level is controlled separately via its own configuration.
        workDir:
          type: string
          description: Explicit working directory required for a new run; must be within the Edge workspace allowlist.
        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 identity for Edge-owned callbacks and cross-transport
            delivery admission. When set, receipts bind to this business task;
            without it, legacy delivery scope binds projectId/threadId. Callback
            ownership must still avoid duplicate Edge/Desktop output bridges.
        callbackOwner:
          type: string
          enum: [edge, desktop]
          description: Required for modern Hub delivery; selects the task callback reporter on first admission. Requires hubTaskId; replay returns the stored owner without reassignment.
        trace_id:
          type: string
          description: Hub dispatch trace correlation identifier.
        messages:
          type: array
          items:
            $ref: "#/components/schemas/DispatchContextMessage"
          description: Hub conversation history forwarded unchanged to the runtime context.
        pinnedMessages:
          type: array
          items:
            $ref: "#/components/schemas/DispatchContextMessage"
          description: Pinned Hub context forwarded unchanged to the runtime.

    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.
            Only the claude adapter acts on this value; other adapters ignore it.
        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.
    Attachment:
      type: object
      description: File attachment metadata (aligned to hub-server model.Attachment json tags).
      required: [id, hash, size, mime_type, uploader_user_id, created_at]
      properties:
        id:
          type: string
          format: uuid
        hash:
          type: string
          description: Content hash (sha256/sha512 hex digest).
        size:
          type: integer
          format: int64
          description: File size in bytes.
        mime_type:
          type: string
        original_name:
          type: string
          description: Original filename if provided by uploader.
        uploader_user_id:
          type: string
          format: uuid
        metadata:
          type: string
          description: JSON object string with additional attachment metadata.
        created_at:
          type: string
          format: date-time
    MessageReplyToInfo:
      type: object
      description: Nested reply-target projection on Message (aligned to message.ReplyToInfo json tags).
      required: [id, sender_id, content_type, content, recalled, created_at]
      properties:
        id:
          type: string
          format: uuid
        sender_id:
          type: string
          format: uuid
        content_type:
          type: string
        content:
          type: string
        recalled:
          type: boolean
        created_at:
          type: string
          format: date-time
    Message:
      type: object
      description: >
        Hub session IM message API projection (aligned to model.Message +
        message.MessageResponse json tags). Used by /client/sessions/{id}/messages
        and /client/messages/{id} routes. The web-project projection
        WorkspaceThreadMessage is a separate, smaller schema for /web/projects
        thread routes.
      required: [id, session_id, seq_id, client_msg_id, sender_type, sender_id, content_type, content, recalled, edited, created_at]
      properties:
        id:
          type: string
          format: uuid
        session_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
          format: uuid
        content_type:
          type: string
          enum: [text, code, diff, image, file, link_card, deploy_card]
        content:
          type: string
          description: Normalized JSON string. Text messages are persisted as text-only JSON or text plus metadata JSON.
        reply_to_message_id:
          type: string
          format: uuid
          nullable: true
          description: ID of the message this one replies to (absent when not a reply).
        reply_to:
          allOf:
            - $ref: "#/components/schemas/MessageReplyToInfo"
          nullable: true
          description: Nested reply-target projection. Absent when not a reply or when the reply target has been deleted.
        attachments:
          type: array
          items:
            $ref: "#/components/schemas/Attachment"
          description: File attachments associated with the message.
        recalled:
          type: boolean
        edited:
          type: boolean
        edited_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
    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
        callbackOwner:
          type: string
          enum: [edge, desktop]
          description: Persisted task callback reporter. Replayed receipts retain the original owner; legacy absence is not an ownership grant.
        admissionState:
          type: string
          enum: [pending, accepted, rejected]
          description: Hub task admission evidence, independent of execution status. Absent on legacy or non-Hub runs.
        admissionErrorCode:
          type: string
          description: Public-safe rejection code recorded with rejected admission; not an execution failure reason.
        deduplicated:
          type: boolean
          description: True on an accepted replay of an already admitted delivery (same runId returned, no new run created).
        deliveryId:
          type: string
          description: On an accepted replay, echoes the current request's deliveryId; a cold replay with a different deliveryId may therefore differ from the original receipt.

    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 }

    HubPendingAgentTask:
      type: object
      required: [id, agent_instance_id, triggered_by_user_id, trigger_message_id, status, created_at, expire_at]
      properties:
        id: { type: string, format: uuid }
        agent_instance_id: { type: string, format: uuid }
        triggered_by_user_id: { type: string, format: uuid }
        trigger_message_id: { type: string, format: uuid }
        target_id: { type: string, format: uuid }
        status: { type: string }
        edge_run_id: { type: string }
        edge_device_id: { type: string, format: uuid }
        error_message: { type: string }
        created_at: { type: string, format: date-time }
        dispatched_at: { type: string, format: date-time, nullable: true }
        finished_at: { type: string, format: date-time, nullable: true }
        expire_at: { type: string, format: date-time }

    HubDocument:
      type: object
      required: [id, owner_id, title, type, source, location, status, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        owner_id: { type: string, format: uuid }
        project_id: { type: string, format: uuid }
        title: { type: string }
        type:
          type: string
          description: Document format such as md.
        source: { type: string }
        source_ref: { type: string }
        tag: { type: string }
        location:
          type: string
          description: Library/folder label the document belongs to.
        content: { type: string }
        status: { type: string }
        metadata:
          type: string
          description: JSON-encoded metadata blob; serialized as a string, not a nested object.
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    HubDocumentListItem:
      type: object
      required: [id, owner_id, title, type, source, location, status, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        owner_id: { type: string, format: uuid }
        title: { type: string }
        type: { type: string }
        source: { type: string }
        source_ref: { type: string }
        tag: { type: string }
        location: { type: string }
        status: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    HubCompeteSummaryResponse:
      type: object
      required: [team_run_id, summary, entries, created_at]
      properties:
        team_run_id: { type: string, format: uuid }
        summary: { type: string }
        entries:
          type: array
          items:
            $ref: "#/components/schemas/HubCompeteSummaryEntry"
        created_at: { type: string, format: date-time }

    HubCompeteSummaryEntry:
      type: object
      required: [member_id, assignment_id, result, status]
      properties:
        member_id: { type: string, format: uuid }
        assignment_id: { type: string, format: uuid }
        task_id: { type: string }
        agent_task_id: { type: string, format: uuid }
        result: { type: string }
        status: { type: string }

    HubHumanReviewDecision:
      type: object
      required: [action]
      properties:
        action:
          type: string
          enum: [approve, discuss, modify]
        comment: { type: string }
        changes:
          type: array
          items:
            $ref: "#/components/schemas/HubHumanReviewChange"

    HubHumanReviewChange:
      type: object
      required: [field, value]
      properties:
        field:
          type: string
          description: Plan field being modified, for example instructions or next_worker.
        value: { type: string }

    HubHumanReviewState:
      type: object
      required: [review_id, run_id, action, created_at]
      properties:
        review_id: { type: string, format: uuid }
        run_id: { type: string, format: uuid }
        action:
          type: string
          enum: [approve, discuss, modify]
        comment: { type: string }
        changes:
          type: array
          items:
            $ref: "#/components/schemas/HubHumanReviewChange"
        decided_by: { type: string, format: uuid }
        created_at: { type: string, format: date-time }
        decided_at: { type: string, format: date-time, nullable: true }

    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, pending_review, 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, compete]
        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, pending_review, 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, compete]
        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"