@sanqianx/claude-ai-workbench 0.11.0

package/docs/sdk/openapi.yaml

@@ -0,0 +1,760 @@
+openapi: 3.1.0
+info:
+  title: Claude AI Workbench API
+  version: 0.11.0
+  description: Versioned local API for AI Profile, credential and Claude Code session management.
+servers:
+  - url: http://127.0.0.1:5760/api/claude-workbench/v1
+tags:
+  - name: System
+  - name: Agents
+  - name: Projects
+  - name: Profiles
+  - name: Sessions
+paths:
+  /health:
+    get:
+      tags: [System]
+      operationId: getHealth
+      responses:
+        "200":
+          description: Server health
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Health" }
+  /runtime:
+    get:
+      tags: [System]
+      operationId: getRuntime
+      responses:
+        "200":
+          description: Claude Code runtime availability
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/RuntimeInfo" }
+  /agents:
+    get:
+      tags: [Agents]
+      operationId: listAgents
+      responses:
+        "200":
+          description: Known agents with their capability matrix
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [agents]
+                properties:
+                  agents:
+                    type: array
+                    items: { $ref: "#/components/schemas/AgentInfo" }
+  /projects:
+    get:
+      tags: [Projects]
+      operationId: listProjects
+      responses:
+        "200":
+          description: User-created workspace projects
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [projects]
+                properties:
+                  projects:
+                    type: array
+                    items: { $ref: "#/components/schemas/Project" }
+    post:
+      tags: [Projects]
+      operationId: createProject
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ProjectInput" }
+      responses:
+        "201":
+          description: Created project
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Project" }
+        "400": { $ref: "#/components/responses/Error" }
+  /projects/{projectId}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+    get:
+      tags: [Projects]
+      operationId: getProject
+      responses:
+        "200":
+          description: Single project
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Project" }
+        "404": { $ref: "#/components/responses/Error" }
+    patch:
+      tags: [Projects]
+      operationId: updateProject
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name: { type: string, maxLength: 128 }
+                defaultAiProfileId: { type: [string, "null"], description: Default provider; null selects the agent's own login. }
+                defaultModel: { type: [string, "null"] }
+                defaultAgentId: { type: string, enum: [claude-code, codex, opencode, zcode] }
+      responses:
+        "200":
+          description: Updated project name or defaults
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Project" }
+        "400": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+    delete:
+      tags: [Projects]
+      operationId: removeProject
+      description: Removes the project together with all of its sessions.
+      responses:
+        "204": { description: Removed }
+        "404": { $ref: "#/components/responses/Error" }
+  /profiles:
+    get:
+      tags: [Profiles]
+      operationId: listProfiles
+      responses:
+        "200":
+          description: Public profiles; never contains a plaintext credential
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [profiles]
+                properties:
+                  profiles:
+                    type: array
+                    items: { $ref: "#/components/schemas/AiProfile" }
+    post:
+      tags: [Profiles]
+      operationId: createProfile
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/AiProfileInput" }
+      responses:
+        "201":
+          description: Created profile
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AiProfile" }
+        "400": { $ref: "#/components/responses/Error" }
+  /profiles/test:
+    post:
+      tags: [Profiles]
+      operationId: testProfileDraft
+      description: Tests the submitted draft without saving the profile or credential.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [profile]
+              properties:
+                profile: { $ref: "#/components/schemas/AiProfileInput" }
+                credential:
+                  type: string
+                  writeOnly: true
+                  description: Temporary credential. If omitted, an existing stored credential for the same profile id is used.
+      responses:
+        "200":
+          description: Verified by the Claude Code runtime
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ProfileTestResult" }
+        "400": { $ref: "#/components/responses/Error" }
+  /profiles/{profileId}:
+    parameters:
+      - $ref: "#/components/parameters/ProfileId"
+    get:
+      tags: [Profiles]
+      operationId: getProfile
+      responses:
+        "200":
+          description: Public profile
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AiProfile" }
+        "404": { $ref: "#/components/responses/Error" }
+    put:
+      tags: [Profiles]
+      operationId: updateProfile
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/AiProfileInput" }
+      responses:
+        "200":
+          description: Updated profile
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AiProfile" }
+        "400": { $ref: "#/components/responses/Error" }
+    delete:
+      tags: [Profiles]
+      operationId: deleteProfile
+      responses:
+        "204": { description: Profile and its credential were deleted }
+        "404": { $ref: "#/components/responses/Error" }
+  /profiles/{profileId}/credential:
+    parameters:
+      - $ref: "#/components/parameters/ProfileId"
+    put:
+      tags: [Profiles]
+      operationId: setProfileCredential
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [secret]
+              properties:
+                secret: { type: string, minLength: 1, writeOnly: true }
+      responses:
+        "204": { description: Credential stored separately from the public profile }
+        "400": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+  /profiles/{profileId}/test:
+    parameters:
+      - $ref: "#/components/parameters/ProfileId"
+    post:
+      tags: [Profiles]
+      operationId: testSavedProfile
+      responses:
+        "200":
+          description: Verified by the Claude Code runtime
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ProfileTestResult" }
+        "400": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+  /sessions:
+    get:
+      tags: [Sessions]
+      operationId: listSessions
+      parameters:
+        - in: query
+          name: contextId
+          required: true
+          schema: { type: string }
+        - in: query
+          name: archived
+          required: false
+          description: Set to 1 or true to include archived sessions
+          schema: { type: string, enum: ["", "1", "true"] }
+      responses:
+        "200":
+          description: Sessions for a context
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sessions:
+                    type: array
+                    items: { $ref: "#/components/schemas/SessionSummary" }
+    post:
+      tags: [Sessions]
+      operationId: startSession
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [context]
+              properties:
+                context: { $ref: "#/components/schemas/WorkbenchContext" }
+                aiProfileId: { type: [string, "null"], description: Session provider override; omitted inherits the project default; null selects agent-owned login. }
+                model: { type: [string, "null"], description: Session model override. }
+                permissionMode: { $ref: "#/components/schemas/PermissionMode" }
+                agentId:
+                  type: string
+                  enum: [claude-code, codex, opencode, zcode]
+                  description: Omitted inherits the project default, then claude-code.
+                effort:
+                  type: string
+                  enum: [low, medium, high, max]
+                  description: Reasoning effort slot; only agents whose capabilities include "effort" accept it.
+      responses:
+        "201":
+          description: Session created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  session: { $ref: "#/components/schemas/SessionSummary" }
+        "400": { $ref: "#/components/responses/Error" }
+  /sessions/{sessionId}:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+    get:
+      tags: [Sessions]
+      operationId: getSession
+      responses:
+        "200": { description: Session snapshot }
+        "404": { $ref: "#/components/responses/Error" }
+  /sessions/{sessionId}/events:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+    get:
+      tags: [Sessions]
+      operationId: subscribeSessionEvents
+      parameters:
+        - in: header
+          name: Last-Event-ID
+          schema: { type: integer, minimum: 0 }
+      responses:
+        "200":
+          description: Normalized Server-Sent Events
+          content:
+            text/event-stream:
+              schema: { type: string }
+  /sessions/{sessionId}/input:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+    post:
+      tags: [Sessions]
+      operationId: sendSessionInput
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: At least one of text or attachments must be supplied.
+              properties:
+                text: { type: string }
+                attachments:
+                  type: array
+                  maxItems: 20
+                  description: Images and UTF-8 text files; maximum combined decoded payload is 20 MiB.
+                  items: { $ref: "#/components/schemas/AttachmentInput" }
+                options: { type: object, additionalProperties: true }
+      responses:
+        "202": { description: Input accepted }
+        "400": { $ref: "#/components/responses/Error" }
+        "413": { $ref: "#/components/responses/Error" }
+        "415": { $ref: "#/components/responses/Error" }
+  /sessions/{sessionId}/commands:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+    get:
+      tags: [Sessions]
+      operationId: listSessionCommands
+      description: Returns commands discovered from the active Claude Code runtime, including installed skills and plugins.
+      responses:
+        "200":
+          description: Commands supported by this session
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [commands]
+                properties:
+                  commands:
+                    type: array
+                    items: { $ref: "#/components/schemas/SlashCommand" }
+        "400": { $ref: "#/components/responses/Error" }
+        "404": { $ref: "#/components/responses/Error" }
+  /sessions/{sessionId}/attachments/{attachmentId}:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+      - $ref: "#/components/parameters/AttachmentId"
+    get:
+      tags: [Sessions]
+      operationId: getSessionAttachment
+      responses:
+        "200":
+          description: Persisted image or text attachment. Text files are served as downloads with content sniffing disabled.
+          content:
+            image/jpeg: { schema: { type: string, format: binary } }
+            image/png: { schema: { type: string, format: binary } }
+            image/gif: { schema: { type: string, format: binary } }
+            image/webp: { schema: { type: string, format: binary } }
+            text/plain: { schema: { type: string } }
+            text/markdown: { schema: { type: string } }
+            application/json: { schema: { type: string } }
+            text/csv: { schema: { type: string } }
+        "404": { $ref: "#/components/responses/Error" }
+  /sessions/{sessionId}/permissions/{requestId}/resolve:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+      - in: path
+        name: requestId
+        required: true
+        schema: { type: string }
+    post:
+      tags: [Sessions]
+      operationId: resolvePermission
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [allow]
+              properties:
+                allow: { type: boolean }
+                message: { type: string }
+      responses:
+        "200": { description: Permission resolved }
+  /sessions/{sessionId}/abort:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+    post:
+      tags: [Sessions]
+      operationId: abortSession
+      responses:
+        "202": { description: Abort accepted }
+  /sessions/{sessionId}/permission-mode:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+    put:
+      tags: [Sessions]
+      operationId: setPermissionMode
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [mode]
+              properties:
+                mode: { $ref: "#/components/schemas/PermissionMode" }
+      responses:
+        "200": { description: Permission mode updated }
+  /sessions/{sessionId}/archive:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+    put:
+      tags: [Sessions]
+      operationId: archiveSession
+      responses:
+        "200":
+          description: Session archived
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sessionId: { type: string }
+                  archivedAt: { type: string, format: date-time }
+        "404": { $ref: "#/components/responses/Error" }
+    delete:
+      tags: [Sessions]
+      operationId: restoreSession
+      responses:
+        "204": { description: Session restored }
+        "404": { $ref: "#/components/responses/Error" }
+  /sessions/{sessionId}/context-usage:
+    parameters:
+      - $ref: "#/components/parameters/SessionId"
+    get:
+      tags: [Sessions]
+      operationId: getSessionContextUsage
+      description: Approximate context occupancy for the capacity indicator.
+      responses:
+        "200":
+          description: Context usage snapshot
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sessionId: { type: string }
+                  agentId: { type: string }
+                  model: { type: [string, "null"] }
+                  contextWindow: { type: integer }
+                  used: { type: integer }
+                  percent: { type: [number, "null"] }
+                  inputTokens: { type: integer }
+                  outputTokens: { type: integer }
+                  breakdown:
+                    type: object
+                    properties:
+                      messages: { type: integer }
+                      tools: { type: integer }
+                      other: { type: integer }
+                  estimated: { type: boolean }
+        "404": { $ref: "#/components/responses/Error" }
+components:
+  parameters:
+    ProfileId:
+      in: path
+      name: profileId
+      required: true
+      schema: { type: string, pattern: "^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$" }
+    SessionId:
+      in: path
+      name: sessionId
+      required: true
+      schema: { type: string }
+    AttachmentId:
+      in: path
+      name: attachmentId
+      required: true
+      schema: { type: string }
+    ProjectId:
+      in: path
+      name: projectId
+      required: true
+      schema: { type: string, pattern: "^prj-[a-zA-Z0-9._:-]+$" }
+  responses:
+    Error:
+      description: Request failed
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/ErrorResponse" }
+  schemas:
+    PermissionMode:
+      type: string
+      enum: [default, acceptEdits, plan, bypassPermissions]
+    AgentInfo:
+      type: object
+      required: [id, label, transport, authModes, capabilities, available]
+      properties:
+        id: { type: string, enum: [claude-code, codex, opencode, zcode] }
+        label: { type: string }
+        transport: { type: string }
+        authModes: { type: array, items: { type: string } }
+        available: { type: boolean }
+        version: { type: [string, "null"] }
+        capabilities:
+          type: object
+          required: [thinking, permissions, toolStream, images, resume, modelOverride, generationParams]
+          properties:
+            thinking: { type: boolean }
+            permissions: { type: boolean }
+            toolStream: { type: boolean }
+            images: { type: boolean }
+            resume: { type: boolean }
+            modelOverride: { type: boolean }
+            generationParams: { type: array, items: { type: string } }
+    Project:
+      type: object
+      required: [id, name, rootPath, createdAt, updatedAt]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        rootPath: { type: string, description: Absolute local directory that must exist }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+        defaultAiProfileId: { type: [string, "null"] }
+        defaultModel: { type: [string, "null"] }
+        defaultAgentId: { type: string, enum: [claude-code, codex, opencode, zcode] }
+    ProjectInput:
+      type: object
+      required: [name, rootPath]
+      properties:
+        name: { type: string, minLength: 1, maxLength: 128 }
+        rootPath: { type: string, minLength: 1 }
+        defaultAiProfileId: { type: [string, "null"] }
+        defaultModel: { type: [string, "null"] }
+        defaultAgentId: { type: string, enum: [claude-code, codex, opencode, zcode] }
+    WorkbenchContext:
+      type: object
+      required: [contextId]
+      properties:
+        contextId: { type: string }
+        contextType: { type: string }
+        displayName: { type: string }
+        workspaceRef: { type: string }
+        aiProfileId: { type: [string, "null"] }
+        model: { type: [string, "null"] }
+        metadata: { type: object, additionalProperties: true }
+    AiProfileModels:
+      type: object
+      required: [default]
+      properties:
+        default: { type: string, minLength: 1 }
+        fast: { type: string }
+        reasoning: { type: string }
+        coding: { type: string }
+        largeContext: { type: string }
+        list:
+          type: array
+          maxItems: 100
+          items: { $ref: "#/components/schemas/ModelListEntry" }
+      additionalProperties: { type: string }
+    ModelListEntry:
+      type: object
+      required: [id]
+      properties:
+        id: { type: string, minLength: 1, maxLength: 128 }
+        openaiId: { type: string, maxLength: 128, description: "OpenAI protocol model id; defaults to id with a trailing '[1m]' removed." }
+        label: { type: string, maxLength: 128 }
+        tags: { type: array, maxItems: 8, items: { type: string, maxLength: 32 } }
+    AiProfileInput:
+      type: object
+      required: [id, provider, baseUrl, models]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        provider: { type: string }
+        runtime: { type: string, const: claude-code }
+        protocol: { type: string, default: anthropic-compatible }
+        baseUrl: { type: string, format: uri }
+        openaiBaseUrl:
+          type: string
+          description: OpenAI-compatible endpoint used by Codex and OpenCode. MiniMax China defaults to https://api.minimaxi.com/v1; MiniMax global defaults to https://api.minimax.io/v1.
+        credentialRef: { type: string }
+        models: { $ref: "#/components/schemas/AiProfileModels" }
+        contextWindow: { type: integer, minimum: 1, default: 200000 }
+        timeoutMs: { type: integer, minimum: 1, default: 300000 }
+        permissionMode: { $ref: "#/components/schemas/PermissionMode" }
+        systemPrompt: { type: object, additionalProperties: true }
+        enabled: { type: boolean, default: true }
+    AiProfile:
+      allOf:
+        - $ref: "#/components/schemas/AiProfileInput"
+        - type: object
+          required: [name, runtime, protocol, credentialRef, credentialConfigured, enabled]
+          properties:
+            credentialConfigured: { type: boolean, readOnly: true }
+            credentialMasked:
+              type: string
+              readOnly: true
+              description: Masked preview only; never the plaintext secret.
+    ProfileTestResult:
+      type: object
+      required: [ok, runtime, runtimeVerified, profileId, model, firstEventMs, durationMs, resultPreview]
+      properties:
+        ok: { type: boolean, const: true }
+        runtime: { type: string, const: claude-code }
+        runtimeVerified: { type: boolean, const: true }
+        profileId: { type: string }
+        model: { type: string }
+        firstEventMs: { type: integer, minimum: 0 }
+        durationMs: { type: integer, minimum: 0 }
+        resultPreview: { type: string }
+    Health:
+      type: object
+      required: [status, version, apiVersion, activeProcesses, sessions, time]
+      properties:
+        status: { type: string, const: ok }
+        version: { type: string }
+        apiVersion: { type: string }
+        activeProcesses: { type: integer }
+        sessions: { type: integer }
+        time: { type: string, format: date-time }
+    RuntimeInfo:
+      type: object
+      required: [runtime, available, transport]
+      properties:
+        runtime: { type: string, const: claude-code }
+        available: { type: boolean }
+        executable: { type: [string, "null"] }
+        transport: { type: string }
+    SessionSummary:
+      type: object
+      required: [sessionId, contextId, state]
+      properties:
+        sessionId: { type: string }
+        contextId: { type: string }
+        projectId: { type: string }
+        agentId: { type: string, enum: [claude-code, codex, opencode, zcode] }
+        title: { type: string }
+        active: { type: boolean }
+        state: { type: string }
+        model: { type: [string, "null"] }
+        aiProfileId: { type: [string, "null"] }
+        providerName: { type: [string, "null"] }
+        authSource: { type: string, enum: [profile-injected, agent-owned] }
+        selectedModel: { type: [string, "null"] }
+        archived: { type: boolean }
+        permissionMode: { $ref: "#/components/schemas/PermissionMode" }
+        turns: { type: integer }
+        startedAt: { type: string }
+        updatedAt: { type: string }
+        connectionState: { type: string }
+    AttachmentInput:
+      oneOf:
+        - $ref: "#/components/schemas/ImageAttachmentInput"
+        - $ref: "#/components/schemas/TextAttachmentInput"
+    TextAttachmentInput:
+      type: object
+      required: [name, mediaType, data]
+      properties:
+        id: { type: string }
+        name:
+          type: string
+          pattern: '\.([tT][xX][tT]|[mM][dD]|[jJ][sS][oO][nN]|[cC][sS][vV])$'
+          description: File name with a supported text extension (case-insensitive).
+        mediaType: { type: string, enum: [text/plain, text/markdown, application/json, text/csv] }
+        data:
+          type: string
+          format: byte
+          description: Base64-encoded UTF-8 text, at most 512 KiB decoded. Text is included in the agent prompt inside attachment boundary blocks. Events expose metadata and a URL only.
+        size: { type: integer, minimum: 1, maximum: 524288 }
+    Attachment:
+      type: object
+      required: [id, name, mediaType, size, url]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        mediaType: { type: string, enum: [image/jpeg, image/png, image/gif, image/webp, text/plain, text/markdown, application/json, text/csv] }
+        size: { type: integer }
+        width: { type: integer }
+        height: { type: integer }
+        url: { type: string }
+    ImageAttachmentInput:
+      type: object
+      required: [name, mediaType, data]
+      properties:
+        id: { type: string }
+        name: { type: string, minLength: 1 }
+        mediaType:
+          type: string
+          enum: [image/jpeg, image/png, image/gif, image/webp]
+        data:
+          type: string
+          format: byte
+          description: Base64-encoded image data. Each decoded image is limited to 10 MiB.
+        size: { type: integer, minimum: 1, maximum: 10485760 }
+        width: { type: integer, minimum: 1 }
+        height: { type: integer, minimum: 1 }
+    ImageAttachment:
+      type: object
+      required: [id, name, mediaType, size, url]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        mediaType: { type: string }
+        size: { type: integer }
+        width: { type: integer }
+        height: { type: integer }
+        url: { type: string }
+    SlashCommand:
+      type: object
+      required: [name]
+      properties:
+        name: { type: string }
+        description: { type: string }
+        argumentHint: { type: string }
+        aliases:
+          type: array
+          items: { type: string }
+    ErrorResponse:
+      type: object
+      required: [ok, error]
+      properties:
+        ok: { type: boolean, const: false }
+        error: { type: string }