@vellumai/assistant 0.8.10 → 0.8.11-dev.202606112057.e4bc22e

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
@@ -5978,6 +5937,7 @@ paths:
                                 - macos_notification_view
                                 - macos_conversation_opened
                                 - ios_conversation_opened
+                                - web_bulk_mark_read
                                 - telegram_inbound_message
                                 - telegram_callback
                                 - slack_inbound_message
@@ -6012,6 +5972,8 @@ paths:
                           additionalProperties: false
                         archivedAt:
                           type: number
+                        surfacedAt:
+                          type: number
                         inferenceProfile:
                           type: string
                         isProcessing:
@@ -6339,6 +6301,7 @@ paths:
                               - macos_notification_view
                               - macos_conversation_opened
                               - ios_conversation_opened
+                              - web_bulk_mark_read
                               - telegram_inbound_message
                               - telegram_callback
                               - slack_inbound_message
@@ -6373,6 +6336,8 @@ paths:
                         additionalProperties: false
                       archivedAt:
                         type: number
+                      surfacedAt:
+                        type: number
                       inferenceProfile:
                         type: string
                       isProcessing:
@@ -6537,6 +6502,7 @@ paths:
                               - macos_notification_view
                               - macos_conversation_opened
                               - ios_conversation_opened
+                              - web_bulk_mark_read
                               - telegram_inbound_message
                               - telegram_callback
                               - slack_inbound_message
@@ -6571,6 +6537,8 @@ paths:
                         additionalProperties: false
                       archivedAt:
                         type: number
+                      surfacedAt:
+                        type: number
                       inferenceProfile:
                         type: string
                       isProcessing:
@@ -6979,6 +6947,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
@@ -7080,6 +7098,44 @@ paths:
           required: true
           schema:
             type: string
+  /v1/conversations/archive/bulk:
+    post:
+      operationId: conversations_archive_bulk_post
+      summary: Bulk archive conversations
+      description: Archive multiple conversations in one request. Emits a single sync invalidation for the entire batch.
+      tags:
+        - conversations
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  archived:
+                    type: number
+                required:
+                  - ok
+                  - archived
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversationIds:
+                  minItems: 1
+                  type: array
+                  items:
+                    type: string
+              required:
+                - conversationIds
+              additionalProperties: false
   /v1/conversations/attention:
     get:
       operationId: conversations_attention_get
@@ -7500,6 +7556,7 @@ paths:
                               - macos_notification_view
                               - macos_conversation_opened
                               - ios_conversation_opened
+                              - web_bulk_mark_read
                               - telegram_inbound_message
                               - telegram_callback
                               - slack_inbound_message
@@ -7534,6 +7591,8 @@ paths:
                         additionalProperties: false
                       archivedAt:
                         type: number
+                      surfacedAt:
+                        type: number
                       inferenceProfile:
                         type: string
                       isProcessing:
@@ -8505,6 +8564,46 @@ paths:
               required:
                 - conversationId
               additionalProperties: false
+  /v1/conversations/seen/bulk:
+    post:
+      operationId: conversations_seen_bulk_post
+      summary: Bulk mark conversations as seen
+      description:
+        Mark multiple conversations as seen in one request. Emits a single sync invalidation for the entire batch
+        instead of per-conversation events.
+      tags:
+        - conversations
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  updated:
+                    type: number
+                required:
+                  - ok
+                  - updated
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversationIds:
+                  minItems: 1
+                  type: array
+                  items:
+                    type: string
+              required:
+                - conversationIds
+              additionalProperties: false
   /v1/conversations/switch:
     post:
       operationId: conversations_switch_post
@@ -11174,6 +11273,14 @@ paths:
                     required:
                       - connected
                     additionalProperties: false
+                  capabilities:
+                    type: object
+                    properties:
+                      memoryOptOut:
+                        type: boolean
+                    required:
+                      - memoryOptOut
+                    additionalProperties: false
                   profiler:
                     type: object
                     properties:
@@ -11258,6 +11365,7 @@ paths:
                   - cpu
                   - migrations
                   - ces
+                  - capabilities
                 additionalProperties: false
   /v1/healthz:
     get:
@@ -11342,6 +11450,14 @@ paths:
                     required:
                       - connected
                     additionalProperties: false
+                  capabilities:
+                    type: object
+                    properties:
+                      memoryOptOut:
+                        type: boolean
+                    required:
+                      - memoryOptOut
+                    additionalProperties: false
                   profiler:
                     type: object
                     properties:
@@ -11426,6 +11542,7 @@ paths:
                   - cpu
                   - migrations
                   - ces
+                  - capabilities
                 additionalProperties: false
   /v1/heartbeat/checklist:
     get:
@@ -12885,6 +13002,23 @@ paths:
                   - source
                   - refreshing
                 additionalProperties: false
+      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.
   /v1/image-generation/generate:
     post:
       operationId: imagegeneration_generate_post
@@ -15937,6 +16071,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 +16377,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 +16430,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 +16474,10 @@ paths:
                                     const: thinking
                                   thinking:
                                     type: string
+                                  startedAt:
+                                    type: number
+                                  completedAt:
+                                    type: number
                                 required:
                                   - type
                                   - thinking
@@ -19380,15 +19532,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 +19552,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
@@ -19417,6 +19563,24 @@ paths:
                   ref:
                     type: string
                     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.
+                        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
@@ -19427,6 +19591,7 @@ paths:
                   - source
                   - readme
                   - ref
+                  - artifact
                 additionalProperties: false
         "400":
           description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
@@ -19449,13 +19614,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 +19667,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 +19679,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 +19708,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 +20443,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -20342,6 +20495,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -20439,9 +20593,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -20491,6 +20645,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -20512,6 +20667,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 +20772,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -20666,6 +20824,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -20762,9 +20921,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -20814,6 +20973,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -20840,6 +21000,8 @@ paths:
               properties:
                 name:
                   type: string
+                description:
+                  type: string
                 expression:
                   type: string
                 timezone:
@@ -20953,9 +21115,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -21005,6 +21167,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -21102,9 +21265,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -21154,6 +21317,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -21340,9 +21504,9 @@ paths:
                             - type: number
                             - type: "null"
                         description:
-                          anyOf:
-                            - type: string
-                            - type: "null"
+                          type: string
+                        cadenceDescription:
+                          type: string
                         mode:
                           type: string
                           enum:
@@ -21392,6 +21556,7 @@ paths:
                         - createdFromConversationExists
                         - createdFromConversationArchivedAt
                         - description
+                        - cadenceDescription
                         - mode
                         - status
                         - routingIntent
@@ -22176,6 +22341,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 +22395,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 +22469,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 +22558,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 +22731,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 +22970,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 +23153,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 +23207,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 +23281,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 +23370,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 +23734,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 +23788,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 +23862,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 +23951,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 +25052,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