@vellumai/assistant 0.8.0 → 0.8.1

package/src/runtime/middleware/request-logger.ts

@@ -3,14 +3,73 @@
  *
  * Logs method, path, status, and latency for every request to aid
  * debugging client issues. Uses structured Pino logging.
+ *
+ * Routes can opt in to suppress the per-request INFO line after a confirmed
+ * run of N successful responses by declaring `logging.silenceSuccessAfter`
+ * on the route definition. Warning (4xx) and error (5xx) lines are always
+ * emitted regardless of this setting.
  */
 
 import { getLogger } from "../../util/logger.js";
+import type { RouteLoggingConfig } from "../routes/types.js";
 
 const log = getLogger("http-request");
 
 const UNKNOWN = "unknown" as const;
 
+/**
+ * Optional metadata supplied by the caller (typically resolved from the
+ * matched route) that lets the middleware adjust its per-request log
+ * behavior — e.g. suppressing success logs after a threshold for noisy
+ * polling endpoints like `/v1/health`.
+ */
+export interface RequestLogMetadata {
+  /**
+   * Stable identifier used as the success-suppression counter key. Two
+   * requests with the same counterKey share a single counter (so all
+   * variants of a parameterized route share suppression state).
+   */
+  counterKey: string;
+  config: RouteLoggingConfig;
+}
+
+// Module-level counter map. Tracks the cumulative number of successful
+// (status < 400) responses logged per `counterKey`. Once the count passes
+// the route's `silenceSuccessAfter` threshold, further successful responses
+// skip the per-request INFO log line. Counters never reset within a
+// process — the behavior is "the route worked, stop spamming".
+const successCounters = new Map<string, number>();
+
+/**
+ * Test-only: reset the per-route success counters. Production code never
+ * calls this; tests use it to isolate suppression state between cases.
+ */
+export function _resetRequestLoggingCountersForTests(): void {
+  successCounters.clear();
+}
+
+/**
+ * Decide whether the success log line should be suppressed for this
+ * request. Returns true when the counter has already reached the
+ * configured threshold. Pure read — the counter is only mutated when
+ * the log line is actually emitted.
+ */
+function shouldSuppressSuccess(meta: RequestLogMetadata | undefined): boolean {
+  if (!meta) return false;
+  const threshold = meta.config.silenceSuccessAfter;
+  if (threshold === undefined || threshold <= 0) return false;
+  const current = successCounters.get(meta.counterKey) ?? 0;
+  return current >= threshold;
+}
+
+/** Record that we just emitted a success log line for this route. */
+function bumpSuccessCounter(meta: RequestLogMetadata | undefined): void {
+  if (!meta) return;
+  if (meta.config.silenceSuccessAfter === undefined) return;
+  const current = successCounters.get(meta.counterKey) ?? 0;
+  successCounters.set(meta.counterKey, current + 1);
+}
+
 /**
  * Wrap a request handler to log request metadata and response timing.
  *
@@ -20,6 +79,7 @@ const UNKNOWN = "unknown" as const;
 export async function withRequestLogging(
   req: Request,
   handler: () => Promise<Response>,
+  meta?: RequestLogMetadata,
 ): Promise<Response> {
   const start = performance.now();
   const url = new URL(req.url);
@@ -66,8 +126,9 @@ export async function withRequestLogging(
     log.error(logData, `${method} ${path} -> ${status} (${latencyMs}ms)`);
   } else if (status >= 400) {
     log.warn(logData, `${method} ${path} -> ${status} (${latencyMs}ms)`);
-  } else {
+  } else if (!shouldSuppressSuccess(meta)) {
     log.info(logData, `${method} ${path} -> ${status} (${latencyMs}ms)`);
+    bumpSuccessCounter(meta);
   }
 
   return response;

package/src/runtime/pre-first-message-gate.ts

@@ -0,0 +1,83 @@
+/**
+ * Gate for LLM-touching background work that runs between daemon start and
+ * the user's first interaction.
+ *
+ * ## Why this exists
+ *
+ * Cloud-hosted assistants are served from a warm pool: the daemon boots,
+ * background services initialize, and the image waits to be claimed by a
+ * real user. Before the user claims an image, no provider credentials are
+ * registered, so any background job that tries to call the LLM fails — and
+ * those failure rows persist in the local SQLite database, becoming visible
+ * in the conversation sidebar the moment the user hatches.
+ *
+ * ## The probe
+ *
+ * `hasReceivedUserMessage()` returns `true` once at least one
+ * `role='user'` message exists in a `conversation_type='standard'`
+ * conversation. Background / scheduled conversations don't count — they're
+ * exactly the noise we're trying to suppress.
+ *
+ * The result is cached in-process after the first `true` because the flag
+ * is monotonic: a user message, once present, is never deleted in a way
+ * that should re-open the gate. (Even a destructive sweep that wipes all
+ * messages would still want background jobs paused until a real user
+ * interaction resumes, so re-querying on miss is the correct behavior.)
+ *
+ * Callers should treat the gate as advisory + defense-in-depth: prefer to
+ * skip at the service level (heartbeat, update-bulletin, etc.) so no run
+ * row / conversation row is created at all, and rely on the gate inside
+ * `runBackgroundJob` as the universal backstop.
+ */
+import { rawGet } from "../memory/raw-query.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("pre-first-message-gate");
+
+let cachedHasUserMessage = false;
+
+/**
+ * Returns `true` if the local store has ever recorded a user-authored
+ * message in a standard conversation.
+ *
+ * Cheap: indexed lookup with `LIMIT 1`. After the first `true` result the
+ * answer is cached in-process and subsequent calls are O(1).
+ *
+ * On query error the function logs a warning and returns `false` — the
+ * conservative interpretation is "we can't prove the user has interacted,
+ * so don't fire background work."
+ */
+export function hasReceivedUserMessage(): boolean {
+  if (cachedHasUserMessage) return true;
+
+  try {
+    const row = rawGet<{ one: number }>(
+      `SELECT 1 AS one FROM messages m
+       JOIN conversations c ON m.conversation_id = c.id
+       WHERE m.role = 'user'
+         AND c.conversation_type = 'standard'
+       LIMIT 1`,
+    );
+    if (row != null) {
+      cachedHasUserMessage = true;
+      return true;
+    }
+    return false;
+  } catch (err) {
+    log.warn(
+      { err },
+      "hasReceivedUserMessage: query failed; treating as not-yet-received so background work stays paused",
+    );
+    return false;
+  }
+}
+
+/**
+ * Test-only reset of the in-process cache. Real code paths must never
+ * call this — the cache is monotonic by design.
+ *
+ * @internal
+ */
+export function _resetPreFirstMessageGateCacheForTests(): void {
+  cachedHasUserMessage = false;
+}

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

@@ -720,10 +720,17 @@ describe("handleBackupVerify", () => {
 // ---------------------------------------------------------------------------
 
 describe("ROUTES", () => {
-  test("registers four routes with the expected endpoint+method pairs", () => {
+  test("registers routes with the expected endpoint+method pairs", () => {
     const pairs = ROUTES.map((d) => `${d.method} ${d.endpoint}`).sort();
     expect(pairs).toEqual([
+      "GET backup/destinations",
+      "GET backup/status",
       "GET backups",
+      "POST backup/destinations/add",
+      "POST backup/destinations/remove",
+      "POST backup/destinations/set-encrypt",
+      "POST backup/disable",
+      "POST backup/enable",
       "POST backups/create",
       "POST backups/restore",
       "POST backups/verify",

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

@@ -0,0 +1,251 @@
+/**
+ * Tests for the bookmark route handlers in `bookmark-routes.ts`.
+ *
+ * Covers:
+ *   - POST + GET round-trip
+ *   - POST idempotency (no duplicate row, same id returned)
+ *   - POST FK validation (unknown messageId → 4xx)
+ *   - DELETE /by-message/:messageId
+ *   - SSE event publication on create AND delete
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Capture publish() invocations so the tests can assert on emitted events
+// without spinning up real SSE infrastructure.
+const publishCalls: unknown[] = [];
+
+mock.module("../../assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: async (event: unknown) => {
+      publishCalls.push(event);
+    },
+    subscribe: () => () => {},
+  },
+}));
+
+import { getDb } from "../../../memory/db-connection.js";
+import { initializeDb } from "../../../memory/db-init.js";
+import {
+  conversations,
+  messageBookmarks,
+  messages,
+} from "../../../memory/schema.js";
+import { ROUTES as BOOKMARK_ROUTES } from "../bookmark-routes.js";
+import type { RouteDefinition, RouteHandlerArgs } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// DB bootstrap
+// ---------------------------------------------------------------------------
+
+initializeDb();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function findHandler(operationId: string): RouteDefinition["handler"] {
+  const route = BOOKMARK_ROUTES.find((r) => r.operationId === operationId);
+  if (!route) throw new Error(`Route ${operationId} not found`);
+  return route.handler;
+}
+
+const listHandler = findHandler("bookmarks_list");
+const createHandler = findHandler("bookmarks_create");
+const deleteByMessageHandler = findHandler("bookmarks_delete_by_message");
+
+function clearDb(): void {
+  const db = getDb();
+  // Bookmarks first (FK), then messages, then conversations.
+  db.delete(messageBookmarks).run();
+  db.delete(messages).run();
+  db.delete(conversations).run();
+}
+
+function seedConversationAndMessage(opts: {
+  conversationId: string;
+  messageId: string;
+  conversationTitle?: string;
+  messageContent?: string;
+  messageRole?: string;
+}): void {
+  const now = Date.now();
+  const db = getDb();
+  db.insert(conversations)
+    .values({
+      id: opts.conversationId,
+      title: opts.conversationTitle ?? "Test conversation",
+      createdAt: now,
+      updatedAt: now,
+      source: "test",
+      conversationType: "standard",
+      memoryScopeId: "default",
+    })
+    .run();
+  db.insert(messages)
+    .values({
+      id: opts.messageId,
+      conversationId: opts.conversationId,
+      role: opts.messageRole ?? "user",
+      content: opts.messageContent ?? "hello world",
+      createdAt: now,
+    })
+    .run();
+}
+
+async function call(
+  handler: RouteDefinition["handler"],
+  args: RouteHandlerArgs,
+): Promise<unknown> {
+  return await handler(args);
+}
+
+interface EventEnvelope {
+  message: { type: string; [key: string]: unknown };
+}
+
+function publishedTypes(): string[] {
+  return publishCalls.map((e) => (e as EventEnvelope).message.type);
+}
+
+beforeEach(() => {
+  clearDb();
+  publishCalls.length = 0;
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("bookmark routes", () => {
+  test("POST then GET returns the new bookmark", async () => {
+    seedConversationAndMessage({
+      conversationId: "conv-1",
+      messageId: "msg-1",
+      messageContent: "first message body",
+      messageRole: "assistant",
+    });
+
+    const created = (await call(createHandler, {
+      body: { messageId: "msg-1", conversationId: "conv-1" },
+    })) as { id: string; messageId: string; messagePreview: string };
+
+    expect(created.messageId).toBe("msg-1");
+    expect(created.messagePreview).toBe("first message body");
+
+    const listed = (await call(listHandler, {})) as {
+      bookmarks: Array<{ id: string; messageId: string }>;
+    };
+
+    expect(listed.bookmarks).toHaveLength(1);
+    expect(listed.bookmarks[0]?.id).toBe(created.id);
+    expect(listed.bookmarks[0]?.messageId).toBe("msg-1");
+  });
+
+  test("POST is idempotent — second call returns same id, no duplicate row", async () => {
+    seedConversationAndMessage({
+      conversationId: "conv-2",
+      messageId: "msg-2",
+    });
+
+    const first = (await call(createHandler, {
+      body: { messageId: "msg-2", conversationId: "conv-2" },
+    })) as { id: string };
+    const second = (await call(createHandler, {
+      body: { messageId: "msg-2", conversationId: "conv-2" },
+    })) as { id: string };
+
+    expect(second.id).toBe(first.id);
+
+    const listed = (await call(listHandler, {})) as {
+      bookmarks: unknown[];
+    };
+    expect(listed.bookmarks).toHaveLength(1);
+  });
+
+  test("POST with non-existent messageId returns a 4xx", async () => {
+    seedConversationAndMessage({
+      conversationId: "conv-3",
+      messageId: "msg-3",
+    });
+
+    let caught: unknown = null;
+    try {
+      await call(createHandler, {
+        body: { messageId: "missing-msg", conversationId: "conv-3" },
+      });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).not.toBeNull();
+    // RouteError subclasses (BadRequestError, NotFoundError, …) carry a
+    // `statusCode` field that the HTTP adapter forwards to the wire — assert
+    // that we throw something in the 4xx range without coupling to the
+    // specific subclass.
+    const statusCode = (caught as { statusCode?: number }).statusCode;
+    expect(
+      typeof statusCode === "number" && statusCode >= 400 && statusCode < 500,
+    ).toBe(true);
+  });
+
+  test("DELETE /by-message/:messageId removes the row", async () => {
+    seedConversationAndMessage({
+      conversationId: "conv-5",
+      messageId: "msg-5",
+    });
+    await call(createHandler, {
+      body: { messageId: "msg-5", conversationId: "conv-5" },
+    });
+
+    const result = (await call(deleteByMessageHandler, {
+      pathParams: { messageId: "msg-5" },
+    })) as { success: boolean };
+    expect(result.success).toBe(true);
+
+    const listed = (await call(listHandler, {})) as { bookmarks: unknown[] };
+    expect(listed.bookmarks).toHaveLength(0);
+  });
+
+  test("publishes SSE events on create AND delete", async () => {
+    seedConversationAndMessage({
+      conversationId: "conv-6",
+      messageId: "msg-6",
+    });
+
+    const created = (await call(createHandler, {
+      body: { messageId: "msg-6", conversationId: "conv-6" },
+    })) as { id: string };
+
+    // Publishes are fire-and-forget (`.catch(...)`), so let any pending
+    // microtasks settle before asserting.
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(publishedTypes()).toEqual(["bookmark.created"]);
+    const createdEvent = publishCalls[0] as EventEnvelope;
+    expect(createdEvent.message.type).toBe("bookmark.created");
+    expect(
+      (createdEvent.message as unknown as { bookmark: { id: string } }).bookmark
+        .id,
+    ).toBe(created.id);
+
+    publishCalls.length = 0;
+
+    await call(deleteByMessageHandler, { pathParams: { messageId: "msg-6" } });
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(publishedTypes()).toEqual(["bookmark.deleted"]);
+    const deletedEvent = publishCalls[0] as EventEnvelope;
+    expect(
+      (deletedEvent.message as unknown as { messageId?: string }).messageId,
+    ).toBe("msg-6");
+  });
+
+  test("DELETE on a non-existent messageId does not publish", async () => {
+    await call(deleteByMessageHandler, {
+      pathParams: { messageId: "does-not-exist" },
+    });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(publishCalls).toHaveLength(0);
+  });
+});

package/src/runtime/routes/__tests__/connection-routes-vs-cli-parity.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Cutover-proof parity test: CLI create vs HTTP route create.
+ *
+ * Runs a CLI `createConnection` call and an HTTP-route `handleCreateConnection`
+ * call with the same payload, then asserts the resulting DB rows are identical
+ * (after normalizing timestamps). This proves the HTTP route wraps the same
+ * store path the CLI uses — no divergent code path.
+ *
+ * Rule: cc-cutover-proof (see PR_B_TASK.md).
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ── Module mocks (must come before imports) ──────────────────────────────────
+
+mock.module("../../../config/loader.js", () => ({
+  getConfigReadOnly: () => ({}),
+  getConfig: () => ({}),
+  invalidateConfigCache: () => {},
+}));
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+}));
+
+// ── Real imports ──────────────────────────────────────────────────────────────
+
+import { getDb } from "../../../memory/db-connection.js";
+import { initializeDb } from "../../../memory/db-init.js";
+import { providerConnections } from "../../../memory/schema/inference.js";
+import { createConnection, getConnection } from "../../../providers/inference/connections.js";
+import { ROUTES } from "../inference-provider-connection-routes.js";
+import type { RouteDefinition } from "../types.js";
+
+// ── DB bootstrap ──────────────────────────────────────────────────────────────
+
+initializeDb();
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function findHandler(operationId: string): RouteDefinition["handler"] {
+  const route = ROUTES.find((r) => r.operationId === operationId);
+  if (!route) throw new Error(`Route ${operationId} not found`);
+  return route.handler;
+}
+
+function clearConnections(): void {
+  getDb().delete(providerConnections).run();
+}
+
+function normalizeTimestamps<T extends object>(obj: T): Omit<T, "createdAt" | "updatedAt"> {
+  const { createdAt: _c, updatedAt: _u, ...rest } = obj as T & { createdAt?: unknown; updatedAt?: unknown };
+  return rest as Omit<T, "createdAt" | "updatedAt">;
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  clearConnections();
+});
+
+describe("CLI vs HTTP route parity", () => {
+  test("api_key connection: CLI createConnection and HTTP POST produce identical DB rows", async () => {
+    const payload = {
+      name: "parity-anthropic",
+      provider: "anthropic" as const,
+      auth: { type: "api_key" as const, credential: "vault/anthropic/key" },
+    };
+
+    // ── CLI path ──────────────────────────────────────────────────────────────
+    const cliResult = createConnection(getDb(), payload);
+    expect(cliResult.ok).toBe(true);
+    if (!cliResult.ok) throw new Error("CLI create failed");
+    const cliRow = getConnection(getDb(), payload.name);
+    expect(cliRow).not.toBeNull();
+
+    // Clean up CLI row before HTTP create so names don't collide.
+    clearConnections();
+
+    // ── HTTP route path ───────────────────────────────────────────────────────
+    const httpResult = (await findHandler("inference_provider_connections_create")({
+      body: {
+        name: payload.name,
+        provider: payload.provider,
+        auth: payload.auth,
+      },
+    })) as { name: string; provider: string; auth: object };
+
+    expect(httpResult.name).toBe(payload.name);
+    const httpRow = getConnection(getDb(), payload.name);
+    expect(httpRow).not.toBeNull();
+
+    // ── Compare ───────────────────────────────────────────────────────────────
+    // Both rows should have identical non-timestamp fields.
+    expect(normalizeTimestamps(httpRow!)).toEqual(normalizeTimestamps(cliRow!));
+  });
+
+  test("platform connection: CLI createConnection and HTTP POST produce identical DB rows", async () => {
+    const payload = {
+      name: "parity-openai-managed",
+      provider: "openai" as const,
+      auth: { type: "platform" as const },
+    };
+
+    const cliResult = createConnection(getDb(), payload);
+    expect(cliResult.ok).toBe(true);
+    if (!cliResult.ok) throw new Error("CLI create failed");
+    const cliRow = getConnection(getDb(), payload.name);
+
+    clearConnections();
+
+    await findHandler("inference_provider_connections_create")({
+      body: { name: payload.name, provider: payload.provider, auth: payload.auth },
+    });
+    const httpRow = getConnection(getDb(), payload.name);
+
+    expect(normalizeTimestamps(httpRow!)).toEqual(normalizeTimestamps(cliRow!));
+  });
+
+  test("none auth connection: CLI createConnection and HTTP POST produce identical DB rows", async () => {
+    const payload = {
+      name: "parity-ollama",
+      provider: "ollama" as const,
+      auth: { type: "none" as const },
+    };
+
+    const cliResult = createConnection(getDb(), payload);
+    expect(cliResult.ok).toBe(true);
+    if (!cliResult.ok) throw new Error("CLI create failed");
+    const cliRow = getConnection(getDb(), payload.name);
+
+    clearConnections();
+
+    await findHandler("inference_provider_connections_create")({
+      body: { name: payload.name, provider: payload.provider, auth: payload.auth },
+    });
+    const httpRow = getConnection(getDb(), payload.name);
+
+    expect(normalizeTimestamps(httpRow!)).toEqual(normalizeTimestamps(cliRow!));
+  });
+});