@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

package/src/runtime/agent-wake.ts

@@ -1112,7 +1112,7 @@ export async function wakeAgentForOpportunity(
       try {
         recordRequestLog(
           conversationId,
-          JSON.stringify(record.rawRequest),
+          JSON.stringify(record.rawRequest ?? null),
           JSON.stringify(record.rawResponse),
           undefined,
           record.provider,

package/src/runtime/approval-message-composer.ts

@@ -2,9 +2,8 @@
  * Layered approval message composition system.
  *
  * Generates approval prompt text through a priority chain:
- *   1. Assistant preface (macOS parity — reuse existing assistant text)
- *   2. Generator-produced rewrite of deterministic fallback text (when provided by daemon)
- *   3. Deterministic fallback templates (natural, scenario-specific messages)
+ *   1. Generator-produced rewrite of deterministic fallback text (when provided by daemon)
+ *   2. Deterministic fallback templates (natural, scenario-specific messages)
  */
 import { getLogger } from "../util/logger.js";
 import type {
@@ -25,18 +24,10 @@ const log = getLogger("approval-message-composer");
 // Public API
 // ---------------------------------------------------------------------------
 
-/**
- * Compose an approval message using layered source selection:
- *   1. If an assistant preface is provided and non-empty, return it directly.
- *   2. Otherwise fall back to a deterministic scenario-specific template.
- */
+/** Compose an approval message from its deterministic scenario template. */
 export function composeApprovalMessage(
   context: ApprovalMessageContext,
 ): string {
-  if (context.assistantPreface && context.assistantPreface.trim().length > 0) {
-    return context.assistantPreface;
-  }
-
   return getFallbackMessage(context);
 }
 
@@ -99,10 +90,6 @@ export async function composeApprovalMessageGenerative(
   options: ComposeApprovalMessageGenerativeOptions = {},
   generator?: ApprovalCopyGenerator,
 ): Promise<string> {
-  if (context.assistantPreface && context.assistantPreface.trim().length > 0) {
-    return context.assistantPreface;
-  }
-
   const fallbackText =
     options.fallbackText?.trim() || getFallbackMessage(context);
 
@@ -155,45 +142,12 @@ export function getFallbackMessage(context: ApprovalMessageContext): string {
     case "reminder_prompt":
       return "There is a pending approval request. Ask a follow-up question or say approve/deny when you are ready.";
 
-    case "guardian_delivery_failed":
-      return context.toolName
-        ? `Your request to run "${context.toolName}" could not be sent to the guardian for approval. The request has been denied for safety.`
-        : "I wasn't able to reach the guardian to request approval. The request has been denied for safety.";
-
-    case "guardian_request_forwarded":
-      return `Your request to use "${
-        context.toolName ?? "unknown"
-      }" has been forwarded to the guardian for approval. I'll let you know once they decide.`;
-
-    case "guardian_disambiguation":
-      return `There are ${
-        context.pendingCount ?? "multiple"
-      } pending approval requests. Please use the approval buttons to specify which request you're responding to.`;
-
     case "guardian_identity_mismatch":
       return "This approval request can only be handled by the designated guardian.";
 
     case "request_pending_guardian":
       return "Your request is pending guardian approval. Please wait for the guardian to respond.";
 
-    case "guardian_decision_outcome":
-      return `The guardian has ${
-        context.decision ?? "decided on"
-      } your request to use "${context.toolName ?? "unknown"}".`;
-
-    case "guardian_expired_requester":
-      return `The approval request for "${
-        context.toolName ?? "unknown"
-      }" has expired without a guardian response. The request has been denied.`;
-
-    case "guardian_expired_guardian":
-      return `The approval request from ${
-        context.requesterIdentifier ?? "the requester"
-      } for "${context.toolName ?? "unknown"}" has expired.`;
-
-    case "guardian_verify_success":
-      return "Guardian verification successful! You are now set as the guardian for this channel.";
-
     case "guardian_verify_failed":
       return `Verification failed. ${
         context.failureReason ?? "Please try again."
@@ -220,29 +174,9 @@ export function getFallbackMessage(context: ApprovalMessageContext): string {
       return `To complete guardian verification, send the code: ${code}.`;
     }
 
-    case "guardian_verify_status_bound":
-      return "A guardian is currently active for this channel.";
-
-    case "guardian_verify_status_unbound":
-      return "No guardian is currently configured for this channel.";
-
-    case "guardian_deny_no_identity":
-      return "This action requires approval, but your identity could not be verified. The request has been denied for safety.";
-
-    case "guardian_deny_no_binding":
-      return "This action requires guardian approval, but no guardian has been configured for this channel. The request has been denied for safety.";
-
-    case "requester_cancel":
-      return context.toolName
-        ? `Your request to use "${context.toolName}" has been cancelled.`
-        : "Your pending request has been cancelled.";
-
     case "approval_already_resolved":
       return "This approval request has already been resolved.";
 
-    case "guardian_text_unavailable":
-      return "I can't process text replies for approvals right now. Please use the approve/deny buttons above to respond.";
-
     default: {
       // Exhaustive check — TypeScript will flag if a scenario is missing.
       const _exhaustive: never = context.scenario;

package/src/runtime/assistant-event-hub.ts

@@ -49,10 +49,15 @@ export function capabilityForMessageType(
 }
 import type { AssistantEventEnvelope } from "../api/index.js";
 import { forwardEventPublishToDaemon } from "../ipc/events-publish-client.js";
+import {
+  type ClientConnectionEventReason,
+  recordClientConnectionEvent,
+} from "../persistence/client-connection-events-store.js";
 import { appendEventToStream } from "../signals/event-stream.js";
 import { getLogger } from "../util/logger.js";
 import { buildAssistantEvent } from "./assistant-event.js";
 import type { AssistantEventPublishOptions } from "./assistant-event-publish-options.js";
+import { matchesTargeting } from "./assistant-event-targeting.js";
 import { stampAndBuffer } from "./assistant-stream-state.js";
 import { isMainDaemonProcess } from "./process-role.js";
 
@@ -72,7 +77,7 @@ export type AssistantEventCallback = (
 
 /** Opaque handle returned by `subscribe`. Call `dispose()` to remove the subscription. */
 export interface AssistantEventSubscription {
-  dispose(): void;
+  dispose(reason?: ClientConnectionEventReason): void;
   /** True until `dispose()` has been called. */
   readonly active: boolean;
   /**
@@ -142,6 +147,10 @@ interface ClientEntry extends BaseSubscriberEntry {
    * service-token connections that have no principal.
    */
   actorPrincipalId?: string;
+  /** Client-reported build version (e.g. extension manifest version). */
+  clientVersion?: string;
+  /** Whether the client advertised an SSE idle watchdog on this connection. */
+  sseWatchdog?: boolean;
   /**
    * Last desktop presence reported by this client, for clients that report it.
    * In-memory only, so consumers must fail open when it is absent.
@@ -193,14 +202,22 @@ type SubscriberInput = DistributiveOmit<
  * Client connections register as subscribers with metadata and are queryable
  * via `listClients()`, `getMostRecentClientByCapability()`, etc.
  */
+export type ClientConnectionRecorder = typeof recordClientConnectionEvent;
+
 export class AssistantEventHub {
   private readonly subscribers = new Set<SubscriberEntry>();
   private readonly maxSubscribers: number;
   /** Monotonic source for per-connection ids, scoped to this hub. */
   private connectionCounter = 0;
+  private readonly recordConnection: ClientConnectionRecorder;
 
-  constructor(options?: { maxSubscribers?: number }) {
+  constructor(options?: {
+    maxSubscribers?: number;
+    recordConnection?: ClientConnectionRecorder;
+  }) {
     this.maxSubscribers = options?.maxSubscribers ?? Infinity;
+    this.recordConnection =
+      options?.recordConnection ?? recordClientConnectionEvent;
   }
 
   /**
@@ -231,6 +248,7 @@ export class AssistantEventHub {
       for (const entry of stale) {
         entry.active = false;
         this.subscribers.delete(entry);
+        this.recordClientLifecycle(entry, "stale_replaced");
         try {
           entry.onEvict();
         } catch {
@@ -258,6 +276,7 @@ export class AssistantEventHub {
       }
       oldest.active = false;
       this.subscribers.delete(oldest);
+      this.recordClientLifecycle(oldest, "cap_evicted");
       try {
         oldest.onEvict();
       } catch {
@@ -287,6 +306,7 @@ export class AssistantEventHub {
         },
         "subscriber registered (client)",
       );
+      this.recordClientLifecycle(entry, "sse_open");
     } else {
       log.info({ connectionId }, "subscriber registered (process)");
     }
@@ -294,11 +314,12 @@ export class AssistantEventHub {
     this.subscribers.add(entry);
 
     return {
-      dispose: () => {
+      dispose: (reason) => {
         if (entry.active) {
           entry.active = false;
           this.subscribers.delete(entry);
           if (entry.type === "client") {
+            this.recordClientLifecycle(entry, reason ?? "sse_close");
             log.info(
               {
                 clientId: entry.clientId,
@@ -323,21 +344,14 @@ export class AssistantEventHub {
    * Publish an event to all matching subscribers.
    *
    * Matching rules:
-   * - if `excludeClientId` is set, the subscriber with that clientId is
-   *   skipped regardless of every other rule (self-echo suppression — the
-   *   client that originated the mutation does not receive its own
-   *   invalidation back through the hub).
-   * - if `targetClientId` is set, deliver only to the subscriber with that
-   *   clientId, bypassing the conversation-id filter entirely (the web-origin
-   *   event's conversationId differs from the macOS client's subscribed
-   *   conversation).
-   * - if `filter.conversationId` is set (and `targetClientId` is not), the
-   *   `event.conversationId` must equal it
-   * - if `targetCapability` is set, only subscribers whose capabilities include
-   *   it receive the event; untargeted events go to all
-   * - if `targetInterfaceId` is set, only client subscribers whose
-   *   `interfaceId` matches receive the event; process subscribers and
-   *   non-matching clients are skipped.
+   * - the event's targeting (`excludeClientId`, `targetInterfaceId`,
+   *   `targetActorPrincipalId`, `targetClientId`, `targetCapability`) must
+   *   admit the subscriber, per {@link matchesTargeting}, the same check
+   *   replay applies
+   * - a subscriber's `filter.conversationId` must equal `event.conversationId`,
+   *   unless the event names a client with `targetClientId` (a web-origin
+   *   event's conversationId can differ from the conversation the targeted
+   *   macOS client subscribed to)
    *
    * Fanout is isolated: a throwing or rejecting subscriber does not abort
    * delivery to remaining subscribers.
@@ -362,10 +376,6 @@ export class AssistantEventHub {
       }
     }
 
-    const targetCapability = options?.targetCapability;
-    const targetClientId = options?.targetClientId;
-    const targetInterfaceId = options?.targetInterfaceId;
-    const excludeClientId = options?.excludeClientId;
     const snapshot = Array.from(this.subscribers);
     const errors: unknown[] = [];
 
@@ -373,63 +383,18 @@ export class AssistantEventHub {
       if (!entry.active) {
         continue;
       }
-
-      // Self-echo suppression: the originating client never receives the
-      // event back. Checked before every other rule so it composes with
-      // both targeted and untargeted broadcasts.
+      if (!matchesTargeting(options, entry)) {
+        continue;
+      }
       if (
-        excludeClientId != null &&
-        entry.type === "client" &&
-        entry.clientId === excludeClientId
+        options?.targetClientId == null &&
+        event.conversationId != null &&
+        entry.filter.conversationId != null &&
+        entry.filter.conversationId !== event.conversationId
       ) {
         continue;
       }
 
-      // Interface targeting: skip any subscriber that is not a client of
-      // the requested interface. Composes with `targetClientId` and
-      // `targetCapability` below.
-      if (targetInterfaceId != null) {
-        if (
-          entry.type !== "client" ||
-          entry.interfaceId !== targetInterfaceId
-        ) {
-          continue;
-        }
-      }
-
-      if (targetClientId != null) {
-        // Targeted: bypass conversation filter, deliver only to the named client.
-        if (entry.type !== "client" || entry.clientId !== targetClientId) {
-          continue;
-        }
-        if (
-          targetCapability != null &&
-          !entry.capabilities.includes(targetCapability)
-        ) {
-          continue;
-        }
-      } else {
-        // Untargeted: existing conversation-scoped + capability logic.
-        if (
-          event.conversationId != null &&
-          entry.filter.conversationId != null &&
-          entry.filter.conversationId !== event.conversationId
-        ) {
-          continue;
-        }
-
-        // Capability targeting: targeted events only go to subscribers that
-        // declare the required capability.
-        if (targetCapability != null) {
-          if (
-            entry.type !== "client" ||
-            !entry.capabilities.includes(targetCapability)
-          ) {
-            continue;
-          }
-        }
-      }
-
       try {
         await entry.callback(event);
       } catch (err) {
@@ -673,6 +638,7 @@ export class AssistantEventHub {
     for (const entry of targets) {
       entry.active = false;
       this.subscribers.delete(entry);
+      this.recordClientLifecycle(entry, "force_disconnect");
       try {
         entry.onEvict();
       } catch {
@@ -688,6 +654,29 @@ export class AssistantEventHub {
     return targets.length;
   }
 
+  /**
+   * Best-effort history row for a client subscriber. Process subscribers
+   * and an unready database are skipped; a write failure never throws.
+   */
+  private recordClientLifecycle(
+    entry: SubscriberEntry,
+    reason: ClientConnectionEventReason,
+  ): void {
+    if (entry.type !== "client") {
+      return;
+    }
+    this.recordConnection({
+      clientId: entry.clientId,
+      interfaceId: entry.interfaceId,
+      connectionId: entry.connectionId,
+      reason,
+      actorPrincipalId: entry.actorPrincipalId,
+      clientVersion: entry.clientVersion,
+      sseWatchdog: entry.sseWatchdog,
+      machineName: entry.machineName,
+    });
+  }
+
   /** Number of currently active subscribers (useful for tests and caps). */
   subscriberCount(): number {
     return this.subscribers.size;
@@ -716,6 +705,12 @@ export const assistantEventHub = new AssistantEventHub({ maxSubscribers: 100 });
  */
 let _hubChain = Promise.resolve();
 
+/** Targeting a caller of {@link broadcastMessage} may request. */
+export type BroadcastMessageOptions = Pick<
+  AssistantEventPublishOptions,
+  "targetClientId" | "targetInterfaceId" | "targetActorPrincipalId"
+>;
+
 /**
  * Wraps a `AssistantEvent` in an `AssistantEventEnvelope` envelope and publishes it
  * to the process-level hub.
@@ -735,11 +730,12 @@ let _hubChain = Promise.resolve();
 export function broadcastMessage(
   msg: AssistantEvent,
   conversationId?: string,
-  options?: { targetClientId?: string; targetInterfaceId?: InterfaceId },
+  options?: BroadcastMessageOptions,
 ): void {
   const resolvedConversationId = conversationId ?? extractConversationId(msg);
   const targetClientId = options?.targetClientId;
   const targetInterfaceId = options?.targetInterfaceId;
+  const targetActorPrincipalId = options?.targetActorPrincipalId;
 
   const event = buildAssistantEvent(msg, resolvedConversationId);
   // A reconnect can overlap an older executor with the same device ID.
@@ -765,11 +761,13 @@ export function broadcastMessage(
     targetCapability != null ||
     targetClientId != null ||
     targetInterfaceId != null ||
+    targetActorPrincipalId != null ||
     excludeClientId != null
       ? {
           targetCapability,
           targetClientId,
           targetInterfaceId,
+          targetActorPrincipalId,
           excludeClientId,
         }
       : undefined;

package/src/runtime/assistant-event-publish-options.ts

@@ -15,6 +15,13 @@ export const AssistantEventPublishOptionsSchema = z.object({
   targetCapability: z.enum(HOST_PROXY_CAPABILITIES).optional(),
   targetClientId: z.string().optional(),
   targetInterfaceId: z.enum(INTERFACE_IDS).optional(),
+  /**
+   * Deliver only to client subscribers whose verified `actorPrincipalId`
+   * equals this value. Subscribers without a principal never match, so an
+   * event scoped to one person fails closed rather than reaching a connection
+   * whose identity is unknown.
+   */
+  targetActorPrincipalId: z.string().optional(),
   /**
    * Skip the subscriber with this `clientId`. Used for self-echo suppression on
    * `sync_changed`: the route handler echoes the originating tab's

package/src/runtime/assistant-event-targeting.ts

@@ -0,0 +1,79 @@
+/**
+ * Who receives a targeted assistant event. Live fanout
+ * (`AssistantEventHub.publish`) and replay (`getReplayWindow`, reached from
+ * the SSE reconnect and the `events/tail` route) both decide delivery with
+ * {@link matchesTargeting}, so a targeting rule added here reaches every
+ * path at once.
+ *
+ * Conversation scoping is deliberately not part of this check. Live fanout
+ * applies a subscriber's conversation filter only to events that do not name
+ * a client; replay scopes to the conversation its caller asked for. Each path
+ * applies its own scoping after this check.
+ */
+
+import type { HostProxyCapability, InterfaceId } from "../channels/types.js";
+import type { AssistantEventPublishOptions } from "./assistant-event-publish-options.js";
+
+/** The connection an event is being delivered to, live or on replay. */
+export interface SubscriberIdentity {
+  type: "client" | "process";
+  clientId?: string;
+  interfaceId?: InterfaceId;
+  capabilities?: readonly HostProxyCapability[];
+  actorPrincipalId?: string;
+}
+
+/**
+ * Whether `subscriber` receives an event carrying `targeting`. An event with
+ * no targeting reaches every subscriber. Every rule a targeted event sets must
+ * hold, and a process subscriber never matches a rule that names a client
+ * property.
+ */
+export function matchesTargeting(
+  targeting: AssistantEventPublishOptions | undefined,
+  subscriber: SubscriberIdentity,
+): boolean {
+  if (!targeting) {
+    return true;
+  }
+  const isClient = subscriber.type === "client";
+
+  // Self-echo suppression: the client that originated a mutation does not
+  // receive its own invalidation back.
+  if (
+    targeting.excludeClientId != null &&
+    isClient &&
+    subscriber.clientId === targeting.excludeClientId
+  ) {
+    return false;
+  }
+  if (
+    targeting.targetInterfaceId != null &&
+    (!isClient || subscriber.interfaceId !== targeting.targetInterfaceId)
+  ) {
+    return false;
+  }
+  // An event scoped to one person reaches only that person's connections; a
+  // connection with no verified principal never matches.
+  if (
+    targeting.targetActorPrincipalId != null &&
+    (!isClient ||
+      subscriber.actorPrincipalId !== targeting.targetActorPrincipalId)
+  ) {
+    return false;
+  }
+  if (
+    targeting.targetClientId != null &&
+    (!isClient || subscriber.clientId !== targeting.targetClientId)
+  ) {
+    return false;
+  }
+  if (
+    targeting.targetCapability != null &&
+    (!isClient ||
+      !subscriber.capabilities?.includes(targeting.targetCapability))
+  ) {
+    return false;
+  }
+  return true;
+}

package/src/runtime/assistant-stream-state.ts

@@ -70,6 +70,11 @@ import {
 import type { AssistantEventEnvelope } from "../api/index.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
+import type { AssistantEventPublishOptions } from "./assistant-event-publish-options.js";
+import {
+  matchesTargeting,
+  type SubscriberIdentity,
+} from "./assistant-event-targeting.js";
 
 const log = getLogger("assistant-stream-state");
 
@@ -93,39 +98,13 @@ const SEQ_RESERVATION_BLOCK = 1024;
 
 // ── Types ────────────────────────────────────────────────────────────
 
-/**
- * Targeting / exclusion modifiers attached to an event at publish time.
- * Stored on ring entries so replay can re-apply the same delivery
- * filter that the live `publish()` path used.
- *
- * Fields use plain `string` rather than branded channel types so
- * this module stays independent of the `channels/` package.
- */
-export interface EventTargeting {
-  targetCapability?: string;
-  targetClientId?: string;
-  targetInterfaceId?: string;
-  excludeClientId?: string;
-}
-
-/**
- * Identity of the subscriber requesting a replay window. Replay
- * filtering mirrors the live `publish()` logic in `AssistantEventHub`:
- * targeted entries are only delivered when the subscriber matches.
- */
-export interface ReplaySubscriber {
-  type: "client" | "process";
-  clientId?: string;
-  interfaceId?: string;
-  capabilities?: readonly string[];
-}
-
 interface RingEntry {
   seq: number;
   event: AssistantEventEnvelope;
   emittedAt: number;
   sizeBytes: number;
-  targeting?: EventTargeting;
+  /** The publish options the event went out with, re-applied on replay. */
+  targeting?: AssistantEventPublishOptions;
 }
 
 interface AssistantStreamState {
@@ -215,7 +194,7 @@ export function isStreamSeqStampingDisabled(): boolean {
  */
 export function stampAndBuffer(
   event: AssistantEventEnvelope,
-  options?: { targeting?: EventTargeting },
+  options?: { targeting?: AssistantEventPublishOptions },
 ): void {
   if (stampingDisabled) {
     return;
@@ -272,9 +251,9 @@ export function stampAndBuffer(
  * buffered entry -- callers should fall back to a snapshot resync.
  *
  * When `subscriber` is provided, entries carrying targeting metadata
- * are filtered using the same rules as the live `publish()` path in
- * `AssistantEventHub`, so targeted events do not leak to subscribers
- * outside their intended delivery set on reconnect.
+ * are filtered with {@link matchesTargeting}, the check the live
+ * `publish()` path in `AssistantEventHub` applies, so targeted events do
+ * not leak to subscribers outside their intended delivery set on reconnect.
  *
  * When `conversationId` is provided, only that conversation's events are
  * returned -- a conversation-scoped subscription only delivers its own
@@ -287,7 +266,7 @@ export function stampAndBuffer(
  */
 export function getReplayWindow(
   lastSeenSeq: number,
-  subscriber?: ReplaySubscriber,
+  subscriber?: SubscriberIdentity,
   conversationId?: string,
 ): readonly AssistantEventEnvelope[] | null {
   evict();
@@ -315,7 +294,7 @@ export function getReplayWindow(
         entry.seq > lastSeenSeq &&
         (conversationId == null ||
           entry.event.conversationId === conversationId) &&
-        (subscriber == null || matchesSubscriber(entry, subscriber)),
+        (subscriber == null || matchesTargeting(entry.targeting, subscriber)),
     )
     .map((entry) => entry.event);
 }
@@ -518,72 +497,6 @@ function readReservedCeiling(): number {
   return 0;
 }
 
-/**
- * Mirrors the delivery logic in `AssistantEventHub.publish()`. Returns
- * `true` when `subscriber` would have received the entry during live
- * fanout.
- */
-function matchesSubscriber(
-  entry: RingEntry,
-  subscriber: ReplaySubscriber,
-): boolean {
-  const t = entry.targeting;
-  if (!t) {
-    return true;
-  }
-
-  // Self-echo suppression: the originating client never receives the
-  // event back.
-  if (
-    t.excludeClientId != null &&
-    subscriber.type === "client" &&
-    subscriber.clientId === t.excludeClientId
-  ) {
-    return false;
-  }
-
-  // Interface targeting: only clients of the requested interface.
-  if (t.targetInterfaceId != null) {
-    if (
-      subscriber.type !== "client" ||
-      subscriber.interfaceId !== t.targetInterfaceId
-    ) {
-      return false;
-    }
-  }
-
-  if (t.targetClientId != null) {
-    // Client targeting: bypass conversation filter, deliver only to the
-    // named client.
-    if (
-      subscriber.type !== "client" ||
-      subscriber.clientId !== t.targetClientId
-    ) {
-      return false;
-    }
-    if (
-      t.targetCapability != null &&
-      !subscriber.capabilities?.includes(t.targetCapability)
-    ) {
-      return false;
-    }
-    return true;
-  }
-
-  // Capability targeting (without client targeting): only subscribers
-  // that declare the required capability.
-  if (t.targetCapability != null) {
-    if (
-      subscriber.type !== "client" ||
-      !subscriber.capabilities?.includes(t.targetCapability)
-    ) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
 function evict(): void {
   const now = Date.now();
   while (state.ring.length > 0) {