@vellumai/assistant 0.11.4-staging.2 → 0.11.4-staging.4

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -11,6 +11,12 @@
  *       (`gateway/src/http/routes/remote-web-pairing-verification.ts`)
  *   - `POST /v1/remote-web/pairing-token`         poll + exchange device code
  *       (`gateway/src/http/routes/remote-web-pairing-token.ts`)
+ *   - `GET  /v1/remote-web/pairing-requests`          list pending challenges
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/approve`  approve by request id
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/deny`     deny (delete) by request id
+ *       (loopback-only)
  *
  * These shapes mirror those handlers' request/response bodies exactly so the
  * gateway, the `vellum pair` CLI (`cli/src/commands/pair.ts`), and the web SPA
@@ -68,6 +74,60 @@ export interface RemoteWebPairingVerificationResponse {
   expiresAt: string;
 }
 
+/**
+ * One pending challenge as shown on a host approval surface.
+ *
+ * The requesting device already sees the plaintext `userCode` in its own
+ * challenge response ({@link RemoteWebPairingChallengeResponse.userCode});
+ * the loopback-gated list route is the only host-side re-exposure. Displaying
+ * it there is what lets the approver match the code against the requesting
+ * device's screen: the device-flow anti-phishing binding.
+ */
+export interface RemoteWebPairingRequestSummary {
+  /** Opaque server-side id used to approve or deny this request. */
+  requestId: string;
+  /** The human-readable code the requesting device is displaying (e.g. "ABCD-EFGH"). */
+  userCode: string;
+  /** Public base URL the challenge was minted for. */
+  publicBaseUrl: string;
+  /** ISO-8601 instant the challenge was minted. */
+  requestedAt: string;
+  /** ISO-8601 instant the challenge expires. */
+  expiresAt: string;
+  /**
+   * Client IP of the mint request: the loopback/host address when minted
+   * locally, or the edge-observed client address when the mint arrived
+   * through the nginx tunnel edge (which stamps it via `proxy_set_header`,
+   * so a remote client cannot smuggle a value).
+   */
+  requesterIp: string;
+  /** User-Agent header of the mint request, or null when absent. */
+  requesterUserAgent: string | null;
+  /**
+   * Whether the mint arrived through the public tunnel edge rather than the
+   * host itself.
+   */
+  viaEdgeProxy: boolean;
+}
+
+/** `GET /v1/remote-web/pairing-requests` success response body (200). */
+export interface RemoteWebPairingRequestListResponse {
+  requests: RemoteWebPairingRequestSummary[];
+}
+
+/**
+ * Request body for the pairing-request approve and deny routes. The approve
+ * route's success body reuses {@link RemoteWebPairingVerificationResponse}.
+ */
+export interface RemoteWebPairingRequestActionRequest {
+  requestId: string;
+}
+
+/** `POST /v1/remote-web/pairing-requests/deny` success response body (200). */
+export interface RemoteWebPairingRequestDenyResponse {
+  status: "denied";
+}
+
 /** `POST /v1/remote-web/pairing-token` request body. */
 export interface RemoteWebPairingTokenRequest {
   /** The `deviceCode` from the challenge. */

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.11.3
+  version: 0.11.4
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -6596,6 +6596,18 @@ paths:
             "system:all" for conversations in no group, "system:pinned" for the Pinned section, or a custom group id. A
             group-scoped request is recency-ordered like every list read (COALESCE(last_message_at, updated_at)
             descending) and never has pinned rows appended to it. Omit to span every group.
+        - name: needsAttention
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - "true"
+          description:
+            'Pass "true" to return only conversations whose latest assistant message the user has not seen: the same
+            predicate behind the unread count and the section index, so a client that keeps no complete conversation
+            list can ask for exactly the rows its attention surfaces need. Composes with every other filter. Any value
+            other than "true" is rejected. Omit to span every conversation.'
       responses:
         "200":
           description: Successful response
@@ -6953,7 +6965,9 @@ paths:
     get:
       operationId: conversations_by_id_get
       summary: Get conversation detail
-      description: Retrieve a single conversation with full metadata.
+      description:
+        Retrieve a single conversation with full metadata. Rows the listing hides by type (legacy private rows) are
+        not found here either.
       tags:
         - conversations
       parameters:
@@ -10906,11 +10920,6 @@ paths:
                     type: number
                   updatedAt:
                     type: number
-                  workspacePath:
-                    anyOf:
-                      - type: string
-                      - type: "null"
-                    description: Workspace-relative file this document is bound to, or null
                 required:
                   - success
                   - surfaceId
@@ -10920,7 +10929,6 @@ paths:
                   - wordCount
                   - createdAt
                   - updatedAt
-                  - workspacePath
                 additionalProperties: false
   /v1/documents/{id}/comments:
     get:
@@ -11338,74 +11346,6 @@ paths:
               schema:
                 type: string
                 format: binary
-  /v1/documents/for-workspace-file:
-    post:
-      operationId: documents_forworkspacefile_post
-      summary: Get or create the document for a workspace markdown file
-      description:
-        "Return the document bound to a workspace markdown file, creating it on first open. The file is the source
-        of truth at open time: stored content that has drifted from the file is refreshed from disk before the document
-        is returned."
-      tags:
-        - documents
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                path:
-                  type: string
-                  description: Workspace-relative path to a .md/.markdown file
-                conversationId:
-                  type: string
-                  description: Conversation the document is opened from
-              required:
-                - path
-                - conversationId
-      responses:
-        "200":
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  success:
-                    type: boolean
-                  surfaceId:
-                    type: string
-                  conversationId:
-                    type: string
-                  title:
-                    type: string
-                  content:
-                    type: string
-                  wordCount:
-                    type: number
-                  createdAt:
-                    type: number
-                  updatedAt:
-                    type: number
-                  workspacePath:
-                    anyOf:
-                      - type: string
-                      - type: "null"
-                    description: Workspace-relative file this document is bound to, or null
-                required:
-                  - success
-                  - surfaceId
-                  - conversationId
-                  - title
-                  - content
-                  - wordCount
-                  - createdAt
-                  - updatedAt
-                  - workspacePath
-                additionalProperties: false
-        "422":
-          description: Path is not a markdown file
   /v1/domain/register:
     post:
       operationId: domain_register_post
@@ -25778,6 +25718,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -25814,6 +25768,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26011,6 +25966,20 @@ paths:
                         description:
                           User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                           applies. Always null for user-created schedules.
+                      disarmReason:
+                        anyOf:
+                          - type: string
+                            enum:
+                              - user_disabled
+                              - plugin_removed
+                              - plugin_disabled
+                              - declaration_removed
+                              - declaration_disabled
+                          - type: "null"
+                        description:
+                          "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                          the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                          is on, and always null for user-created schedules."
                       isOneShot:
                         type: boolean
                       isDeferred:
@@ -26047,6 +26016,7 @@ paths:
                       - workflowName
                       - sourceKey
                       - userEnabled
+                      - disarmReason
                       - isOneShot
                       - isDeferred
                     additionalProperties: false
@@ -26196,6 +26166,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26232,6 +26216,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26378,6 +26363,20 @@ paths:
                         description:
                           User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                           applies. Always null for user-created schedules.
+                      disarmReason:
+                        anyOf:
+                          - type: string
+                            enum:
+                              - user_disabled
+                              - plugin_removed
+                              - plugin_disabled
+                              - declaration_removed
+                              - declaration_disabled
+                          - type: "null"
+                        description:
+                          "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                          the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                          is on, and always null for user-created schedules."
                       isOneShot:
                         type: boolean
                       isDeferred:
@@ -26414,6 +26413,7 @@ paths:
                       - workflowName
                       - sourceKey
                       - userEnabled
+                      - disarmReason
                       - isOneShot
                       - isDeferred
                     additionalProperties: false
@@ -26620,6 +26620,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26656,6 +26670,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26805,6 +26820,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26841,6 +26870,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26992,6 +27022,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -27028,6 +27072,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -27314,6 +27359,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -27350,6 +27409,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.4-staging.2",
+  "version": "0.11.4-staging.4",
   "license": "MIT",
   "type": "module",
   "exports": {

package/scripts/write-plugin-api-shim.ts

@@ -0,0 +1,10 @@
+import path from "node:path";
+
+import { ensurePluginApiShim } from "../src/plugins/ensure-plugin-api-shim.js";
+
+const outputDir = Bun.argv[2];
+if (!outputDir || !path.isAbsolute(outputDir)) {
+  throw new Error("An absolute plugin API shim output directory is required.");
+}
+
+await ensurePluginApiShim({ workspaceDir: outputDir });

package/src/__tests__/app-control-flow.test.ts

@@ -140,6 +140,7 @@ function buildContext(
       guardianPrincipalId: "user-1",
     },
     sendToClient: () => {},
+    emit: () => {},
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/approval-routes-http.test.ts

@@ -113,7 +113,7 @@ function makeIdleSession(opts?: {
     ensureActorScopedHistory: async () => {},
     getMessages: () => [],
     usageStats: { inputTokens: 0, outputTokens: 0, estimatedCost: 0 },
-    updateClient: () => {},
+    replayActivityState: () => {},
     setHostBrowserProxy: () => {},
     setHostCuProxy: () => {},
     setHostAppControlProxy: () => {},
@@ -176,7 +176,7 @@ function makeConfirmationEmittingSession(opts?: {
     ensureActorScopedHistory: async () => {},
     getMessages: () => [],
     usageStats: { inputTokens: 0, outputTokens: 0, estimatedCost: 0 },
-    updateClient: () => {},
+    replayActivityState: () => {},
     setHostBrowserProxy: () => {},
     setHostCuProxy: () => {},
     setHostAppControlProxy: () => {},

package/src/__tests__/assistant-feature-flag-guard.test.ts

@@ -40,7 +40,10 @@ interface RegistryFlag {
   key: string;
   label: string;
   description: string;
-  defaultEnabled: boolean;
+  /** Boolean for a gate; the winning variation's name for a multivariate flag. */
+  defaultEnabled: boolean | string;
+  /** Declared variations. Present only on multivariate flags. */
+  values?: string[];
 }
 
 interface Registry {
@@ -179,8 +182,27 @@ describe("assistant feature flag guard", () => {
     const violations: string[] = [];
 
     for (const flag of assistantFlags) {
-      if (typeof flag.defaultEnabled !== "boolean") {
-        violations.push(`${flag.key}: missing or non-boolean 'defaultEnabled'`);
+      // A gate declares a boolean default. A multivariate flag declares its
+      // variations in `values` and names the winning one in `defaultEnabled`,
+      // which the resolver serves verbatim to string consumers.
+      if (flag.values === undefined) {
+        if (typeof flag.defaultEnabled !== "boolean") {
+          violations.push(
+            `${flag.key}: missing or non-boolean 'defaultEnabled'`,
+          );
+        }
+      } else if (
+        !Array.isArray(flag.values) ||
+        flag.values.length < 2 ||
+        flag.values.some((value) => typeof value !== "string")
+      ) {
+        violations.push(
+          `${flag.key}: 'values' must list at least two string variations`,
+        );
+      } else if (!flag.values.includes(flag.defaultEnabled as string)) {
+        violations.push(
+          `${flag.key}: 'defaultEnabled' must name one of the declared 'values'`,
+        );
       }
       if (
         typeof flag.description !== "string" ||

package/src/__tests__/channel-setup-panel-ack.test.ts

@@ -28,7 +28,7 @@ function makeContext(
 ): Conversation {
   return asConversation({
     conversationId: "session-1",
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/compaction-events.test.ts

@@ -436,12 +436,11 @@ describe("forceCompact context-window usage push", () => {
     expect(usageEvent.maxTokens).toBe(200_000);
   });
 
-  test("pushes to the caller's sink when the conversation's own sender is dead", async () => {
-    // A `/compact` draining behind an interactive turn: `process-message.ts`
-    // resets `sendToClient` to a no-op in its `finally`, while the queued item
-    // still carries the live sink its result card streams on. The push has to
-    // follow the card, not the dead sender.
-    const stranded: AssistantEvent[] = [];
+  test("pushes to the caller's sink instead of the conversation sink when one is given", async () => {
+    // A `/compact` draining from the queue carries the queued item's own
+    // sink, the one its result card streams on. The push has to follow the
+    // card so the two can never be delivered to different places.
+    const conversationSink: AssistantEvent[] = [];
     const cardSink: AssistantEvent[] = [];
     mockCompactResult = {
       messages: [],
@@ -460,11 +459,10 @@ describe("forceCompact context-window usage push", () => {
     };
 
     const conversation = makeConversation(
-      stranded,
-      "conv-compact-dead-sender",
+      conversationSink,
+      "conv-compact-caller-sink",
       [56_000, 18_000],
     );
-    conversation.updateClient(() => {}, true);
 
     const result = await conversation.forceCompact((msg) => cardSink.push(msg));
 
@@ -475,7 +473,7 @@ describe("forceCompact context-window usage push", () => {
         .tokens,
     ).toBe(result.estimatedInputTokens);
     expect(
-      stranded.filter((m) => m.type === "context_window_usage").length,
+      conversationSink.filter((m) => m.type === "context_window_usage").length,
     ).toBe(0);
   });
 

package/src/__tests__/conversation-agent-loop.test.ts

@@ -1345,7 +1345,10 @@ describe("session-agent-loop", () => {
       });
       const cleanupFlagDuringInjection = captureCleanupFlagDuringInjection(ctx);
 
-      await runAgentLoopImpl(ctx, "free up space", "msg-1", () => {});
+      // Presence is declared per turn; the policy input must carry it.
+      await runAgentLoopImpl(ctx, "free up space", "msg-1", () => {}, {
+        isInteractive: true,
+      });
 
       expect(classifyDiskPressureTurnPolicyMock).toHaveBeenCalledWith(
         mockDiskPressureStatus,