@vellumai/assistant 0.11.4-staging.1 → 0.11.4-staging.3

package/openapi.yaml

@@ -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.1",
+  "version": "0.11.4-staging.3",
   "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__/byok-default-profile-ensure.test.ts

@@ -282,11 +282,26 @@ describe("ensureByokDefaultProfiles", () => {
     ["openai", "quality-optimized", "gpt-5.4"],
     ["fireworks", "balanced", "accounts/fireworks/models/kimi-k2p5"],
     ["fireworks", "balanced", "accounts/fireworks/models/kimi-k2p6"],
+    [
+      "fireworks",
+      "balanced",
+      "accounts/fireworks/models/deepseek-v4-flash-0731",
+    ],
     [
       "fireworks",
       "quality-optimized",
       "accounts/fireworks/models/deepseek-v4-flash",
     ],
+    [
+      "fireworks",
+      "quality-optimized",
+      "accounts/fireworks/models/deepseek-v4-flash-0731",
+    ],
+    [
+      "fireworks",
+      "cost-optimized",
+      "accounts/fireworks/models/deepseek-v4-flash",
+    ],
   ] as const)(
     "a historical intent-era copy converts (%s %s pinned to %s)",
     (provider, key, model) => {

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,

package/src/__tests__/conversation-confirmation-signals.test.ts

@@ -431,3 +431,115 @@ describe("sendToClient receives state signals", () => {
     });
   });
 });
+
+describe("the sink is fixed for the conversation's life", () => {
+  test("a cold instance delivers activity state with no turn ever having run", () => {
+    // The summarize-up-to route resolves its conversation outside the send
+    // path and emits a thinking indicator before any turn: it must reach the
+    // sink the conversation was built with, not depend on a send having wired
+    // one (LUM-2987).
+    const clientMsgs: AssistantEvent[] = [];
+    const conversation = makeConversation((msg) => clientMsgs.push(msg));
+
+    conversation.emitActivityState("thinking", "context_compacting", {
+      statusText: "Summarizing conversation",
+    });
+
+    const activity = clientMsgs.filter(
+      (m) => m.type === "assistant_activity_state",
+    );
+    expect(activity).toHaveLength(1);
+    expect((activity[0] as { statusText?: string }).statusText).toBe(
+      "Summarizing conversation",
+    );
+  });
+
+  test("presence is a property of the turn, not of delivery", () => {
+    // Nothing is in flight, so no human is asserted present, even though the
+    // sink is live and delivering.
+    const clientMsgs: AssistantEvent[] = [];
+    const conversation = makeConversation((msg) => clientMsgs.push(msg));
+    expect(conversation.hasNoClient).toBe(true);
+    conversation.emitActivityState("thinking", "message_dequeued");
+    expect(clientMsgs).toHaveLength(1);
+    expect(conversation.hasNoClient).toBe(true);
+  });
+});
+
+describe("event observers", () => {
+  test("an observer sees each event after the sink delivered it, and detaches", () => {
+    const order: string[] = [];
+    const conversation = makeConversation((msg) => {
+      order.push(`sink:${msg.type}`);
+    });
+    const detach = conversation.addEventObserver((msg) => {
+      order.push(`observer:${msg.type}`);
+    });
+
+    conversation.emitActivityState("thinking", "message_dequeued");
+    expect(order).toEqual([
+      "sink:assistant_activity_state",
+      "observer:assistant_activity_state",
+    ]);
+
+    detach();
+    conversation.emitActivityState("idle", "message_complete");
+    expect(order).toEqual([
+      "sink:assistant_activity_state",
+      "observer:assistant_activity_state",
+      "sink:assistant_activity_state",
+    ]);
+  });
+
+  test("a throwing observer neither blocks the sink nor its siblings", () => {
+    const seen: string[] = [];
+    const conversation = makeConversation((msg) => {
+      seen.push(`sink:${msg.type}`);
+    });
+    conversation.addEventObserver(() => {
+      throw new Error("observer boom");
+    });
+    conversation.addEventObserver((msg) => {
+      seen.push(`second:${msg.type}`);
+    });
+
+    conversation.emitActivityState("thinking", "message_dequeued");
+    expect(seen).toEqual([
+      "sink:assistant_activity_state",
+      "second:assistant_activity_state",
+    ]);
+  });
+
+  test("the prompter's confirmation_request reaches observers after the sink", () => {
+    // Voice auto-resolves approval prompts it has no UI for; it must observe
+    // the request only once the sink has put it on the wire, so its resolution
+    // lands after the request it answers.
+    const order: string[] = [];
+    const conversation = makeConversation((msg) => {
+      order.push(`sink:${msg.type}`);
+    });
+    conversation.addEventObserver((msg) => {
+      if (msg.type === "confirmation_request") {
+        order.push("observer:confirmation_request");
+        conversation.handleConfirmationResponse(msg.requestId, "deny", {
+          emissionContext: { source: "system" },
+        });
+      }
+    });
+
+    void conversation.prompter.prompt(
+      "bash",
+      { command: "rm -rf /tmp/x" },
+      "high",
+      [],
+      [],
+      undefined,
+      conversation.conversationId,
+      "sandbox",
+      false,
+    );
+
+    expect(order[0]).toBe("sink:confirmation_request");
+    expect(order[1]).toBe("observer:confirmation_request");
+  });
+});

package/src/__tests__/conversation-notifiers-provenance.test.ts

@@ -35,7 +35,7 @@ describe("live-call question provenance", () => {
 
   test("a row persisted after the turn settled carries the owner, not the stale turn actor", async () => {
     registerConversationNotifiers("conv-n1", {
-      sendToClient: () => {},
+      emit: () => {},
       messages: [],
       // Voice cleanup restored the owner; the per-turn field still holds the
       // finished voice turn's contact.