@vellumai/assistant 0.12.2-dev.202609182015.188de8a → 0.12.2-dev.202609182214.bd8f92f

package/ARCHITECTURE.md

@@ -1930,12 +1930,14 @@ Keep-alive heartbeats (every 30 s by default):
 
 ### Key Source Files
 
-| File                                            | Role                                                                           |
-| ----------------------------------------------- | ------------------------------------------------------------------------------ |
-| `assistant/src/runtime/assistant-event.ts`      | `AssistantEvent` type, `buildAssistantEvent()` factory, SSE framing helpers    |
-| `assistant/src/runtime/assistant-event-hub.ts`  | `AssistantEventHub` class and process-level singleton                          |
-| `assistant/src/runtime/routes/events-routes.ts` | `handleSubscribeAssistantEvents()` — SSE route handler                         |
-| `assistant/src/daemon/server.ts`                | Session event paths that publish to the hub (`send` → `publishAssistantEvent`) |
+| File                                                 | Role                                                                                  |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `assistant/src/runtime/assistant-event.ts`           | `AssistantEvent` type, `buildAssistantEvent()` factory, SSE framing helpers           |
+| `assistant/src/runtime/assistant-event-hub.ts`       | `AssistantEventHub` class and process-level singleton                                 |
+| `assistant/src/runtime/assistant-event-targeting.ts` | `matchesTargeting()`, the targeting check live fanout and replay share                |
+| `assistant/src/runtime/assistant-stream-state.ts`    | Per-assistant `seq` counter and ring buffer behind reconnect and `events/tail` replay |
+| `assistant/src/runtime/routes/events-routes.ts`      | `handleSubscribeAssistantEvents()`, the SSE route handler                             |
+| `assistant/src/daemon/server.ts`                     | Session event paths that publish to the hub (`send` → `publishAssistantEvent`)        |
 
 ---
 

package/docs/architecture/turn-actor.md

@@ -29,6 +29,8 @@ 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. 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.
 
 ## When the acting actor is unknown

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.202609182015.188de8a",
+  "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__/assistant-event-targeting.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Tests for `matchesTargeting`, the one targeting check behind live fanout
+ * (`AssistantEventHub.publish`) and replay (`getReplayWindow`).
+ *
+ * The parity block runs every case through both paths and requires them to
+ * agree, so a rule added to one path alone fails here.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import type { AssistantEventEnvelope } from "../api/index.js";
+import type { HostProxyCapability, InterfaceId } from "../channels/types.js";
+import { AssistantEventHub } from "../runtime/assistant-event-hub.js";
+import type { AssistantEventPublishOptions } from "../runtime/assistant-event-publish-options.js";
+import { matchesTargeting } from "../runtime/assistant-event-targeting.js";
+import {
+  _resetStreamStateForTesting,
+  getReplayWindow,
+  stampAndBuffer,
+} from "../runtime/assistant-stream-state.js";
+
+const CONV = "conv-targeting";
+
+interface ClientIdentity {
+  type: "client";
+  clientId: string;
+  interfaceId: InterfaceId;
+  capabilities: HostProxyCapability[];
+  actorPrincipalId?: string;
+}
+
+const MAC: ClientIdentity = {
+  type: "client",
+  clientId: "mac-1",
+  interfaceId: "macos",
+  capabilities: ["host_bash", "host_browser"],
+  actorPrincipalId: "principal-g",
+};
+const WEB: ClientIdentity = {
+  type: "client",
+  clientId: "web-1",
+  interfaceId: "web",
+  capabilities: [],
+  actorPrincipalId: "principal-g",
+};
+const OTHER_USER: ClientIdentity = {
+  type: "client",
+  clientId: "web-2",
+  interfaceId: "web",
+  capabilities: [],
+  actorPrincipalId: "principal-x",
+};
+const NO_PRINCIPAL: ClientIdentity = {
+  type: "client",
+  clientId: "legacy-1",
+  interfaceId: "web",
+  capabilities: [],
+};
+interface ProcessIdentity {
+  type: "process";
+}
+
+const PROCESS: ProcessIdentity = { type: "process" };
+
+const SUBSCRIBERS: Array<[string, ClientIdentity | ProcessIdentity]> = [
+  ["mac", MAC],
+  ["web", WEB],
+  ["other user", OTHER_USER],
+  ["no principal", NO_PRINCIPAL],
+  ["process", PROCESS],
+];
+
+/** Each targeting case with the subscribers it must reach, by label. */
+const CASES: Array<{
+  name: string;
+  targeting: AssistantEventPublishOptions | undefined;
+  reaches: string[];
+}> = [
+  {
+    name: "untargeted",
+    targeting: undefined,
+    reaches: ["mac", "web", "other user", "no principal", "process"],
+  },
+  {
+    name: "self-echo exclusion",
+    targeting: { excludeClientId: "web-1" },
+    reaches: ["mac", "other user", "no principal", "process"],
+  },
+  {
+    name: "interface",
+    targeting: { targetInterfaceId: "web" },
+    reaches: ["web", "other user", "no principal"],
+  },
+  {
+    name: "principal",
+    targeting: { targetActorPrincipalId: "principal-g" },
+    reaches: ["mac", "web"],
+  },
+  {
+    name: "client",
+    targeting: { targetClientId: "mac-1" },
+    reaches: ["mac"],
+  },
+  {
+    name: "capability",
+    targeting: { targetCapability: "host_browser" },
+    reaches: ["mac"],
+  },
+  {
+    name: "client without the capability",
+    targeting: { targetClientId: "web-1", targetCapability: "host_browser" },
+    reaches: [],
+  },
+  {
+    name: "principal and interface together",
+    targeting: {
+      targetActorPrincipalId: "principal-g",
+      targetInterfaceId: "web",
+    },
+    reaches: ["web"],
+  },
+];
+
+function makeEvent(): AssistantEventEnvelope {
+  return {
+    id: `evt-${Math.random().toString(36).slice(2, 10)}`,
+    conversationId: CONV,
+    emittedAt: new Date().toISOString(),
+    message: { type: "assistant_text_delta", conversationId: CONV, text: "x" },
+  };
+}
+
+async function reachedLive(
+  targeting: AssistantEventPublishOptions | undefined,
+): Promise<string[]> {
+  const hub = new AssistantEventHub();
+  const reached: string[] = [];
+  for (const [label, identity] of SUBSCRIBERS) {
+    const callback = () => {
+      reached.push(label);
+    };
+    if (identity.type === "process") {
+      hub.subscribe({ type: "process", callback });
+    } else {
+      hub.subscribe({ ...identity, callback });
+    }
+  }
+  await hub.publish(makeEvent(), targeting);
+  return reached.sort();
+}
+
+function reachedOnReplay(
+  targeting: AssistantEventPublishOptions | undefined,
+): string[] {
+  _resetStreamStateForTesting();
+  stampAndBuffer(makeEvent(), targeting ? { targeting } : undefined);
+  return SUBSCRIBERS.filter(
+    ([, identity]) => (getReplayWindow(0, identity) ?? []).length > 0,
+  )
+    .map(([label]) => label)
+    .sort();
+}
+
+describe("matchesTargeting", () => {
+  for (const { name, targeting, reaches } of CASES) {
+    test(`${name}: reaches exactly its subscribers`, () => {
+      const reached = SUBSCRIBERS.filter(([, identity]) =>
+        matchesTargeting(targeting, identity),
+      ).map(([label]) => label);
+      expect(reached.sort()).toEqual([...reaches].sort());
+    });
+  }
+});
+
+describe("live fanout and replay agree", () => {
+  beforeEach(() => {
+    _resetStreamStateForTesting();
+  });
+
+  for (const { name, targeting, reaches } of CASES) {
+    test(`${name}: both paths deliver to the same subscribers`, async () => {
+      const expected = [...reaches].sort();
+      expect(await reachedLive(targeting)).toEqual(expected);
+      expect(reachedOnReplay(targeting)).toEqual(expected);
+    });
+  }
+});