@vellumai/assistant 0.12.2-dev.202609182114.335fa56 → 0.12.2-dev.202609182214.bd8f92f

package/docs/architecture/turn-actor.md

@@ -29,7 +29,7 @@ Do not read `trustContext` or `currentTurnTrustContext` directly. Call sites han
 
 **Use `getTurnOrRestingTrust()`** for provenance stamped onto persisted rows (see `provenanceFromTrustContext`). Provenance is read back by the memory indexer, which runs extraction only for guardian rows, and by the transcript assembly, which wraps non-guardian user content before it reaches the model. The turn's actor is correct when a turn is running; rows persisted with no turn in flight (wake notices) must keep the owner's class, because stamping `"unknown"` there silently stops memory extraction for the owner's own flows.
 
-That provenance describes the turn, so it is stamped on every row the turn writes, the assistant's replies and tool results included. Who wrote a row is a separate fact: `provenanceContactId` names the author's contact and needs positive evidence. It is added only where a person's own inbound words or actions are persisted (`actorAuthorProvenance`): a message channel ingress or its retry replay relays with an explicit `author`, unless that row is scripted or hidden, and the actor's reaction row. The shared user-message writer never infers an author from the conversation's trust, because machine-authored rows (ACP and subagent notifications, pointer turns) persist through it too. Rows the assistant writes during someone's turn never carry it. Slack backfill imports other people's messages, so the turn's actor says nothing about them; each backfilled sender is classified by the same gateway verdict live ingress uses (`resolve_inbound_trust`, see `inbound-stages/backfill-sender-provenance.ts`), which supplies both its trust class and its contact id.
+That provenance describes the turn, so it is stamped on every row the turn writes, the assistant's replies and tool results included. Who wrote a row is a separate fact: `provenanceContactId` names the author's contact and needs positive evidence. It is added only where a person's own inbound words or actions are persisted (`actorAuthorProvenance`): a message channel ingress or its retry replay relays with an explicit `author`, unless that row is scripted or hidden, and the actor's reaction row. The shared user-message writer never infers an author from the conversation's trust, because machine-authored rows (ACP and subagent notifications, pointer turns) persist through it too. Rows the assistant writes during someone's turn never carry it. Slack backfill imports other people's messages, so the turn's actor says nothing about them; each backfilled sender is classified by the same gateway verdict live ingress uses (`resolve_inbound_trust`, see `inbound-stages/backfill-sender-provenance.ts`), which supplies both its trust class and its contact id. When that lookup returns no usable verdict, the row falls back to the guardian-address comparison and is marked `provenanceLookupFailed`, so a failed lookup is never stored as the same fact as a sender the gateway resolved as a stranger. Live ingress needs no such marker: it denies a turn whose verdict failed.
 
 **Use `getTrustContext()`** when there is no turn: HTTP routes reporting conversation state, hydration, and persistence of conversation-level options. Also when a caller deliberately wants the conversation's owner rather than whoever is currently acting; that intent should be obvious from the call site, and if it is not, it is probably the wrong accessor.
 

package/openapi.yaml

@@ -5647,6 +5647,64 @@ paths:
                 required:
                   - disconnected
                 additionalProperties: false
+  /v1/clients/history:
+    get:
+      operationId: clients_history_get
+      summary: List client connection history
+      description:
+        Return persisted client subscribe/dispose events and coalesced sessions. Reconnects shorter than 60 seconds
+        are flaps, not outages.
+      tags:
+        - clients
+      parameters:
+        - name: clientId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Restrict history to one client UUID.
+        - name: interfaceId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Restrict history to one interface (e.g. chrome-extension).
+        - name: since
+          in: query
+          required: false
+          schema:
+            type: string
+          description: ISO-8601 or epoch-ms lower bound. Sessions already open at this time are included.
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Max coalesced sessions to return (1-500, default 50).
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sessions:
+                    type: array
+                    items:
+                      type: object
+                      properties: {}
+                      additionalProperties: {}
+                  events:
+                    type: array
+                    items:
+                      type: object
+                      properties: {}
+                      additionalProperties: {}
+                required:
+                  - sessions
+                  - events
+                additionalProperties: false
   /v1/clients/presence:
     post:
       operationId: clients_presence_post
@@ -24646,11 +24704,58 @@ paths:
                     type: boolean
                   reason:
                     type: string
+                  selectedChannels:
+                    type: array
+                    items:
+                      type: string
+                  deliveryResults:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        channel:
+                          type: string
+                        destination:
+                          type: string
+                        status:
+                          type: string
+                          enum:
+                            - pending
+                            - sent
+                            - failed
+                            - skipped
+                        errorCode:
+                          type: string
+                        errorMessage:
+                          type: string
+                        sentAt:
+                          type: number
+                        conversationId:
+                          type: string
+                        messageId:
+                          type: string
+                        conversationStrategy:
+                          type: string
+                      required:
+                        - channel
+                        - destination
+                        - status
+                      additionalProperties: false
+                  receiptClass:
+                    type: string
+                    enum:
+                      - provider_accepted
+                      - gateway_accepted
+                      - client_os_posted
+                      - unknown
                 required:
                   - signalId
                   - dispatched
                   - deduplicated
                   - reason
+                  - selectedChannels
+                  - deliveryResults
+                  - receiptClass
                 additionalProperties: false
   /v1/notifications/events:
     post:
@@ -29107,8 +29212,8 @@ paths:
       operationId: roadmap_by_slug_patch
       summary: Update a roadmap item
       description:
-        Updates a roadmap item. At least one field is required; the roadmap service decides which items this
-        assistant may edit.
+        Updates the title or description of a roadmap item this assistant filed, while the item is still open.
+        Status and tags are set by Vellum staff.
       tags:
         - roadmap
       parameters:
@@ -29128,13 +29233,7 @@ paths:
                   type: string
                 description:
                   type: string
-                status:
-                  type: string
-                tags:
-                  description: Tag slugs
-                  type: array
-                  items:
-                    type: string
+              additionalProperties: false
       responses:
         "200":
           description: Successful response

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609182114.335fa56",
+  "version": "0.12.2-dev.202609182214.bd8f92f",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/approval-message-composer.test.ts

@@ -17,21 +17,10 @@ const ALL_SCENARIOS: ApprovalMessageScenario[] = [
   "standard_prompt",
   "guardian_prompt",
   "reminder_prompt",
-  "guardian_delivery_failed",
-  "guardian_request_forwarded",
-  "guardian_disambiguation",
   "guardian_identity_mismatch",
   "request_pending_guardian",
-  "guardian_decision_outcome",
-  "guardian_expired_requester",
-  "guardian_expired_guardian",
-  "guardian_verify_success",
   "guardian_verify_failed",
   "guardian_verify_challenge_setup",
-  "guardian_verify_status_bound",
-  "guardian_verify_status_unbound",
-  "guardian_deny_no_identity",
-  "guardian_deny_no_binding",
 ];
 
 describe("approval-message-composer", () => {
@@ -66,59 +55,6 @@ describe("approval-message-composer", () => {
       expect(msg).toContain("write_file");
     });
 
-    test("guardian_delivery_failed includes toolName when provided", () => {
-      const msg = getFallbackMessage({
-        scenario: "guardian_delivery_failed",
-        toolName: "execute_shell",
-      });
-      expect(msg).toContain("execute_shell");
-    });
-
-    test("guardian_request_forwarded includes toolName", () => {
-      const msg = getFallbackMessage({
-        scenario: "guardian_request_forwarded",
-        toolName: "execute_shell",
-      });
-      expect(msg).toContain("execute_shell");
-    });
-
-    test("guardian_disambiguation includes pendingCount", () => {
-      const msg = getFallbackMessage({
-        scenario: "guardian_disambiguation",
-        pendingCount: 3,
-      });
-      expect(msg).toContain("3");
-    });
-
-    test("guardian_decision_outcome includes decision and toolName", () => {
-      const msg = getFallbackMessage({
-        scenario: "guardian_decision_outcome",
-        decision: "approved",
-        toolName: "read_file",
-      });
-      expect(msg).toContain("approved");
-      expect(msg).toContain("read_file");
-    });
-
-    test("guardian_expired_requester includes toolName", () => {
-      const msg = getFallbackMessage({
-        scenario: "guardian_expired_requester",
-        toolName: "deploy",
-      });
-      expect(msg).toContain("deploy");
-      expect(msg).toContain("expired");
-    });
-
-    test("guardian_expired_guardian includes requester and toolName", () => {
-      const msg = getFallbackMessage({
-        scenario: "guardian_expired_guardian",
-        requesterIdentifier: "bob",
-        toolName: "delete_file",
-      });
-      expect(msg).toContain("bob");
-      expect(msg).toContain("delete_file");
-    });
-
     test("guardian_verify_failed includes failureReason", () => {
       const msg = getFallbackMessage({
         scenario: "guardian_verify_failed",
@@ -141,36 +77,7 @@ describe("approval-message-composer", () => {
   // -----------------------------------------------------------------------
 
   describe("composeApprovalMessage", () => {
-    test("returns assistantPreface when provided (primary source)", () => {
-      const preface = "The assistant already said something helpful.";
-      const msg = composeApprovalMessage({
-        scenario: "standard_prompt",
-        toolName: "execute_shell",
-        assistantPreface: preface,
-      });
-      expect(msg).toBe(preface);
-    });
-
-    test("ignores empty assistantPreface and falls back to template", () => {
-      const msg = composeApprovalMessage({
-        scenario: "standard_prompt",
-        toolName: "execute_shell",
-        assistantPreface: "",
-      });
-      expect(msg).toContain("execute_shell");
-      expect(msg).not.toBe("");
-    });
-
-    test("ignores whitespace-only assistantPreface", () => {
-      const msg = composeApprovalMessage({
-        scenario: "standard_prompt",
-        toolName: "execute_shell",
-        assistantPreface: "   ",
-      });
-      expect(msg).toContain("execute_shell");
-    });
-
-    test("falls back to deterministic template when no assistantPreface", () => {
+    test("returns the deterministic template", () => {
       const msg = composeApprovalMessage({
         scenario: "guardian_prompt",
         toolName: "write_file",
@@ -222,29 +129,5 @@ describe("approval-message-composer", () => {
       expect(msg.length).toBeGreaterThan(0);
       expect(msg).toContain("invalid or has expired");
     });
-
-    test("guardian_verify_success produces a non-empty success message", () => {
-      const msg = composeApprovalMessage({
-        scenario: "guardian_verify_success",
-      });
-      expect(typeof msg).toBe("string");
-      expect(msg.length).toBeGreaterThan(0);
-    });
-
-    test("guardian_verify_status_bound produces a non-empty message", () => {
-      const msg = composeApprovalMessage({
-        scenario: "guardian_verify_status_bound",
-      });
-      expect(typeof msg).toBe("string");
-      expect(msg.length).toBeGreaterThan(0);
-    });
-
-    test("guardian_verify_status_unbound produces a non-empty message", () => {
-      const msg = composeApprovalMessage({
-        scenario: "guardian_verify_status_unbound",
-      });
-      expect(typeof msg).toBe("string");
-      expect(msg.length).toBeGreaterThan(0);
-    });
   });
 });

package/src/__tests__/assistant-event-hub-connection-history.test.ts

@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import type { ClientConnectionEventInput } from "../persistence/client-connection-events-store.js";
+import { AssistantEventHub } from "../runtime/assistant-event-hub.js";
+
+describe("AssistantEventHub connection history", () => {
+  const recorded: Array<Pick<ClientConnectionEventInput, "clientId" | "reason">> =
+    [];
+
+  beforeEach(() => {
+    recorded.length = 0;
+  });
+
+  function hub(options?: { maxSubscribers?: number }): AssistantEventHub {
+    return new AssistantEventHub({
+      ...options,
+      recordConnection: (input) => {
+        recorded.push({ clientId: input.clientId, reason: input.reason });
+        return null;
+      },
+    });
+  }
+
+  test("records sse_open on client subscribe and sse_close on dispose", () => {
+    const sub = hub().subscribe({
+      type: "client",
+      clientId: "client-123",
+      interfaceId: "chrome-extension",
+      capabilities: ["host_browser"],
+      callback: () => {},
+    });
+
+    expect(recorded.map((row) => row.reason)).toEqual(["sse_open"]);
+    sub.dispose();
+    expect(recorded.map((row) => row.reason)).toEqual(["sse_open", "sse_close"]);
+  });
+
+  test("records stale_replaced then sse_open on reconnect", () => {
+    const instance = hub();
+    instance.subscribe({
+      type: "client",
+      clientId: "client-123",
+      interfaceId: "chrome-extension",
+      capabilities: ["host_browser"],
+      callback: () => {},
+    });
+    instance.subscribe({
+      type: "client",
+      clientId: "client-123",
+      interfaceId: "chrome-extension",
+      capabilities: ["host_browser"],
+      callback: () => {},
+    });
+
+    expect(recorded.map((row) => row.reason)).toEqual([
+      "sse_open",
+      "stale_replaced",
+      "sse_open",
+    ]);
+  });
+
+  test("records force_disconnect from disposeClient", () => {
+    const instance = hub();
+    instance.subscribe({
+      type: "client",
+      clientId: "client-123",
+      interfaceId: "chrome-extension",
+      capabilities: ["host_browser"],
+      callback: () => {},
+    });
+    recorded.length = 0;
+
+    expect(instance.disposeClient("client-123")).toBe(1);
+    expect(recorded.map((row) => row.reason)).toEqual(["force_disconnect"]);
+  });
+
+  test("records cap_evicted when the oldest subscriber is shed", () => {
+    const instance = hub({ maxSubscribers: 1 });
+    instance.subscribe({
+      type: "client",
+      clientId: "client-old",
+      interfaceId: "web",
+      capabilities: [],
+      callback: () => {},
+    });
+    recorded.length = 0;
+
+    instance.subscribe({
+      type: "client",
+      clientId: "client-new",
+      interfaceId: "web",
+      capabilities: [],
+      callback: () => {},
+    });
+
+    expect(recorded.map((row) => row.reason)).toEqual([
+      "cap_evicted",
+      "sse_open",
+    ]);
+    expect(recorded[0].clientId).toBe("client-old");
+  });
+
+  test("does not record process subscribers", () => {
+    const sub = hub().subscribe({
+      type: "process",
+      callback: () => {},
+    });
+    sub.dispose();
+    expect(recorded).toEqual([]);
+  });
+});

package/src/__tests__/dm-backfill.test.ts

@@ -199,6 +199,7 @@ function readPersistedSlackRows(): Array<{
   provenanceGuardianExternalUserId: string | undefined;
   provenanceRequesterIdentifier: string | undefined;
   provenanceContactId: string | undefined;
+  provenanceLookupFailed: boolean | undefined;
   sentAt: number | undefined;
   createdAt: number;
 }> {
@@ -257,6 +258,10 @@ function readPersistedSlackRows(): Array<{
           typeof envelope.provenanceContactId === "string"
             ? envelope.provenanceContactId
             : undefined,
+        provenanceLookupFailed:
+          typeof envelope.provenanceLookupFailed === "boolean"
+            ? envelope.provenanceLookupFailed
+            : undefined,
         sentAt:
           typeof envelope.sentAt === "number" ? envelope.sentAt : undefined,
         createdAt: row.createdAt,
@@ -360,6 +365,8 @@ describe("PR 23 — Slack DM cold-start backfill", () => {
       expect(meta!.channelId).toBe(SLACK_DM_CHANNEL_ID);
       expect(meta!.actorExternalUserId).toBe(SLACK_DM_USER_ID);
       expect(r.provenanceTrustClass).toBe("unknown");
+      // No gateway in the test process: the lookup failed, and the row says so.
+      expect(r.provenanceLookupFailed).toBe(true);
       expect(r.provenanceSourceChannel).toBe("slack");
       expect(r.provenanceRequesterIdentifier).toBe(SLACK_DM_USER_ID);
       return meta!.channelTs;
@@ -597,6 +604,7 @@ describe("PR 23 — Slack DM cold-start backfill", () => {
     for (const row of memberRows) {
       expect(row.provenanceTrustClass).toBe("trusted_contact");
       expect(row.provenanceContactId).toBe("contact-dm-user");
+      expect(row.provenanceLookupFailed).toBeUndefined();
     }
     const ownPost = rows.find((r) => r.role === "assistant");
     expect(ownPost?.provenanceTrustClass).toBe("unknown");

package/src/__tests__/emit-signal-routing-intent.test.ts

@@ -95,7 +95,10 @@ mock.module("../platform/client.js", () => ({
   isPlatformClientConfigured: () => isPlatformClientConfiguredMock(),
 }));
 
-import { emitNotificationSignal } from "../notifications/emit-signal.js";
+import {
+  classifyNotificationReceipt,
+  emitNotificationSignal,
+} from "../notifications/emit-signal.js";
 
 beforeEach(() => {
   evaluateSignalMock.mockReset();
@@ -707,3 +710,140 @@ describe("high/critical urgency channel force", () => {
     });
   });
 });
+
+describe("exclusive channelAllowlist policy", () => {
+  function makeDecision(overrides: Record<string, unknown>) {
+    return {
+      shouldNotify: true,
+      selectedChannels: ["telegram"],
+      reasoningSummary: "LLM selected telegram only",
+      renderedCopy: {},
+      dedupeKey: "dedupe-allow-1",
+      confidence: 0.9,
+      fallbackUsed: false,
+      persistedDecisionId: "dec-allow-1",
+      ...overrides,
+    };
+  }
+
+  test("skips urgent vellum and platform force", async () => {
+    evaluateSignalMock.mockResolvedValue(
+      makeDecision({ selectedChannels: ["vellum"] }),
+    );
+
+    const result = await emitNotificationSignal({
+      sourceEventName: "user.send_notification",
+      sourceChannel: "assistant_tool",
+      sourceContextId: "cli-allowlist-1",
+      attentionHints: {
+        requiresAction: true,
+        urgency: "critical",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        requestedMessage: "telegram only",
+        channelAllowlist: ["vellum"],
+      },
+    });
+
+    expect(enforceRoutingIntentMock).not.toHaveBeenCalled();
+    const dispatched = dispatchDecisionMock.mock.calls[0][1] as {
+      selectedChannels: string[];
+      reasoningSummary: string;
+    };
+    expect(dispatched.selectedChannels).toEqual(["vellum"]);
+    expect(dispatched.reasoningSummary).not.toContain("forced");
+    expect(result.selectedChannels).toEqual(["vellum"]);
+    expect(result.receiptClass).toBe("unknown");
+  });
+
+  test("replaces an LLM selection with the connected allowlist", async () => {
+    evaluateSignalMock.mockResolvedValue(
+      makeDecision({ selectedChannels: ["vellum", "telegram", "platform"] }),
+    );
+
+    await emitNotificationSignal({
+      sourceEventName: "user.send_notification",
+      sourceChannel: "assistant_tool",
+      sourceContextId: "cli-allowlist-2",
+      attentionHints: {
+        requiresAction: true,
+        urgency: "high",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+      contextPayload: { channelAllowlist: ["vellum"] },
+    });
+
+    const dispatched = dispatchDecisionMock.mock.calls[0][1] as {
+      selectedChannels: string[];
+      shouldNotify: boolean;
+      reasoningSummary: string;
+    };
+    expect(dispatched.selectedChannels).toEqual(["vellum"]);
+    expect(dispatched.shouldNotify).toBe(true);
+    expect(dispatched.reasoningSummary).toContain("channelAllowlist: vellum");
+  });
+
+  test("access-request floor still adds vellum when the allowlist omitted it", async () => {
+    evaluateSignalMock.mockResolvedValue(
+      makeDecision({ shouldNotify: false, selectedChannels: [] }),
+    );
+
+    await emitNotificationSignal<string>({
+      sourceEventName: "ingress.access_request",
+      sourceChannel: "telegram",
+      sourceContextId: "access-req-allowlist-1",
+      requiresConversation: true,
+      attentionHints: {
+        requiresAction: true,
+        urgency: "high",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        requestId: "req-allowlist-1",
+        channelAllowlist: ["telegram"],
+      },
+    });
+
+    const dispatched = dispatchDecisionMock.mock.calls[0][1] as {
+      shouldNotify: boolean;
+      selectedChannels: string[];
+      reasoningSummary: string;
+    };
+    expect(dispatched.shouldNotify).toBe(true);
+    expect(dispatched.selectedChannels).toContain("vellum");
+    expect(dispatched.reasoningSummary).toContain(
+      "vellum forced: decisionable access request",
+    );
+  });
+});
+
+describe("classifyNotificationReceipt", () => {
+  test("reports provider_accepted when an external channel is sent", () => {
+    expect(
+      classifyNotificationReceipt([
+        { channel: "telegram", destination: "chat-1", status: "sent" },
+        { channel: "vellum", destination: "vellum", status: "sent" },
+      ]),
+    ).toBe("provider_accepted");
+  });
+
+  test("reports gateway_accepted when only platform is accepted", () => {
+    expect(
+      classifyNotificationReceipt([
+        { channel: "platform", destination: "push", status: "pending" },
+      ]),
+    ).toBe("gateway_accepted");
+  });
+
+  test("does not claim client_os_posted from a vellum sent row", () => {
+    expect(
+      classifyNotificationReceipt([
+        { channel: "vellum", destination: "vellum", status: "sent" },
+      ]),
+    ).toBe("unknown");
+  });
+});

package/src/calls/__tests__/voice-escalation-judge.test.ts

@@ -18,7 +18,7 @@ function text(role: "user" | "assistant", body: string): Message {
 }
 
 function jevResponse(noul: number): ProviderResponse {
-  const answers = { needs_escalation: { type: "noul", noul } };
+  const answers = { answer: { type: "noul", noul } };
   return {
     content: [{ type: "text", text: JSON.stringify(answers) }],
     model: "jev-latest",
@@ -102,7 +102,7 @@ describe("judgeEscalation", () => {
     const request = seen as unknown as {
       body: {
         state: { caller_just_said: string; recent_conversation: string };
-        questions: { needs_escalation: { type: string } };
+        questions: { answer: { type: string } };
       };
       options: SendMessageOptions;
     };
@@ -110,7 +110,7 @@ describe("judgeEscalation", () => {
     expect(request.body.state.recent_conversation).toBe(
       "assistant: Hi, what can I do?",
     );
-    expect(request.body.questions.needs_escalation.type).toBe("noul");
+    expect(request.body.questions.answer.type).toBe("noul");
     expect(
       (request.options.config as { callSite?: string } | undefined)?.callSite,
     ).toBe(VOICE_ESCALATION_JUDGE_CALL_SITE);

package/src/calls/guardian-action-sweep.ts

@@ -12,7 +12,7 @@ import { DELIVERY_STATUS } from "@vellumai/gateway-client";
 import { resolveDeliverCallbackUrlForChannel } from "../approvals/guardian-channel-delivery.js";
 import { addMessage } from "../persistence/conversation-crud.js";
 import { deliverChannelReply } from "../runtime/gateway-client.js";
-import { composeGuardianActionMessageGenerative } from "../runtime/guardian-action-message-composer.js";
+import { composeGuardianActionMessage } from "../runtime/guardian-action-message-composer.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("guardian-action-sweep");
@@ -52,9 +52,8 @@ export async function sendGuardianExpiryNotices(
     }
 
     try {
-      const expiryText = await composeGuardianActionMessageGenerative({
+      const expiryText = composeGuardianActionMessage({
         scenario: "guardian_stale_expired",
-        channel: delivery.destinationChannel,
       });
 
       if (