@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/runtime/__tests__/question-resolution.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Tests for the shared question resolver (`question-resolution.ts`) — the single
+ * implementation `/v1/question-response` and the channel wizard both funnel
+ * through. Focuses on the discriminated outcome (resolved / not_found / invalid)
+ * that lets each caller map to its own surface.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import type { QuestionPromptResult } from "../../permissions/question-prompter.js";
+import * as pendingInteractions from "../pending-interactions.js";
+import { resolvePendingQuestion } from "../question-resolution.js";
+
+function registerQuestion(
+  requestId: string,
+  questions: Array<{ id: string; options: string[] }>,
+  rpcResolve: (value: unknown) => void = () => {},
+): void {
+  const optionsById: Record<string, string[]> = {};
+  for (const q of questions) {
+    optionsById[q.id] = q.options;
+  }
+  pendingInteractions.register(requestId, {
+    conversationId: "conv-1",
+    kind: "question",
+    rpcResolve,
+    metadata: { orderedIds: questions.map((q) => q.id), optionsById },
+  });
+}
+
+beforeEach(() => pendingInteractions.clear());
+afterEach(() => pendingInteractions.clear());
+
+describe("resolvePendingQuestion", () => {
+  test("resolved: submits, fires rpcResolve, and consumes the interaction", () => {
+    const resolved: QuestionPromptResult[] = [];
+    registerQuestion("req-1", [{ id: "q1", options: ["a", "b"] }], (v) =>
+      resolved.push(v as QuestionPromptResult),
+    );
+
+    const outcome = resolvePendingQuestion("req-1", {
+      kind: "submit",
+      submissions: [{ questionId: "q1", kind: "option", optionId: "a" }],
+    });
+
+    expect(outcome).toMatchObject({
+      status: "resolved",
+      conversationId: "conv-1",
+    });
+    expect(resolved[0].overall).toBe("completed");
+    expect(pendingInteractions.get("req-1")).toBeUndefined();
+  });
+
+  test("close: reports every question skipped, overall closed", () => {
+    const resolved: QuestionPromptResult[] = [];
+    registerQuestion(
+      "req-1",
+      [
+        { id: "q1", options: ["a"] },
+        { id: "q2", options: ["b"] },
+      ],
+      (v) => resolved.push(v as QuestionPromptResult),
+    );
+
+    const outcome = resolvePendingQuestion("req-1", { kind: "close" });
+    expect(outcome.status).toBe("resolved");
+    expect(resolved[0]).toEqual({
+      overall: "closed",
+      entries: [
+        { questionId: "q1", decision: "skipped" },
+        { questionId: "q2", decision: "skipped" },
+      ],
+    });
+  });
+
+  test("not_found: unknown or wrong-kind requestId leaves nothing resolved", () => {
+    expect(resolvePendingQuestion("missing", { kind: "close" })).toEqual({
+      status: "not_found",
+    });
+
+    pendingInteractions.register("conf-1", {
+      conversationId: "conv-1",
+      kind: "confirmation",
+    });
+    expect(
+      resolvePendingQuestion("conf-1", {
+        kind: "submit",
+        submissions: [{ questionId: "q1", kind: "skip" }],
+      }),
+    ).toEqual({ status: "not_found" });
+  });
+
+  test("invalid: a bad submission leaves the interaction intact for a retry", () => {
+    let resolveCount = 0;
+    registerQuestion(
+      "req-1",
+      [{ id: "q1", options: ["a", "b"] }],
+      () => resolveCount++,
+    );
+
+    const outcome = resolvePendingQuestion("req-1", {
+      kind: "submit",
+      submissions: [{ questionId: "q1", kind: "option", optionId: "nope" }],
+    });
+
+    expect(outcome.status).toBe("invalid");
+    // Interaction untouched — the prompt can be resubmitted.
+    expect(pendingInteractions.get("req-1")).toBeDefined();
+    expect(resolveCount).toBe(0);
+  });
+});

package/src/runtime/access-request-helper.ts

@@ -25,7 +25,7 @@ import {
   recordGuardianRequestDeliveries,
 } from "../notifications/guardian-delivery-recorder.js";
 import type { GuardianResolutionSource } from "../notifications/signal.js";
-import { getConversation } from "../persistence/conversation-crud.js";
+import { buildVellumCardAffinity } from "../notifications/vellum-card-affinity.js";
 import { IntegrityError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import { resolveAnchoredGuardian } from "./anchored-guardian.js";
@@ -332,20 +332,12 @@ export async function notifyGuardianOfAccessRequest(
     TEXT_CHANNELS_WITH_DELIVERY.has(sourceChannel) &&
     guardianResolutionSource === "source-channel-contact";
 
-  // Pin the in-app (vellum) card to the originating conversation when the caller
-  // supplied one, so the card lands inside it instead of a fresh standalone
-  // "Chat". `pairDeliveryWithConversation` reuses a conversation only when its
-  // source matches the signal's, so mirror the target's source (inbound
-  // conversations default to "user"); a stale/missing target falls back to a
-  // new conversation via the same pairing path.
-  const vellumConversationAffinity = destinationConversationId
-    ? {
-        conversationAffinityHint: { vellum: destinationConversationId },
-        conversationMetadata: {
-          source: getConversation(destinationConversationId)?.source ?? "user",
-        },
-      }
-    : undefined;
+  // Pin the in-app (vellum) card to the originating conversation when the
+  // caller supplied one, so the card lands inside it instead of a fresh
+  // standalone "Chat".
+  const vellumConversationAffinity = buildVellumCardAffinity(
+    destinationConversationId,
+  );
 
   void emitNotificationSignal({
     sourceEventName: "ingress.access_request",

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

@@ -12,8 +12,8 @@
  * Client-oriented queries (list, find-by-capability) are methods on the hub.
  */
 
+import type { AssistantEvent } from "../api/index.js";
 import type { HostProxyCapability, InterfaceId } from "../channels/types.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
 
 // ---------------------------------------------------------------------------
 // Message type → capability inference
@@ -40,11 +40,14 @@ export function capabilityForMessageType(
   const stem = type.replace(/_(request|cancel)$/, "");
   return HOST_PREFIX_TO_CAPABILITY[stem];
 }
+import type { AssistantEventEnvelope } from "../api/index.js";
+import { forwardEventPublishToDaemon } from "../ipc/events-publish-client.js";
 import { appendEventToStream } from "../signals/event-stream.js";
 import { getLogger } from "../util/logger.js";
-import type { AssistantEvent } from "./assistant-event.js";
 import { buildAssistantEvent } from "./assistant-event.js";
+import type { AssistantEventPublishOptions } from "./assistant-event-publish-options.js";
 import { stampAndBuffer } from "./assistant-stream-state.js";
+import { isMainDaemonProcess } from "./process-role.js";
 
 const log = getLogger("assistant-event-hub");
 
@@ -57,7 +60,7 @@ export type AssistantEventFilter = {
 };
 
 export type AssistantEventCallback = (
-  event: AssistantEvent,
+  event: AssistantEventEnvelope,
 ) => void | Promise<void>;
 
 /** Opaque handle returned by `subscribe`. Call `dispose()` to remove the subscription. */
@@ -138,7 +141,7 @@ type SubscriberInput = DistributiveOmit<
 // ── Hub ───────────────────────────────────────────────────────────────────────
 
 /**
- * Lightweight pub/sub hub for `AssistantEvent` messages.
+ * Lightweight pub/sub hub for `AssistantEventEnvelope` messages.
  *
  * Filtering is applied at subscription level:
  *   - `conversationId`: scoped events match subscribers with same conversationId
@@ -301,21 +304,17 @@ export class AssistantEventHub {
    * delivery to remaining subscribers.
    */
   async publish(
-    event: AssistantEvent,
-    options?: {
-      targetCapability?: HostProxyCapability;
-      targetClientId?: string;
-      targetInterfaceId?: InterfaceId;
-      /**
-       * Skip the subscriber with this `clientId`. Used for self-echo
-       * suppression on `sync_changed`: the route handler echoes the
-       * originating tab's `X-Vellum-Client-Id` back on the event, and the
-       * hub uses it here to avoid re-delivering the invalidation to the
-       * tab that already mutated its own optimistic state.
-       */
-      excludeClientId?: string;
-    },
+    event: AssistantEventEnvelope,
+    options?: AssistantEventPublishOptions,
   ): Promise<void> {
+    // Only the main daemon owns the subscribers real clients connect to. In any
+    // other process (a sidecar worker, the route host) this hub has no SSE
+    // subscriber, so hand the event to the daemon — it republishes on the hub
+    // clients actually observe. Best-effort: a transport failure is logged, not
+    // thrown, and never blocks the caller.
+    if (!isMainDaemonProcess()) {
+      return forwardEventPublishToDaemon(event, options);
+    }
     if (event.conversationId) {
       try {
         appendEventToStream(event.conversationId, event);
@@ -332,7 +331,9 @@ export class AssistantEventHub {
     const errors: unknown[] = [];
 
     for (const entry of snapshot) {
-      if (!entry.active) continue;
+      if (!entry.active) {
+        continue;
+      }
 
       // Self-echo suppression: the originating client never receives the
       // event back. Checked before every other rule so it composes with
@@ -349,27 +350,34 @@ export class AssistantEventHub {
       // the requested interface. Composes with `targetClientId` and
       // `targetCapability` below.
       if (targetInterfaceId != null) {
-        if (entry.type !== "client" || entry.interfaceId !== targetInterfaceId)
+        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)
+        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.
@@ -377,8 +385,9 @@ export class AssistantEventHub {
           if (
             entry.type !== "client" ||
             !entry.capabilities.includes(targetCapability)
-          )
+          ) {
             continue;
+          }
         }
       }
 
@@ -407,8 +416,9 @@ export class AssistantEventHub {
         entry.active &&
         entry.type === "client" &&
         entry.clientId === clientId
-      )
+      ) {
         return entry;
+      }
     }
     return undefined;
   }
@@ -430,10 +440,12 @@ export class AssistantEventHub {
    * event based on the same conversation matching rules as publish().
    */
   hasSubscribersForEvent(
-    event: Pick<AssistantEvent, "conversationId">,
+    event: Pick<AssistantEventEnvelope, "conversationId">,
   ): boolean {
     for (const entry of this.subscribers) {
-      if (!entry.active) continue;
+      if (!entry.active) {
+        continue;
+      }
       if (
         event.conversationId != null &&
         entry.filter.conversationId != null &&
@@ -563,7 +575,7 @@ export class AssistantEventHub {
  */
 export const assistantEventHub = new AssistantEventHub({ maxSubscribers: 100 });
 
-// ── Convenience: ServerMessage → AssistantEvent publish ───────────────────────
+// ── Convenience: AssistantEvent → AssistantEventEnvelope publish ───────────────────────
 
 /**
  * Promise chain that serializes publishes so subscribers always observe
@@ -572,7 +584,7 @@ export const assistantEventHub = new AssistantEventHub({ maxSubscribers: 100 });
 let _hubChain = Promise.resolve();
 
 /**
- * Wraps a `ServerMessage` in an `AssistantEvent` envelope and publishes it
+ * Wraps a `AssistantEvent` in an `AssistantEventEnvelope` envelope and publishes it
  * to the process-level hub.
  *
  * When `conversationId` is omitted, it is auto-extracted from the message
@@ -588,7 +600,7 @@ let _hubChain = Promise.resolve();
  * services should call this directly instead of threading a broadcast callback.
  */
 export function broadcastMessage(
-  msg: ServerMessage,
+  msg: AssistantEvent,
   conversationId?: string,
   options?: { targetClientId?: string; targetInterfaceId?: InterfaceId },
 ): void {
@@ -666,7 +678,7 @@ export function broadcastMessage(
     });
 }
 
-function extractConversationId(msg: ServerMessage): string | undefined {
+function extractConversationId(msg: AssistantEvent): string | undefined {
   const record = msg as unknown as Record<string, unknown>;
   if ("conversationId" in msg && typeof record.conversationId === "string") {
     return record.conversationId as string;

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

@@ -0,0 +1,31 @@
+/**
+ * Canonical schema + type for the targeting/suppression options accepted by the
+ * assistant event hub's `publish`.
+ *
+ * Kept in its own module so both the in-process consumer (the hub's `publish`
+ * signature) and the wire consumer (the `/events/publish` IPC route's param
+ * validation) reuse one definition instead of drifting apart.
+ */
+
+import { z } from "zod";
+
+import { HOST_PROXY_CAPABILITIES, INTERFACE_IDS } from "../channels/types.js";
+
+export const AssistantEventPublishOptionsSchema = z.object({
+  targetCapability: z.enum(HOST_PROXY_CAPABILITIES).optional(),
+  targetClientId: z.string().optional(),
+  targetInterfaceId: z.enum(INTERFACE_IDS).optional(),
+  /**
+   * Skip the subscriber with this `clientId`. Used for self-echo suppression on
+   * `sync_changed`: the route handler echoes the originating tab's
+   * `X-Vellum-Client-Id` back on the event, and the hub uses it here to avoid
+   * re-delivering the invalidation to the tab that already mutated its own
+   * optimistic state.
+   */
+  excludeClientId: z.string().optional(),
+});
+
+/** Targeting/suppression options for {@link AssistantEventHub.publish}. */
+export type AssistantEventPublishOptions = z.infer<
+  typeof AssistantEventPublishOptionsSchema
+>;

package/src/runtime/assistant-event.ts

@@ -1,16 +1,18 @@
 /**
- * Assistant Events -- shared envelope type, SSE framing helpers, and the
+ * Assistant Events -- generic SSE envelope, framing helpers, and the
  * daemon-side specialization.
  *
  * The generic `BaseAssistantEvent<TMessage>` envelope and its framing
- * helpers carry no daemon imports. This file pins the generic payload to
- * the daemon-side `ServerMessage` union so existing callers continue to get
- * full discriminated-union narrowing.
+ * helpers carry no daemon imports. The daemon-side `AssistantEvent` type and
+ * `buildAssistantEvent` builder pin the payload to the canonical
+ * `AssistantEvent` message union (`z.infer<AssistantEventSchema>`), so callers
+ * get full discriminated-union narrowing. The concrete envelope shape is the
+ * canonical `AssistantEventEnvelope` from `../api`.
  */
 
 import { randomUUID } from "node:crypto";
 
-import type { ServerMessage } from "../daemon/message-protocol.js";
+import type { AssistantEvent, AssistantEventEnvelope } from "../api/index.js";
 
 // -- Generic base --------------------------------------------------------------
 
@@ -39,24 +41,6 @@ interface BaseAssistantEvent<TMessage = unknown> {
   message: TMessage;
 }
 
-/**
- * Construct a `BaseAssistantEvent` envelope around a message payload.
- *
- * @param message         The outbound message payload.
- * @param conversationId  Optional conversation id -- pass when known.
- */
-function baseBuildAssistantEvent<TMessage>(
-  message: TMessage,
-  conversationId?: string,
-): BaseAssistantEvent<TMessage> {
-  return {
-    id: randomUUID(),
-    conversationId,
-    emittedAt: new Date().toISOString(),
-    message,
-  };
-}
-
 // -- SSE framing ---------------------------------------------------------------
 
 /**
@@ -92,13 +76,18 @@ export function formatSseHeartbeat(): string {
 
 // -- Daemon-side specialization ------------------------------------------------
 
-/** Daemon-side specialization of the generic event envelope. */
-export type AssistantEvent = BaseAssistantEvent<ServerMessage>;
-
-/** Daemon-side wrapper preserving the original `ServerMessage`-typed signature. */
+/**
+ * Build a daemon event envelope (`AssistantEventEnvelope`) around an
+ * `AssistantEvent` message payload.
+ */
 export function buildAssistantEvent(
-  message: ServerMessage,
+  message: AssistantEvent,
   conversationId?: string,
-): AssistantEvent {
-  return baseBuildAssistantEvent<ServerMessage>(message, conversationId);
+): AssistantEventEnvelope {
+  return {
+    id: randomUUID(),
+    conversationId,
+    emittedAt: new Date().toISOString(),
+    message,
+  };
 }

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

@@ -67,9 +67,9 @@ import {
   SSE_REPLAY_RING_AGE_LIMIT_MS,
   SSE_REPLAY_RING_COUNT_LIMIT,
 } from "../api/constants/sse-replay.js";
+import type { AssistantEventEnvelope } from "../api/index.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
-import type { AssistantEvent } from "./assistant-event.js";
 
 const log = getLogger("assistant-stream-state");
 
@@ -122,7 +122,7 @@ export interface ReplaySubscriber {
 
 interface RingEntry {
   seq: number;
-  event: AssistantEvent;
+  event: AssistantEventEnvelope;
   emittedAt: number;
   sizeBytes: number;
   targeting?: EventTargeting;
@@ -214,7 +214,7 @@ export function isStreamSeqStampingDisabled(): boolean {
  * Mutates `event.seq` in place.
  */
 export function stampAndBuffer(
-  event: AssistantEvent,
+  event: AssistantEventEnvelope,
   options?: { targeting?: EventTargeting },
 ): void {
   if (stampingDisabled) {
@@ -289,7 +289,7 @@ export function getReplayWindow(
   lastSeenSeq: number,
   subscriber?: ReplaySubscriber,
   conversationId?: string,
-): readonly AssistantEvent[] | null {
+): readonly AssistantEventEnvelope[] | null {
   evict();
 
   if (state.ring.length === 0) {

package/src/runtime/channel-approvals.ts

@@ -220,28 +220,3 @@ export function buildGuardianApprovalPrompt(
 
   return { promptText, actions, plainTextFallback };
 }
-
-// ---------------------------------------------------------------------------
-// 5. Channel UI capability check
-// ---------------------------------------------------------------------------
-
-/**
- * Channels known to support rich inline approval UI (e.g. inline keyboards).
- * All other channels fall back to plain-text instructions embedded in the
- * message body.
- */
-const RICH_APPROVAL_CHANNELS: ReadonlySet<string> = new Set([
-  "telegram",
-  "whatsapp",
-  "slack",
-]);
-
-/**
- * Returns true when the given channel supports rich approval UI such as
- * inline buttons / keyboards. For channels that return false, the
- * plainTextFallback instructions should be appended to the message body
- * so the user sees how to approve or reject via text.
- */
-export function channelSupportsRichApprovalUI(channel: string): boolean {
-  return RICH_APPROVAL_CHANNELS.has(channel);
-}