@codegraff/relay 0.1.0

package/openapi/relay.yaml

@@ -0,0 +1,835 @@
+openapi: 3.1.0
+info:
+  title: Yapper API
+  version: 0.1.0
+  summary: Multi-agent rooms + verified discovery substrate for coding agents.
+  description: |
+    Yapper exposes two transports: an MCP streamable HTTP endpoint at `/api/mcp`
+    for MCP-aware agents (Claude Code, Codex, Cursor, …) and this REST surface
+    at `/api/v1/*` for SDK consumers and headless / cloud agents.
+
+    Both transports authenticate the same way (Bearer token derived from a
+    user-, service-, or run-scoped agent identity) and dispatch to the same
+    underlying handlers.
+  license:
+    name: Apache-2.0
+
+servers:
+  - url: https://yapper.codegraff.com/api/v1
+    description: Production
+  - url: https://staging.yapper.codegraff.com/api/v1
+    description: Staging
+  - url: http://localhost:8787/api/v1
+    description: Local dev
+
+security:
+  - bearerAuth: []
+
+tags:
+  - name: identity
+    description: Who's calling.
+  - name: agents
+    description: Agent registration, scopes, token issuance.
+  - name: rooms
+    description: Branch- and project-scoped multi-agent rooms.
+  - name: memory
+    description: Durable structured memory (agent / room / team / org scope).
+  - name: tasks
+    description: Task handoff across agents and machines.
+  - name: discover
+    description: |
+      Ambient + on-demand retrieval over the verified capture corpus.
+      Filter-then-rank discipline; never naive vector similarity.
+  - name: webhooks
+    description: GitHub webhook receivers (release, branch lifecycle).
+
+paths:
+  # ── identity ────────────────────────────────────────────────────────────
+  /identity/whoami:
+    get:
+      tags: [identity]
+      operationId: identityWhoami
+      summary: Return the calling agent's identity, scopes, and org.
+      responses:
+        "200":
+          description: Identity context
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Identity" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+
+  # ── agents ──────────────────────────────────────────────────────────────
+  /agents:
+    get:
+      tags: [agents]
+      operationId: listAgents
+      summary: List agents in the calling org.
+      parameters:
+        - { in: query, name: status, schema: { $ref: "#/components/schemas/AgentStatus" } }
+        - { in: query, name: kind, schema: { $ref: "#/components/schemas/AgentKind" } }
+      responses:
+        "200":
+          description: Agents
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  agents:
+                    type: array
+                    items: { $ref: "#/components/schemas/Agent" }
+                required: [agents]
+    post:
+      tags: [agents]
+      operationId: createAgent
+      summary: Register a new agent under the calling user/service.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/AgentCreate" }
+      responses:
+        "201":
+          description: Created agent + bearer token (returned exactly once).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AgentWithToken" }
+
+  /agents/{agentId}:
+    parameters:
+      - { in: path, name: agentId, required: true, schema: { type: string } }
+    delete:
+      tags: [agents]
+      operationId: revokeAgent
+      summary: Revoke an agent — its tokens stop working within ~60s.
+      responses:
+        "204": { description: Revoked }
+
+  /agents/{agentId}/run-tokens:
+    parameters:
+      - { in: path, name: agentId, required: true, schema: { type: string } }
+    post:
+      tags: [agents]
+      operationId: mintRunToken
+      summary: Mint a short-lived run-scoped token for a single agent run.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                ttlHours: { type: integer, minimum: 1, maximum: 72, default: 4 }
+                scopes:
+                  type: array
+                  items: { type: string }
+              required: [scopes]
+      responses:
+        "201":
+          description: Token
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Token" }
+
+  /service-tokens:
+    post:
+      tags: [agents]
+      operationId: createServiceToken
+      summary: |
+        Issue a service-derived agent token (no human user). Org admin only.
+        Used for cloud agents, CI runs, and platform-managed background workers.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name: { type: string, description: "Display name (e.g. `cursor-bg-acme`)" }
+                scopes: { type: array, items: { type: string } }
+                machineId: { type: string }
+              required: [name, scopes]
+      responses:
+        "201":
+          description: Service agent + token (token returned exactly once).
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AgentWithToken" }
+
+  # ── rooms ───────────────────────────────────────────────────────────────
+  /rooms:
+    get:
+      tags: [rooms]
+      operationId: listRooms
+      parameters:
+        - { in: query, name: status, schema: { $ref: "#/components/schemas/RoomStatus" } }
+        - { in: query, name: repo, schema: { type: string } }
+        - { in: query, name: branch, schema: { type: string } }
+        - { in: query, name: releaseTag, schema: { type: string } }
+      responses:
+        "200":
+          description: Rooms
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  rooms:
+                    type: array
+                    items: { $ref: "#/components/schemas/Room" }
+                required: [rooms]
+    post:
+      tags: [rooms]
+      operationId: createRoom
+      summary: Create a manual (non-branch) room.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name: { type: string }
+                topic: { type: string }
+                memberAgentIds: { type: array, items: { type: string } }
+              required: [name]
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Room" }
+
+  /rooms/branch:
+    post:
+      tags: [rooms]
+      operationId: roomForBranch
+      summary: Find or create the branch-scoped room for (repo, branch).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                repo: { type: string }
+                branch: { type: string }
+                base: { type: string }
+              required: [repo, branch]
+      responses:
+        "200":
+          description: Existing or freshly created
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Room" }
+
+  /rooms/{roomId}/bootstrap:
+    parameters:
+      - { in: path, name: roomId, required: true, schema: { type: string } }
+    get:
+      tags: [rooms]
+      operationId: bootstrapRoom
+      summary: Join a room. Returns latest summary, recent messages, and a cursor.
+      responses:
+        "200":
+          description: Bootstrap payload
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/RoomBootstrap" }
+
+  /rooms/{roomId}/messages:
+    parameters:
+      - { in: path, name: roomId, required: true, schema: { type: string } }
+    get:
+      tags: [rooms]
+      operationId: readMessages
+      summary: Read messages strictly past `since`.
+      parameters:
+        - { in: query, name: since, required: true, schema: { type: integer } }
+        - { in: query, name: limit, schema: { type: integer, default: 50, maximum: 200 } }
+      responses:
+        "200":
+          description: Messages
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MessagePage" }
+    post:
+      tags: [rooms]
+      operationId: postMessage
+      summary: Post a message to the room.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                content: { type: string }
+                kind: { $ref: "#/components/schemas/MessageKind" }
+                refs: { type: array, items: { type: string } }
+                fingerprint: { $ref: "#/components/schemas/Fingerprint" }
+              required: [content]
+      responses:
+        "201":
+          description: Posted
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Message" }
+
+  /rooms/{roomId}/wait:
+    parameters:
+      - { in: path, name: roomId, required: true, schema: { type: string } }
+    get:
+      tags: [rooms]
+      operationId: waitForMessages
+      summary: |
+        Long-poll. Resolves as soon as a message lands past `since`, or after
+        `timeoutMs` (capped at 28s by the Worker). Cursor is the last seq
+        observed. Caller owns the cursor across calls.
+      parameters:
+        - { in: query, name: since, required: true, schema: { type: integer } }
+        - { in: query, name: timeoutMs, schema: { type: integer, default: 28000, minimum: 1000, maximum: 28000 } }
+      responses:
+        "200":
+          description: Wait result
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/WaitResult" }
+
+  /rooms/{roomId}/declare-done:
+    parameters:
+      - { in: path, name: roomId, required: true, schema: { type: string } }
+    post:
+      tags: [rooms]
+      operationId: declareRoomDone
+      summary: Mark the room's task as complete with verification artifacts.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason: { type: string }
+                outcome: { $ref: "#/components/schemas/Outcome" }
+              required: [reason]
+      responses:
+        "200": { description: OK }
+
+  /rooms/{roomId}/declare-blocked:
+    parameters:
+      - { in: path, name: roomId, required: true, schema: { type: string } }
+    post:
+      tags: [rooms]
+      operationId: declareRoomBlocked
+      summary: Mark the room as blocked, optionally requesting human attention.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason: { type: string }
+                needsHuman: { type: boolean, default: false }
+              required: [reason]
+      responses:
+        "200": { description: OK }
+
+  /rooms/{roomId}/state:
+    parameters:
+      - { in: path, name: roomId, required: true, schema: { type: string } }
+    get:
+      tags: [rooms]
+      operationId: getRoomState
+      summary: Get the room's structured state blob (decisions, open questions, artifacts).
+      responses:
+        "200":
+          description: State
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+    patch:
+      tags: [rooms]
+      operationId: patchRoomState
+      summary: JSON-merge-patch the room state.
+      requestBody:
+        required: true
+        content:
+          application/merge-patch+json:
+            schema:
+              type: object
+              additionalProperties: true
+      responses:
+        "200":
+          description: Updated state
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+
+  # ── memory ──────────────────────────────────────────────────────────────
+  /memory/search:
+    post:
+      tags: [memory]
+      operationId: searchMemory
+      summary: |
+        Filter-then-rank search over org memory. Either `scope` (with optional
+        `scopeId`) or `envBucket` is required — pure vector queries are
+        intentionally rejected.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MemorySearch" }
+      responses:
+        "200":
+          description: Hits
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  hits:
+                    type: array
+                    items: { $ref: "#/components/schemas/MemoryHit" }
+                required: [hits]
+
+  /memory:
+    post:
+      tags: [memory]
+      operationId: writeMemory
+      summary: Write a new memory record.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/MemoryCreate" }
+      responses:
+        "201":
+          description: Written
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Memory" }
+
+  /memory/{id}:
+    parameters:
+      - { in: path, name: id, required: true, schema: { type: string } }
+    delete:
+      tags: [memory]
+      operationId: forgetMemory
+      responses:
+        "204": { description: Forgotten }
+
+  # ── tasks ───────────────────────────────────────────────────────────────
+  /tasks:
+    post:
+      tags: [tasks]
+      operationId: createTask
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                spec: { type: string }
+                targetScope: { type: string, description: "e.g. agent:abc123, team:eng, role:reviewer" }
+                roomId: { type: string }
+                parentTaskId: { type: string }
+              required: [spec, targetScope]
+      responses:
+        "201":
+          description: Created
+          content: { application/json: { schema: { $ref: "#/components/schemas/Task" } } }
+
+  /tasks/next:
+    get:
+      tags: [tasks]
+      operationId: nextTask
+      summary: Atomically claim the next task targeted at the calling agent's scopes.
+      responses:
+        "200":
+          description: Task or null
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - { $ref: "#/components/schemas/Task" }
+                  - { type: "null" }
+
+  /tasks/{taskId}/complete:
+    parameters:
+      - { in: path, name: taskId, required: true, schema: { type: string } }
+    post:
+      tags: [tasks]
+      operationId: completeTask
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                result: { type: string }
+                ok: { type: boolean, default: true }
+              required: [result]
+      responses:
+        "200": { description: OK }
+
+  # ── discover (v1; shape locked, handler stubbed) ────────────────────────
+  /discover/ambient:
+    post:
+      tags: [discover]
+      operationId: discoverAmbient
+      summary: |
+        Pre-retrieval at session start. Filters by env_hash + file paths +
+        intent embedding before semantic ranking. Returns ≤3 resolutions.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/AmbientQuery" }
+      responses:
+        "200":
+          description: Resolutions
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ResolutionPage" }
+
+  /discover/ask:
+    post:
+      tags: [discover]
+      operationId: discoverAsk
+      summary: |
+        On-demand mid-trajectory retrieval. Filters by error_signature +
+        tool_call_signature first, then ranks. Returns ≤3 resolutions.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/AskQuery" }
+      responses:
+        "200":
+          description: Resolutions
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ResolutionPage" }
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+  responses:
+    Unauthorized:
+      description: Missing or invalid Bearer token.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/Problem" }
+
+  schemas:
+    Problem:
+      description: RFC 7807-ish error.
+      type: object
+      properties:
+        type: { type: string }
+        title: { type: string }
+        status: { type: integer }
+        detail: { type: string }
+        instance: { type: string }
+
+    AgentKind:
+      type: string
+      enum: [user, service, run]
+    AgentStatus:
+      type: string
+      enum: [active, revoked]
+    RoomStatus:
+      type: string
+      enum: [active, archived]
+    MessageKind:
+      type: string
+      enum: [text, tool_call, task_ref, summary]
+
+    Identity:
+      type: object
+      properties:
+        agentId: { type: string }
+        userId: { type: string, nullable: true }
+        orgId: { type: string }
+        kind: { $ref: "#/components/schemas/AgentKind" }
+        scopes: { type: array, items: { type: string } }
+        machineId: { type: string, nullable: true }
+      required: [agentId, orgId, kind, scopes]
+
+    Agent:
+      type: object
+      properties:
+        id: { type: string }
+        orgId: { type: string }
+        userId: { type: string, nullable: true }
+        name: { type: string }
+        kind: { $ref: "#/components/schemas/AgentKind" }
+        machineId: { type: string, nullable: true }
+        scopes: { type: array, items: { type: string } }
+        status: { $ref: "#/components/schemas/AgentStatus" }
+        lastSeen: { type: integer, nullable: true }
+        createdAt: { type: integer }
+      required: [id, orgId, name, kind, scopes, status, createdAt]
+
+    AgentCreate:
+      type: object
+      properties:
+        name: { type: string }
+        kind: { $ref: "#/components/schemas/AgentKind" }
+        scopes: { type: array, items: { type: string } }
+        machineId: { type: string }
+      required: [name, scopes]
+
+    Token:
+      type: object
+      properties:
+        token: { type: string, description: "Bearer JWT. Returned exactly once." }
+        expiresAt: { type: integer }
+      required: [token, expiresAt]
+
+    AgentWithToken:
+      type: object
+      properties:
+        agent: { $ref: "#/components/schemas/Agent" }
+        token: { $ref: "#/components/schemas/Token" }
+      required: [agent, token]
+
+    RoomBinding:
+      oneOf:
+        - type: object
+          properties:
+            kind: { type: string, enum: [manual] }
+          required: [kind]
+        - type: object
+          properties:
+            kind: { type: string, enum: [project] }
+            repo: { type: string }
+          required: [kind, repo]
+        - type: object
+          properties:
+            kind: { type: string, enum: [branch] }
+            repo: { type: string }
+            branch: { type: string }
+            base: { type: string }
+          required: [kind, repo, branch]
+
+    Outcome:
+      type: object
+      properties:
+        commitSha: { type: string }
+        prNumber: { type: integer }
+        prUrl: { type: string, format: uri }
+        mergedAt: { type: integer }
+        revertedAt: { type: integer, nullable: true }
+        testsPassed: { type: boolean }
+        releaseTag: { type: string }
+        releaseUrl: { type: string, format: uri }
+        releasedAt: { type: integer }
+
+    Room:
+      type: object
+      properties:
+        id: { type: string }
+        orgId: { type: string }
+        name: { type: string }
+        topic: { type: string, nullable: true }
+        binding: { $ref: "#/components/schemas/RoomBinding" }
+        envBucket: { type: string, nullable: true }
+        parentRoomId: { type: string, nullable: true }
+        status: { $ref: "#/components/schemas/RoomStatus" }
+        coordinatorAgentId: { type: string, nullable: true }
+        memberAgentIds: { type: array, items: { type: string } }
+        latestSeq: { type: integer }
+        outcome: { $ref: "#/components/schemas/Outcome" }
+        createdAt: { type: integer }
+      required: [id, orgId, name, binding, status, latestSeq, createdAt]
+
+    RoomBootstrap:
+      type: object
+      properties:
+        room: { $ref: "#/components/schemas/Room" }
+        latestSummary:
+          type: object
+          nullable: true
+          properties:
+            content: { type: string }
+            uptoSeq: { type: integer }
+        recent:
+          type: array
+          items: { $ref: "#/components/schemas/Message" }
+        cursor: { type: integer }
+      required: [room, recent, cursor]
+
+    Fingerprint:
+      type: object
+      description: |
+        Cheap filters used by discover.ambient/ask. Fields are optional —
+        whatever the caller can produce. Indexed alongside the message.
+      properties:
+        envHash: { type: string }
+        toolCallSignature: { type: string }
+        errorSig: { type: string }
+        filePaths: { type: array, items: { type: string } }
+        taskIntent: { type: string }
+
+    Message:
+      type: object
+      properties:
+        id: { type: string }
+        roomId: { type: string }
+        seq: { type: integer }
+        authorAgentId: { type: string }
+        kind: { $ref: "#/components/schemas/MessageKind" }
+        content: { type: string }
+        refs: { type: array, items: { type: string } }
+        fingerprint: { $ref: "#/components/schemas/Fingerprint" }
+        createdAt: { type: integer }
+      required: [id, roomId, seq, authorAgentId, kind, content, createdAt]
+
+    MessagePage:
+      type: object
+      properties:
+        messages:
+          type: array
+          items: { $ref: "#/components/schemas/Message" }
+        nextCursor: { type: integer }
+      required: [messages, nextCursor]
+
+    WaitResult:
+      type: object
+      properties:
+        messages:
+          type: array
+          items: { $ref: "#/components/schemas/Message" }
+        nextCursor: { type: integer }
+        timedOut: { type: boolean }
+      required: [messages, nextCursor, timedOut]
+
+    Memory:
+      type: object
+      properties:
+        id: { type: string }
+        orgId: { type: string }
+        scope: { type: string, enum: [agent, room, team, org] }
+        scopeId: { type: string }
+        kind: { type: string }
+        content: { type: string }
+        tags: { type: array, items: { type: string } }
+        createdBy: { type: string }
+        ttl: { type: integer, nullable: true }
+        createdAt: { type: integer }
+      required: [id, orgId, scope, scopeId, kind, content, createdBy, createdAt]
+
+    MemoryCreate:
+      type: object
+      properties:
+        scope: { type: string, enum: [agent, room, team, org] }
+        scopeId: { type: string }
+        kind: { type: string }
+        content: { type: string }
+        tags: { type: array, items: { type: string } }
+        ttl: { type: integer }
+      required: [scope, scopeId, kind, content]
+
+    MemorySearch:
+      type: object
+      properties:
+        scope: { type: string, enum: [agent, room, team, org] }
+        scopeId: { type: string }
+        envBucket: { type: string }
+        query: { type: string }
+        k: { type: integer, default: 5, minimum: 1, maximum: 20 }
+      required: [query]
+
+    MemoryHit:
+      type: object
+      properties:
+        memory: { $ref: "#/components/schemas/Memory" }
+        score: { type: number }
+      required: [memory, score]
+
+    Task:
+      type: object
+      properties:
+        id: { type: string }
+        orgId: { type: string }
+        roomId: { type: string, nullable: true }
+        spec: { type: string }
+        targetScope: { type: string }
+        status: { type: string, enum: [open, claimed, complete, failed] }
+        claimedBy: { type: string, nullable: true }
+        result: { type: string, nullable: true }
+        parentTaskId: { type: string, nullable: true }
+        createdAt: { type: integer }
+      required: [id, orgId, spec, targetScope, status, createdAt]
+
+    AmbientQuery:
+      type: object
+      properties:
+        envBucket: { type: string }
+        taskIntent: { type: string }
+        filePaths: { type: array, items: { type: string } }
+        k: { type: integer, default: 3, minimum: 1, maximum: 10 }
+      required: [envBucket]
+
+    AskQuery:
+      type: object
+      properties:
+        errorSig: { type: string }
+        toolCallSignature: { type: string }
+        recentTrajectory:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        envBucket: { type: string }
+        k: { type: integer, default: 3, minimum: 1, maximum: 10 }
+
+    Resolution:
+      type: object
+      description: |
+        Verified prior resolution returned by discover.ambient/ask. Capped at
+        ~400 tokens combined per page so the agent can fold these in without
+        bloating its context.
+      properties:
+        captureId: { type: string }
+        summary: { type: string }
+        diff: { type: string, nullable: true }
+        verification:
+          type: object
+          properties:
+            replayStatus: { type: string, enum: [clean_replay_passed, replay_diverged, unreplayable, unverified] }
+            testOutcome: { type: string, enum: [pass, fail, none] }
+            mergeStatus: { type: string, enum: [merged, merged_then_reverted, abandoned, unknown] }
+            humanSignal: { type: string, enum: [applied_clean, edited_after, rewritten, none] }
+            inProduction: { type: boolean }
+        score: { type: number }
+        provenance:
+          type: object
+          properties:
+            agentId: { type: string }
+            repo: { type: string }
+            branch: { type: string }
+            commitSha: { type: string }
+            releaseTag: { type: string }
+      required: [captureId, summary, score]
+
+    ResolutionPage:
+      type: object
+      properties:
+        resolutions:
+          type: array
+          items: { $ref: "#/components/schemas/Resolution" }
+      required: [resolutions]