@vellumai/assistant 0.9.0 → 0.10.0-dev.202606192226.8ed8a6a

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.9.0
+  version: 0.10.0
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -3951,6 +3951,14 @@ paths:
                       type: boolean
                     account:
                       type: string
+                    admissionPolicy:
+                      type: string
+                      enum:
+                        - no_one
+                        - guardian_only
+                        - trusted_contacts
+                        - any_contact
+                        - strangers
                     emailSubject:
                       type: string
                     emailRecipient:
@@ -6144,6 +6152,12 @@ paths:
                   description: Only standard conversations are created by this endpoint
                   type: string
                   const: standard
+                title:
+                  description:
+                    Explicit title for the conversation. When provided on creation, it is persisted as a user-set title (never
+                    overwritten by the auto-titler). Used by flows that mint a conversation up-front and don't want an
+                    auto-generated title.
+                  type: string
       responses:
         "200":
           description: Successful response
@@ -7041,6 +7055,71 @@ paths:
       responses:
         "202":
           description: Successful response
+  /v1/conversations/{id}/slash:
+    post:
+      operationId: conversations_by_id_slash_post
+      summary: Resolve a local meta slash command
+      description:
+        "Run a local meta slash command (/clean, /status, /commands, /models) without starting a turn: no messages
+        are persisted and no turn events are emitted. /clean also strips runtime injections from the history. Returns
+        the text to render and, for /clean, the post-strip context usage."
+      tags:
+        - conversations
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                command:
+                  type: string
+                  description: The slash command text, e.g. `/clean` or `/status`.
+              required:
+                - command
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  kind:
+                    type: string
+                    enum:
+                      - clean
+                      - info
+                  text:
+                    type: string
+                  contextUsage:
+                    type: object
+                    properties:
+                      tokens:
+                        type: number
+                      maxTokens:
+                        anyOf:
+                          - type: number
+                          - type: "null"
+                      fillRatio:
+                        anyOf:
+                          - type: number
+                          - type: "null"
+                    required:
+                      - tokens
+                      - maxTokens
+                      - fillRatio
+                    additionalProperties: false
+                required:
+                  - kind
+                  - text
+                additionalProperties: false
   /v1/conversations/{id}/surface:
     post:
       operationId: conversations_by_id_surface_post
@@ -12043,6 +12122,19 @@ paths:
                           propertyNames:
                             type: string
                           additionalProperties: {}
+                        sourceType:
+                          type: string
+                          enum:
+                            - heartbeat
+                            - memory_consolidation
+                            - schedule
+                            - auto_analysis
+                            - user
+                            - other
+                        sourceKey:
+                          type: string
+                        sourceLabel:
+                          type: string
                         createdAt:
                           type: string
                       required:
@@ -12223,6 +12315,19 @@ paths:
                     propertyNames:
                       type: string
                     additionalProperties: {}
+                  sourceType:
+                    type: string
+                    enum:
+                      - heartbeat
+                      - memory_consolidation
+                      - schedule
+                      - auto_analysis
+                      - user
+                      - other
+                  sourceKey:
+                    type: string
+                  sourceLabel:
+                    type: string
                   createdAt:
                     type: string
                 required:
@@ -12435,6 +12540,19 @@ paths:
                           propertyNames:
                             type: string
                           additionalProperties: {}
+                        sourceType:
+                          type: string
+                          enum:
+                            - heartbeat
+                            - memory_consolidation
+                            - schedule
+                            - auto_analysis
+                            - user
+                            - other
+                        sourceKey:
+                          type: string
+                        sourceLabel:
+                          type: string
                         createdAt:
                           type: string
                       required:
@@ -13030,60 +13148,6 @@ paths:
                   - home
                   - version
                 additionalProperties: false
-  /v1/identity/intro:
-    get:
-      operationId: identity_intro_get
-      summary: Get identity greetings
-      description:
-        Returns greetings sourced from SOUL.md, the generated cache, or generic fallbacks while background
-        generation refreshes the cache.
-      tags:
-        - identity
-      parameters:
-        - name: localHour
-          in: query
-          required: false
-          schema:
-            type: integer
-            minimum: 0
-            maximum: 23
-          description: Optional client-local hour of day used only when refreshing generated greetings.
-        - name: localMinute
-          in: query
-          required: false
-          schema:
-            type: integer
-            minimum: 0
-            maximum: 59
-          description: Optional client-local minute used only when refreshing generated greetings.
-      responses:
-        "200":
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  greetings:
-                    type: array
-                    items:
-                      type: string
-                  text:
-                    type: string
-                  source:
-                    type: string
-                    enum:
-                      - workspace
-                      - cache
-                      - fallback
-                  refreshing:
-                    type: boolean
-                required:
-                  - greetings
-                  - text
-                  - source
-                  - refreshing
-                additionalProperties: false
   /v1/image-generation/generate:
     post:
       operationId: imagegeneration_generate_post
@@ -13230,7 +13294,7 @@ paths:
             type: string
           description:
             "Filter by provider. One of: anthropic, openai, gemini, ollama, fireworks, openrouter, openai-compatible,
-            minimax"
+            minimax, atlascloud"
       responses:
         "200":
           description: Successful response
@@ -13781,6 +13845,11 @@ paths:
                     type: string
                   botUsername:
                     type: string
+                  threadMode:
+                    type: string
+                    enum:
+                      - mention_only
+                      - mention_then_thread
                   error:
                     type: string
                   warning:
@@ -13791,6 +13860,7 @@ paths:
                   - hasAppToken
                   - hasUserToken
                   - connected
+                  - threadMode
                 additionalProperties: false
     get:
       operationId: integrations_slack_channel_config_get
@@ -13826,6 +13896,75 @@ paths:
                     type: string
                   botUsername:
                     type: string
+                  threadMode:
+                    type: string
+                    enum:
+                      - mention_only
+                      - mention_then_thread
+                  error:
+                    type: string
+                  warning:
+                    type: string
+                required:
+                  - success
+                  - hasBotToken
+                  - hasAppToken
+                  - hasUserToken
+                  - connected
+                  - threadMode
+                additionalProperties: false
+    patch:
+      operationId: integrations_slack_channel_config_patch
+      summary: Update Slack channel settings
+      description: Update Slack channel behavior settings (e.g. thread mode).
+      tags:
+        - integrations
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                threadMode:
+                  type: string
+                  enum:
+                    - mention_only
+                    - mention_then_thread
+                  description: Controls whether the bot follows threads after an initial @mention
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  hasBotToken:
+                    type: boolean
+                  hasAppToken:
+                    type: boolean
+                  hasUserToken:
+                    type: boolean
+                  connected:
+                    type: boolean
+                  teamId:
+                    type: string
+                  teamName:
+                    type: string
+                  teamUrl:
+                    type: string
+                  botUserId:
+                    type: string
+                  botUsername:
+                    type: string
+                  threadMode:
+                    type: string
+                    enum:
+                      - mention_only
+                      - mention_then_thread
                   error:
                     type: string
                   warning:
@@ -13836,6 +13975,7 @@ paths:
                   - hasAppToken
                   - hasUserToken
                   - connected
+                  - threadMode
                 additionalProperties: false
     post:
       operationId: integrations_slack_channel_config_post
@@ -13887,6 +14027,11 @@ paths:
                     type: string
                   botUsername:
                     type: string
+                  threadMode:
+                    type: string
+                    enum:
+                      - mention_only
+                      - mention_then_thread
                   error:
                     type: string
                   warning:
@@ -13897,6 +14042,7 @@ paths:
                   - hasAppToken
                   - hasUserToken
                   - connected
+                  - threadMode
                 additionalProperties: false
   /v1/integrations/telegram/commands:
     post:
@@ -14511,6 +14657,54 @@ paths:
       responses:
         "200":
           description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  servers:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        status:
+                          type: string
+                        transport:
+                          type: object
+                          properties:
+                            type:
+                              type: string
+                              enum:
+                                - stdio
+                                - sse
+                                - streamable-http
+                          required:
+                            - type
+                          additionalProperties: {}
+                        enabled:
+                          type: boolean
+                        defaultRiskLevel:
+                          type: string
+                        allowedTools:
+                          type: array
+                          items:
+                            type: string
+                        blockedTools:
+                          type: array
+                          items:
+                            type: string
+                      required:
+                        - id
+                        - status
+                        - transport
+                        - enabled
+                        - defaultRiskLevel
+                      additionalProperties: false
+                required:
+                  - servers
+                additionalProperties: false
   /v1/internal/mcp/reload:
     post:
       operationId: internal_mcp_reload_post
@@ -14542,38 +14736,136 @@ paths:
       responses:
         "200":
           description: Successful response
-  /v1/internal/oauth/callback:
-    post:
-      operationId: internal_oauth_callback_post
-      summary: Internal OAuth callback
+  /v1/internal/mcp/tools-summary:
+    get:
+      operationId: internal_mcp_toolssummary_get
+      summary: Per-server MCP tool counts and token estimates
       description:
-        Receives forwarded OAuth callback results (code or error) from the gateway and resolves the pending
-        callback in the runtime.
+        Returns registered tool counts, individual tool details, and estimated token overhead for each connected
+        MCP server.
       tags:
         - internal
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                state:
-                  type: string
-                code:
-                  type: string
-                error:
-                  type: string
-              required:
-                - state
       responses:
         "200":
           description: Successful response
-  /v1/internal/oauth/connect/start:
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  servers:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        serverId:
+                          type: string
+                        toolCount:
+                          type: number
+                        estimatedTokens:
+                          type: number
+                        tools:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              name:
+                                type: string
+                              description:
+                                type: string
+                              estimatedTokens:
+                                type: number
+                            required:
+                              - name
+                              - description
+                              - estimatedTokens
+                            additionalProperties: false
+                      required:
+                        - serverId
+                        - toolCount
+                        - estimatedTokens
+                        - tools
+                      additionalProperties: false
+                  totalToolCount:
+                    type: number
+                  totalEstimatedTokens:
+                    type: number
+                required:
+                  - servers
+                  - totalToolCount
+                  - totalEstimatedTokens
+                additionalProperties: false
+  /v1/internal/mcp/update:
     post:
-      operationId: internal_oauth_connect_start_post
-      summary: Start daemon-owned OAuth connect flow
-      description: Starts an OAuth connect flow in the daemon and returns the authorization URL for the CLI to open in the browser.
+      operationId: internal_mcp_update_post
+      summary: Update an MCP server configuration
+      description: Updates fields on an existing MCP server config entry and triggers a reload.
+      tags:
+        - internal
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                enabled:
+                  type: boolean
+                defaultRiskLevel:
+                  type: string
+                maxTools:
+                  type: number
+                allowedTools:
+                  anyOf:
+                    - type: array
+                      items:
+                        type: string
+                    - type: "null"
+                blockedTools:
+                  anyOf:
+                    - type: array
+                      items:
+                        type: string
+                    - type: "null"
+              required:
+                - name
+      responses:
+        "200":
+          description: Successful response
+  /v1/internal/oauth/callback:
+    post:
+      operationId: internal_oauth_callback_post
+      summary: Internal OAuth callback
+      description:
+        Receives forwarded OAuth callback results (code or error) from the gateway and resolves the pending
+        callback in the runtime.
+      tags:
+        - internal
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                state:
+                  type: string
+                code:
+                  type: string
+                error:
+                  type: string
+              required:
+                - state
+      responses:
+        "200":
+          description: Successful response
+  /v1/internal/oauth/connect/start:
+    post:
+      operationId: internal_oauth_connect_start_post
+      summary: Start daemon-owned OAuth connect flow
+      description: Starts an OAuth connect flow in the daemon and returns the authorization URL for the CLI to open in the browser.
       tags:
         - internal
       requestBody:
@@ -15191,6 +15483,81 @@ paths:
                 additionalProperties: false
         "409":
           description: Another memory item with this content already exists
+  /v1/memory/eval/run:
+    post:
+      operationId: memory_eval_run_post
+      summary: Build blinded A/B retrieval-eval packets over two concept corpora (snapshot vs staged wiki)
+      tags:
+        - memory
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                stagingDir:
+                  type: string
+                  minLength: 1
+                snapshotDir:
+                  type: string
+                  minLength: 1
+                outDir:
+                  type: string
+                  minLength: 1
+                turns:
+                  type: integer
+                  exclusiveMinimum: 0
+                  maximum: 9007199254740991
+                perConversationCap:
+                  type: integer
+                  exclusiveMinimum: 0
+                  maximum: 9007199254740991
+                k:
+                  type: integer
+                  exclusiveMinimum: 0
+                  maximum: 9007199254740991
+                dense:
+                  type: boolean
+                seed:
+                  type: integer
+                  minimum: -9007199254740991
+                  maximum: 9007199254740991
+              required:
+                - stagingDir
+                - snapshotDir
+                - outDir
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  turnsMined:
+                    type: number
+                  packetsWritten:
+                    type: number
+                  packetsPath:
+                    type: string
+                  keyPath:
+                    type: string
+                  snapshotPages:
+                    type: number
+                  stagingPages:
+                    type: number
+                  dense:
+                    type: boolean
+                required:
+                  - turnsMined
+                  - packetsWritten
+                  - packetsPath
+                  - keyPath
+                  - snapshotPages
+                  - stagingPages
+                  - dense
+                additionalProperties: false
   /v1/memory/v2/backfill:
     post:
       operationId: memory_v2_backfill_post
@@ -15872,6 +16239,7 @@ paths:
                                           - brave
                                           - perplexity
                                           - tavily
+                                          - firecrawl
                                       resultCount:
                                         type: number
                                       durationMs:
@@ -15919,6 +16287,11 @@ paths:
                                         type: string
                                       finalUrl:
                                         type: string
+                                      provider:
+                                        type: string
+                                        enum:
+                                          - default
+                                          - firecrawl
                                       status:
                                         type: number
                                       contentType:
@@ -16035,6 +16408,48 @@ paths:
                                 required:
                                   - requestId
                                 additionalProperties: false
+                              pendingQuestion:
+                                type: object
+                                properties:
+                                  requestId:
+                                    type: string
+                                  entries:
+                                    type: array
+                                    items:
+                                      type: object
+                                      properties:
+                                        id:
+                                          type: string
+                                        question:
+                                          type: string
+                                        description:
+                                          type: string
+                                        options:
+                                          type: array
+                                          items:
+                                            type: object
+                                            properties:
+                                              id:
+                                                type: string
+                                              label:
+                                                type: string
+                                              description:
+                                                type: string
+                                            required:
+                                              - id
+                                              - label
+                                            additionalProperties: false
+                                        freeTextPlaceholder:
+                                          type: string
+                                      required:
+                                        - id
+                                        - question
+                                        - options
+                                      additionalProperties: false
+                                required:
+                                  - requestId
+                                  - entries
+                                additionalProperties: false
                             required:
                               - name
                               - input
@@ -16254,6 +16669,7 @@ paths:
                                                   - brave
                                                   - perplexity
                                                   - tavily
+                                                  - firecrawl
                                               resultCount:
                                                 type: number
                                               durationMs:
@@ -16301,6 +16717,11 @@ paths:
                                                 type: string
                                               finalUrl:
                                                 type: string
+                                              provider:
+                                                type: string
+                                                enum:
+                                                  - default
+                                                  - firecrawl
                                               status:
                                                 type: number
                                               contentType:
@@ -16417,6 +16838,48 @@ paths:
                                         required:
                                           - requestId
                                         additionalProperties: false
+                                      pendingQuestion:
+                                        type: object
+                                        properties:
+                                          requestId:
+                                            type: string
+                                          entries:
+                                            type: array
+                                            items:
+                                              type: object
+                                              properties:
+                                                id:
+                                                  type: string
+                                                question:
+                                                  type: string
+                                                description:
+                                                  type: string
+                                                options:
+                                                  type: array
+                                                  items:
+                                                    type: object
+                                                    properties:
+                                                      id:
+                                                        type: string
+                                                      label:
+                                                        type: string
+                                                      description:
+                                                        type: string
+                                                    required:
+                                                      - id
+                                                      - label
+                                                    additionalProperties: false
+                                                freeTextPlaceholder:
+                                                  type: string
+                                              required:
+                                                - id
+                                                - question
+                                                - options
+                                              additionalProperties: false
+                                        required:
+                                          - requestId
+                                          - entries
+                                        additionalProperties: false
                                     required:
                                       - name
                                       - input
@@ -16721,6 +17184,12 @@ paths:
                       type: array
                       items:
                         type: string
+                    title:
+                      description:
+                        Explicit title for the conversation minted on this first message. Persisted as a user-set title (never
+                        overwritten by the auto-titler). Used by onboarding flows that mint a conversation behind the
+                        scenes.
+                      type: string
                   required:
                     - tools
                     - tasks
@@ -17681,6 +18150,7 @@ paths:
               properties:
                 deliveryId:
                   type: string
+                  minLength: 1
                   description: Notification delivery ID
                 success:
                   type: boolean
@@ -17758,9 +18228,113 @@ paths:
                     type: boolean
                   feedItem:
                     type: object
-                    propertyNames:
-                      type: string
-                    additionalProperties: {}
+                    properties:
+                      id:
+                        type: string
+                      type:
+                        type: string
+                        const: notification
+                      priority:
+                        type: integer
+                        minimum: 0
+                        maximum: 100
+                      title:
+                        type: string
+                      summary:
+                        type: string
+                      timestamp:
+                        type: string
+                      status:
+                        default: new
+                        type: string
+                        enum:
+                          - new
+                          - seen
+                          - acted_on
+                          - dismissed
+                      expiresAt:
+                        type: string
+                      actions:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            id:
+                              type: string
+                            label:
+                              type: string
+                            prompt:
+                              type: string
+                          required:
+                            - id
+                            - label
+                            - prompt
+                          additionalProperties: false
+                      urgency:
+                        type: string
+                        enum:
+                          - low
+                          - medium
+                          - high
+                          - critical
+                      conversationId:
+                        type: string
+                      detailPanel:
+                        type: object
+                        properties:
+                          kind:
+                            type: string
+                            enum:
+                              - emailDraft
+                              - documentPreview
+                              - permissionChat
+                              - paymentAuth
+                              - toolPermission
+                              - updatesList
+                        required:
+                          - kind
+                        additionalProperties: false
+                      category:
+                        type: string
+                        enum:
+                          - security
+                          - scheduling
+                          - background
+                          - email
+                          - system
+                      noteworthy:
+                        type: boolean
+                      fromAssistant:
+                        type: boolean
+                      metadata:
+                        type: object
+                        propertyNames:
+                          type: string
+                        additionalProperties: {}
+                      sourceType:
+                        type: string
+                        enum:
+                          - heartbeat
+                          - memory_consolidation
+                          - schedule
+                          - auto_analysis
+                          - user
+                          - other
+                      sourceKey:
+                        type: string
+                      sourceLabel:
+                        type: string
+                      createdAt:
+                        type: string
+                    required:
+                      - id
+                      - type
+                      - priority
+                      - summary
+                      - timestamp
+                      - status
+                      - createdAt
+                    additionalProperties: false
                   channels:
                     type: array
                     items:
@@ -17815,7 +18389,11 @@ paths:
                     - vellum
                     - phone
                     - telegram
+                    - whatsapp
                     - slack
+                    - email
+                    - platform
+                    - a2a
                     - scheduler
                     - watcher
                 sourceContextId:
@@ -18737,9 +19315,37 @@ paths:
                     additionalProperties: {}
                     description: Pending confirmation details or null
                   pendingSecret:
-                    type: object
-                    properties: {}
-                    additionalProperties: {}
+                    anyOf:
+                      - type: object
+                        properties:
+                          requestId:
+                            type: string
+                          service:
+                            type: string
+                          field:
+                            type: string
+                          label:
+                            type: string
+                          description:
+                            type: string
+                          placeholder:
+                            type: string
+                          purpose:
+                            type: string
+                          allowedTools:
+                            type: array
+                            items:
+                              type: string
+                          allowedDomains:
+                            type: array
+                            items:
+                              type: string
+                          allowOneTimeSend:
+                            type: boolean
+                        required:
+                          - requestId
+                        additionalProperties: {}
+                      - type: "null"
                     description: Pending secret request or null
                   interactions:
                     type: array
@@ -19210,41 +19816,144 @@ paths:
                     description: Git ref the catalog metadata / README were resolved at.
                   artifact:
                     anyOf:
-                      - type: object
-                        properties:
-                          url:
-                            type: string
-                            description: HTTPS URL the prebuilt client artifact is downloaded from.
-                          sha256:
-                            type: string
-                            description: Lowercase 64-char hex SHA-256 the download is verified against.
-                          label:
-                            description: Optional human label for the download (e.g. "Download for macOS"); absent when the plugin doesn't name it.
-                            type: string
-                        required:
-                          - url
-                          - sha256
-                        additionalProperties: false
+                      - type: object
+                        properties:
+                          url:
+                            type: string
+                            description: HTTPS URL the prebuilt client artifact is downloaded from.
+                          sha256:
+                            type: string
+                            description: Lowercase 64-char hex SHA-256 the download is verified against.
+                          label:
+                            description: Optional human label for the download (e.g. "Download for macOS"); absent when the plugin doesn't name it.
+                            type: string
+                        required:
+                          - url
+                          - sha256
+                        additionalProperties: false
+                      - type: "null"
+                    description:
+                      Prebuilt client artifact from `package.json` `vellum.artifact`, or null when the plugin ships none or its
+                      descriptor is incomplete (e.g. a placeholder sha256).
+                required:
+                  - name
+                  - installed
+                  - description
+                  - homepage
+                  - license
+                  - version
+                  - source
+                  - readme
+                  - ref
+                  - artifact
+                additionalProperties: false
+        "400":
+          description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
+        "404":
+          description: No installed copy and no catalog entry claims the given name.
+  /v1/plugins/{name}/diff:
+    post:
+      operationId: plugins_by_name_diff_post
+      summary: Diff a plugin against its install commit
+      description:
+        "Show a unified diff of local edits to an installed plugin against the exact commit it was installed at
+        (recorded in its `install-meta.json`). Computing the diff re-materializes the baseline through the install
+        pipeline — a network clone plus a temp-dir write — so this is a POST: it is not a safe, cacheable GET even
+        though it leaves persistent state untouched (requires only `settings.read`). Drift is classified against the
+        install-time fingerprint so an adapter overlay that moved since install never reads as a local change. Returns
+        the baseline `commit`, a `clean` flag, and a `files` array of `{ path, status, diff, binary, reconstructed }`
+        for each modified/added/removed file. The baseline is the install commit, not the marketplace pin — comparing
+        against the current pin is `POST /v1/plugins/:name/upgrade` with `dryRun`. A name with no installed copy returns
+        404; an install that recorded no commit or fingerprint returns 409; an unreachable source returns 503. Mirrors
+        the CLI's `assistant plugins diff <name>`."
+      tags:
+        - plugins
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  name:
+                    type: string
+                    description: Install name. Matches `assistant plugins install <name>`.
+                  target:
+                    type: string
+                    description: Absolute path to the installed plugin directory on the host.
+                  commit:
+                    type: string
+                    description: Commit the baseline was re-materialized from (the recorded install SHA).
+                  committedAt:
+                    anyOf:
+                      - type: string
                       - type: "null"
-                    description:
-                      Prebuilt client artifact from `package.json` `vellum.artifact`, or null when the plugin ships none or its
-                      descriptor is incomplete (e.g. a placeholder sha256).
+                    description: ISO-8601 committer timestamp (UTC) of `commit`; null when not recorded.
+                  clean:
+                    type: boolean
+                    description: True when the on-disk tree exactly matches the re-materialized baseline.
+                  files:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        path:
+                          type: string
+                          description: POSIX-relative path within the plugin root.
+                        status:
+                          type: string
+                          enum:
+                            - modified
+                            - added
+                            - removed
+                          description: Whether the file was edited, newly added, or deleted since install.
+                        diff:
+                          type: string
+                          description:
+                            Unified diff (`--- a/… / +++ b/…`) of the file. A short `Binary files differ` marker for binary files, or a
+                            `Baseline unavailable` marker when `reconstructed` is false.
+                        binary:
+                          type: boolean
+                          description: True when either side was detected as binary (NUL byte present).
+                        reconstructed:
+                          type: boolean
+                          description:
+                            True when the install-time baseline for this file was faithfully recovered (re-materialized bytes
+                            hash-match the install fingerprint). False when it could not be reconstructed (e.g. the
+                            curated adapter overlay changed since install), in which case `diff` is a marker, not a
+                            patch. Always true for added files.
+                      required:
+                        - path
+                        - status
+                        - diff
+                        - binary
+                        - reconstructed
+                      additionalProperties: false
+                      description: Unified diff of a single drifted file.
+                    description: One entry per drifted file, sorted by path. Empty when `clean`.
                 required:
                   - name
-                  - installed
-                  - description
-                  - homepage
-                  - license
-                  - version
-                  - source
-                  - readme
-                  - ref
-                  - artifact
+                  - target
+                  - commit
+                  - committedAt
+                  - clean
+                  - files
                 additionalProperties: false
         "400":
           description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
         "404":
-          description: No installed copy and no catalog entry claims the given name.
+          description: No copy of the plugin is installed, or its recorded commit resolves to nothing.
+        "409":
+          description: The install recorded no commit or no fingerprint to re-materialize and verify a baseline from.
+        "503":
+          description: The plugin source (GitHub) was temporarily unavailable; the diff is retryable.
   /v1/plugins/{name}/inspect:
     get:
       operationId: plugins_by_name_inspect_get
@@ -19459,6 +20168,35 @@ paths:
                       - type: string
                       - type: "null"
                     description: Marketplace fetch error message, when the catalog could not be read.
+                  surfaces:
+                    anyOf:
+                      - type: object
+                        properties:
+                          skills:
+                            type: array
+                            items:
+                              type: string
+                            description: Skill ids shipped at `skills/<id>/SKILL.md`.
+                          hooks:
+                            type: array
+                            items:
+                              type: string
+                            description: Lifecycle hook names from `hooks/<name>.{ts,js}` (e.g. `pre-model-call`).
+                          tools:
+                            type: array
+                            items:
+                              type: string
+                            description:
+                              Registered tool names from `tools/<name>.{ts,js}` (filenames derived to tool names, e.g. `create-issue` →
+                              `create_issue`).
+                        required:
+                          - skills
+                          - hooks
+                          - tools
+                        additionalProperties: false
+                        description: Surfaces the installed copy contributes, read from its on-disk tree.
+                      - type: "null"
+                    description: Surfaces the installed copy contributes (skills, hooks, tools); null when the plugin is not installed.
                 required:
                   - name
                   - installed
@@ -19466,6 +20204,7 @@ paths:
                   - local
                   - remote
                   - remoteError
+                  - surfaces
                 additionalProperties: false
         "400":
           description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
@@ -19481,9 +20220,13 @@ paths:
         mirroring `plugins install`''s curation boundary. A no-op (`outcome: "already-up-to-date"`) when the installed
         commit already equals the pin; pass `dryRun` to preview the move (`outcome: "would-upgrade"`) without touching
         the install. Installs lacking provenance are re-pinned to the current SHA. The assistant must be restarted to
-        load the upgraded code. This does not gate on local edits — callers should consult `GET
-        /v1/plugins/:name/inspect` (`local.localChanges`) first and confirm before overwriting. Mirrors the CLI''s
-        `assistant plugins upgrade <name>`.'
+        load the upgraded code. `strategy` controls how local edits are reconciled: `overwrite` (default) discards them
+        and re-installs the pin wholesale; `ours`/`theirs`/`assistant` perform a three-way merge against the
+        re-materialized install commit, carrying non-conflicting edits from both sides forward and resolving conflicting
+        hunks toward the local edit (`ours`) or the pin (`theirs`), or writing git conflict markers into the file and
+        reporting them in `conflicts`/`binaryConflicts` for the assistant to resolve (`assistant`). A merge strategy
+        whose install-time baseline cannot be reconstructed returns 409. Mirrors the CLI''s `assistant plugins upgrade
+        <name> [--strategy <s>]`.'
       tags:
         - plugins
       parameters:
@@ -19502,6 +20245,17 @@ paths:
                 dryRun:
                   description: Report what would change without modifying the install. Defaults to false.
                   type: boolean
+                strategy:
+                  description:
+                    How to reconcile local edits with the pin. `overwrite` (default) discards local edits and re-installs the
+                    pin; `ours`/`theirs` three-way merge, resolving conflicting hunks toward the local edit or the pin
+                    respectively; `assistant` is not yet supported.
+                  type: string
+                  enum:
+                    - ours
+                    - theirs
+                    - overwrite
+                    - assistant
       responses:
         "200":
           description: Successful response
@@ -19553,6 +20307,28 @@ paths:
                   dryRun:
                     type: boolean
                     description: Whether this was a dry run (no changes made).
+                  strategy:
+                    type: string
+                    enum:
+                      - ours
+                      - theirs
+                      - overwrite
+                      - assistant
+                    description: Conflict-resolution strategy the upgrade applied.
+                  conflicts:
+                    type: array
+                    items:
+                      type: string
+                    description:
+                      "Paths left for the assistant to resolve under the `assistant` strategy: text files carry git conflict
+                      markers, modify/delete divergences keep the surviving content. Empty for other strategies."
+                  binaryConflicts:
+                    type: array
+                    items:
+                      type: string
+                    description:
+                      Binary files that conflicted under the `assistant` strategy; the local copy was kept since markers cannot
+                      be written into binary content. Empty for other strategies.
                   provenanceWasUnknown:
                     type: boolean
                     description:
@@ -19568,6 +20344,9 @@ paths:
                   - target
                   - fileCount
                   - dryRun
+                  - strategy
+                  - conflicts
+                  - binaryConflicts
                   - provenanceWasUnknown
                 additionalProperties: false
         "400":
@@ -19575,9 +20354,72 @@ paths:
         "404":
           description: No copy of the plugin is installed, or its source resolves to nothing.
         "409":
-          description: The install exists but has no marketplace entry to advance to.
+          description:
+            The install exists but has no marketplace entry to advance to, or a merge strategy was requested whose
+            install-time baseline cannot be reconstructed.
         "503":
           description: The plugin source (GitHub) was temporarily unavailable; the upgrade is retryable.
+  /v1/plugins/{name}/versions:
+    get:
+      operationId: plugins_by_name_versions_get
+      summary: List a plugin's reviewed marketplace pins
+      description:
+        Report the distinct marketplace pins a plugin has been promoted to over time, newest first (the first entry
+        is the current pin), capped at `limit` (default 5). The curated `marketplace.json` stores only the current pin,
+        so this is reconstructed from the manifest's own commit history on the default branch — every entry is therefore
+        a reviewed, known-good revision. Pair with `POST /v1/plugins/install`'s `pin` field to roll a plugin back to an
+        older reviewed version. An unknown name (never in the manifest) returns an empty array, not 404.
+      tags:
+        - plugins
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Maximum number of pins to return (positive integer; default 5).
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    pin:
+                      type: string
+                      description: Plugin commit SHA pinned at this point in marketplace history.
+                    marketplaceCommit:
+                      type: string
+                      description: Marketplace-manifest commit to install this pin from (the newest commit carrying it).
+                    promotedAt:
+                      anyOf:
+                        - type: string
+                        - type: "null"
+                      description: ISO-8601 committer date (UTC) of the marketplace commit that promoted this pin; null when unreadable.
+                    current:
+                      type: boolean
+                      description: True for the pin currently active on the default branch.
+                  required:
+                    - pin
+                    - marketplaceCommit
+                    - promotedAt
+                    - current
+                  additionalProperties: false
+                description:
+                  Distinct marketplace pins a plugin has been promoted to, newest first; the first entry is the current pin.
+                  Empty when the plugin has no resolvable history.
+        "400":
+          description: The plugin name failed sanitization, or `limit` was not a positive integer.
+        "503":
+          description: The marketplace pin history could not be read from GitHub (rate-limited or upstream error); retryable.
   /v1/plugins/install:
     post:
       operationId: plugins_install_post
@@ -19604,6 +20446,13 @@ paths:
                 force:
                   description: Overwrite an existing install in place. Defaults to false.
                   type: boolean
+                pin:
+                  description:
+                    Install a specific reviewed marketplace pin (full commit SHA) instead of the current one. The pin is
+                    validated against the plugin's marketplace pin history (`GET /v1/plugins/:name/versions`) and
+                    installed from the marketplace revision that introduced it; an unreviewed SHA is rejected. Use this
+                    to roll a plugin back to an older reviewed version.
+                  type: string
               required:
                 - name
       responses:
@@ -27356,6 +28205,88 @@ paths:
                 additionalProperties: false
         "404":
           description: Run not found
+  /v1/workflows/runs/{id}/journal:
+    get:
+      operationId: workflows_runs_by_id_journal_get
+      summary: Get workflow run journal
+      description: Return a workflow run's leaf journal as bounded per-leaf summaries (one entry per finished leaf).
+      tags:
+        - workflows
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  runId:
+                    type: string
+                  status:
+                    type: string
+                    enum:
+                      - running
+                      - completed
+                      - failed
+                      - aborted
+                      - cap_exceeded
+                      - interrupted
+                  agentsSpawned:
+                    type: number
+                  inputTokens:
+                    type: number
+                  outputTokens:
+                    type: number
+                  phase:
+                    type: string
+                  leaves:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        seq:
+                          type: number
+                        kind:
+                          type: string
+                          enum:
+                            - agent
+                            - workflow
+                        label:
+                          type: string
+                        phase:
+                          type: string
+                        promptSummary:
+                          type: string
+                        status:
+                          type: string
+                        resultSummary:
+                          type: string
+                        inputTokens:
+                          type: number
+                        outputTokens:
+                          type: number
+                        createdAt:
+                          anyOf:
+                            - type: number
+                            - type: "null"
+                      required:
+                        - seq
+                        - kind
+                        - status
+                        - createdAt
+                      additionalProperties: false
+                required:
+                  - runId
+                  - leaves
+                additionalProperties: false
+        "404":
+          description: Run not found
   /v1/workflows/runs/{id}/resume:
     post:
       operationId: workflows_runs_by_id_resume_post
@@ -27888,6 +28819,14 @@ components:
                               maximum: 2
                             - type: "null"
                         - type: "null"
+                    topP:
+                      anyOf:
+                        - anyOf:
+                            - type: number
+                              minimum: 0
+                              maximum: 1
+                            - type: "null"
+                        - type: "null"
                     thinking:
                       anyOf:
                         - type: object
@@ -27994,6 +28933,10 @@ components:
               anyOf:
                 - type: string
                 - type: "null"
+            advisorProfile:
+              anyOf:
+                - type: string
+                - type: "null"
             callSites:
               type: object
               propertyNames:
@@ -28029,6 +28972,16 @@ components:
                       type: string
                   additionalProperties: {}
                 - type: "null"
+            web-fetch:
+              anyOf:
+                - type: object
+                  properties:
+                    mode:
+                      $ref: "#/components/schemas/ServiceMode"
+                    provider:
+                      type: string
+                  additionalProperties: {}
+                - type: "null"
             image-generation:
               anyOf:
                 - type: object
@@ -28058,6 +29011,7 @@ components:
         - openrouter
         - openai-compatible
         - minimax
+        - atlascloud
     ProfilePatchEntry:
       type: object
       properties:
@@ -28110,6 +29064,14 @@ components:
                   maximum: 2
                 - type: "null"
             - type: "null"
+        topP:
+          anyOf:
+            - anyOf:
+                - type: number
+                  minimum: 0
+                  maximum: 1
+                - type: "null"
+            - type: "null"
         thinking:
           anyOf:
             - type: object
@@ -28223,6 +29185,12 @@ components:
                 - $ref: "#/components/schemas/ProfileStatus"
                 - type: "null"
             - type: "null"
+        advisorEnabled:
+          anyOf:
+            - anyOf:
+                - type: boolean
+                - type: "null"
+            - type: "null"
         mix:
           anyOf:
             - minItems: 2
@@ -28298,6 +29266,14 @@ components:
                   maximum: 2
                 - type: "null"
             - type: "null"
+        topP:
+          anyOf:
+            - anyOf:
+                - type: number
+                  minimum: 0
+                  maximum: 1
+                - type: "null"
+            - type: "null"
         thinking:
           anyOf:
             - type: object
@@ -28415,6 +29391,7 @@ components:
         - openrouter
         - openai-compatible
         - minimax
+        - atlascloud
     Auth:
       oneOf:
         - type: object
@@ -28520,6 +29497,12 @@ components:
                       minimum: 0
                       maximum: 2
                     - type: "null"
+                topP:
+                  anyOf:
+                    - type: number
+                      minimum: 0
+                      maximum: 1
+                    - type: "null"
                 thinking:
                   type: object
                   properties:
@@ -28613,6 +29596,8 @@ components:
                 type: string
             activeProfile:
               type: string
+            advisorProfile:
+              type: string
             callSites:
               type: object
               propertyNames:
@@ -28656,6 +29641,12 @@ components:
                             minimum: 0
                             maximum: 2
                           - type: "null"
+                      topP:
+                        anyOf:
+                          - type: number
+                            minimum: 0
+                            maximum: 1
+                          - type: "null"
                       thinking:
                         type: object
                         properties:
@@ -28763,6 +29754,14 @@ components:
                 provider:
                   type: string
               additionalProperties: {}
+            web-fetch:
+              type: object
+              properties:
+                mode:
+                  $ref: "#/components/schemas/ServiceMode"
+                provider:
+                  type: string
+              additionalProperties: {}
             image-generation:
               type: object
               properties:
@@ -28815,6 +29814,12 @@ components:
               minimum: 0
               maximum: 2
             - type: "null"
+        topP:
+          anyOf:
+            - type: number
+              minimum: 0
+              maximum: 1
+            - type: "null"
         thinking:
           type: object
           properties:
@@ -28912,6 +29917,10 @@ components:
           anyOf:
             - $ref: "#/components/schemas/ProfileStatus"
             - type: "null"
+        advisorEnabled:
+          anyOf:
+            - type: boolean
+            - type: "null"
         mix:
           minItems: 2
           type: array