@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/runtime/routes/canonical-guardian-expiry-sweep.ts

@@ -1,129 +0,0 @@
-/**
- * Canonical guardian request expiry sweep.
- *
- * Periodically scans the `canonical_guardian_requests` table for pending
- * requests whose `expiresAt` timestamp has passed and transitions them to
- * the `expired` status.  This ensures that stale requests are cleaned up
- * even when no follow-up traffic arrives from either the guardian or the
- * requester.
- *
- * This sweep operates on the unified canonical domain
- * (`canonical_guardian_requests`). On expiry it transitions the request status
- * (the single source of truth), withdraws the approval cards on every surface,
- * notifies the requester that their request expired, and releases any in-memory
- * pending interaction. Requester notices are delivered straight to the
- * requester's channel — not the guardian-facing notification pipeline — and the
- * guardian stays passive, since the withdrawn card already reflects expiry.
- */
-
-import { withdrawGuardianRequestCards } from "../../approvals/guardian-card-withdrawal.js";
-import { notifyExpiredGuardianRequest } from "../../approvals/guardian-expiry-notifier.js";
-import {
-  listCanonicalGuardianRequests,
-  resolveCanonicalGuardianRequest,
-} from "../../contacts/canonical-guardian-store.js";
-import { getLogger } from "../../util/logger.js";
-
-const log = getLogger("canonical-guardian-expiry-sweep");
-
-/** Interval at which the expiry sweep runs (60 seconds). */
-const SWEEP_INTERVAL_MS = 60_000;
-
-/** Timer handle for the sweep so it can be stopped in tests and shutdown. */
-let sweepTimer: ReturnType<typeof setInterval> | null = null;
-
-/** Guard against overlapping sweeps. */
-let sweepInProgress = false;
-
-/**
- * Sweep all pending canonical guardian requests that have expired.
- *
- * Uses CAS resolution (`resolveCanonicalGuardianRequest`) so that a
- * concurrent decision that wins the race is never overwritten by the
- * sweep.  Returns the count of requests transitioned to expired.
- */
-export async function sweepExpiredCanonicalGuardianRequests(): Promise<number> {
-  const pending = listCanonicalGuardianRequests({ status: "pending" });
-  const now = Date.now();
-  let expiredCount = 0;
-
-  for (const request of pending) {
-    if (!request.expiresAt) continue;
-
-    const expiresAtMs = request.expiresAt;
-    if (expiresAtMs >= now) continue;
-
-    // CAS resolve: only transition from 'pending' to 'expired'.
-    // If someone resolved it between our read and this write, the CAS
-    // fails harmlessly (returns null) and we skip the request.
-    const resolved = resolveCanonicalGuardianRequest(request.id, "pending", {
-      status: "expired",
-    });
-
-    if (resolved) {
-      expiredCount++;
-      log.info(
-        {
-          event: "canonical_request_expired",
-          requestId: request.id,
-          kind: request.kind,
-          expiresAt: request.expiresAt,
-        },
-        "Expired canonical guardian request via sweep",
-      );
-
-      // Withdraw the now-stale approval cards on every surface. No origin
-      // channel — the expiry is system-driven, so all surfaces (including
-      // in-app) are withdrawn. Best-effort and non-throwing.
-      await withdrawGuardianRequestCards({
-        request: resolved,
-        status: "expired",
-      });
-
-      // Notify the requester their request expired and release any in-memory
-      // pending interaction. Best-effort and non-throwing, like the card
-      // withdrawal above.
-      await notifyExpiredGuardianRequest(resolved);
-    }
-  }
-
-  if (expiredCount > 0) {
-    log.info(
-      { event: "canonical_expiry_sweep_complete", expiredCount },
-      `Canonical guardian expiry sweep: expired ${expiredCount} request(s)`,
-    );
-  }
-
-  return expiredCount;
-}
-
-/**
- * Start the periodic canonical guardian expiry sweep. Idempotent — calling
- * it multiple times reuses the same timer.
- */
-export function startCanonicalGuardianExpirySweep(): void {
-  if (sweepTimer) return;
-  sweepTimer = setInterval(() => {
-    if (sweepInProgress) return;
-    sweepInProgress = true;
-    void sweepExpiredCanonicalGuardianRequests()
-      .catch((err) => {
-        log.error({ err }, "Canonical guardian expiry sweep failed");
-      })
-      .finally(() => {
-        sweepInProgress = false;
-      });
-  }, SWEEP_INTERVAL_MS);
-}
-
-/**
- * Stop the periodic canonical guardian expiry sweep. Used in tests and
- * shutdown.
- */
-export function stopCanonicalGuardianExpirySweep(): void {
-  if (sweepTimer) {
-    clearInterval(sweepTimer);
-    sweepTimer = null;
-  }
-  sweepInProgress = false;
-}

package/src/runtime/routes/inbound-stages/escalation-intercept.test.ts

@@ -1,158 +0,0 @@
-/**
- * Unit tests for `handleEscalationIntercept` guardian-principal resolution.
- *
- * A guardian binding whose gateway row carries no principal is UNRESOLVED, not
- * present-but-empty: the intercept adopts the principal from the assistant's
- * vellum anchor (via `resolveDecidableGuardianPrincipalId`), and when neither
- * resolves it fails closed instead of creating an undecidable (principal-less)
- * canonical request. The `""`-is-unresolved contract itself is pinned in
- * `local-actor-identity.test.ts`.
- */
-import { beforeEach, describe, expect, mock, test } from "bun:test";
-
-mock.module("../../../util/logger.js", () => ({
-  getLogger: () =>
-    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
-}));
-
-let mockBindingPrincipalId: string | null = null;
-let mockBindingPresent = true;
-mock.module("../../channel-verification-service.js", () => ({
-  getGuardianBinding: async () =>
-    mockBindingPresent
-      ? {
-          guardianExternalUserId: "guardian-1",
-          guardianPrincipalId: mockBindingPrincipalId,
-        }
-      : null,
-}));
-
-// Faithful stand-in for the shared adopt/repair helper: binding principal
-// when present, else the (test-controlled) vellum anchor principal.
-let mockAnchorPrincipal: string | undefined;
-mock.module("../../local-actor-identity.js", () => ({
-  resolveDecidableGuardianPrincipalId: async (
-    bindingPrincipalId: string | null,
-  ) => bindingPrincipalId || mockAnchorPrincipal,
-}));
-
-const createdRequests: Array<Record<string, unknown>> = [];
-mock.module("../../../contacts/canonical-guardian-store.js", () => ({
-  createCanonicalGuardianRequest: (params: Record<string, unknown>) => {
-    createdRequests.push(params);
-    return { ...params, requestCode: "ABC123" };
-  },
-}));
-
-mock.module("../../../notifications/emit-signal.js", () => ({
-  emitNotificationSignal: async () => ({ deliveryResults: [] }),
-}));
-
-mock.module("../../../persistence/delivery-crud.js", () => ({
-  storePayload: () => {},
-}));
-
-const { handleEscalationIntercept } = await import("./escalation-intercept.js");
-type EscalationInterceptParams = Parameters<
-  typeof handleEscalationIntercept
->[0];
-
-function makeParams(
-  overrides: Partial<EscalationInterceptParams> = {},
-): EscalationInterceptParams {
-  return {
-    resolvedMember: {
-      contactId: "contact-1",
-      channelId: "channel-1",
-      status: "active",
-      policy: "escalate",
-      verifiedAt: null,
-      displayName: "Member",
-    },
-    canonicalAssistantId: "self",
-    sourceChannel: "telegram",
-    sourceInterface: "telegram",
-    conversationExternalId: "chat-1",
-    externalMessageId: "msg-1",
-    conversationId: "conv-1",
-    eventId: "evt-1",
-    content: "hello",
-    attachmentIds: undefined,
-    sourceMetadata: undefined,
-    actorDisplayName: "Member",
-    actorExternalId: "member-1",
-    actorUsername: "member_one",
-    replyCallbackUrl: "http://localhost/deliver",
-    canonicalSenderId: "member-1",
-    rawSenderId: "member-1",
-    ...overrides,
-  };
-}
-
-beforeEach(() => {
-  mockBindingPresent = true;
-  mockBindingPrincipalId = null;
-  mockAnchorPrincipal = undefined;
-  createdRequests.length = 0;
-});
-
-describe("handleEscalationIntercept — guardian principal resolution", () => {
-  test("binding with a principal creates the request with that principal", async () => {
-    mockBindingPrincipalId = "principal-1";
-
-    const response = await handleEscalationIntercept(makeParams());
-
-    expect(response).toMatchObject({ accepted: true, escalated: true });
-    expect(createdRequests).toHaveLength(1);
-    expect(createdRequests[0].guardianPrincipalId).toBe("principal-1");
-  });
-
-  test("null-principal binding adopts the vellum anchor principal (repair path)", async () => {
-    mockBindingPrincipalId = null;
-    mockAnchorPrincipal = "anchor-principal";
-
-    const response = await handleEscalationIntercept(makeParams());
-
-    expect(response).toMatchObject({ accepted: true, escalated: true });
-    expect(createdRequests).toHaveLength(1);
-    expect(createdRequests[0].guardianPrincipalId).toBe("anchor-principal");
-  });
-
-  test("unresolvable principal fails closed — no principal-less request is created", async () => {
-    mockBindingPrincipalId = null;
-    mockAnchorPrincipal = undefined;
-
-    const response = await handleEscalationIntercept(makeParams());
-
-    expect(response).toMatchObject({
-      accepted: true,
-      denied: true,
-      reason: "escalate_no_guardian",
-    });
-    expect(createdRequests).toHaveLength(0);
-  });
-
-  test("no binding at all still denies fail-closed", async () => {
-    mockBindingPresent = false;
-
-    const response = await handleEscalationIntercept(makeParams());
-
-    expect(response).toMatchObject({
-      accepted: true,
-      denied: true,
-      reason: "escalate_no_guardian",
-    });
-    expect(createdRequests).toHaveLength(0);
-  });
-
-  test("non-escalate member policy is a pass-through", async () => {
-    const params = makeParams();
-    const response = await handleEscalationIntercept(
-      makeParams({
-        resolvedMember: { ...params.resolvedMember!, policy: "allow" },
-      }),
-    );
-
-    expect(response).toBeNull();
-  });
-});

package/src/runtime/routes/inbound-stages/escalation-intercept.ts

@@ -1,187 +0,0 @@
-/**
- * Ingress escalation stage: when a member's policy is 'escalate', creates
- * a pending guardian approval request, emits a notification signal, and
- * halts the inbound pipeline. The guardian must approve the message
- * before it enters the agent loop.
- *
- * Extracted from inbound-message-handler.ts to keep the top-level handler
- * focused on orchestration.
- */
-import type { ChannelId, InterfaceId } from "../../../channels/types.js";
-import { createCanonicalGuardianRequest } from "../../../contacts/canonical-guardian-store.js";
-import { emitNotificationSignal } from "../../../notifications/emit-signal.js";
-import { storePayload } from "../../../persistence/delivery-crud.js";
-import { getLogger } from "../../../util/logger.js";
-import { getGuardianBinding } from "../../channel-verification-service.js";
-import { resolveDecidableGuardianPrincipalId } from "../../local-actor-identity.js";
-import type { VerdictMember } from "../../trust-verdict-consumer.js";
-import { GUARDIAN_APPROVAL_TTL_MS } from "../channel-route-shared.js";
-
-const log = getLogger("runtime-http");
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-export interface EscalationInterceptParams {
-  resolvedMember: VerdictMember | null;
-  canonicalAssistantId: string;
-  sourceChannel: ChannelId;
-  sourceInterface: InterfaceId;
-  conversationExternalId: string;
-  externalMessageId: string;
-  conversationId: string;
-  eventId: string;
-  content: string | undefined;
-  attachmentIds: string[] | undefined;
-  sourceMetadata: import("@vellumai/gateway-client").SourceMetadata | undefined;
-  actorDisplayName: string | undefined;
-  actorExternalId: string | undefined;
-  actorUsername: string | undefined;
-  replyCallbackUrl: string | undefined;
-  canonicalSenderId: string | null;
-  rawSenderId: string | undefined;
-}
-
-/**
- * Check whether the resolved member has an 'escalate' policy and, if so,
- * create a guardian approval request and emit a notification.
- *
- * Returns a Response if the escalation was handled (the pipeline should
- * short-circuit), or null to continue the pipeline.
- */
-export async function handleEscalationIntercept(
-  params: EscalationInterceptParams,
-): Promise<Record<string, unknown> | null> {
-  const {
-    resolvedMember,
-    canonicalAssistantId,
-    sourceChannel,
-    sourceInterface,
-    conversationExternalId,
-    externalMessageId,
-    conversationId,
-    eventId,
-    content,
-    attachmentIds,
-    sourceMetadata,
-    actorDisplayName,
-    actorExternalId,
-    actorUsername,
-    replyCallbackUrl,
-    canonicalSenderId,
-    rawSenderId,
-  } = params;
-
-  if (resolvedMember?.policy !== "escalate") {
-    return null;
-  }
-
-  const binding = await getGuardianBinding(canonicalAssistantId, sourceChannel);
-  if (!binding) {
-    // Fail-closed: can't escalate without a guardian to route to
-    log.info(
-      { sourceChannel, channelId: resolvedMember.channelId },
-      "Ingress ACL: escalate policy but no guardian binding, denying",
-    );
-    return {
-      accepted: true,
-      denied: true,
-      reason: "escalate_no_guardian",
-    };
-  }
-
-  // A binding with no principal is unresolved, not empty: adopt the vellum
-  // anchor principal so the resulting request is decidable by the guardian.
-  // When neither resolves, fail closed — a principal-less tool_approval
-  // request can never be authorized by anyone (it would sit pending with
-  // dead Approve/Reject buttons until expiry).
-  const guardianPrincipalId = await resolveDecidableGuardianPrincipalId(
-    binding.guardianPrincipalId,
-  );
-  if (!guardianPrincipalId) {
-    log.warn(
-      { sourceChannel, channelId: resolvedMember.channelId },
-      "Ingress ACL: escalate policy but guardian principal unresolved, denying",
-    );
-    return {
-      accepted: true,
-      denied: true,
-      reason: "escalate_no_guardian",
-    };
-  }
-
-  // Persist the raw payload so the decide handler can recover the original
-  // message content when the escalation is approved.
-  storePayload(eventId, {
-    sourceChannel,
-    interface: sourceInterface,
-    externalChatId: conversationExternalId,
-    externalMessageId,
-    content,
-    attachmentIds,
-    sourceMetadata,
-    senderName: actorDisplayName,
-    senderExternalUserId: actorExternalId,
-    senderUsername: actorUsername,
-    replyCallbackUrl,
-    assistantId: canonicalAssistantId,
-  });
-
-  try {
-    createCanonicalGuardianRequest({
-      kind: "tool_approval",
-      sourceType: "channel",
-      sourceChannel,
-      conversationId,
-      requesterExternalUserId: canonicalSenderId ?? rawSenderId ?? undefined,
-      guardianExternalUserId: binding.guardianExternalUserId,
-      guardianPrincipalId,
-      toolName: "ingress_message",
-      questionText: "Ingress policy requires guardian approval",
-      expiresAt: Date.now() + GUARDIAN_APPROVAL_TTL_MS,
-    });
-  } catch (err) {
-    log.warn(
-      { err, conversationId, sourceChannel },
-      "Failed to create canonical guardian request for ingress escalation — escalation continues via notification pipeline",
-    );
-  }
-
-  // Emit notification signal through the unified pipeline (fire-and-forget).
-  // This lets the decision engine route escalation alerts to all configured
-  // channels, supplementing the direct guardian notification below.
-  void emitNotificationSignal({
-    sourceEventName: "ingress.escalation",
-    sourceChannel,
-    sourceContextId: conversationId,
-    attentionHints: {
-      requiresAction: true,
-      urgency: "high",
-      isAsyncBackground: false,
-      visibleInSourceNow: false,
-    },
-    contextPayload: {
-      conversationId,
-      sourceChannel,
-      conversationExternalId,
-      senderIdentifier:
-        actorDisplayName || actorUsername || rawSenderId || "Unknown sender",
-      eventId,
-    },
-    dedupeKey: `escalation:${eventId}`,
-  });
-
-  // Guardian escalation channel delivery is handled by the notification
-  // pipeline -- no legacy callback dispatch needed.
-  log.info(
-    { conversationId },
-    "Guardian escalation created — notification pipeline handles channel delivery",
-  );
-
-  return {
-    accepted: true,
-    escalated: true,
-    reason: "policy_escalate",
-  };
-}

package/src/runtime/routes/memory-worker-routes.ts

@@ -1,227 +0,0 @@
-/**
- * Memory worker control endpoints (start / stop / status).
- *
- * These run inside the daemon so the worker process the daemon spawns is a
- * direct child of the daemon — which is what makes it show up in the daemon's
- * process tree (`assistant ps`) and lets the daemon tear it down on shutdown.
- * The `assistant memory worker` CLI is a thin IPC client over these routes; if
- * it spawned the worker itself, the worker would be parented to the short-lived
- * CLI process (reparented to init) instead of the daemon.
- */
-
-import { z } from "zod";
-
-import {
-  getConfigReadOnly,
-  loadRawConfig,
-  saveRawConfig,
-  setNestedValue,
-} from "../../config/loader.js";
-import { getMemoryBackendStatus } from "../../persistence/embeddings/embedding-backend.js";
-import {
-  MemoryWorkerSpawnError,
-  probeMemoryWorker,
-  spawnMemoryWorkerProcess,
-  stopMemoryWorkerProcess,
-} from "../../persistence/worker-control.js";
-import { getLogger } from "../../util/logger.js";
-import { getMemoryWorkerPidPath } from "../../util/platform.js";
-import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
-import { InternalError } from "./errors.js";
-import type { RouteDefinition } from "./types.js";
-
-const log = getLogger("memory-worker-routes");
-
-/**
- * Persist `memory.worker.enabled` to the on-disk config via the shared
- * raw-config helpers, so only this leaf changes (schema defaults are not baked
- * into the file). The daemon's worker supervisor re-reads the flag from disk on
- * its next poll, so the change takes effect without a restart.
- */
-function setMemoryWorkerEnabled(enabled: boolean): void {
-  const raw = loadRawConfig();
-  setNestedValue(raw, "memory.worker.enabled", enabled);
-  saveRawConfig(raw);
-}
-
-const workerStatusSchema = z.object({
-  status: z.enum(["running", "not_running"]),
-  pid: z.number().optional(),
-});
-
-const startResponseSchema = z.object({
-  pid: z.number(),
-  alreadyRunning: z.boolean(),
-  workerEnabled: z.literal(true),
-  pidPath: z.string(),
-});
-
-const stopResponseSchema = z.object({
-  workerWasRunning: z.boolean(),
-  pid: z.number().optional(),
-  workerEnabled: z.literal(false),
-});
-
-export const embeddingStatusSchema = z.object({
-  enabled: z.boolean(),
-  degraded: z.boolean(),
-  provider: z.enum(["local", "openai", "gemini", "ollama"]).nullable(),
-  model: z.string().nullable(),
-  reason: z.string().nullable(),
-});
-
-const statusResponseSchema = z.object({
-  status: z.enum(["running", "not_running"]),
-  pid: z.number().optional(),
-  workerEnabled: z.boolean(),
-  syncRunner: workerStatusSchema,
-  embedding: embeddingStatusSchema,
-});
-
-/**
- * Start (or reuse) the memory worker process as a child of the daemon, then
- * enable `memory.worker.enabled` so the daemon's supervisor stands its
- * synchronous in-process runner down. The flag is only enabled once the worker
- * is confirmed up — on spawn failure it is left untouched so the synchronous
- * runner keeps draining the queue rather than standing down for a worker that
- * never came up.
- */
-async function startMemoryWorker() {
-  let result: { pid: number; alreadyRunning: boolean };
-  try {
-    // `detached: false` parents the worker to the daemon. `terminateOnTimeout`
-    // matches the leave-the-flag-off-on-failure contract below: a worker that
-    // came up late would otherwise drain the queue alongside the synchronous
-    // runner.
-    result = await spawnMemoryWorkerProcess({
-      detached: false,
-      terminateOnTimeout: true,
-    });
-  } catch (err) {
-    const message =
-      err instanceof MemoryWorkerSpawnError || err instanceof Error
-        ? err.message
-        : String(err);
-    log.warn({ err }, "Failed to start memory worker process");
-    throw new InternalError(message);
-  }
-
-  setMemoryWorkerEnabled(true);
-
-  return {
-    pid: result.pid,
-    alreadyRunning: result.alreadyRunning,
-    workerEnabled: true as const,
-    pidPath: getMemoryWorkerPidPath(),
-  };
-}
-
-/**
- * Disable `memory.worker.enabled` (handing the queue back to the synchronous
- * in-process runner) and SIGTERM the worker process if it is running. A worker
- * that is not running is not an error — flipping the flag alone restores
- * synchronous mode.
- */
-function stopMemoryWorker() {
-  setMemoryWorkerEnabled(false);
-
-  let before: ReturnType<typeof stopMemoryWorkerProcess>;
-  try {
-    before = stopMemoryWorkerProcess();
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    log.warn({ err }, "Failed to signal memory worker process");
-    throw new InternalError(message);
-  }
-
-  return {
-    workerWasRunning: before.status === "running",
-    ...(before.pid != null ? { pid: before.pid } : {}),
-    workerEnabled: false as const,
-  };
-}
-
-/**
- * Report the worker process state, the `memory.worker.enabled` config value,
- * and whether the daemon's synchronous in-process runner is currently draining
- * the queue.
- *
- * The supervisor drains in-process exactly when memory is enabled and the
- * out-of-process worker is not (it stands down on `memory.worker.enabled`).
- * This handler runs inside the daemon — the very process that is (or isn't) the
- * synchronous runner — so the runner's state is derived directly from config,
- * with the daemon's own PID, rather than read back from a marker file.
- *
- * The `embedding` block reports the resolved embedding backend (or the
- * degraded state when none resolves), so a silent embedding-backend
- * degradation — memory enqueues fine but never embeds — is observable.
- */
-async function memoryWorkerStatus() {
-  const worker = probeMemoryWorker();
-  const config = getConfigReadOnly();
-  const workerEnabled = config.memory.worker.enabled;
-
-  const syncRunnerActive = config.memory.enabled !== false && !workerEnabled;
-  const syncRunner: { status: "running" | "not_running"; pid?: number } =
-    syncRunnerActive
-      ? { status: "running", pid: process.pid }
-      : { status: "not_running" };
-
-  const embedding = await getMemoryBackendStatus(config);
-
-  return {
-    status: worker.status,
-    ...(worker.pid != null ? { pid: worker.pid } : {}),
-    workerEnabled,
-    syncRunner,
-    embedding,
-  };
-}
-
-export const ROUTES: RouteDefinition[] = [
-  {
-    operationId: "memory_worker_start",
-    endpoint: "memory/worker/start",
-    method: "POST",
-    policy: {
-      requiredScopes: ["settings.write"],
-      allowedPrincipalTypes: ACTOR_PRINCIPALS,
-    },
-    handler: startMemoryWorker,
-    summary: "Start the memory worker",
-    description:
-      "Spawns (or reuses) the memory worker process as a child of the daemon and enables memory.worker.enabled.",
-    tags: ["system"],
-    responseBody: startResponseSchema,
-  },
-  {
-    operationId: "memory_worker_stop",
-    endpoint: "memory/worker/stop",
-    method: "POST",
-    policy: {
-      requiredScopes: ["settings.write"],
-      allowedPrincipalTypes: ACTOR_PRINCIPALS,
-    },
-    handler: stopMemoryWorker,
-    summary: "Stop the memory worker",
-    description:
-      "Disables memory.worker.enabled and SIGTERMs the memory worker process if it is running.",
-    tags: ["system"],
-    responseBody: stopResponseSchema,
-  },
-  {
-    operationId: "memory_worker_status",
-    endpoint: "memory/worker/status",
-    method: "GET",
-    policy: {
-      requiredScopes: ["settings.read"],
-      allowedPrincipalTypes: ACTOR_PRINCIPALS,
-    },
-    handler: memoryWorkerStatus,
-    summary: "Memory worker status",
-    description:
-      "Reports the memory worker process state, memory.worker.enabled, the synchronous in-process runner, and the embedding-backend status (including a degraded flag and reason when no backend resolves).",
-    tags: ["system"],
-    responseBody: statusResponseSchema,
-  },
-];