@vellumai/assistant 0.8.10 → 0.8.11-staging.1

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.8.10
+  version: 0.8.11
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -96,8 +96,11 @@ paths:
       operationId: acp_by_id_steer_post
       summary: Steer ACP session
       description:
-        Send a steering instruction to an ACP session. Sessions no longer in memory (completed, or lost to a daemon
-        restart) are transparently resumed from persisted history first, when the agent supports ACP session loading.
+        "Send a steering instruction to an ACP session. Sessions no longer in memory (completed, or lost to a
+        daemon restart) are transparently resumed from persisted history first, when the agent supports ACP session
+        loading. Resuming a terminal session re-spawns the host agent, so it requires guardian approval: the route acks
+        immediately with approvalPending=true and performs the resume in the background once approved, streaming results
+        over SSE."
       tags:
         - acp
       responses:
@@ -115,6 +118,11 @@ paths:
                   resumed:
                     description: True when the session was resumed from persisted history before steering.
                     type: boolean
+                  approvalPending:
+                    description:
+                      True when the steer triggered a guardian-approval-gated resume that will run asynchronously; watch SSE for
+                      the outcome.
+                    type: boolean
                 required:
                   - acpSessionId
                   - steered
@@ -4531,55 +4539,6 @@ paths:
                   - lastRunAt
                   - success
                 additionalProperties: false
-    put:
-      operationId: consolidation_config_put
-      summary: Update consolidation config
-      description: Update the memory v2 consolidation schedule configuration.
-      tags:
-        - consolidation
-      responses:
-        "200":
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  available:
-                    type: boolean
-                  enabled:
-                    type: boolean
-                  intervalMs:
-                    type: number
-                  nextRunAt:
-                    anyOf:
-                      - type: number
-                      - type: "null"
-                  lastRunAt:
-                    anyOf:
-                      - type: number
-                      - type: "null"
-                  success:
-                    type: boolean
-                required:
-                  - available
-                  - enabled
-                  - intervalMs
-                  - nextRunAt
-                  - lastRunAt
-                  - success
-                additionalProperties: false
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                enabled:
-                  description: Enable or disable automatic consolidation
-                  type: boolean
-              additionalProperties: false
   /v1/consolidation/run-now:
     post:
       operationId: consolidation_runnow_post
@@ -6012,6 +5971,8 @@ paths:
                           additionalProperties: false
                         archivedAt:
                           type: number
+                        surfacedAt:
+                          type: number
                         inferenceProfile:
                           type: string
                         isProcessing:
@@ -6373,6 +6334,8 @@ paths:
                         additionalProperties: false
                       archivedAt:
                         type: number
+                      surfacedAt:
+                        type: number
                       inferenceProfile:
                         type: string
                       isProcessing:
@@ -6571,6 +6534,8 @@ paths:
                         additionalProperties: false
                       archivedAt:
                         type: number
+                      surfacedAt:
+                        type: number
                       inferenceProfile:
                         type: string
                       isProcessing:
@@ -6979,6 +6944,56 @@ paths:
           required: true
           schema:
             type: string
+  /v1/conversations/{id}/surface:
+    post:
+      operationId: conversations_by_id_surface_post
+      summary: Surface a conversation into Recents
+      description:
+        Explicitly promote a background or scheduled conversation into the default conversation listing (the
+        Recents sidebar grouping), or demote it with surfaced=false. Conversations are never surfaced automatically.
+      tags:
+        - conversations
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  conversationId:
+                    type: string
+                  surfacedAt:
+                    anyOf:
+                      - type: number
+                      - type: "null"
+                    description: Epoch-ms timestamp of the promotion, or null when cleared.
+                required:
+                  - ok
+                  - conversationId
+                  - surfacedAt
+                additionalProperties: false
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                surfaced:
+                  type: boolean
+                  description: true to surface the conversation into Recents, false to clear the promotion.
+              required:
+                - surfaced
+              additionalProperties: false
   /v1/conversations/{id}/unarchive:
     post:
       operationId: conversations_by_id_unarchive_post
@@ -7534,6 +7549,8 @@ paths:
                         additionalProperties: false
                       archivedAt:
                         type: number
+                      surfacedAt:
+                        type: number
                       inferenceProfile:
                         type: string
                       isProcessing:
@@ -11174,6 +11191,14 @@ paths:
                     required:
                       - connected
                     additionalProperties: false
+                  capabilities:
+                    type: object
+                    properties:
+                      memoryOptOut:
+                        type: boolean
+                    required:
+                      - memoryOptOut
+                    additionalProperties: false
                   profiler:
                     type: object
                     properties:
@@ -11258,6 +11283,7 @@ paths:
                   - cpu
                   - migrations
                   - ces
+                  - capabilities
                 additionalProperties: false
   /v1/healthz:
     get:
@@ -11342,6 +11368,14 @@ paths:
                     required:
                       - connected
                     additionalProperties: false
+                  capabilities:
+                    type: object
+                    properties:
+                      memoryOptOut:
+                        type: boolean
+                    required:
+                      - memoryOptOut
+                    additionalProperties: false
                   profiler:
                     type: object
                     properties:
@@ -11426,6 +11460,7 @@ paths:
                   - cpu
                   - migrations
                   - ces
+                  - capabilities
                 additionalProperties: false
   /v1/heartbeat/checklist:
     get:
@@ -15937,6 +15972,8 @@ paths:
                             - assistant
                         content:
                           type: string
+                          deprecated: true
+                          description: "Deprecated: superseded by contentBlocks. Flat plain-text body (joined text segments)."
                         timestamp:
                           type: string
                         attachments:
@@ -16241,6 +16278,8 @@ paths:
                               - name
                               - input
                             additionalProperties: false
+                          deprecated: true
+                          description: "Deprecated: superseded by contentBlocks (the tool_use variant). Flat list of tool calls."
                         surfaces:
                           type: array
                           items:
@@ -16292,18 +16331,28 @@ paths:
                               - surfaceType
                               - data
                             additionalProperties: false
+                          deprecated: true
+                          description: "Deprecated: superseded by contentBlocks (the surface variant). Flat list of surfaces."
                         textSegments:
                           type: array
                           items:
                             type: string
+                          deprecated: true
+                          description: "Deprecated: superseded by contentBlocks. Text segments split by tool-call boundaries."
                         thinkingSegments:
                           type: array
                           items:
                             type: string
+                          deprecated: true
+                          description: "Deprecated: superseded by contentBlocks. Reasoning text extracted from thinking blocks."
                         contentOrder:
                           type: array
                           items:
                             type: string
+                          deprecated: true
+                          description:
+                            'Deprecated: superseded by contentBlocks. Positional "<type>:<index>" content ordering (e.g. "text:0",
+                            "thinking:1").'
                         contentBlocks:
                           type: array
                           items:
@@ -16326,6 +16375,10 @@ paths:
                                     const: thinking
                                   thinking:
                                     type: string
+                                  startedAt:
+                                    type: number
+                                  completedAt:
+                                    type: number
                                 required:
                                   - type
                                   - thinking
@@ -19380,15 +19433,7 @@ paths:
                       - type: "null"
                     description: Resolved version (installed copy first, then repo `package.json`).
                   source:
-                    oneOf:
-                      - type: object
-                        properties:
-                          kind:
-                            type: string
-                            const: first-party
-                        required:
-                          - kind
-                        additionalProperties: false
+                    anyOf:
                       - type: object
                         properties:
                           kind:
@@ -19408,7 +19453,9 @@ paths:
                           - repo
                           - ref
                         additionalProperties: false
-                    description: "Origin of the match: a first-party in-repo plugin or a whitelisted external one."
+                        description: "Origin of the match: a whitelisted external plugin repository."
+                      - type: "null"
+                    description: Pinned origin from the marketplace entry, or null when an installed copy has no catalog entry.
                   readme:
                     anyOf:
                       - type: string
@@ -19449,13 +19496,12 @@ paths:
       operationId: plugins_install_post
       summary: Install a plugin
       description:
-        "Install a plugin by name from the canonical source — a whitelisted `experimental/plugins/marketplace.json`
-        entry, else the first-party `experimental/plugins/<name>/` convention. Always resolves against the curated
-        default git ref (no caller-supplied ref): installing from an unreviewed revision would bypass the
-        marketplace/first-party curation boundary and let attacker-controlled code be loaded. Materializes the plugin
-        under `<workspaceDir>/plugins/<name>/`; the assistant must be restarted to load it. Mirrors the CLI's `assistant
-        plugins install <name>`. An already-installed name without `force` returns 409; a name that resolves to nothing
-        returns 404. Sibling to `POST /v1/skills/install`."
+        "Install a plugin by name from the canonical source — a whitelisted `plugins/marketplace.json` entry.
+        Always resolves against the curated default git ref (no caller-supplied ref): installing from an unreviewed
+        revision would bypass the marketplace curation boundary and let attacker-controlled code be loaded. Materializes
+        the plugin under `<workspaceDir>/plugins/<name>/`; the assistant must be restarted to load it. Mirrors the CLI's
+        `assistant plugins install <name>`. An already-installed name without `force` returns 409; a name that resolves
+        to nothing returns 404. Sibling to `POST /v1/skills/install`."
       tags:
         - plugins
       responses:
@@ -19503,7 +19549,7 @@ paths:
               properties:
                 name:
                   type: string
-                  description: Install name to resolve against the catalog (first-party directory or marketplace entry).
+                  description: Install name to resolve against the marketplace catalog.
                 force:
                   description: Overwrite an existing install in place. Defaults to false.
                   type: boolean
@@ -19515,9 +19561,9 @@ paths:
       operationId: plugins_search_get
       summary: Search the plugin catalog
       description:
-        List installable plugins from the canonical `vellum-ai/vellum-assistant` catalog at
-        `experimental/plugins/`. The query is an ECMAScript regex matched case-insensitively against the directory name
-        (e.g. `memory`, `^simple`). Empty query returns every entry. Mirrors the CLI's `assistant plugins search`.
+        List installable plugins from the curated `plugins/marketplace.json` catalog. The query is an ECMAScript
+        regex matched case-insensitively against the plugin name (e.g. `memory`, `^simple`). Empty query returns every
+        entry. Mirrors the CLI's `assistant plugins search`.
       tags:
         - plugins
       responses:
@@ -19544,42 +19590,31 @@ paths:
                           description: Install name. Matches `assistant plugins install <name>`.
                         path:
                           type: string
-                          description:
-                            "Human-readable origin: a repo-relative path (`experimental/plugins/<name>`) for first-party plugins or a
-                            `github:owner/repo@ref` locator for external ones."
+                          description: "Human-readable origin: a `github:owner/repo@ref` locator for the external plugin."
                         description:
                           description: Short description, when known (external entries only today).
                           type: string
                         source:
-                          oneOf:
-                            - type: object
-                              properties:
-                                kind:
-                                  type: string
-                                  const: first-party
-                              required:
-                                - kind
-                              additionalProperties: false
-                            - type: object
-                              properties:
-                                kind:
-                                  type: string
-                                  const: github
-                                repo:
-                                  type: string
-                                  description: "`owner/repo` of the external plugin repository."
-                                path:
-                                  description: Directory within the repo, when the plugin is not at the root.
-                                  type: string
-                                ref:
-                                  type: string
-                                  description: Pinned git ref the plugin is fetched from.
-                              required:
-                                - kind
-                                - repo
-                                - ref
-                              additionalProperties: false
-                          description: "Origin of the match: a first-party in-repo plugin or a whitelisted external one."
+                          type: object
+                          properties:
+                            kind:
+                              type: string
+                              const: github
+                            repo:
+                              type: string
+                              description: "`owner/repo` of the external plugin repository."
+                            path:
+                              description: Directory within the repo, when the plugin is not at the root.
+                              type: string
+                            ref:
+                              type: string
+                              description: Pinned git ref the plugin is fetched from.
+                          required:
+                            - kind
+                            - repo
+                            - ref
+                          additionalProperties: false
+                          description: "Origin of the match: a whitelisted external plugin repository."
                       required:
                         - name
                         - path
@@ -20290,9 +20325,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -20342,6 +20377,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -20439,9 +20475,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -20491,6 +20527,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -20512,6 +20549,9 @@ paths:
                 name:
                   type: string
                   description: Display name
+                description:
+                  type: string
+                  description: Authored schedule description. Defaults to the schedule name when omitted for backward compatibility.
                 expression:
                   type: string
                   description: Cron or RRULE expression
@@ -20614,9 +20654,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -20666,6 +20706,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -20762,9 +20803,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -20814,6 +20855,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -20840,6 +20882,8 @@ paths:
               properties:
                 name:
                   type: string
+                description:
+                  type: string
                 expression:
                   type: string
                 timezone:
@@ -20953,9 +20997,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -21005,6 +21049,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -21102,9 +21147,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -21154,6 +21199,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -21340,9 +21386,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -21392,6 +21438,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -22176,6 +22223,22 @@ paths:
                                 - available
                             category:
                               type: string
+                            owner:
+                              type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  enum:
+                                    - skill
+                                    - mcp
+                                    - plugin
+                                    - workspace
+                                id:
+                                  type: string
+                              required:
+                                - kind
+                                - id
+                              additionalProperties: false
                             origin:
                               type: string
                               const: vellum
@@ -22214,6 +22277,22 @@ paths:
                                 - available
                             category:
                               type: string
+                            owner:
+                              type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  enum:
+                                    - skill
+                                    - mcp
+                                    - plugin
+                                    - workspace
+                                id:
+                                  type: string
+                              required:
+                                - kind
+                                - id
+                              additionalProperties: false
                             origin:
                               type: string
                               const: clawhub
@@ -22272,6 +22351,22 @@ paths:
                                 - available
                             category:
                               type: string
+                            owner:
+                              type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  enum:
+                                    - skill
+                                    - mcp
+                                    - plugin
+                                    - workspace
+                                id:
+                                  type: string
+                              required:
+                                - kind
+                                - id
+                              additionalProperties: false
                             origin:
                               type: string
                               const: skillssh
@@ -22345,6 +22440,22 @@ paths:
                                 - available
                             category:
                               type: string
+                            owner:
+                              type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  enum:
+                                    - skill
+                                    - mcp
+                                    - plugin
+                                    - workspace
+                                id:
+                                  type: string
+                              required:
+                                - kind
+                                - id
+                              additionalProperties: false
                             origin:
                               type: string
                               const: custom
@@ -22502,6 +22613,22 @@ paths:
                               - available
                           category:
                             type: string
+                          owner:
+                            type: object
+                            properties:
+                              kind:
+                                type: string
+                                enum:
+                                  - skill
+                                  - mcp
+                                  - plugin
+                                  - workspace
+                              id:
+                                type: string
+                            required:
+                              - kind
+                              - id
+                            additionalProperties: false
                           origin:
                             type: string
                             const: vellum
@@ -22725,6 +22852,22 @@ paths:
                               - available
                           category:
                             type: string
+                          owner:
+                            type: object
+                            properties:
+                              kind:
+                                type: string
+                                enum:
+                                  - skill
+                                  - mcp
+                                  - plugin
+                                  - workspace
+                              id:
+                                type: string
+                            required:
+                              - kind
+                              - id
+                            additionalProperties: false
                           origin:
                             type: string
                             const: custom
@@ -22892,6 +23035,22 @@ paths:
                               - available
                           category:
                             type: string
+                          owner:
+                            type: object
+                            properties:
+                              kind:
+                                type: string
+                                enum:
+                                  - skill
+                                  - mcp
+                                  - plugin
+                                  - workspace
+                              id:
+                                type: string
+                            required:
+                              - kind
+                              - id
+                            additionalProperties: false
                           origin:
                             type: string
                             const: vellum
@@ -22930,6 +23089,22 @@ paths:
                               - available
                           category:
                             type: string
+                          owner:
+                            type: object
+                            properties:
+                              kind:
+                                type: string
+                                enum:
+                                  - skill
+                                  - mcp
+                                  - plugin
+                                  - workspace
+                              id:
+                                type: string
+                            required:
+                              - kind
+                              - id
+                            additionalProperties: false
                           origin:
                             type: string
                             const: clawhub
@@ -22988,6 +23163,22 @@ paths:
                               - available
                           category:
                             type: string
+                          owner:
+                            type: object
+                            properties:
+                              kind:
+                                type: string
+                                enum:
+                                  - skill
+                                  - mcp
+                                  - plugin
+                                  - workspace
+                              id:
+                                type: string
+                            required:
+                              - kind
+                              - id
+                            additionalProperties: false
                           origin:
                             type: string
                             const: skillssh
@@ -23061,6 +23252,22 @@ paths:
                               - available
                           category:
                             type: string
+                          owner:
+                            type: object
+                            properties:
+                              kind:
+                                type: string
+                                enum:
+                                  - skill
+                                  - mcp
+                                  - plugin
+                                  - workspace
+                              id:
+                                type: string
+                            required:
+                              - kind
+                              - id
+                            additionalProperties: false
                           origin:
                             type: string
                             const: custom
@@ -23409,6 +23616,22 @@ paths:
                                 - available
                             category:
                               type: string
+                            owner:
+                              type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  enum:
+                                    - skill
+                                    - mcp
+                                    - plugin
+                                    - workspace
+                                id:
+                                  type: string
+                              required:
+                                - kind
+                                - id
+                              additionalProperties: false
                             origin:
                               type: string
                               const: vellum
@@ -23447,6 +23670,22 @@ paths:
                                 - available
                             category:
                               type: string
+                            owner:
+                              type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  enum:
+                                    - skill
+                                    - mcp
+                                    - plugin
+                                    - workspace
+                                id:
+                                  type: string
+                              required:
+                                - kind
+                                - id
+                              additionalProperties: false
                             origin:
                               type: string
                               const: clawhub
@@ -23505,6 +23744,22 @@ paths:
                                 - available
                             category:
                               type: string
+                            owner:
+                              type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  enum:
+                                    - skill
+                                    - mcp
+                                    - plugin
+                                    - workspace
+                                id:
+                                  type: string
+                              required:
+                                - kind
+                                - id
+                              additionalProperties: false
                             origin:
                               type: string
                               const: skillssh
@@ -23578,6 +23833,22 @@ paths:
                                 - available
                             category:
                               type: string
+                            owner:
+                              type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  enum:
+                                    - skill
+                                    - mcp
+                                    - plugin
+                                    - workspace
+                                id:
+                                  type: string
+                              required:
+                                - kind
+                                - id
+                              additionalProperties: false
                             origin:
                               type: string
                               const: custom
@@ -24663,13 +24934,74 @@ paths:
   /v1/tools:
     get:
       operationId: tools_get
-      summary: List tools
-      description: Return available tool names with their descriptions, risk levels, and categories.
+      summary: List registered tools with metadata and schemas
+      description:
+        "Return registered tools. Without `conversationId`, returns every tool in the global registry; `tools`
+        carries per-tool metadata (description, author-asserted risk level, category, and contributing source: core,
+        skill, plugin, or MCP server) and `names`/`schemas` additionally cover skill tools whose manifests are present
+        but not yet loaded, for the permission-simulator catalog. With `conversationId`, scopes the result to the tools
+        available to that conversation as of its most recent turn (including skill/MCP tools registered over its
+        lifecycle); 404 if no such conversation is active."
       tags:
         - tools
       responses:
         "200":
           description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  names:
+                    type: array
+                    items:
+                      type: string
+                  schemas:
+                    type: object
+                    propertyNames:
+                      type: string
+                    additionalProperties:
+                      type: object
+                      propertyNames:
+                        type: string
+                      additionalProperties: {}
+                  tools:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        name:
+                          type: string
+                        description:
+                          type: string
+                        riskLevel:
+                          type: string
+                        category:
+                          type: string
+                        source:
+                          type: string
+                          description:
+                            'Tool origin: "core" for built-ins, otherwise "<kind>:<id>" (e.g. "plugin:echo", "skill:my-skill",
+                            "mcp:server").'
+                      required:
+                        - name
+                        - description
+                        - riskLevel
+                        - category
+                        - source
+                      additionalProperties: false
+                required:
+                  - names
+                  - schemas
+                  - tools
+                additionalProperties: false
+      parameters:
+        - name: conversationId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: When set, scope the tool inventory to this conversation's most recent turn instead of the global registry.
   /v1/tools/simulate-permission:
     post:
       operationId: tools_simulatepermission_post