@vellumai/assistant 0.6.6 → 0.7.0

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.0.0
 info:
   title: Vellum Assistant API
-  version: 0.6.6
+  version: 0.7.0
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -133,10 +133,40 @@ paths:
                 - instruction
               additionalProperties: false
   /v1/acp/sessions:
+    delete:
+      operationId: acp_sessions_delete
+      summary: Bulk-clear terminal ACP sessions
+      description: Remove every terminal-state row (completed/failed/cancelled) from the persisted acp_session_history table.
+      tags:
+        - acp
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  deleted:
+                    type: integer
+                    minimum: -9007199254740991
+                    maximum: 9007199254740991
+                required:
+                  - deleted
+                additionalProperties: false
+      parameters:
+        - name: status
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Must be 'completed'. Shorthand for all terminal statuses (completed/failed/cancelled).
     get:
       operationId: acp_sessions_get
       summary: List ACP sessions
-      description: Return all active ACP sessions.
+      description:
+        Return the merged set of in-memory and persisted ACP sessions, newest first. In-memory sessions take
+        precedence on id collision.
       tags:
         - acp
       responses:
@@ -149,11 +179,88 @@ paths:
                 properties:
                   sessions:
                     type: array
-                    items: {}
-                    description: ACP session status objects
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        agentId:
+                          type: string
+                        acpSessionId:
+                          type: string
+                        parentConversationId:
+                          type: string
+                        status:
+                          type: string
+                        startedAt:
+                          type: number
+                        completedAt:
+                          anyOf:
+                            - type: number
+                            - type: "null"
+                        error:
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                        stopReason:
+                          anyOf:
+                            - type: string
+                            - type: "null"
+                        eventLog:
+                          type: array
+                          items: {}
+                      required:
+                        - id
+                        - agentId
+                        - acpSessionId
+                        - status
+                        - startedAt
+                      additionalProperties: false
+                    description: Merged in-memory and persisted ACP sessions.
                 required:
                   - sessions
                 additionalProperties: false
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+          description: Maximum number of sessions to return (default 50, max 500).
+        - name: conversationId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter to sessions whose parentConversationId matches this value.
+  /v1/acp/sessions/{id}:
+    delete:
+      operationId: acp_sessions_by_id_delete
+      summary: Delete ACP session from history
+      description:
+        Remove a persisted ACP session row. Rejects with 409 when the session is still active in memory; idempotent
+        for unknown ids.
+      tags:
+        - acp
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  deleted:
+                    type: boolean
+                required:
+                  - deleted
+                additionalProperties: false
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
   /v1/acp/spawn:
     post:
       operationId: acp_spawn_post
@@ -432,6 +539,11 @@ paths:
           required: true
           schema:
             type: string
+        - name: method
+          in: query
+          required: false
+          schema:
+            type: string
     post:
       operationId: apps_by_id_data_post
       summary: Mutate app data
@@ -500,6 +612,16 @@ paths:
           required: true
           schema:
             type: string
+        - name: fromCommit
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: toCommit
+          in: query
+          required: false
+          schema:
+            type: string
   /v1/apps/{id}/history:
     get:
       operationId: apps_by_id_history_get
@@ -530,6 +652,11 @@ paths:
           required: true
           schema:
             type: string
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: number
   /v1/apps/{id}/open:
     post:
       operationId: apps_by_id_open_post
@@ -905,7 +1032,6 @@ paths:
                   description: Canonical JSON payload to sign
                 signature:
                   type: string
-                  description: Ed25519 signature (optional, completes signing)
                 keyId:
                   type: string
                 publicKey:
@@ -931,7 +1057,7 @@ paths:
       tags:
         - attachments
       responses:
-        "200":
+        "204":
           description: Successful response
       requestBody:
         required: true
@@ -996,6 +1122,11 @@ paths:
                 filePath:
                   type: string
                   description: On-disk file path (file-backed upload)
+                trustedSource:
+                  type: boolean
+                  description:
+                    Set by the gateway when the file came from a guardian-bound channel actor. Honored only when the request is
+                    authenticated as a gateway service token; ignored otherwise.
               required:
                 - filename
                 - mimeType
@@ -1026,8 +1157,10 @@ paths:
                   kind:
                     type: string
                   data:
-                    type: string
-                    description: Base64-encoded content
+                    anyOf:
+                      - type: string
+                        description: Base64-encoded content
+                      - type: "null"
                   fileBacked:
                     type: boolean
                 required:
@@ -1037,7 +1170,6 @@ paths:
                   - sizeBytes
                   - kind
                   - data
-                  - fileBacked
                 additionalProperties: false
       parameters:
         - name: id
@@ -1055,20 +1187,125 @@ paths:
       responses:
         "200":
           description: Successful response
+        "416":
+          description: Range Not Satisfiable
       parameters:
         - name: id
           in: path
           required: true
           schema:
             type: string
-  /v1/audio/{id}:
+  /v1/attachments/lookup:
+    post:
+      operationId: attachments_lookup_post
+      summary: Look up attachment by source path
+      description: Search for a previously registered attachment by its original source path, scoped to a conversation.
+      tags:
+        - attachments
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  filePath:
+                    type: string
+                required:
+                  - filePath
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                sourcePath:
+                  type: string
+                  description: Original source path of the file
+                conversationId:
+                  type: string
+                  description: Conversation ID to search within
+              required:
+                - sourcePath
+                - conversationId
+              additionalProperties: false
+  /v1/attachments/register:
+    post:
+      operationId: attachments_register_post
+      summary: Register a file-backed attachment
+      description:
+        Register an on-disk file as a file-backed attachment. The file must be within the workspace directory and
+        must remain on disk for the lifetime of the attachment.
+      tags:
+        - attachments
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  originalFilename:
+                    type: string
+                  mimeType:
+                    type: string
+                  sizeBytes:
+                    type: number
+                  kind:
+                    type: string
+                  filePath:
+                    type: string
+                  createdAt:
+                    type: number
+                required:
+                  - id
+                  - originalFilename
+                  - mimeType
+                  - sizeBytes
+                  - kind
+                  - filePath
+                  - createdAt
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                path:
+                  type: string
+                  description: Absolute path to the file
+                mimeType:
+                  type: string
+                  description: MIME type of the file
+                filename:
+                  type: string
+                  description: Display filename (defaults to basename of path)
+              required:
+                - path
+                - mimeType
+              additionalProperties: false
+  /v1/audio/{audioId}:
     get:
-      operationId: audio_by_id_get
+      operationId: audio_by_audioId_get
+      summary: Get audio segment
+      description:
+        Retrieve a previously stored audio segment by ID. Unauthenticated — the audioId is an unguessable UUID
+        capability token.
+      tags:
+        - audio
       responses:
         "200":
           description: Successful response
       parameters:
-        - name: id
+        - name: audioId
           in: path
           required: true
           schema:
@@ -1083,6 +1320,26 @@ paths:
       responses:
         "200":
           description: Successful response
+  /v1/avatar/notify-updated:
+    post:
+      operationId: avatar_notifyupdated_post
+      summary: Notify avatar updated
+      description: Publish an avatar_updated SSE event to connected clients.
+      tags:
+        - avatar
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                required:
+                  - ok
+                additionalProperties: false
   /v1/avatar/render-from-traits:
     post:
       operationId: avatar_renderfromtraits_post
@@ -1121,6 +1378,85 @@ paths:
                 - eyeStyle
                 - color
               additionalProperties: false
+  /v1/background-tools:
+    get:
+      operationId: backgroundtools_get
+      summary: List active background tools
+      description: List all active background tool executions, optionally filtered by conversationId.
+      tags:
+        - background-tools
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tools:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        toolName:
+                          type: string
+                        conversationId:
+                          type: string
+                        command:
+                          type: string
+                        startedAt:
+                          type: number
+                      required:
+                        - id
+                        - toolName
+                        - conversationId
+                        - command
+                        - startedAt
+                      additionalProperties: false
+                required:
+                  - tools
+                additionalProperties: false
+      parameters:
+        - name: conversationId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter by conversation ID
+  /v1/background-tools/cancel:
+    post:
+      operationId: backgroundtools_cancel_post
+      summary: Cancel a background tool
+      description: Cancel an active background tool execution by ID.
+      tags:
+        - background-tools
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  cancelled:
+                    type: boolean
+                required:
+                  - cancelled
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                id:
+                  type: string
+              required:
+                - id
+              additionalProperties: false
   /v1/backups:
     get:
       operationId: backups_get
@@ -1332,15 +1668,96 @@ paths:
     get:
       operationId: braingraphui_get
       summary: Serve brain graph UI
-      description: Return the brain-graph HTML visualization page with an embedded auth token.
+      description: Return the brain-graph HTML visualization page. The gateway injects an auth token before serving.
       tags:
         - brain-graph
       responses:
         "200":
           description: Successful response
-  /v1/btw:
+  /v1/browser/execute:
     post:
-      operationId: btw_post
+      operationId: browser_execute_post
+      summary: Execute a browser operation
+      description: Invoke a browser operation (navigate, click, type, screenshot, etc.) via the headless browser subsystem.
+      tags:
+        - browser
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  content:
+                    type: string
+                  isError:
+                    type: boolean
+                  screenshots:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        mediaType:
+                          type: string
+                        data:
+                          type: string
+                      required:
+                        - mediaType
+                        - data
+                      additionalProperties: false
+                required:
+                  - content
+                  - isError
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                operation:
+                  type: string
+                  enum:
+                    - navigate
+                    - snapshot
+                    - screenshot
+                    - close
+                    - attach
+                    - detach
+                    - click
+                    - type
+                    - press_key
+                    - scroll
+                    - select_option
+                    - hover
+                    - wait_for
+                    - extract
+                    - wait_for_download
+                    - fill_credential
+                    - status
+                input:
+                  default: {}
+                  type: object
+                  propertyNames:
+                    type: string
+                  additionalProperties: {}
+                sessionId:
+                  default: default
+                  type: string
+                  minLength: 1
+                conversationId:
+                  type: string
+                  minLength: 1
+              required:
+                - operation
+                - input
+                - sessionId
+              additionalProperties: false
+  /v1/btw:
+    post:
+      operationId: btw_post
       summary: Run ephemeral LLM side-chain
       description:
         Stream an ephemeral LLM call reusing the conversation's provider and message history. Response is SSE
@@ -1367,9 +1784,114 @@ paths:
                 - conversationKey
                 - content
               additionalProperties: false
-  /v1/calls/{id}:
+  /v1/cache/delete:
+    post:
+      operationId: cache_delete_post
+      summary: Delete a cache entry
+      description: Remove a cached value by key.
+      tags:
+        - cache
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  deleted:
+                    type: boolean
+                required:
+                  - deleted
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                key:
+                  type: string
+                  minLength: 1
+              required:
+                - key
+              additionalProperties: false
+  /v1/cache/get:
+    post:
+      operationId: cache_get_post
+      summary: Get a cache entry
+      description: Retrieve a cached value by key. Returns null if not found.
+      tags:
+        - cache
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                anyOf:
+                  - type: object
+                    properties:
+                      data: {}
+                    required:
+                      - data
+                    additionalProperties: false
+                  - type: "null"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                key:
+                  type: string
+                  minLength: 1
+              required:
+                - key
+              additionalProperties: false
+  /v1/cache/set:
+    post:
+      operationId: cache_set_post
+      summary: Set a cache entry
+      description: Store a value in the daemon's in-memory cache, optionally with a TTL.
+      tags:
+        - cache
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  key:
+                    type: string
+                required:
+                  - key
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                data: {}
+                key:
+                  type: string
+                  minLength: 1
+                ttl_ms:
+                  type: integer
+                  exclusiveMinimum: 0
+                  maximum: 9007199254740991
+              required:
+                - data
+              additionalProperties: false
+  /v1/calls/{callSessionId}:
     get:
-      operationId: calls_by_id_get
+      operationId: calls_by_callSessionId_get
       summary: Get call status
       description: Return the current status and details of a call session.
       tags:
@@ -1399,15 +1921,23 @@ paths:
                   task:
                     type: string
                   startedAt:
-                    type: string
+                    anyOf:
+                      - type: string
+                      - type: "null"
                   endedAt:
-                    type: string
+                    anyOf:
+                      - type: string
+                      - type: "null"
                   lastError:
-                    type: string
+                    anyOf:
+                      - type: string
+                      - type: "null"
                   pendingQuestion:
-                    type: object
-                    properties: {}
-                    additionalProperties: {}
+                    anyOf:
+                      - type: object
+                        properties: {}
+                        additionalProperties: {}
+                      - type: "null"
                   createdAt:
                     type: string
                   updatedAt:
@@ -1429,14 +1959,14 @@ paths:
                   - updatedAt
                 additionalProperties: false
       parameters:
-        - name: id
+        - name: callSessionId
           in: path
           required: true
           schema:
             type: string
-  /v1/calls/{id}/answer:
+  /v1/calls/{callSessionId}/answer:
     post:
-      operationId: calls_by_id_answer_post
+      operationId: calls_by_callSessionId_answer_post
       summary: Answer a pending call question
       description: Provide an answer to a pending question during an active call.
       tags:
@@ -1458,7 +1988,7 @@ paths:
                   - questionId
                 additionalProperties: false
       parameters:
-        - name: id
+        - name: callSessionId
           in: path
           required: true
           schema:
@@ -1478,11 +2008,10 @@ paths:
                   description: ID of the pending question
               required:
                 - answer
-                - pendingQuestionId
               additionalProperties: false
-  /v1/calls/{id}/cancel:
+  /v1/calls/{callSessionId}/cancel:
     post:
-      operationId: calls_by_id_cancel_post
+      operationId: calls_by_callSessionId_cancel_post
       summary: Cancel a call
       description: Cancel an active or pending call.
       tags:
@@ -1504,7 +2033,7 @@ paths:
                   - status
                 additionalProperties: false
       parameters:
-        - name: id
+        - name: callSessionId
           in: path
           required: true
           schema:
@@ -1519,12 +2048,10 @@ paths:
                 reason:
                   type: string
                   description: Cancellation reason
-              required:
-                - reason
               additionalProperties: false
-  /v1/calls/{id}/instruction:
+  /v1/calls/{callSessionId}/instruction:
     post:
-      operationId: calls_by_id_instruction_post
+      operationId: calls_by_callSessionId_instruction_post
       summary: Relay instruction to active call
       description: Send a real-time instruction to an active call.
       tags:
@@ -1543,7 +2070,7 @@ paths:
                   - ok
                 additionalProperties: false
       parameters:
-        - name: id
+        - name: callSessionId
           in: path
           required: true
           schema:
@@ -1569,7 +2096,7 @@ paths:
       tags:
         - calls
       responses:
-        "200":
+        "201":
           description: Successful response
           content:
             application/json:
@@ -1634,19 +2161,6 @@ paths:
       responses:
         "200":
           description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  success:
-                    type: boolean
-                  channel:
-                    type: string
-                required:
-                  - success
-                  - channel
-                additionalProperties: false
       requestBody:
         required: true
         content:
@@ -1792,7 +2306,7 @@ paths:
       tags:
         - channels
       responses:
-        "200":
+        "204":
           description: Successful response
   /v1/channels/inbound:
     post:
@@ -1894,6 +2408,37 @@ paths:
       responses:
         "200":
           description: Successful response
+  /v1/clients:
+    get:
+      operationId: clients_get
+      summary: List connected clients
+      description: Return all connected clients, optionally filtered by capability.
+      tags:
+        - clients
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  clients:
+                    type: array
+                    items:
+                      type: object
+                      properties: {}
+                      additionalProperties: {}
+                required:
+                  - clients
+                additionalProperties: false
+      parameters:
+        - name: capability
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter clients by a specific capability.
   /v1/config:
     get:
       operationId: config_get
@@ -1946,6 +2491,22 @@ paths:
               required:
                 - provider
               additionalProperties: false
+  /v1/config/llm/profiles/{name}:
+    put:
+      operationId: config_llm_profiles_by_name_put
+      summary: Replace an inference profile
+      description: Replace the settings-UI-managed leaves of a single llm.profiles entry while preserving non-UI leaves.
+      tags:
+        - config
+      responses:
+        "200":
+          description: Successful response
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
   /v1/config/platform:
     get:
       operationId: config_platform_get
@@ -2022,7 +2583,7 @@ paths:
                   description: Pending interaction request ID
                 decision:
                   type: string
-                  description: "One of: allow, allow_10m, allow_conversation, deny, always_allow, always_deny"
+                  description: "One of: allow, deny"
                 selectedPattern:
                   type: string
                   description: Allowlist pattern for persistent decisions
@@ -2111,6 +2672,43 @@ paths:
                   - ok
                   - contacts
                 additionalProperties: false
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+          description: Max contacts to return (default 50)
+        - name: role
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter by role (e.g. guardian)
+        - name: contactType
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter by contact type (human or assistant)
+        - name: query
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Full-text search query
+        - name: channelAddress
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter by channel address
+        - name: channelType
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter by channel type
     post:
       operationId: contacts_post
       summary: Create or update a contact
@@ -2172,7 +2770,7 @@ paths:
       tags:
         - contacts
       responses:
-        "200":
+        "204":
           description: Successful response
       parameters:
         - name: id
@@ -2217,11 +2815,11 @@ paths:
           required: true
           schema:
             type: string
-  /v1/contacts/guardian/channel:
-    post:
-      operationId: contacts_guardian_channel_post
-      summary: Add a channel to the guardian contact
-      description: Used by the guardian to auto-verify their own channel.
+  /v1/contacts/invites:
+    get:
+      operationId: contacts_invites_get
+      summary: List invites
+      description: Return all invites, optionally filtered by sourceChannel or status.
       tags:
         - contacts
       responses:
@@ -2234,63 +2832,13 @@ paths:
                 properties:
                   ok:
                     type: boolean
-                  contact:
-                    type: object
-                    properties: {}
-                    additionalProperties: {}
-                    description: Updated guardian contact
+                  invites:
+                    type: array
+                    items: {}
+                    description: Invite objects
                 required:
                   - ok
-                  - contact
-                additionalProperties: false
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                type:
-                  type: string
-                  description: Channel type, e.g. 'email'
-                address:
-                  type: string
-                  description: Channel address, e.g. 'user@example.com'
-                externalUserId:
-                  type: string
-                  description: External user ID for trust resolution
-                status:
-                  description: "Channel status (default: active)"
-                  type: string
-              required:
-                - type
-                - address
-                - externalUserId
-              additionalProperties: false
-  /v1/contacts/invites:
-    get:
-      operationId: contacts_invites_get
-      summary: List invites
-      description: Return all invites, optionally filtered by sourceChannel or status.
-      tags:
-        - contacts
-      responses:
-        "200":
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  ok:
-                    type: boolean
-                  invites:
-                    type: array
-                    items: {}
-                    description: Invite objects
-                required:
-                  - ok
-                  - invites
+                  - invites
                 additionalProperties: false
       parameters:
         - name: sourceChannel
@@ -2312,7 +2860,7 @@ paths:
       tags:
         - contacts
       responses:
-        "200":
+        "201":
           description: Successful response
           content:
             application/json:
@@ -2330,6 +2878,8 @@ paths:
                   - ok
                   - invite
                 additionalProperties: false
+        "400":
+          description: Invalid invite parameters
       requestBody:
         required: true
         content:
@@ -2377,6 +2927,8 @@ paths:
       responses:
         "200":
           description: Successful response
+        "404":
+          description: Invite not found
       parameters:
         - name: id
           in: path
@@ -2407,6 +2959,8 @@ paths:
                   - ok
                   - callSid
                 additionalProperties: false
+        "400":
+          description: Invite not eligible for outbound call
       parameters:
         - name: id
           in: path
@@ -2447,6 +3001,8 @@ paths:
                   - type
                   - memberId
                 additionalProperties: false
+        "400":
+          description: Invalid redemption parameters or failed redemption
       requestBody:
         required: true
         content:
@@ -2527,6 +3083,40 @@ paths:
                 - keepId
                 - mergeId
               additionalProperties: false
+  /v1/contacts/search:
+    post:
+      operationId: contacts_search_post
+      summary: Search contacts
+      description: Search contacts by query, channel address, or channel type.
+      tags:
+        - contacts
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties: {}
+                  additionalProperties: {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                query:
+                  type: string
+                channelAddress:
+                  type: string
+                channelType:
+                  type: string
+                limit:
+                  type: number
+              additionalProperties: false
   /v1/conversation-starters:
     get:
       operationId: conversationstarters_get
@@ -2583,15 +3173,46 @@ paths:
           schema:
             type: string
           description: Scope ID (default "default")
+  /v1/conversation-starters/{id}:
+    delete:
+      operationId: conversationstarters_by_id_delete
+      summary: Delete conversation starter
+      description: Remove a generated conversation starter chip from the current starter set.
+      tags:
+        - conversation-starters
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  deleted:
+                    type: boolean
+                  id:
+                    type: string
+                required:
+                  - deleted
+                  - id
+                additionalProperties: false
+        "404":
+          description: Conversation starter not found
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
   /v1/conversations:
     delete:
       operationId: conversations_delete
       summary: Clear all conversations
-      description: Permanently delete ALL conversations, messages, and memory. Requires X-Confirm-Destructive header.
+      description: Permanently delete ALL conversations, messages, and memory.
       tags:
         - conversations
       responses:
-        "200":
+        "204":
           description: Successful response
     get:
       operationId: conversations_get
@@ -2618,10 +3239,13 @@ paths:
                     type: string
                   conversationType:
                     type: string
+                  created:
+                    type: boolean
                 required:
                   - id
                   - conversationKey
                   - conversationType
+                  - created
                 additionalProperties: false
       requestBody:
         required: true
@@ -2634,11 +3258,11 @@ paths:
                   type: string
                   description: Idempotency key for the conversation
                 conversationType:
+                  description: Only standard conversations are created by this endpoint
                   type: string
-                  description: "'standard' (default) or 'private'"
+                  const: standard
               required:
                 - conversationKey
-                - conversationType
               additionalProperties: false
   /v1/conversations/{id}:
     delete:
@@ -2648,7 +3272,7 @@ paths:
       tags:
         - conversations
       responses:
-        "200":
+        "204":
           description: Successful response
       parameters:
         - name: id
@@ -2687,9 +3311,7 @@ paths:
     post:
       operationId: conversations_by_id_archive_post
       summary: Archive a conversation
-      description:
-        Move a conversation to the archived state. Archived conversations are hidden from the default sidebar but
-        preserved for search and recall.
+      description: Move a conversation to the archived state.
       tags:
         - conversations
       responses:
@@ -2709,47 +3331,19 @@ paths:
       tags:
         - conversations
       responses:
-        "200":
-          description: Successful response
-      parameters:
-        - name: id
-          in: path
-          required: true
-          schema:
-            type: string
-  /v1/conversations/{id}/host-access:
-    get:
-      operationId: conversations_by_id_hostaccess_get
-      summary: Get conversation host access
-      description: Return whether the conversation can use host tools.
-      tags:
-        - conversations
-      responses:
-        "200":
+        "202":
           description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  conversationId:
-                    type: string
-                  hostAccess:
-                    type: boolean
-                required:
-                  - conversationId
-                  - hostAccess
-                additionalProperties: false
       parameters:
         - name: id
           in: path
           required: true
           schema:
             type: string
-    patch:
-      operationId: conversations_by_id_hostaccess_patch
-      summary: Update conversation host access
-      description: Enable or disable host access for a conversation.
+  /v1/conversations/{id}/inference-profile:
+    put:
+      operationId: conversations_by_id_inferenceprofile_put
+      summary: Set conversation inference profile
+      description: Override the LLM inference profile for a single conversation.
       tags:
         - conversations
       responses:
@@ -2762,11 +3356,13 @@ paths:
                 properties:
                   conversationId:
                     type: string
-                  hostAccess:
-                    type: boolean
+                  profile:
+                    anyOf:
+                      - type: string
+                      - type: "null"
                 required:
                   - conversationId
-                  - hostAccess
+                  - profile
                 additionalProperties: false
       parameters:
         - name: id
@@ -2781,10 +3377,12 @@ paths:
             schema:
               type: object
               properties:
-                hostAccess:
-                  type: boolean
+                profile:
+                  anyOf:
+                    - type: string
+                    - type: "null"
               required:
-                - hostAccess
+                - profile
               additionalProperties: false
   /v1/conversations/{id}/name:
     patch:
@@ -2898,7 +3496,7 @@ paths:
       tags:
         - conversations
       responses:
-        "200":
+        "202":
           description: Successful response
       parameters:
         - name: id
@@ -3075,6 +3673,33 @@ paths:
               required:
                 - conversationId
               additionalProperties: false
+  /v1/conversations/rename:
+    post:
+      operationId: conversations_rename_post
+      summary: Rename a conversation
+      description: Update the display title of a conversation.
+      tags:
+        - conversations
+      responses:
+        "200":
+          description: Successful response
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversationId:
+                  type: string
+                  minLength: 1
+                title:
+                  type: string
+                  minLength: 1
+              required:
+                - conversationId
+                - title
+              additionalProperties: false
   /v1/conversations/reorder:
     post:
       operationId: conversations_reorder_post
@@ -3123,6 +3748,25 @@ paths:
                   - query
                   - results
                 additionalProperties: false
+      parameters:
+        - name: q
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Search query
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+          description: Max results
+        - name: maxMessagesPerConversation
+          in: query
+          required: false
+          schema:
+            type: integer
+          description: Max messages per conversation
   /v1/conversations/seen:
     post:
       operationId: conversations_seen_post
@@ -3150,13 +3794,12 @@ paths:
                     type: string
                   conversationType:
                     type: string
-                  hostAccess:
-                    type: boolean
+                  inferenceProfile:
+                    type: string
                 required:
                   - conversationId
                   - title
                   - conversationType
-                  - hostAccess
                 additionalProperties: false
       requestBody:
         required: true
@@ -3179,13 +3822,13 @@ paths:
       responses:
         "200":
           description: Successful response
-  /v1/debug:
-    get:
-      operationId: debug_get
-      summary: Debug introspection
-      description: "Return runtime diagnostics: uptime, provider info, memory stats, job counts, and schedule counts."
+  /v1/conversations/wake:
+    post:
+      operationId: conversations_wake_post
+      summary: Wake a conversation
+      description: Invoke the agent loop for a conversation with an opportunity hint.
       tags:
-        - debug
+        - conversations
       responses:
         "200":
           description: Successful response
@@ -3194,59 +3837,370 @@ paths:
               schema:
                 type: object
                 properties:
-                  session:
-                    type: object
-                    properties: {}
-                    additionalProperties: {}
-                    description: Uptime and start time
-                  provider:
-                    type: object
-                    properties: {}
-                    additionalProperties: {}
-                    description: Inference provider configuration
-                  memory:
-                    type: object
-                    properties: {}
-                    additionalProperties: {}
-                    description: Conversation and memory item counts
-                  jobs:
-                    type: object
-                    properties: {}
-                    additionalProperties: {}
-                    description: Background job counts
-                  schedules:
-                    type: object
-                    properties: {}
-                    additionalProperties: {}
-                    description: Schedule counts (total, enabled)
-                  timestamp:
+                  invoked:
+                    type: boolean
+                  producedToolCalls:
+                    type: boolean
+                  reason:
                     type: string
-                    description: Current server timestamp (ISO 8601)
                 required:
-                  - session
-                  - provider
-                  - memory
-                  - jobs
-                  - schedules
-                  - timestamp
+                  - invoked
+                  - producedToolCalls
                 additionalProperties: false
-  /v1/diagnostics/env-vars:
-    get:
-      operationId: diagnostics_envvars_get
-      summary: List safe environment variables
-      description: Return environment variable names and values that are safe to expose (no secrets).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversationId:
+                  type: string
+                  minLength: 1
+                hint:
+                  type: string
+                  minLength: 1
+                source:
+                  default: cli
+                  type: string
+              required:
+                - conversationId
+                - hint
+                - source
+              additionalProperties: false
+  /v1/conversations/wipe:
+    post:
+      operationId: conversations_wipe_post
+      summary: Wipe a conversation
+      description: Permanently delete a conversation and its associated data including memory vectors.
       tags:
-        - diagnostics
+        - conversations
       responses:
         "200":
           description: Successful response
-  /v1/dictation:
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  wiped:
+                    type: boolean
+                  unsupersededItems:
+                    type: number
+                  deletedSummaries:
+                    type: number
+                  cancelledJobs:
+                    type: number
+                required:
+                  - wiped
+                  - unsupersededItems
+                  - deletedSummaries
+                  - cancelledJobs
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversationId:
+                  type: string
+                  minLength: 1
+              required:
+                - conversationId
+              additionalProperties: false
+  /v1/credentials/prompt:
     post:
-      operationId: dictation_post
-      summary: Process dictation
-      description: Classify voice input as dictation or action, clean up text, and apply user style preferences.
+      operationId: credentials_prompt_post
+      summary: Prompt user for a credential
+      description: Trigger a secure input prompt in the user's app to collect a credential value.
       tags:
-        - diagnostics
+        - credentials
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  error:
+                    type: string
+                  service:
+                    type: string
+                  field:
+                    type: string
+                required:
+                  - ok
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                service:
+                  type: string
+                  minLength: 1
+                field:
+                  type: string
+                  minLength: 1
+                label:
+                  type: string
+                  minLength: 1
+                description:
+                  type: string
+                placeholder:
+                  type: string
+                allowedDomains:
+                  type: array
+                  items:
+                    type: string
+                allowedTools:
+                  type: array
+                  items:
+                    type: string
+                injectionTemplates:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      hostPattern:
+                        type: string
+                        minLength: 1
+                      injectionType:
+                        type: string
+                        enum:
+                          - header
+                          - query
+                      headerName:
+                        type: string
+                      valuePrefix:
+                        type: string
+                      queryParamName:
+                        type: string
+                    required:
+                      - hostPattern
+                      - injectionType
+                    additionalProperties: false
+              required:
+                - service
+                - field
+                - label
+              additionalProperties: false
+  /v1/debug:
+    get:
+      operationId: debug_get
+      summary: Debug introspection
+      description: "Return runtime diagnostics: uptime, provider info, memory stats, job counts, and schedule counts."
+      tags:
+        - debug
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  session:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                    description: Uptime and start time
+                  provider:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                    description: Inference provider configuration
+                  memory:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                    description: Conversation and memory item counts
+                  jobs:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                    description: Background job counts
+                  schedules:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                    description: Schedule counts (total, enabled)
+                  timestamp:
+                    type: string
+                    description: Current server timestamp (ISO 8601)
+                required:
+                  - session
+                  - provider
+                  - memory
+                  - jobs
+                  - schedules
+                  - timestamp
+                additionalProperties: false
+  /v1/defer/cancel:
+    post:
+      operationId: defer_cancel_post
+      summary: Cancel deferred wakes
+      description: Cancel a specific deferred wake by ID, or all defers for a conversation.
+      tags:
+        - defer
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  cancelled:
+                    type: number
+                  error:
+                    type: string
+                required:
+                  - cancelled
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                id:
+                  type: string
+                all:
+                  type: boolean
+                conversationId:
+                  type: string
+              additionalProperties: false
+  /v1/defer/create:
+    post:
+      operationId: defer_create_post
+      summary: Create a deferred wake
+      description: Schedule a future wake-up on a conversation, optionally with a delay or absolute timestamp.
+      tags:
+        - defer
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  name:
+                    type: string
+                  fireAt:
+                    type: number
+                  conversationId:
+                    type: string
+                required:
+                  - id
+                  - name
+                  - fireAt
+                  - conversationId
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversationId:
+                  type: string
+                  minLength: 1
+                hint:
+                  type: string
+                  minLength: 1
+                delaySeconds:
+                  type: number
+                fireAt:
+                  type: number
+                name:
+                  type: string
+              required:
+                - conversationId
+                - hint
+              additionalProperties: false
+  /v1/defer/list:
+    post:
+      operationId: defer_list_post
+      summary: List active deferred wakes
+      description: List all active deferred wakes, optionally filtered by conversation.
+      tags:
+        - defer
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  defers:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        name:
+                          type: string
+                        hint:
+                          type: string
+                        conversationId:
+                          type: string
+                        fireAt:
+                          type: number
+                        status:
+                          type: string
+                      required:
+                        - id
+                        - name
+                        - hint
+                        - conversationId
+                        - fireAt
+                        - status
+                      additionalProperties: false
+                required:
+                  - defers
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversationId:
+                  type: string
+              additionalProperties: false
+  /v1/diagnostics/env-vars:
+    get:
+      operationId: diagnostics_envvars_get
+      summary: List safe environment variables
+      description: Return environment variable names and values that are safe to expose (no secrets).
+      tags:
+        - diagnostics
+      responses:
+        "200":
+          description: Successful response
+  /v1/dictation:
+    post:
+      operationId: dictation_post
+      summary: Process dictation
+      description: Classify voice input as dictation or action, clean up text, and apply user style preferences.
+      tags:
+        - diagnostics
       responses:
         "200":
           description: Successful response
@@ -3344,6 +4298,7 @@ paths:
                 properties:
                   success:
                     type: boolean
+                    const: true
                   surfaceId:
                     type: string
                 required:
@@ -3453,6 +4408,8 @@ paths:
       responses:
         "200":
           description: Successful response
+        "500":
+          description: Failed to create archive
       requestBody:
         required: true
         content:
@@ -3469,9 +4426,7 @@ paths:
                   description: Scope to a single conversation
                   type: string
                 full:
-                  description:
-                    Full export — include messages, LLM request logs, and usage events for all conversations. Use for test data
-                    debugging.
+                  description: Full export — include messages, LLM request logs, and usage events for all conversations.
                   type: boolean
                 startTime:
                   description: Lower bound epoch ms
@@ -3567,8 +4522,10 @@ paths:
       tags:
         - groups
       responses:
-        "200":
+        "201":
           description: Successful response
+        "400":
+          description: Missing or invalid name, or sort_position ceiling reached
       requestBody:
         required: true
         content:
@@ -3590,8 +4547,12 @@ paths:
       tags:
         - groups
       responses:
-        "200":
+        "204":
           description: Successful response
+        "403":
+          description: System groups cannot be deleted
+        "404":
+          description: Group not found
       parameters:
         - name: groupId
           in: path
@@ -3607,6 +4568,10 @@ paths:
       responses:
         "200":
           description: Successful response
+        "403":
+          description: System group sort position cannot be changed
+        "404":
+          description: Group not found
       parameters:
         - name: groupId
           in: path
@@ -3635,6 +4600,8 @@ paths:
       responses:
         "200":
           description: Successful response
+        "403":
+          description: Cannot reorder system groups
       requestBody:
         required: true
         content:
@@ -3740,18 +4707,6 @@ paths:
           schema:
             type: string
           description: Conversation ID (required)
-  /v1/guardian/init:
-    post:
-      operationId: guardian_init_post
-      responses:
-        "200":
-          description: Successful response
-  /v1/guardian/refresh:
-    post:
-      operationId: guardian_refresh_post
-      responses:
-        "200":
-          description: Successful response
   /v1/health:
     get:
       operationId: health_get
@@ -4071,11 +5026,21 @@ paths:
                   intervalMs:
                     type: number
                   activeHoursStart:
-                    type: number
+                    anyOf:
+                      - type: number
+                      - type: "null"
                   activeHoursEnd:
-                    type: number
+                    anyOf:
+                      - type: number
+                      - type: "null"
                   nextRunAt:
-                    type: string
+                    anyOf:
+                      - type: number
+                      - type: "null"
+                  lastRunAt:
+                    anyOf:
+                      - type: number
+                      - type: "null"
                   success:
                     type: boolean
                 required:
@@ -4084,6 +5049,7 @@ paths:
                   - activeHoursStart
                   - activeHoursEnd
                   - nextRunAt
+                  - lastRunAt
                   - success
                 additionalProperties: false
     put:
@@ -4105,11 +5071,21 @@ paths:
                   intervalMs:
                     type: number
                   activeHoursStart:
-                    type: number
+                    anyOf:
+                      - type: number
+                      - type: "null"
                   activeHoursEnd:
-                    type: number
+                    anyOf:
+                      - type: number
+                      - type: "null"
                   nextRunAt:
-                    type: string
+                    anyOf:
+                      - type: number
+                      - type: "null"
+                  lastRunAt:
+                    anyOf:
+                      - type: number
+                      - type: "null"
                   success:
                     type: boolean
                 required:
@@ -4118,6 +5094,7 @@ paths:
                   - activeHoursStart
                   - activeHoursEnd
                   - nextRunAt
+                  - lastRunAt
                   - success
                 additionalProperties: false
       requestBody:
@@ -4197,7 +5174,7 @@ paths:
           required: false
           schema:
             type: integer
-          description: Max runs to return (default 20)
+          description: Max runs to return (default 20, max 100)
   /v1/home/feed:
     get:
       operationId: home_feed_get
@@ -4508,6 +5485,10 @@ paths:
                   - author
                   - createdAt
                 additionalProperties: false
+        "404":
+          description: Feed item not found
+        "500":
+          description: Failed to persist feed item status
       parameters:
         - name: id
           in: path
@@ -4553,6 +5534,10 @@ paths:
                 required:
                   - conversationId
                 additionalProperties: false
+        "404":
+          description: Feed item or action not found
+        "500":
+          description: Failed to create conversation
       parameters:
         - name: id
           in: path
@@ -4682,6 +5667,8 @@ paths:
                   - assistantName
                   - updatedAt
                 additionalProperties: false
+        "500":
+          description: Failed to compute relationship state
   /v1/host-bash-result:
     post:
       operationId: hostbashresult_post
@@ -4860,6 +5847,45 @@ paths:
               required:
                 - requestId
               additionalProperties: false
+  /v1/host-transfer-result:
+    post:
+      operationId: hosttransferresult_post
+      summary: Submit host transfer result
+      description: Resolve a pending to_host transfer after the client has downloaded and written the file.
+      tags:
+        - host-transfer
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accepted:
+                    type: boolean
+                required:
+                  - accepted
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                requestId:
+                  type: string
+                  description: Pending transfer request ID
+                isError:
+                  type: boolean
+                bytesWritten:
+                  type: number
+                errorMessage:
+                  type: string
+              required:
+                - requestId
+              additionalProperties: false
   /v1/identity:
     get:
       operationId: identity_get
@@ -4948,6 +5974,8 @@ paths:
                     type: string
                   localGatewayTarget:
                     type: string
+                  managedCallbacks:
+                    type: boolean
                   success:
                     type: boolean
                 required:
@@ -5000,145 +6028,183 @@ paths:
   /v1/integrations/slack/channel/config:
     delete:
       operationId: integrations_slack_channel_config_delete
+      summary: Clear Slack channel config
+      description: Clear stored Slack channel credentials.
       tags:
-        - channel
+        - integrations
       responses:
         "200":
           description: Successful response
     get:
       operationId: integrations_slack_channel_config_get
+      summary: Get Slack channel config
+      description: Check current Slack channel configuration status.
       tags:
-        - channel
+        - integrations
       responses:
         "200":
           description: Successful response
     post:
       operationId: integrations_slack_channel_config_post
+      summary: Set Slack channel config
+      description: Validate and store Slack channel credentials.
       tags:
-        - channel
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/slack/channel/oauth-install:
     post:
       operationId: integrations_slack_channel_oauthinstall_post
+      summary: Run Slack OAuth install
+      description: Run an OAuth2 loopback flow to install the Slack app and capture bot + user tokens.
       tags:
-        - channel
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/telegram/commands:
     post:
       operationId: integrations_telegram_commands_post
+      summary: Register Telegram commands
+      description: Register bot commands with the Telegram API.
       tags:
-        - telegram
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/telegram/config:
     delete:
       operationId: integrations_telegram_config_delete
+      summary: Clear Telegram config
+      description: Clear credentials and deregister webhook.
       tags:
-        - telegram
+        - integrations
       responses:
         "200":
           description: Successful response
     get:
       operationId: integrations_telegram_config_get
+      summary: Get Telegram config
+      description: Check current Telegram bot configuration status.
       tags:
-        - telegram
+        - integrations
       responses:
         "200":
           description: Successful response
     post:
       operationId: integrations_telegram_config_post
+      summary: Set Telegram config
+      description: Set bot token and configure webhook.
       tags:
-        - telegram
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/telegram/setup:
     post:
       operationId: integrations_telegram_setup_post
+      summary: Setup Telegram
+      description: "Composite: set config + register commands."
       tags:
-        - telegram
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/twilio/config:
     get:
       operationId: integrations_twilio_config_get
+      summary: Get Twilio config
+      description: Return current Twilio configuration status.
       tags:
-        - twilio
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/twilio/credentials:
     delete:
       operationId: integrations_twilio_credentials_delete
+      summary: Clear Twilio credentials
+      description: Remove stored Twilio credentials.
       tags:
-        - twilio
+        - integrations
       responses:
         "200":
           description: Successful response
     post:
       operationId: integrations_twilio_credentials_post
+      summary: Set Twilio credentials
+      description: Validate and store Twilio account SID and auth token.
       tags:
-        - twilio
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/twilio/numbers:
     get:
       operationId: integrations_twilio_numbers_get
+      summary: List Twilio numbers
+      description: List phone numbers on the Twilio account.
       tags:
-        - twilio
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/twilio/numbers/assign:
     post:
       operationId: integrations_twilio_numbers_assign_post
+      summary: Assign Twilio number
+      description: Assign an existing phone number to this assistant.
       tags:
-        - twilio
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/twilio/numbers/provision:
     post:
       operationId: integrations_twilio_numbers_provision_post
+      summary: Provision Twilio number
+      description: Search for and provision a new phone number.
       tags:
-        - twilio
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/twilio/numbers/release:
     post:
       operationId: integrations_twilio_numbers_release_post
+      summary: Release Twilio number
+      description: Release a phone number back to Twilio.
       tags:
-        - twilio
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/integrations/vercel/config:
     delete:
       operationId: integrations_vercel_config_delete
+      summary: Delete Vercel config
+      description: Delete the stored Vercel API token.
       tags:
-        - vercel
+        - integrations
       responses:
         "200":
           description: Successful response
     get:
       operationId: integrations_vercel_config_get
+      summary: Get Vercel config
+      description: Check if a Vercel API token is stored.
       tags:
-        - vercel
+        - integrations
       responses:
         "200":
           description: Successful response
     post:
       operationId: integrations_vercel_config_post
+      summary: Set or delete Vercel config
+      description: Set or delete the Vercel API token. Action is determined by the body action field.
       tags:
-        - vercel
+        - integrations
       responses:
         "200":
           description: Successful response
@@ -5218,6 +6284,8 @@ paths:
       responses:
         "200":
           description: Successful response
+        "500":
+          description: Failed to create archive
       requestBody:
         required: true
         content:
@@ -5234,9 +6302,7 @@ paths:
                   description: Scope to a single conversation
                   type: string
                 full:
-                  description:
-                    Full export — include messages, LLM request logs, and usage events for all conversations. Use for test data
-                    debugging.
+                  description: Full export — include messages, LLM request logs, and usage events for all conversations.
                   type: boolean
                 startTime:
                   description: Lower bound epoch ms
@@ -5320,7 +6386,7 @@ paths:
       tags:
         - memory
       responses:
-        "200":
+        "201":
           description: Successful response
           content:
             application/json:
@@ -5335,6 +6401,8 @@ paths:
                 required:
                   - item
                 additionalProperties: false
+        "409":
+          description: A memory with this content already exists
       requestBody:
         required: true
         content:
@@ -5366,18 +6434,8 @@ paths:
       tags:
         - memory
       responses:
-        "200":
+        "204":
           description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  ok:
-                    type: boolean
-                required:
-                  - ok
-                additionalProperties: false
       parameters:
         - name: id
           in: path
@@ -5434,6 +6492,8 @@ paths:
                 required:
                   - item
                 additionalProperties: false
+        "409":
+          description: Another memory item with this content already exists
       parameters:
         - name: id
           in: path
@@ -5458,6 +6518,75 @@ paths:
                 importance:
                   type: number
               additionalProperties: false
+  /v1/memory/v2/backfill:
+    post:
+      operationId: memory_v2_backfill_post
+      summary: Enqueue a memory v2 backfill job
+      description:
+        Enqueues one of four operator-triggered backfill jobs (migrate, rebuild-edges, reembed,
+        activation-recompute) against the memory jobs queue.
+      tags:
+        - memory
+      responses:
+        "200":
+          description: Successful response
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                op:
+                  type: string
+                  enum:
+                    - migrate
+                    - rebuild-edges
+                    - reembed
+                    - activation-recompute
+                force:
+                  type: boolean
+              required:
+                - op
+              additionalProperties: false
+  /v1/memory/v2/reembed-skills:
+    post:
+      operationId: memory_v2_reembedskills_post
+      summary: Re-seed v2 skill entries from the current skill catalog
+      description:
+        Synchronously re-runs seedV2SkillEntries against the current skill catalog. Gated on memory-v2-enabled flag
+        and config.memory.v2.enabled.
+      tags:
+        - memory
+      responses:
+        "200":
+          description: Successful response
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties: {}
+              additionalProperties: false
+  /v1/memory/v2/validate:
+    post:
+      operationId: memory_v2_validate_post
+      summary: Validate memory v2 workspace state
+      description: Read-only structural validation of the v2 workspace — reports orphan edges, oversized pages, and parse failures.
+      tags:
+        - memory
+      responses:
+        "200":
+          description: Successful response
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties: {}
+              additionalProperties: false
   /v1/messages:
     get:
       operationId: messages_get
@@ -5481,11 +6610,17 @@ paths:
                     description: Whether older messages exist beyond this page
                     type: boolean
                   oldestTimestamp:
-                    description: Timestamp of the oldest message in this page (ms since epoch)
-                    type: number
+                    description:
+                      Timestamp of the oldest message in this page (ms since epoch). Null when page=latest is used on an empty
+                      conversation.
+                    anyOf:
+                      - type: number
+                      - type: "null"
                   oldestMessageId:
                     description: ID of the oldest message in this page
-                    type: string
+                    anyOf:
+                      - type: string
+                      - type: "null"
                 required:
                   - messages
                 additionalProperties: false
@@ -5496,7 +6631,7 @@ paths:
       tags:
         - messages
       responses:
-        "200":
+        "202":
           description: Successful response
       requestBody:
         required: true
@@ -5518,6 +6653,17 @@ paths:
                   type: string
                 slashCommand:
                   type: string
+                inferenceProfile:
+                  anyOf:
+                    - type: string
+                    - type: "null"
+                riskThreshold:
+                  type: string
+                  enum:
+                    - none
+                    - low
+                    - medium
+                    - high
               required:
                 - content
               additionalProperties: false
@@ -5537,6 +6683,12 @@ paths:
           required: true
           schema:
             type: string
+        - name: conversationId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Optional conversation ID filter
   /v1/messages/{id}/llm-context:
     get:
       operationId: messages_by_id_llmcontext_get
@@ -5572,9 +6724,9 @@ paths:
           required: true
           schema:
             type: string
-  /v1/messages/{id}/tts:
+  /v1/messages/{messageId}/tts:
     post:
-      operationId: messages_by_id_tts_post
+      operationId: messages_by_messageId_tts_post
       summary: Synthesize message to speech
       description: Synthesize a message's text content to audio using the configured TTS provider.
       tags:
@@ -5583,7 +6735,7 @@ paths:
         "200":
           description: Successful response
       parameters:
-        - name: id
+        - name: messageId
           in: path
           required: true
           schema:
@@ -5610,6 +6762,12 @@ paths:
           required: true
           schema:
             type: string
+        - name: conversationId
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Conversation ID (required)
   /v1/migrations/export:
     post:
       operationId: migrations_export_post
@@ -5633,14 +6791,62 @@ paths:
               required:
                 - description
               additionalProperties: false
+  /v1/migrations/export-to-gcs:
+    post:
+      operationId: migrations_exporttogcs_post
+      summary: Start an async export streamed to a GCS signed URL
+      description:
+        Kick off a background export job that PUTs a freshly-built .vbundle archive to the supplied GCS signed URL.
+        Returns 202 with a job_id the caller can poll via the job-status endpoint. Fails fast with 409 if another export
+        job is already pending or running.
+      tags:
+        - migrations
+      responses:
+        "202":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  job_id:
+                    type: string
+                  status:
+                    type: string
+                    const: pending
+                  type:
+                    type: string
+                    const: export
+                required:
+                  - job_id
+                  - status
+                  - type
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                upload_url:
+                  type: string
+                  format: uri
+                  description: Signed GCS PUT URL that receives the exported bundle.
+                description:
+                  description: Human-readable export description.
+                  type: string
+              required:
+                - upload_url
+              additionalProperties: false
   /v1/migrations/import:
     post:
       operationId: migrations_import_post
       summary: Import a .vbundle archive
       description:
         Commit a .vbundle archive import to disk — destructive. Accepts the bundle as raw bytes
-        (application/octet-stream), multipart/form-data, or a JSON body carrying a signed URL the daemon fetches and
-        streams through the importer.
+        (application/octet-stream), multipart/form-data, or a JSON body with `{ url }` carrying a signed URL the daemon
+        fetches.
       tags:
         - migrations
       responses:
@@ -5675,55 +6881,67 @@ paths:
                   - warnings
                 additionalProperties: false
         "502":
-          description:
-            "Upstream fetch failed (URL body only). Body shape: { success: false, reason: 'fetch_failed',
-            upstream_status?: number }."
+          description: Upstream fetch failed (URL body only).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                url:
+                  type: string
+                  format: uri
+                  description: A signed GCS URL pointing to the .vbundle archive (JSON body path only).
+              required:
+                - url
+              additionalProperties: false
+  /v1/migrations/import-from-gcs:
+    post:
+      operationId: migrations_importfromgcs_post
+      summary: Start an async .vbundle import from a signed GCS URL
+      description:
+        Schedule a background import job that fetches the bundle at `bundle_url` and streams it through the
+        importer. Returns 202 with a `job_id`; poll `GET /v1/migrations/jobs/{job_id}` for status. 409 if another import
+        is already in flight.
+      tags:
+        - migrations
+      responses:
+        "202":
+          description: Successful response
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  success:
-                    type: boolean
-                  reason:
+                  job_id:
                     type: string
-                    enum:
-                      - fetch_failed
-                  upstream_status:
-                    type: integer
+                  status:
+                    type: string
+                    const: pending
+                  type:
+                    type: string
+                    const: import
                 required:
-                  - success
-                  - reason
+                  - job_id
+                  - status
+                  - type
+                additionalProperties: false
+        "409":
+          description: Another import job is already pending or running.
       requestBody:
         required: true
         content:
-          application/octet-stream:
-            schema:
-              type: string
-              format: binary
-              description: Raw .vbundle archive bytes.
-          multipart/form-data:
-            schema:
-              type: object
-              properties:
-                file:
-                  type: string
-                  format: binary
-                  description: The .vbundle archive uploaded as a file field.
-              required:
-                - file
           application/json:
             schema:
               type: object
               properties:
-                url:
+                bundle_url:
                   type: string
                   format: uri
-                  description:
-                    A signed GCS URL pointing to the .vbundle archive. The daemon fetches the URL and streams the body through
-                    the importer.
               required:
-                - url
+                - bundle_url
+              additionalProperties: false
   /v1/migrations/import-preflight:
     post:
       operationId: migrations_importpreflight_post
@@ -5762,11 +6980,14 @@ paths:
                   - conflicts
                   - manifest
                 additionalProperties: false
-  /v1/migrations/validate:
-    post:
-      operationId: migrations_validate_post
-      summary: Validate a .vbundle archive
-      description: Upload a .vbundle archive for validation. Accepts raw binary or multipart form data.
+  /v1/migrations/jobs/{job_id}:
+    get:
+      operationId: migrations_jobs_by_job_id_get
+      summary: Get migration job status
+      description:
+        "Return the current status of an async migration job (export or import). The response discriminates on
+        `status`: `processing` (pending or running), `complete` (with `result`), or `failed` (with `error`,
+        `error_code`, optional `upstream_status`)."
       tags:
         - migrations
       responses:
@@ -5775,41 +6996,126 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  is_valid:
-                    type: boolean
-                  errors:
-                    type: array
-                    items: {}
-                  manifest:
-                    type: object
-                    properties: {}
-                    additionalProperties: {}
-                required:
-                  - is_valid
-                  - errors
-                  - manifest
-                additionalProperties: false
-  /v1/model:
-    get:
-      operationId: model_get
-      summary: Get current model config
-      description: Return the active LLM model ID, provider, and available models.
-      tags:
-        - config
-      responses:
-        "200":
-          description: Successful response
-    put:
-      operationId: model_put
-      summary: Set LLM model
-      description: Change the active LLM model and optionally its provider.
-      tags:
-        - config
-      responses:
-        "200":
-          description: Successful response
+                oneOf:
+                  - type: object
+                    properties:
+                      job_id:
+                        type: string
+                      type:
+                        type: string
+                        enum:
+                          - export
+                          - import
+                      status:
+                        type: string
+                        const: processing
+                    required:
+                      - job_id
+                      - type
+                      - status
+                    additionalProperties: false
+                  - type: object
+                    properties:
+                      job_id:
+                        type: string
+                      type:
+                        type: string
+                        enum:
+                          - export
+                          - import
+                      status:
+                        type: string
+                        const: complete
+                      result: {}
+                    required:
+                      - job_id
+                      - type
+                      - status
+                      - result
+                    additionalProperties: false
+                  - type: object
+                    properties:
+                      job_id:
+                        type: string
+                      type:
+                        type: string
+                        enum:
+                          - export
+                          - import
+                      status:
+                        type: string
+                        const: failed
+                      error:
+                        type: string
+                      error_code:
+                        type: string
+                      upstream_status:
+                        type: integer
+                        minimum: -9007199254740991
+                        maximum: 9007199254740991
+                    required:
+                      - job_id
+                      - type
+                      - status
+                      - error
+                      - error_code
+                    additionalProperties: false
+        "404":
+          description: No job matches the given id.
+      parameters:
+        - name: job_id
+          in: path
+          required: true
+          schema:
+            type: string
+  /v1/migrations/validate:
+    post:
+      operationId: migrations_validate_post
+      summary: Validate a .vbundle archive
+      description: Upload a .vbundle archive for validation. Accepts raw binary or multipart form data.
+      tags:
+        - migrations
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  is_valid:
+                    type: boolean
+                  errors:
+                    type: array
+                    items: {}
+                  manifest:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                required:
+                  - is_valid
+                  - errors
+                  - manifest
+                additionalProperties: false
+  /v1/model:
+    get:
+      operationId: model_get
+      summary: Get current model config
+      description: Return the active LLM model ID, provider, and available models.
+      tags:
+        - config
+      responses:
+        "200":
+          description: Successful response
+    put:
+      operationId: model_put
+      summary: Set LLM model
+      description: Change the active LLM model and optionally its provider.
+      tags:
+        - config
+      responses:
+        "200":
+          description: Successful response
       requestBody:
         required: true
         content:
@@ -5889,26 +7195,191 @@ paths:
               required:
                 - deliveryId
               additionalProperties: false
+  /v1/notifications/emit:
+    post:
+      operationId: notifications_emit_post
+      summary: Emit a notification signal
+      description: Emit a notification signal into the pipeline for routing and delivery.
+      tags:
+        - notifications
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  signalId:
+                    type: string
+                  dispatched:
+                    type: boolean
+                  deduplicated:
+                    type: boolean
+                  reason:
+                    type: string
+                required:
+                  - signalId
+                  - dispatched
+                  - deduplicated
+                  - reason
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                sourceEventName:
+                  type: string
+                  minLength: 1
+                sourceChannel:
+                  type: string
+                  enum:
+                    - assistant_tool
+                    - vellum
+                    - phone
+                    - telegram
+                    - slack
+                    - scheduler
+                    - watcher
+                sourceContextId:
+                  type: string
+                  minLength: 1
+                attentionHints:
+                  type: object
+                  properties:
+                    requiresAction:
+                      type: boolean
+                    urgency:
+                      type: string
+                      enum:
+                        - low
+                        - medium
+                        - high
+                    deadlineAt:
+                      type: number
+                    isAsyncBackground:
+                      type: boolean
+                    visibleInSourceNow:
+                      type: boolean
+                  required:
+                    - requiresAction
+                    - urgency
+                    - isAsyncBackground
+                    - visibleInSourceNow
+                  additionalProperties: false
+                contextPayload:
+                  type: object
+                  propertyNames:
+                    type: string
+                  additionalProperties: {}
+                routingIntent:
+                  type: string
+                  enum:
+                    - single_channel
+                    - multi_channel
+                    - all_channels
+                dedupeKey:
+                  type: string
+                throwOnError:
+                  type: boolean
+              required:
+                - sourceEventName
+                - sourceChannel
+                - sourceContextId
+                - attentionHints
+              additionalProperties: false
+  /v1/notifications/events:
+    post:
+      operationId: notifications_events_post
+      summary: List notification events
+      description: List recent notification events, optionally filtered by source event name.
+      tags:
+        - notifications
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    sourceEventName:
+                      type: string
+                    sourceChannel:
+                      type: string
+                    sourceContextId:
+                      type: string
+                    urgency:
+                      type: string
+                    dedupeKey:
+                      anyOf:
+                        - type: string
+                        - type: "null"
+                    createdAt:
+                      type: string
+                  required:
+                    - id
+                    - sourceEventName
+                    - sourceChannel
+                    - sourceContextId
+                    - urgency
+                    - dedupeKey
+                    - createdAt
+                  additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                limit:
+                  type: integer
+                  exclusiveMinimum: 0
+                  maximum: 9007199254740991
+                sourceEventName:
+                  type: string
+              additionalProperties: false
   /v1/oauth/apps:
     get:
       operationId: oauth_apps_get
+      summary: List OAuth apps
+      description: List OAuth apps filtered by provider_key.
       tags:
-        - oauth-apps
+        - oauth
       responses:
         "200":
           description: Successful response
+      parameters:
+        - name: provider_key
+          in: query
+          required: true
+          schema:
+            type: string
+          description: OAuth provider key to filter by
     post:
       operationId: oauth_apps_post
+      summary: Create OAuth app
+      description: Register a new OAuth app with client credentials.
       tags:
-        - oauth-apps
+        - oauth
       responses:
-        "200":
+        "201":
           description: Successful response
   /v1/oauth/apps/{appId}/connect:
     post:
       operationId: oauth_apps_by_appId_connect_post
+      summary: Start OAuth connect
+      description: Start an OAuth connect flow for an app.
       tags:
-        - oauth-apps
+        - oauth
       responses:
         "200":
           description: Successful response
@@ -5921,8 +7392,10 @@ paths:
   /v1/oauth/apps/{appId}/connections:
     get:
       operationId: oauth_apps_by_appId_connections_get
+      summary: List OAuth connections
+      description: List connections for an OAuth app.
       tags:
-        - oauth-apps
+        - oauth
       responses:
         "200":
           description: Successful response
@@ -5935,8 +7408,10 @@ paths:
   /v1/oauth/apps/{id}:
     delete:
       operationId: oauth_apps_by_id_delete
+      summary: Delete OAuth app
+      description: Delete an OAuth app and disconnect all its connections.
       tags:
-        - oauth-apps
+        - oauth
       responses:
         "200":
           description: Successful response
@@ -5949,8 +7424,10 @@ paths:
   /v1/oauth/connections/{id}:
     delete:
       operationId: oauth_connections_by_id_delete
+      summary: Disconnect OAuth connection
+      description: Disconnect a single OAuth connection.
       tags:
-        - oauth-apps
+        - oauth
       responses:
         "200":
           description: Successful response
@@ -5963,16 +7440,27 @@ paths:
   /v1/oauth/providers:
     get:
       operationId: oauth_providers_get
+      summary: List OAuth providers
+      description: List all registered OAuth providers with optional filtering.
       tags:
-        - oauth-providers
+        - oauth
       responses:
         "200":
           description: Successful response
+      parameters:
+        - name: supports_managed_mode
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter by managed mode support (true/false)
   /v1/oauth/providers/{providerKey}:
     get:
       operationId: oauth_providers_by_providerKey_get
+      summary: Get OAuth provider
+      description: Get a single OAuth provider by key.
       tags:
-        - oauth-providers
+        - oauth
       responses:
         "200":
           description: Successful response
@@ -6008,46 +7496,22 @@ paths:
                 - service
                 - requestedScopes
               additionalProperties: false
-  /v1/pairing/register:
-    post:
-      operationId: pairing_register_post
-      summary: Register pairing request
-      description: Pre-register a pairing request when the QR code is displayed.
+  /v1/pages/{appId}:
+    get:
+      operationId: pages_by_appId_get
+      summary: Serve app page
+      description: Render and serve a shareable app page as HTML.
       tags:
-        - pairing
+        - apps
       responses:
         "200":
           description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  ok:
-                    type: boolean
-                required:
-                  - ok
-                additionalProperties: false
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                pairingRequestId:
-                  type: string
-                pairingSecret:
-                  type: string
-                gatewayUrl:
-                  type: string
-                localLanUrl:
-                  type: string
-              required:
-                - pairingRequestId
-                - pairingSecret
-                - gatewayUrl
-              additionalProperties: false
+      parameters:
+        - name: appId
+          in: path
+          required: true
+          schema:
+            type: string
   /v1/pairing/request:
     post:
       operationId: pairing_request_post
@@ -6340,6 +7804,50 @@ paths:
           required: true
           schema:
             type: string
+  /v1/ps:
+    get:
+      operationId: ps_get
+      summary: Process status
+      description: Returns a JSON summary of the assistant's process tree including qdrant and embed-worker status.
+      tags:
+        - system
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  processes:
+                    type: array
+                    items:
+                      $ref: "#/$defs/__schema0"
+                required:
+                  - processes
+                additionalProperties: false
+                $defs:
+                  __schema0:
+                    type: object
+                    properties:
+                      name:
+                        type: string
+                      status:
+                        type: string
+                        enum:
+                          - running
+                          - not_running
+                          - unreachable
+                      children:
+                        type: array
+                        items:
+                          $ref: "#/$defs/__schema0"
+                      info:
+                        type: string
+                    required:
+                      - name
+                      - status
+                    additionalProperties: false
   /v1/recordings/pause:
     post:
       operationId: recordings_pause_post
@@ -6418,7 +7926,7 @@ paths:
       tags:
         - recordings
       responses:
-        "200":
+        "201":
           description: Successful response
           content:
             application/json:
@@ -6572,6 +8080,13 @@ paths:
                 required:
                   - schedules
                 additionalProperties: false
+      parameters:
+        - name: include_all
+          in: query
+          required: false
+          schema:
+            type: string
+          description: When 'true', include deferred schedules that are normally hidden.
   /v1/schedules/{id}:
     delete:
       operationId: schedules_by_id_delete
@@ -6752,6 +8267,12 @@ paths:
           required: true
           schema:
             type: string
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+          description: Max runs to return (default 10, max 100)
   /v1/schedules/{id}/toggle:
     post:
       operationId: schedules_by_id_toggle_post
@@ -6846,7 +8367,7 @@ paths:
       parameters:
         - name: q
           in: query
-          required: false
+          required: true
           schema:
             type: string
           description: Search query (required)
@@ -7404,7 +8925,7 @@ paths:
       tags:
         - skills
       responses:
-        "200":
+        "201":
           description: Successful response
           content:
             application/json:
@@ -7445,7 +8966,7 @@ paths:
       tags:
         - skills
       responses:
-        "200":
+        "204":
           description: Successful response
       parameters:
         - name: id
@@ -8249,37 +9770,97 @@ paths:
   /v1/slack/channels:
     get:
       operationId: slack_channels_get
+      summary: List Slack channels
+      description: List Slack channels, groups, and DMs for the channel picker.
       tags:
-        - share
+        - integrations
       responses:
         "200":
           description: Successful response
   /v1/slack/share:
     post:
       operationId: slack_share_post
+      summary: Share to Slack channel
+      description: Post an app link directly to a Slack channel.
       tags:
-        - share
+        - integrations
       responses:
         "200":
           description: Successful response
-  /v1/stt/transcribe:
-    post:
-      operationId: stt_transcribe_post
-      summary: Transcribe audio to text
-      description:
-        Transcribe base64-encoded audio to text using the configured STT provider. Provider selection is resolved
-        globally via config.
+  /v1/stt/providers:
+    get:
+      operationId: stt_providers_get
+      summary: List STT providers
+      description: Return the catalog of available STT providers with client-facing metadata.
       tags:
         - stt
       responses:
         "200":
           description: Successful response
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  providers:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        displayName:
+                          type: string
+                        subtitle:
+                          type: string
+                        setupMode:
+                          type: string
+                        setupHint:
+                          type: string
+                        apiKeyProviderName:
+                          type: string
+                        conversationStreamingMode:
+                          type: string
+                        credentialsGuide:
+                          type: string
+                      required:
+                        - id
+                        - displayName
+                      additionalProperties: false
+                required:
+                  - providers
+                additionalProperties: false
+  /v1/stt/transcribe:
+    post:
+      operationId: stt_transcribe_post
+      summary: Transcribe audio to text
+      description: Transcribe base64-encoded audio to text using the configured STT provider.
+      tags:
+        - stt
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  text:
+                    type: string
+                  providerId:
+                    type: string
+                  boundaryId:
+                    type: string
+                required:
+                  - text
+                  - providerId
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
               properties:
                 audioBase64:
                   type: string
@@ -8464,9 +10045,7 @@ paths:
                     type: boolean
                   conversationId:
                     type: string
-                    description:
-                      Id of a newly launched conversation when the action dispatched one (e.g. launch_conversation). Omitted
-                      otherwise.
+                    description: Id of a newly launched conversation when the action dispatched one. Omitted otherwise.
                 required:
                   - ok
                 additionalProperties: false
@@ -8578,6 +10157,378 @@ paths:
           schema:
             type: string
           description: Conversation that owns the surface
+  /v1/tasks/delete:
+    post:
+      operationId: tasks_delete_post
+      summary: Delete task templates
+      description: Delete one or more task templates by ID.
+      tags:
+        - tasks
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  content:
+                    type: string
+                required:
+                  - ok
+                  - content
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                task_ids:
+                  minItems: 1
+                  type: array
+                  items:
+                    type: string
+                    minLength: 1
+              required:
+                - task_ids
+              additionalProperties: false
+  /v1/tasks/list:
+    post:
+      operationId: tasks_list_post
+      summary: List task templates
+      description: List all saved task templates.
+      tags:
+        - tasks
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  content:
+                    type: string
+                required:
+                  - ok
+                  - content
+                additionalProperties: false
+  /v1/tasks/queue/add:
+    post:
+      operationId: tasks_queue_add_post
+      summary: Add to task queue
+      description: Add a new work item to the task queue.
+      tags:
+        - tasks
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  content:
+                    type: string
+                  isError:
+                    type: boolean
+                required:
+                  - content
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                task_id:
+                  type: string
+                task_name:
+                  type: string
+                title:
+                  type: string
+                execution_prompt:
+                  type: string
+                notes:
+                  type: string
+                priority_tier:
+                  type: number
+                sort_index:
+                  type: number
+                if_exists:
+                  type: string
+                  enum:
+                    - create_duplicate
+                    - reuse_existing
+                    - update_existing
+                required_tools:
+                  type: array
+                  items:
+                    type: string
+              additionalProperties: false
+  /v1/tasks/queue/remove:
+    post:
+      operationId: tasks_queue_remove_post
+      summary: Remove from task queue
+      description: Remove a work item from the task queue.
+      tags:
+        - tasks
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  content:
+                    type: string
+                  isError:
+                    type: boolean
+                required:
+                  - content
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                work_item_id:
+                  type: string
+                task_id:
+                  type: string
+                task_name:
+                  type: string
+                title:
+                  type: string
+                priority_tier:
+                  type: number
+                status:
+                  type: string
+                created_order:
+                  type: number
+              additionalProperties: false
+  /v1/tasks/queue/run:
+    post:
+      operationId: tasks_queue_run_post
+      summary: Run next task queue item
+      description: Pick up and execute the next work item from the queue.
+      tags:
+        - tasks
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  content:
+                    type: string
+                  isError:
+                    type: boolean
+                required:
+                  - content
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                work_item_id:
+                  type: string
+                task_name:
+                  type: string
+                title:
+                  type: string
+              additionalProperties: false
+  /v1/tasks/queue/show:
+    post:
+      operationId: tasks_queue_show_post
+      summary: Show task queue
+      description: List work items in the task queue, optionally filtered by status.
+      tags:
+        - tasks
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  content:
+                    type: string
+                  isError:
+                    type: boolean
+                required:
+                  - content
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                status:
+                  anyOf:
+                    - type: string
+                    - type: array
+                      items:
+                        type: string
+              additionalProperties: false
+  /v1/tasks/queue/update:
+    post:
+      operationId: tasks_queue_update_post
+      summary: Update a task queue item
+      description: Update an existing work item in the task queue.
+      tags:
+        - tasks
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  content:
+                    type: string
+                  isError:
+                    type: boolean
+                required:
+                  - content
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                work_item_id:
+                  type: string
+                task_id:
+                  type: string
+                task_name:
+                  type: string
+                title:
+                  type: string
+                priority_tier:
+                  type: number
+                notes:
+                  type: string
+                status:
+                  type: string
+                  enum:
+                    - queued
+                    - running
+                    - awaiting_review
+                    - done
+                    - failed
+                    - cancelled
+                    - archived
+                sort_index:
+                  type: number
+                filter_priority_tier:
+                  type: number
+                filter_status:
+                  type: string
+                created_order:
+                  type: number
+              additionalProperties: false
+  /v1/tasks/run:
+    post:
+      operationId: tasks_run_post
+      summary: Run a task template
+      description: Execute a saved task template by name or ID.
+      tags:
+        - tasks
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  content:
+                    type: string
+                required:
+                  - ok
+                  - content
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                task_name:
+                  type: string
+                  minLength: 1
+                task_id:
+                  type: string
+                  minLength: 1
+                inputs:
+                  type: object
+                  propertyNames:
+                    type: string
+                  additionalProperties:
+                    type: string
+              additionalProperties: false
+  /v1/tasks/save:
+    post:
+      operationId: tasks_save_post
+      summary: Save a task template
+      description: Save the current conversation as a reusable task template.
+      tags:
+        - tasks
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  content:
+                    type: string
+                required:
+                  - ok
+                  - content
+                additionalProperties: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversation_id:
+                  type: string
+                  minLength: 1
+                title:
+                  type: string
+                  minLength: 1
+              additionalProperties: false
   /v1/telemetry/lifecycle:
     post:
       operationId: telemetry_lifecycle_post
@@ -8660,15 +10611,12 @@ paths:
                   additionalProperties: {}
                 workingDir:
                   type: string
-                forcePromptSideEffects:
-                  type: boolean
                 isInteractive:
                   type: boolean
               required:
                 - toolName
                 - input
                 - workingDir
-                - forcePromptSideEffects
                 - isInteractive
               additionalProperties: false
   /v1/trace-events:
@@ -8712,95 +10660,75 @@ paths:
           schema:
             type: integer
           description: Return events after this sequence number
-  /v1/trust-rules:
-    post:
-      operationId: trustrules_post
-      summary: Add a trust rule for a pending confirmation
-      description: Add a trust rule bound to a pending confirmation without resolving it.
+  /v1/transfers/{transferId}/content:
+    get:
+      operationId: transfers_by_transferId_content_get
+      summary: Get transfer content
+      description: "Serve raw file bytes for a to_host transfer. Single-use: returns 404 after first consumption."
       tags:
-        - approvals
+        - host-transfer
       responses:
         "200":
           description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  accepted:
-                    type: boolean
-                required:
-                  - accepted
-                additionalProperties: false
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                requestId:
-                  type: string
-                  description: Pending confirmation request ID
-                pattern:
-                  type: string
-                  description: Allowlist pattern
-                scope:
-                  type: string
-                  description: Scope for the rule
-                decision:
-                  type: string
-                  description: allow or deny
-              required:
-                - requestId
-                - pattern
-                - scope
-                - decision
-              additionalProperties: false
-  /v1/trust-rules/manage:
+      parameters:
+        - name: transferId
+          in: path
+          required: true
+          schema:
+            type: string
+    put:
+      operationId: transfers_by_transferId_content_put
+      summary: Put transfer content
+      description: Receive raw file bytes for a to_sandbox transfer. Verifies SHA-256 integrity via the X-Transfer-SHA256 header.
+      tags:
+        - host-transfer
+      responses:
+        "200":
+          description: Successful response
+      parameters:
+        - name: transferId
+          in: path
+          required: true
+          schema:
+            type: string
+  /v1/trust-rules:
     get:
-      operationId: trustrules_manage_get
-      summary: List all trust rules
-      description: Return all persistent trust rules.
+      operationId: trustrules_get
+      summary: List trust rules
+      description: List trust rules, optionally filtered by tool, origin, or include_all.
       tags:
         - trust-rules
       responses:
         "200":
           description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  type:
-                    type: string
-                  rules:
-                    type: array
-                    items: {}
-                    description: Trust rule objects
-                required:
-                  - type
-                  - rules
-                additionalProperties: false
+      parameters:
+        - name: tool
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter by tool name
+        - name: origin
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Filter by origin
+        - name: include_all
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Include unmodified defaults
     post:
-      operationId: trustrules_manage_post
-      summary: Add a trust rule
-      description: Create a new persistent trust rule (standalone, not approval-flow).
+      operationId: trustrules_post
+      summary: Create a trust rule
+      description: Create a new trust rule with tool, pattern, risk level, and optional description.
       tags:
         - trust-rules
       responses:
         "200":
           description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  ok:
-                    type: boolean
-                required:
-                  - ok
-                additionalProperties: false
       requestBody:
         required: true
         content:
@@ -8808,29 +10736,22 @@ paths:
             schema:
               type: object
               properties:
-                toolName:
+                tool:
                   type: string
-                  description: Tool name
                 pattern:
                   type: string
-                  description: Allowlist pattern
-                scope:
+                risk:
                   type: string
-                  description: Scope (required for scoped tools, ignored for others)
-                decision:
-                  type: string
-                  description: allow, deny, or ask
-                executionTarget:
+                description:
                   type: string
-                  description: Execution target
               required:
-                - toolName
+                - tool
                 - pattern
-                - decision
+                - risk
               additionalProperties: false
-  /v1/trust-rules/manage/{id}:
+  /v1/trust-rules/{id}:
     delete:
-      operationId: trustrules_manage_by_id_delete
+      operationId: trustrules_by_id_delete
       summary: Remove a trust rule
       description: Delete a trust rule by ID.
       tags:
@@ -8838,16 +10759,6 @@ paths:
       responses:
         "200":
           description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  ok:
-                    type: boolean
-                required:
-                  - ok
-                additionalProperties: false
       parameters:
         - name: id
           in: path
@@ -8855,11 +10766,39 @@ paths:
           schema:
             type: string
     patch:
-      operationId: trustrules_manage_by_id_patch
+      operationId: trustrules_by_id_patch
       summary: Update a trust rule
-      description: Partially update fields on an existing trust rule.
+      description: Update the risk level or description of an existing trust rule.
+      tags:
+        - trust-rules
+      responses:
+        "200":
+          description: Successful response
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                risk:
+                  type: string
+                description:
+                  type: string
+              additionalProperties: false
+  /v1/trust-rules/suggest:
+    post:
+      operationId: trustrules_suggest_post
+      summary: Suggest a trust rule
+      description: Use an LLM to suggest a trust rule pattern, risk level, and scope for a given action.
       tags:
-        - trust-rules
+        - trust
       responses:
         "200":
           description: Successful response
@@ -8868,17 +10807,46 @@ paths:
               schema:
                 type: object
                 properties:
-                  ok:
-                    type: boolean
+                  pattern:
+                    type: string
+                  risk:
+                    type: string
+                  scope:
+                    type: string
+                  description:
+                    type: string
+                  scopeOptions:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        pattern:
+                          type: string
+                        label:
+                          type: string
+                      required:
+                        - pattern
+                        - label
+                      additionalProperties: false
+                  directoryScopeOptions:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        scope:
+                          type: string
+                        label:
+                          type: string
+                      required:
+                        - scope
+                        - label
+                      additionalProperties: false
                 required:
-                  - ok
+                  - pattern
+                  - risk
+                  - description
+                  - scopeOptions
                 additionalProperties: false
-      parameters:
-        - name: id
-          in: path
-          required: true
-          schema:
-            type: string
       requestBody:
         required: true
         content:
@@ -8888,33 +10856,70 @@ paths:
               properties:
                 tool:
                   type: string
-                  description: Tool name
-                pattern:
+                  minLength: 1
+                command:
                   type: string
-                  description: Allowlist pattern
-                scope:
+                  minLength: 1
+                riskAssessment:
+                  type: object
+                  properties:
+                    risk:
+                      type: string
+                    reasoning:
+                      type: string
+                    reasonDescription:
+                      type: string
+                  required:
+                    - risk
+                    - reasoning
+                    - reasonDescription
+                  additionalProperties: false
+                scopeOptions:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      pattern:
+                        type: string
+                      label:
+                        type: string
+                    required:
+                      - pattern
+                      - label
+                    additionalProperties: false
+                directoryScopeOptions:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      scope:
+                        type: string
+                      label:
+                        type: string
+                    required:
+                      - scope
+                      - label
+                    additionalProperties: false
+                currentThreshold:
                   type: string
-                  description: Scope
-                decision:
+                intent:
                   type: string
-                  description: allow, deny, or ask
-                priority:
-                  type: number
-                  description: Rule priority
+                  enum:
+                    - auto_approve
+                    - escalate
               required:
                 - tool
-                - pattern
-                - scope
-                - decision
-                - priority
+                - command
+                - riskAssessment
+                - scopeOptions
+                - currentThreshold
+                - intent
               additionalProperties: false
   /v1/tts/synthesize:
     post:
       operationId: tts_synthesize_post
       summary: Synthesize text to speech
-      description:
-        Synthesize arbitrary text to audio using the configured TTS provider. Provider selection is resolved
-        globally via config — callers do not specify a provider.
+      description: Synthesize arbitrary text to audio using the configured TTS provider.
       tags:
         - tts
       responses:
@@ -8931,9 +10936,7 @@ paths:
                   type: string
                   description: Text to synthesize into speech
                 context:
-                  description:
-                    Optional context hint for output policy or capability selection (e.g. voice-mode). Does not affect provider
-                    selection.
+                  description: Optional context hint for output policy or capability selection.
                   type: string
                 conversationId:
                   description: Optional conversation ID for scoping or analytics.
@@ -8941,6 +10944,68 @@ paths:
               required:
                 - text
               additionalProperties: false
+  /v1/ui/request:
+    post:
+      operationId: ui_request_post
+      summary: Present an interactive UI surface
+      description: Present an interactive UI surface to the user and await their response.
+      tags:
+        - ui
+      responses:
+        "200":
+          description: Successful response
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversationId:
+                  type: string
+                  minLength: 1
+                surfaceType:
+                  type: string
+                  enum:
+                    - confirmation
+                    - form
+                title:
+                  type: string
+                data:
+                  type: object
+                  propertyNames:
+                    type: string
+                  additionalProperties: {}
+                actions:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        minLength: 1
+                      label:
+                        type: string
+                        minLength: 1
+                      variant:
+                        type: string
+                        enum:
+                          - primary
+                          - danger
+                          - secondary
+                    required:
+                      - id
+                      - label
+                    additionalProperties: false
+                timeoutMs:
+                  type: integer
+                  exclusiveMinimum: 0
+                  maximum: 9007199254740991
+              required:
+                - conversationId
+                - surfaceType
+                - data
+              additionalProperties: false
   /v1/usage/breakdown:
     get:
       operationId: usage_breakdown_get
@@ -9057,6 +11122,196 @@ paths:
           schema:
             type: integer
           description: End epoch millis (required)
+  /v1/watchers/create:
+    post:
+      operationId: watchers_create_post
+      summary: Create a watcher
+      description: Create a new watcher with a provider and action prompt.
+      tags:
+        - watchers
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+                additionalProperties: {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  minLength: 1
+                provider:
+                  type: string
+                  minLength: 1
+                action_prompt:
+                  type: string
+                  minLength: 1
+                poll_interval_ms:
+                  type: integer
+                  minimum: 15000
+                  maximum: 9007199254740991
+                config:
+                  type: object
+                  propertyNames:
+                    type: string
+                  additionalProperties: {}
+                credential_service:
+                  type: string
+              required:
+                - name
+                - provider
+                - action_prompt
+              additionalProperties: false
+  /v1/watchers/delete:
+    post:
+      operationId: watchers_delete_post
+      summary: Delete a watcher
+      description: Delete a watcher by ID.
+      tags:
+        - watchers
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+                additionalProperties: {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                watcher_id:
+                  type: string
+                  minLength: 1
+              required:
+                - watcher_id
+              additionalProperties: false
+  /v1/watchers/digest:
+    post:
+      operationId: watchers_digest_post
+      summary: Get watcher event digest
+      description: Get recent watcher events, optionally filtered by watcher ID.
+      tags:
+        - watchers
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+                additionalProperties: {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                watcher_id:
+                  type: string
+                hours:
+                  default: 24
+                  type: number
+                  exclusiveMinimum: 0
+                limit:
+                  default: 50
+                  type: integer
+                  exclusiveMinimum: 0
+                  maximum: 9007199254740991
+              required:
+                - hours
+                - limit
+              additionalProperties: false
+  /v1/watchers/list:
+    post:
+      operationId: watchers_list_post
+      summary: List watchers
+      description: List all watchers, or get details for a specific watcher by ID.
+      tags:
+        - watchers
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+                additionalProperties: {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                watcher_id:
+                  type: string
+                enabled_only:
+                  default: false
+                  type: boolean
+              required:
+                - enabled_only
+              additionalProperties: false
+  /v1/watchers/update:
+    post:
+      operationId: watchers_update_post
+      summary: Update a watcher
+      description: Update an existing watcher's configuration.
+      tags:
+        - watchers
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+                additionalProperties: {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                watcher_id:
+                  type: string
+                  minLength: 1
+                name:
+                  type: string
+                action_prompt:
+                  type: string
+                poll_interval_ms:
+                  type: integer
+                  minimum: 15000
+                  maximum: 9007199254740991
+                enabled:
+                  type: boolean
+                config:
+                  type: object
+                  propertyNames:
+                    type: string
+                  additionalProperties: {}
+              required:
+                - watcher_id
+              additionalProperties: false
   /v1/work-items:
     get:
       operationId: workitems_get
@@ -9078,6 +11333,21 @@ paths:
                 required:
                   - items
                 additionalProperties: false
+      parameters:
+        - name: status
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - pending
+              - running
+              - awaiting_review
+              - done
+              - failed
+              - cancelled
+              - archived
+          description: Filter by work item status
   /v1/work-items/{id}:
     delete:
       operationId: workitems_by_id_delete
@@ -9192,6 +11462,10 @@ paths:
       responses:
         "200":
           description: Successful response
+        "404":
+          description: Work item not found
+        "409":
+          description: Work item is not running
       parameters:
         - name: id
           in: path
@@ -9292,6 +11566,12 @@ paths:
       responses:
         "200":
           description: Successful response
+        "403":
+          description: Required tool permissions not approved
+        "404":
+          description: Work item or associated task not found
+        "409":
+          description: Work item is already running or not runnable
       parameters:
         - name: id
           in: path
@@ -9318,6 +11598,13 @@ paths:
       responses:
         "200":
           description: Successful response
+      parameters:
+        - name: path
+          in: query
+          required: true
+          schema:
+            type: string
+          description: File path to read
   /v1/workspace/delete:
     post:
       operationId: workspace_delete_post
@@ -9328,6 +11615,16 @@ paths:
       responses:
         "200":
           description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                required:
+                  - success
+                additionalProperties: false
       requestBody:
         required: true
         content:
@@ -9403,13 +11700,15 @@ paths:
       responses:
         "200":
           description: Successful response
+        "416":
+          description: Range Not Satisfiable
       parameters:
         - name: path
           in: query
-          required: false
+          required: true
           schema:
             type: string
-          description: Relative file path (required)
+          description: Relative file path
         - name: showHidden
           in: query
           required: false