@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/runtime/question-request-guardian-bridge.ts

@@ -0,0 +1,184 @@
+/**
+ * Bridge a guardian's parked `ask_question` prompt to a `guardian.question`
+ * notification.
+ *
+ * Mirrors `confirmation-request-guardian-bridge.ts` for the question kind:
+ * emits the notification signal (the broadcaster renders the options as card
+ * actions — see `resolveQuestionOptionsContext`) and records the resulting
+ * card deliveries so reply routing can address taps and reactions back to the
+ * request.
+ *
+ * Unlike the confirmation bridge — which escalates a NON-guardian's request TO
+ * the guardian — the caller (`question-guardian-request.ts`) has already
+ * established that the asking turn belongs to the guardian; this bridge only
+ * verifies the channel's guardian binding still matches so a rebind between
+ * ingress and prompt emission can't deliver the question card to the wrong
+ * recipient.
+ */
+
+import type { QuestionEntry } from "../api/events/question-request.js";
+import type { GuardianRequestWire } from "../channels/gateway-guardian-requests.js";
+import type { TrustContext } from "../daemon/trust-context-types.js";
+import { emitNotificationSignal } from "../notifications/emit-signal.js";
+import {
+  recordApprovalCardDelivery,
+  recordGuardianRequestDeliveries,
+} from "../notifications/guardian-delivery-recorder.js";
+import { buildVellumCardAffinity } from "../notifications/vellum-card-affinity.js";
+import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
+import { getLogger } from "../util/logger.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
+import { getGuardianBinding } from "./channel-verification-service.js";
+
+const log = getLogger("question-request-guardian-bridge");
+
+export interface BridgeQuestionRequestParams {
+  /** The guardian request already persisted for this question. */
+  guardianRequest: GuardianRequestWire;
+  /** Trust context snapshot from the asking turn. */
+  trustContext: TrustContext;
+  /** Conversation the question was asked in. */
+  conversationId: string;
+  /** The (single) question entry being asked. */
+  question: QuestionEntry;
+  /** Logical assistant ID (defaults to 'self'). */
+  assistantId?: string;
+}
+
+export type BridgeQuestionRequestResult =
+  | { bridged: true; signalId: string }
+  | {
+      skipped: true;
+      reason: "no_guardian_binding" | "binding_identity_mismatch";
+    };
+
+/**
+ * Emit the `guardian.question` signal for a parked question and record the
+ * card deliveries. Fire-and-forget safe: emission errors are logged, never
+ * propagated.
+ */
+export async function bridgeQuestionRequestToGuardian(
+  params: BridgeQuestionRequestParams,
+): Promise<BridgeQuestionRequestResult> {
+  const {
+    guardianRequest,
+    trustContext,
+    conversationId,
+    question,
+    assistantId = DAEMON_INTERNAL_ASSISTANT_ID,
+  } = params;
+
+  const sourceChannel = trustContext.sourceChannel;
+  const binding = await getGuardianBinding(assistantId, sourceChannel);
+  if (!binding) {
+    log.debug(
+      { sourceChannel, conversationId },
+      "No guardian binding for question request bridge",
+    );
+    return { skipped: true, reason: "no_guardian_binding" };
+  }
+
+  // A guardian rebind between ingress and prompt emission would deliver the
+  // question card to the wrong recipient — mirror the confirmation bridge's
+  // canonicalized identity check.
+  const canonicalizedBindingGuardianId = canonicalizeInboundIdentity(
+    sourceChannel,
+    binding.guardianExternalUserId,
+  );
+  const canonicalizedRequestGuardianId = guardianRequest.guardianExternalUserId
+    ? canonicalizeInboundIdentity(
+        sourceChannel,
+        guardianRequest.guardianExternalUserId,
+      )
+    : null;
+  if (
+    canonicalizedRequestGuardianId &&
+    canonicalizedBindingGuardianId !== canonicalizedRequestGuardianId
+  ) {
+    log.warn(
+      {
+        sourceChannel,
+        requestId: guardianRequest.id,
+      },
+      "Guardian binding identity does not match the question request guardian — skipping notification to prevent misrouting",
+    );
+    return { skipped: true, reason: "binding_identity_mismatch" };
+  }
+
+  // The vellum delivery row is created up front in onConversationCreated so
+  // the in-app client sees it immediately; the post-resolve recorder reuses it.
+  let vellumDeliveryIdPromise: Promise<string | undefined> | undefined;
+
+  const signalPromise = emitNotificationSignal({
+    sourceEventName: "guardian.question",
+    sourceChannel,
+    sourceContextId: conversationId,
+    requiresConversation: true,
+    // Pin the in-app (vellum) card to the conversation the question was
+    // asked in, so the guardian answers it in context.
+    ...(buildVellumCardAffinity(conversationId) ?? {}),
+    attentionHints: {
+      requiresAction: true,
+      urgency: "high",
+      isAsyncBackground: false,
+      // MUST be false: visibleInSourceNow is a hard suppression pre-gate in
+      // emitNotificationSignal (source-active check) — it means "the user can
+      // already see this content in the source surface, skip notifying". A
+      // parked ask_question renders NOTHING in the source chat by itself; this
+      // card IS the prompt, so suppressing it would leave the turn hanging
+      // until the prompt timeout.
+      visibleInSourceNow: false,
+    },
+    contextPayload: {
+      requestKind: "pending_question",
+      requestId: guardianRequest.id,
+      requestCode:
+        guardianRequest.requestCode ??
+        guardianRequest.id.slice(0, 6).toUpperCase(),
+      sourceChannel,
+      requesterExternalUserId: trustContext.requesterExternalUserId,
+      requesterChatId: trustContext.requesterChatId ?? null,
+      questionText: question.question,
+      options: question.options.map((option) => ({
+        id: option.id,
+        label: option.label,
+      })),
+    },
+    dedupeKey: `ask-question-request:${guardianRequest.id}`,
+    onConversationCreated: (info) => {
+      vellumDeliveryIdPromise ??= recordApprovalCardDelivery({
+        requestId: guardianRequest.id,
+        channel: "vellum",
+        conversationId: info.conversationId,
+      }).then((delivery) => delivery?.id);
+      return vellumDeliveryIdPromise.then(() => undefined);
+    },
+  });
+
+  void signalPromise
+    .then(async (signalResult) => {
+      await recordGuardianRequestDeliveries({
+        requestId: guardianRequest.id,
+        deliveryResults: signalResult.deliveryResults,
+        vellumDeliveryId: await vellumDeliveryIdPromise,
+      });
+    })
+    .catch((err) => {
+      log.warn(
+        { err, requestId: guardianRequest.id },
+        "Failed to record channel deliveries for question bridge",
+      );
+    });
+
+  log.info(
+    {
+      sourceChannel,
+      requestId: guardianRequest.id,
+      requestCode: guardianRequest.requestCode,
+      optionCount: question.options.length,
+    },
+    "Guardian notified of pending question",
+  );
+
+  return { bridged: true, signalId: guardianRequest.id };
+}

package/src/runtime/question-resolution.ts

@@ -0,0 +1,153 @@
+/**
+ * Shared resolution core for pending `ask_question` interactions.
+ *
+ * A pending `question` interaction (registered by {@link QuestionPrompter}) can
+ * be resolved from two places:
+ *
+ *  - `POST /v1/question-response` — an app/web client submits the user's
+ *    batched selection (see `routes/question-routes.ts`).
+ *  - the guardian-request pipeline — a channel option tap, request-code reply,
+ *    or bare-text answer routes through the guardian reply router to the
+ *    `pending_question` resolver, which builds the submission (see
+ *    `approvals/guardian-request-resolvers.ts`).
+ *
+ * Both funnel through {@link resolvePendingQuestion} so the validate → consume
+ * → `rpcResolve` sequence has a single implementation. The helper is
+ * transport-agnostic: it returns a discriminated outcome rather than throwing
+ * route errors, so each caller maps the outcome to its own surface (HTTP status
+ * codes for the route; a resolver failure reason for the pipeline).
+ */
+
+import {
+  buildBatchEntries,
+  type QuestionBatchMetadata,
+  type QuestionBatchSubmission,
+  QuestionBatchValidationError,
+  type QuestionPromptResult,
+} from "../permissions/question-prompter.js";
+import * as pendingInteractions from "./pending-interactions.js";
+
+/**
+ * How to resolve a pending question: a batched submission (one entry per
+ * question) or a close (every question reported as `skipped`).
+ */
+export type QuestionResolutionInput =
+  | { kind: "submit"; submissions: QuestionBatchSubmission[] }
+  | { kind: "close" };
+
+/**
+ * Outcome of {@link resolvePendingQuestion}.
+ *
+ *  - `resolved` — the interaction was consumed and the prompter's caller
+ *    settled. `conversationId` is the owning conversation (absent for
+ *    conversation-less prompts).
+ *  - `not_found` — no pending `question` interaction matched the requestId
+ *    (already answered, timed out, superseded, or wrong kind). Callers treat
+ *    this as a stale request.
+ *  - `invalid` — the submission failed validation. The interaction is left
+ *    intact (timer still running) so the user can submit a correct batch.
+ */
+export type QuestionResolutionOutcome =
+  | {
+      status: "resolved";
+      result: QuestionPromptResult;
+      conversationId?: string;
+    }
+  | { status: "not_found" }
+  | { status: "invalid"; message: string };
+
+/**
+ * Resolve a pending `question` interaction with a batched submission or a
+ * close. Validation runs BEFORE the interaction is consumed, so an `invalid`
+ * outcome leaves the pending prompt (and its timer) intact for a retry.
+ */
+export function resolvePendingQuestion(
+  requestId: string,
+  input: QuestionResolutionInput,
+): QuestionResolutionOutcome {
+  const interaction = pendingInteractions.get(requestId);
+  if (!interaction || interaction.kind !== "question") {
+    return { status: "not_found" };
+  }
+
+  let result: QuestionPromptResult;
+  try {
+    if (input.kind === "close") {
+      const { orderedIds } = readBatchMetadata(interaction);
+      result = {
+        entries: orderedIds.map((id) => ({
+          questionId: id,
+          decision: "skipped" as const,
+        })),
+        overall: "closed",
+      };
+    } else {
+      result = buildCompletedResult(input.submissions, interaction);
+    }
+  } catch (err) {
+    if (err instanceof QuestionBatchValidationError) {
+      return { status: "invalid", message: err.message };
+    }
+    throw err;
+  }
+
+  // Validation passed — deregister now to clear the prompter timer, then hand
+  // the result to the prompter's caller via rpcResolve.
+  pendingInteractions.resolve(
+    requestId,
+    input.kind === "close" ? "cancelled" : "answered",
+  );
+
+  (
+    interaction.rpcResolve as
+      | ((value: QuestionPromptResult) => void)
+      | undefined
+  )?.(result);
+
+  return {
+    status: "resolved",
+    result,
+    conversationId: interaction.conversationId,
+  };
+}
+
+/**
+ * Build a `completed` QuestionPromptResult from a batched submission and the
+ * per-question metadata the prompter stashed on the interaction. Delegates the
+ * validation + ordering loop to {@link buildBatchEntries} so the prompter, the
+ * route, and the channel wizard share a single implementation.
+ */
+function buildCompletedResult(
+  submissions: QuestionBatchSubmission[],
+  interaction: ReturnType<typeof pendingInteractions.get>,
+): QuestionPromptResult {
+  const { orderedIds, optionsById } = readBatchMetadata(interaction);
+  if (orderedIds.length === 0) {
+    throw new QuestionBatchValidationError(
+      "No registered question ids for this batch",
+    );
+  }
+  const entries = buildBatchEntries(
+    orderedIds,
+    (qid, oid) => (optionsById[qid] ?? []).includes(oid),
+    new Set(Object.keys(optionsById)),
+    submissions,
+  );
+  return { entries, overall: "completed" };
+}
+
+/**
+ * Pull the prompter-stashed batch bookkeeping off a pending interaction.
+ * Returns empty defaults if the metadata is absent.
+ */
+export function readBatchMetadata(
+  interaction: ReturnType<typeof pendingInteractions.get>,
+): QuestionBatchMetadata {
+  const meta = interaction?.metadata as
+    | Partial<QuestionBatchMetadata>
+    | undefined;
+  return {
+    orderedIds: meta?.orderedIds ?? [],
+    optionsById: meta?.optionsById ?? {},
+  };
+}

package/src/runtime/routes/__tests__/bookmark-routes.test.ts

@@ -22,7 +22,9 @@ mock.module("../../assistant-event-hub.js", () => ({
     },
     subscribe: () => () => {},
   },
-  broadcastMessage: async () => {},
+  broadcastMessage: (message: unknown, conversationId?: string) => {
+    publishCalls.push({ message, conversationId });
+  },
 }));
 
 import { getDb } from "../../../persistence/db-connection.js";
@@ -47,7 +49,9 @@ await initializeDb();
 
 function findHandler(operationId: string): RouteDefinition["handler"] {
   const route = BOOKMARK_ROUTES.find((r) => r.operationId === operationId);
-  if (!route) throw new Error(`Route ${operationId} not found`);
+  if (!route) {
+    throw new Error(`Route ${operationId} not found`);
+  }
   return route.handler;
 }
 

package/src/runtime/routes/__tests__/conversation-query-routes.test.ts

@@ -71,7 +71,7 @@ import {
   type MemoryV2ConceptRowRecord,
   type MemoryV2ConfigSnapshot,
   recordMemoryV2ActivationLog,
-} from "../../../plugins/defaults/memory/memory-v2-activation-log-store.js";
+} from "../../../plugins/defaults/memory/v2/activation-log-store.js";
 import {
   createConnection,
   getConnection,

package/src/runtime/routes/__tests__/subagents-routes.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Tests for the subagent route handlers in `subagents-routes.ts`.
+ *
+ * Covers the LUM-2875 recovery contract:
+ *   - `subagents/reconcile` returns per-child identity (label, the
+ *     subagent's OWN conversationId, parentToolUseId) alongside status
+ *   - `subagents/:id` resolves the subagent's own conversation from manager
+ *     state, ignoring a caller-supplied (possibly parent) conversation id
+ *   - `subagents/:id` falls back to the query parameter when the manager
+ *     does not know the subagent
+ *   - `subagents/:id` surfaces label + parentToolUseId from manager state
+ *
+ * The subagent manager is mocked at the module boundary — spinning up real
+ * subagents requires provider resolution, which is out of scope for
+ * route-shape tests. The message store is real (seeded rows), so the
+ * detail parsing runs against genuine DB reads.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Manager mock
+// ---------------------------------------------------------------------------
+
+interface FakeChild {
+  status: string;
+  conversationId: string;
+  config: { id: string; label: string; parentToolUseId?: string };
+}
+
+const fakeChildren = new Map<string, FakeChild[]>();
+const fakeStates = new Map<string, FakeChild>();
+
+mock.module("../../../subagent/index.js", () => ({
+  getSubagentManager: () => ({
+    getChildrenOf: (parentConversationId: string) =>
+      fakeChildren.get(parentConversationId) ?? [],
+    getState: (subagentId: string) => fakeStates.get(subagentId),
+  }),
+}));
+
+import { getDb } from "../../../persistence/db-connection.js";
+import { initializeDb } from "../../../persistence/db-init.js";
+import { conversations, messages } from "../../../persistence/schema/index.js";
+import { ROUTES as SUBAGENT_ROUTES } from "../subagents-routes.js";
+import type { RouteDefinition } from "../types.js";
+
+await initializeDb();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function findHandler(operationId: string): RouteDefinition["handler"] {
+  const route = SUBAGENT_ROUTES.find((r) => r.operationId === operationId);
+  if (!route) {
+    throw new Error(`Route ${operationId} not found`);
+  }
+  return route.handler;
+}
+
+const reconcileHandler = findHandler("reconcileSubagents");
+const detailHandler = findHandler("getSubagentDetail");
+
+function clearDb(): void {
+  const db = getDb();
+  db.delete(messages).run();
+  db.delete(conversations).run();
+}
+
+/** Seed a conversation with one user (objective) + one assistant message. */
+function seedSubagentConversation(opts: {
+  conversationId: string;
+  objective: string;
+  assistantText: string;
+}): void {
+  const now = Date.now();
+  const db = getDb();
+  db.insert(conversations)
+    .values({
+      id: opts.conversationId,
+      title: "Subagent conversation",
+      createdAt: now,
+      updatedAt: now,
+      source: "test",
+      conversationType: "background",
+    })
+    .run();
+  db.insert(messages)
+    .values({
+      id: `${opts.conversationId}-m1`,
+      conversationId: opts.conversationId,
+      role: "user",
+      content: JSON.stringify([{ type: "text", text: opts.objective }]),
+      createdAt: now,
+    })
+    .run();
+  db.insert(messages)
+    .values({
+      id: `${opts.conversationId}-m2`,
+      conversationId: opts.conversationId,
+      role: "assistant",
+      content: JSON.stringify([{ type: "text", text: opts.assistantText }]),
+      createdAt: now + 1,
+    })
+    .run();
+}
+
+beforeEach(() => {
+  clearDb();
+  fakeChildren.clear();
+  fakeStates.clear();
+});
+
+// ---------------------------------------------------------------------------
+// subagents/reconcile
+// ---------------------------------------------------------------------------
+
+describe("reconcileSubagents", () => {
+  test("returns identity fields per child", async () => {
+    fakeChildren.set("conv-parent", [
+      {
+        status: "running",
+        conversationId: "conv-child-1",
+        config: {
+          id: "sa-1",
+          label: "Audit daemon defenses",
+          parentToolUseId: "toolu_1",
+        },
+      },
+      {
+        status: "completed",
+        conversationId: "conv-child-2",
+        config: { id: "sa-2", label: "Citation matrix" },
+      },
+    ]);
+
+    const result = (await reconcileHandler({
+      queryParams: { parentConversationId: "conv-parent" },
+    })) as {
+      subagents: Record<
+        string,
+        {
+          status: string;
+          label?: string;
+          conversationId?: string;
+          parentToolUseId?: string;
+        }
+      >;
+    };
+
+    expect(result.subagents["sa-1"]).toEqual({
+      status: "running",
+      label: "Audit daemon defenses",
+      conversationId: "conv-child-1",
+      parentToolUseId: "toolu_1",
+    });
+    expect(result.subagents["sa-2"]).toEqual({
+      status: "completed",
+      label: "Citation matrix",
+      conversationId: "conv-child-2",
+      parentToolUseId: undefined,
+    });
+  });
+
+  test("returns an empty record for a conversation with no children", async () => {
+    const result = (await reconcileHandler({
+      queryParams: { parentConversationId: "conv-empty" },
+    })) as { subagents: Record<string, unknown> };
+
+    expect(result.subagents).toEqual({});
+  });
+
+  test("rejects a missing parentConversationId", () => {
+    expect(() => reconcileHandler({ queryParams: {} })).toThrow(
+      "parentConversationId query parameter is required",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// subagents/:id
+// ---------------------------------------------------------------------------
+
+describe("getSubagentDetail", () => {
+  test("resolves the subagent's own conversation from manager state, ignoring the query param", async () => {
+    seedSubagentConversation({
+      conversationId: "conv-child",
+      objective: "audit the daemon",
+      assistantText: "found three gaps",
+    });
+    // The parent conversation exists too — a recovering client only knows
+    // this id, and pre-fix the handler would have parsed ITS messages.
+    seedSubagentConversation({
+      conversationId: "conv-parent",
+      objective: "hey B how does vellum handle prompt injections",
+      assistantText: "parent-side text",
+    });
+    fakeStates.set("sa-1", {
+      status: "running",
+      conversationId: "conv-child",
+      config: { id: "sa-1", label: "Auditor", parentToolUseId: "toolu_9" },
+    });
+
+    const result = (await detailHandler({
+      pathParams: { id: "sa-1" },
+      queryParams: { conversationId: "conv-parent" },
+    })) as {
+      subagentId: string;
+      objective?: string;
+      status?: string;
+      label?: string;
+      parentToolUseId?: string;
+      events: Array<{ type: string; content: string }>;
+    };
+
+    expect(result.objective).toBe("audit the daemon");
+    expect(result.events.some((e) => e.content === "found three gaps")).toBe(
+      true,
+    );
+    expect(result.events.some((e) => e.content === "parent-side text")).toBe(
+      false,
+    );
+    expect(result.status).toBe("running");
+    expect(result.label).toBe("Auditor");
+    expect(result.parentToolUseId).toBe("toolu_9");
+  });
+
+  test("falls back to the query param when the manager does not know the subagent", async () => {
+    seedSubagentConversation({
+      conversationId: "conv-child",
+      objective: "legacy objective",
+      assistantText: "legacy text",
+    });
+
+    const result = (await detailHandler({
+      pathParams: { id: "sa-unknown" },
+      queryParams: { conversationId: "conv-child" },
+    })) as { objective?: string; label?: string };
+
+    expect(result.objective).toBe("legacy objective");
+    expect(result.label).toBeUndefined();
+  });
+
+  test("rejects when neither manager state nor query param supply a conversation", () => {
+    expect(() =>
+      detailHandler({ pathParams: { id: "sa-unknown" }, queryParams: {} }),
+    ).toThrow("conversationId query parameter is required");
+  });
+});