@vellumai/assistant 0.8.0 → 0.8.1

package/src/memory/jobs/__tests__/embed-concept-page.test.ts

@@ -203,7 +203,7 @@ describe("embedConceptPageJob — happy path", () => {
   test("reads the page, embeds it, and upserts to the v2 collection", async () => {
     await writePage(tmpWorkspace, {
       slug: "alice-prefers-vs-code",
-      frontmatter: { edges: [], ref_files: [] },
+      frontmatter: { edges: [], ref_files: [], ref_urls: [] },
       body: "Alice prefers VS Code over Vim.\nShe ships at end of day.\n",
     });
 
@@ -231,7 +231,7 @@ describe("embedConceptPageJob — happy path", () => {
   test("populates the SQLite embedding cache row keyed on (concept_page, slug)", async () => {
     await writePage(tmpWorkspace, {
       slug: "bob-uses-zsh",
-      frontmatter: { edges: [], ref_files: [] },
+      frontmatter: { edges: [], ref_files: [], ref_urls: [] },
       body: "Bob uses zsh.\n",
     });
 
@@ -257,6 +257,7 @@ describe("embedConceptPageJob — summary embedding", () => {
       frontmatter: {
         edges: [],
         ref_files: [],
+        ref_urls: [],
         summary: "A short prose summary that retrieval indexes separately.",
       },
       body: "Long-form body content.\n",
@@ -282,7 +283,7 @@ describe("embedConceptPageJob — summary embedding", () => {
   test("skips summary embedding when the page has no summary in frontmatter", async () => {
     await writePage(tmpWorkspace, {
       slug: "legacy-page",
-      frontmatter: { edges: [], ref_files: [] },
+      frontmatter: { edges: [], ref_files: [], ref_urls: [] },
       body: "Body only — no summary in frontmatter.\n",
     });
 
@@ -303,6 +304,7 @@ describe("embedConceptPageJob — summary embedding", () => {
       frontmatter: {
         edges: [],
         ref_files: [],
+        ref_urls: [],
         summary: "   ",
       },
       body: "Body content.\n",
@@ -324,14 +326,12 @@ describe("embedConceptPageJob — summary embedding", () => {
       frontmatter: {
         edges: [],
         ref_files: [],
+        ref_urls: [],
         summary: "First version of the summary.",
       },
       body: "Stable body that never changes.\n",
     });
-    await embedConceptPageJob(
-      makeJob({ slug: "cached-summary" }),
-      TEST_CONFIG,
-    );
+    await embedConceptPageJob(makeJob({ slug: "cached-summary" }), TEST_CONFIG);
     // Body + summary batched into a single backend call on first run.
     expect(embedWithBackendCalls).toHaveLength(1);
     expect(embedWithBackendCalls[0].inputs).toHaveLength(2);
@@ -344,14 +344,12 @@ describe("embedConceptPageJob — summary embedding", () => {
       frontmatter: {
         edges: [],
         ref_files: [],
+        ref_urls: [],
         summary: "Second version of the summary, different wording.",
       },
       body: "Stable body that never changes.\n",
     });
-    await embedConceptPageJob(
-      makeJob({ slug: "cached-summary" }),
-      TEST_CONFIG,
-    );
+    await embedConceptPageJob(makeJob({ slug: "cached-summary" }), TEST_CONFIG);
     // One additional backend call with only the summary text — body hit the cache.
     expect(embedWithBackendCalls).toHaveLength(2);
     expect(embedWithBackendCalls[1].inputs).toHaveLength(1);
@@ -362,7 +360,7 @@ describe("embedConceptPageJob — cache hit", () => {
   test("reuses the cached dense vector when content hash matches", async () => {
     await writePage(tmpWorkspace, {
       slug: "alice-prefers-vs-code",
-      frontmatter: { edges: [], ref_files: [] },
+      frontmatter: { edges: [], ref_files: [], ref_urls: [] },
       body: "Stable content.\n",
     });
 
@@ -387,7 +385,7 @@ describe("embedConceptPageJob — cache hit", () => {
   test("re-embeds when the body changes (content hash mismatch)", async () => {
     await writePage(tmpWorkspace, {
       slug: "alice-prefers-vs-code",
-      frontmatter: { edges: [], ref_files: [] },
+      frontmatter: { edges: [], ref_files: [], ref_urls: [] },
       body: "First content.\n",
     });
     await embedConceptPageJob(
@@ -398,7 +396,7 @@ describe("embedConceptPageJob — cache hit", () => {
     // Rewrite with different body.
     await writePage(tmpWorkspace, {
       slug: "alice-prefers-vs-code",
-      frontmatter: { edges: [], ref_files: [] },
+      frontmatter: { edges: [], ref_files: [], ref_urls: [] },
       body: "Second content (different).\n",
     });
     await embedConceptPageJob(
@@ -453,7 +451,7 @@ describe("enqueueEmbedConceptPageJob", () => {
   test("round-trip: enqueued job dispatches through embedConceptPageJob", async () => {
     await writePage(tmpWorkspace, {
       slug: "round-trip-slug",
-      frontmatter: { edges: [], ref_files: [] },
+      frontmatter: { edges: [], ref_files: [], ref_urls: [] },
       body: "Round-trip body.\n",
     });
 

package/src/memory/jobs/embed-concept-page.ts

@@ -163,21 +163,54 @@ export async function embedConceptPageJob(
     slots.push("summary");
   }
 
-  let bodyDense: number[] | undefined = bodyCacheHit ? bodyCache!.dense : undefined;
+  let bodyDense: number[] | undefined = bodyCacheHit
+    ? bodyCache!.dense
+    : undefined;
   let summaryDense: number[] | undefined = summaryCacheHit
     ? summaryCache!.dense
     : undefined;
   let writeProvider = cacheProvider;
   let writeModel = cacheModel;
+  let bodyFresh = false;
+  let summaryFresh = false;
   if (toEmbed.length > 0) {
-    const embedded = await embedWithBackend(config, toEmbed);
+    let embedded = await embedWithBackend(config, toEmbed);
+    let appliedSlots = slots;
+    // Backend rotation between `getMemoryBackendStatus()` and
+    // `embedWithBackend()` would tag the cached half with the old
+    // provider/model and the fresh half with the new — writing both into
+    // one Qdrant point mixes embedding spaces. Re-embed every slot fresh
+    // when we detect the rotation so the point's named vectors share one
+    // identity.
+    const rotated =
+      (bodyCacheHit || summaryCacheHit) &&
+      (embedded.provider !== cacheProvider || embedded.model !== cacheModel);
+    if (rotated) {
+      const allTexts: Array<{ type: "text"; text: string }> = [
+        { type: "text", text },
+      ];
+      const allSlots: Slot[] = ["body"];
+      if (hasSummary) {
+        allTexts.push({ type: "text", text: summaryText });
+        allSlots.push("summary");
+      }
+      embedded = await embedWithBackend(config, allTexts);
+      appliedSlots = allSlots;
+      bodyDense = undefined;
+      summaryDense = undefined;
+    }
     writeProvider = embedded.provider;
     writeModel = embedded.model;
-    for (let i = 0; i < slots.length; i++) {
+    for (let i = 0; i < appliedSlots.length; i++) {
       const vector = embedded.vectors[i];
       if (!vector) continue;
-      if (slots[i] === "body") bodyDense = vector;
-      else summaryDense = vector;
+      if (appliedSlots[i] === "body") {
+        bodyDense = vector;
+        bodyFresh = true;
+      } else {
+        summaryDense = vector;
+        summaryFresh = true;
+      }
     }
   }
   // Body embedding is the ground truth — without it the page can't surface.
@@ -205,9 +238,12 @@ export async function embedConceptPageJob(
   const now = Date.now();
   // Persist freshly embedded vectors for cross-restart reuse. On cache hit
   // the existing row already has identical content + hash, so the write
-  // would be a no-op — skip it. Best-effort: write failure is not fatal,
-  // we still want the Qdrant upsert below to fire.
-  if (!bodyCacheHit) {
+  // would be a no-op — skip it. Backend rotation flips a cache hit into a
+  // fresh embed (see `rotated` above); the `*Fresh` flags capture that so
+  // the new vector overwrites the now-stale cache row under the new
+  // provider/model identity. Best-effort: write failure is not fatal, we
+  // still want the Qdrant upsert below to fire.
+  if (bodyFresh) {
     writeEmbeddingCache(db, {
       slug,
       cacheId: slug,
@@ -218,7 +254,7 @@ export async function embedConceptPageJob(
       now,
     });
   }
-  if (hasSummary && !summaryCacheHit && summaryDense && summaryContentHash) {
+  if (hasSummary && summaryFresh && summaryDense && summaryContentHash) {
     writeEmbeddingCache(db, {
       slug,
       cacheId: summaryCacheId,

package/src/memory/jobs-store.ts

@@ -42,7 +42,8 @@ export type MemoryJobType =
   | "memory_v2_consolidate"
   | "memory_v2_migrate"
   | "memory_v2_reembed"
-  | "memory_v2_activation_recompute";
+  | "memory_v2_activation_recompute"
+  | "memory_retrospective";
 
 export const EMBED_JOB_TYPES: MemoryJobType[] = [
   "embed_segment",
@@ -52,6 +53,7 @@ export const EMBED_JOB_TYPES: MemoryJobType[] = [
   "embed_graph_node",
   "embed_pkb_file",
   "graph_trigger_embed",
+  "embed_concept_page",
 ];
 
 export const SLOW_LLM_JOB_TYPES: MemoryJobType[] = [
@@ -65,6 +67,7 @@ export const SLOW_LLM_JOB_TYPES: MemoryJobType[] = [
   "memory_v2_sweep",
   "memory_v2_consolidate",
   "memory_v2_migrate",
+  "memory_retrospective",
   "backfill",
   "graph_bootstrap",
 ];
@@ -251,6 +254,53 @@ export function upsertAutoAnalysisJob(
   }
 }
 
+/**
+ * Upsert a pending `memory_retrospective` job keyed by `conversationId`. All
+ * four retrospective triggers (interval, message_count, compaction,
+ * lifecycle) collapse into a single pending row per conversation — rapid
+ * triggers coalesce instead of double-firing. The `runAfter` parameter on a
+ * follow-up enqueue overwrites the existing row's `runAfter` so a sooner
+ * trigger can pull a later-scheduled job earlier; a later-scheduled trigger
+ * does NOT push a sooner-scheduled row further out (consumer takes the
+ * minimum). The trigger metadata is intentionally not retained — it is only
+ * useful for observability at enqueue time.
+ */
+export function upsertMemoryRetrospectiveJob(
+  payload: { conversationId: string },
+  runAfter: number = Date.now(),
+  dbOverride?: Parameters<ReturnType<typeof getDb>["transaction"]>[0] extends (
+    tx: infer T,
+  ) => unknown
+    ? T
+    : never,
+): void {
+  const db = dbOverride ?? getDb();
+  const existing = db
+    .select()
+    .from(memoryJobs)
+    .where(
+      and(
+        eq(memoryJobs.type, "memory_retrospective"),
+        eq(memoryJobs.status, "pending"),
+        sql`json_extract(${memoryJobs.payload}, '$.conversationId') = ${payload.conversationId}`,
+      ),
+    )
+    .get();
+  if (existing) {
+    // Take the minimum of the existing and incoming runAfter so the earliest
+    // trigger always wins. A later trigger never pushes work further out.
+    const nextRunAfter = Math.min(existing.runAfter, runAfter);
+    if (nextRunAfter !== existing.runAfter) {
+      db.update(memoryJobs)
+        .set({ runAfter: nextRunAfter, updatedAt: Date.now() })
+        .where(eq(memoryJobs.id, existing.id))
+        .run();
+    }
+    return;
+  }
+  enqueueMemoryJob("memory_retrospective", payload, runAfter, dbOverride);
+}
+
 /**
  * Check whether a pending or running job of the given type already exists.
  * Used to prevent duplicate enqueues for long-running maintenance jobs.

package/src/memory/jobs-worker.ts

@@ -67,6 +67,8 @@ import {
   resetRunningJobsToPending,
   SLOW_LLM_JOB_TYPES,
 } from "./jobs-store.js";
+import { memoryRetrospectiveJob } from "./memory-retrospective-job.js";
+import { sweepOrphanMemoryRetrospectiveConversations } from "./memory-retrospective-startup-cleanup.js";
 import { QdrantCircuitOpenError } from "./qdrant-circuit-breaker.js";
 import {
   memoryV2ActivationRecomputeJob,
@@ -78,6 +80,26 @@ import { memoryV2SweepJob } from "./v2/sweep-job.js";
 
 const log = getLogger("memory-jobs-worker");
 
+/**
+ * V1 job types that read or write the v1 Qdrant collection via
+ * `getQdrantClient()`. When `memory.v2.enabled` is true, the v1 client is
+ * intentionally left uninitialized in `lifecycle.ts`, so these handlers would
+ * throw `BackendUnavailableError` and accumulate as a deferred backlog. Stale
+ * rows from indexer.ts and other unguarded enqueue sites must short-circuit
+ * here for the same reason `graph_extract` does below.
+ */
+const V1_QDRANT_JOB_TYPES = new Set<MemoryJobType>([
+  "embed_segment",
+  "embed_summary",
+  "embed_media",
+  "embed_attachment",
+  "embed_graph_node",
+  "embed_pkb_file",
+  "graph_trigger_embed",
+  "rebuild_index",
+  "delete_qdrant_vectors",
+]);
+
 /**
  * Job types whose handlers have been removed. Existing rows may still sit in
  * the database — the worker completes them silently instead of throwing.
@@ -111,6 +133,19 @@ export function startMemoryJobsWorker(): MemoryJobsWorker {
     log.info({ recovered }, "Recovered stale running memory jobs");
   }
 
+  // After running-job recovery (so legitimate in-flight retries aren't
+  // swept), clean up orphan memory-retrospective background conversations
+  // left behind by daemon crashes mid-job. Best-effort — never block worker
+  // startup on cleanup failures.
+  try {
+    sweepOrphanMemoryRetrospectiveConversations();
+  } catch (err) {
+    log.warn(
+      { err },
+      "Memory-retrospective startup cleanup failed; continuing worker startup",
+    );
+  }
+
   let stopped = false;
   let tickRunning = false;
   let timer: ReturnType<typeof setTimeout>;
@@ -124,16 +159,24 @@ export function startMemoryJobsWorker(): MemoryJobsWorker {
         enableScheduledCleanup: true,
       });
       if (processed > 0) {
-        currentIntervalMs = POLL_INTERVAL_MIN_MS;
+        // Per-tick claim budget equals the lane caps, so when a tick
+        // processed work the next tick must run immediately to drain any
+        // remaining backlog. Holding the 1.5s floor between ticks would cap
+        // sustained throughput at lane-cap jobs per 1.5s and starve large
+        // backlogs of short jobs.
+        currentIntervalMs = 0;
       } else {
         currentIntervalMs = Math.min(
-          currentIntervalMs * 2,
+          Math.max(currentIntervalMs * 2, POLL_INTERVAL_MIN_MS),
           POLL_INTERVAL_MAX_MS,
         );
       }
     } catch (err) {
       log.error({ err }, "Memory worker tick failed");
-      currentIntervalMs = Math.min(currentIntervalMs * 2, POLL_INTERVAL_MAX_MS);
+      currentIntervalMs = Math.min(
+        Math.max(currentIntervalMs * 2, POLL_INTERVAL_MIN_MS),
+        POLL_INTERVAL_MAX_MS,
+      );
     } finally {
       tickRunning = false;
     }
@@ -462,6 +505,9 @@ async function processJob(
   job: MemoryJob,
   config: AssistantConfig,
 ): Promise<void> {
+  if (config.memory.v2.enabled && V1_QDRANT_JOB_TYPES.has(job.type)) {
+    return;
+  }
   switch (job.type) {
     case "embed_segment":
       await embedSegmentJob(job, config);
@@ -555,6 +601,9 @@ async function processJob(
     case "memory_v2_activation_recompute":
       await memoryV2ActivationRecomputeJob(job, config);
       return;
+    case "memory_retrospective":
+      await memoryRetrospectiveJob(job, config);
+      return;
 
     default: {
       const rawType = (job as { type: string }).type;

package/src/memory/llm-request-log-source-clickhouse.ts

@@ -0,0 +1,317 @@
+/**
+ * ClickHouse-backed LLM request log read source.
+ *
+ * Reads from the ClickHouse mirror (populated out-of-band by the
+ * `mirror-llm-logs-to-clickhouse` cron). Scoped to the running
+ * assistant's own `assistant_id` — never cross-assistant. URL and
+ * password are resolved lazily from the credential store
+ * (`clickhouse:url`, `clickhouse:password`); database/table/user come
+ * from workspace config.
+ *
+ * Known limitation: the mirror is INSERT-only. A row inserted locally
+ * with `message_id = NULL` and backfilled later will appear in
+ * ClickHouse with `message_id = ''` forever. Reads via this source for
+ * the most-recent ~minute of activity therefore have lower fidelity
+ * than the local source. Acceptable for the "internal use while we
+ * finetune prompts" use case; revisit when mirror updates are added.
+ */
+import type { LlmRequestLogsClickHouseConfig } from "../config/schemas/llm-request-logs.js";
+import { credentialKey } from "../security/credential-key.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { getLogger } from "../util/logger.js";
+import {
+  getAssistantMessageIdsInTurn,
+  getMessageById,
+  messageMetadataSchema,
+} from "./conversation-crud.js";
+import type { LlmRequestLogSource } from "./llm-request-log-source.js";
+import type { LogRow } from "./llm-request-log-store.js";
+
+const log = getLogger("clickhouse-llm-request-log-source");
+
+/**
+ * Read a credential and normalize `undefined` → `null`. The credential
+ * resolver factories on this class are typed `() => Promise<string | null>`;
+ * `getSecureKeyAsync` returns `Promise<string | undefined>`. Keep the
+ * coercion in one place so TypeScript stays happy without per-call casts.
+ */
+async function readCredentialOrNull(
+  service: string,
+  field: string,
+): Promise<string | null> {
+  const value = await getSecureKeyAsync(credentialKey(service, field));
+  return value ?? null;
+}
+
+/**
+ * Wire-format row returned by ClickHouse for our query columns. Note
+ * that `created_at` arrives as a string because Int64 is emitted as a
+ * quoted string under the default `output_format_json_quote_64bit_integers=1`
+ * setting; we coerce to `number` in `toLogRow`.
+ */
+interface ClickHouseRow {
+  id: string;
+  conversation_id: string;
+  message_id: string;
+  provider: string;
+  request_payload: string;
+  response_payload: string;
+  created_at: string;
+}
+
+/** Injectable fetch override for tests. Defaults to globalThis.fetch. */
+export type ClickHouseFetch = typeof fetch;
+
+/** Minimal subset of the SQLite message row the fork-source fallback needs. */
+export interface ClickHouseMessageRow {
+  metadata: string | null;
+}
+
+export interface ClickHouseLlmRequestLogSourceDeps {
+  /** Override the credential read for `clickhouse:url`. */
+  resolveUrl?: () => Promise<string | null>;
+  /** Override the credential read for `clickhouse:password`. */
+  resolvePassword?: () => Promise<string | null>;
+  /** Override the credential read for `vellum:platform_assistant_id`. */
+  resolveAssistantId?: () => Promise<string | null>;
+  /** Override the turn-id resolver (default: `getAssistantMessageIdsInTurn`). */
+  resolveTurnMessageIds?: (messageId: string) => string[];
+  /** Override the message lookup (default: `getMessageById`). */
+  resolveMessage?: (messageId: string) => ClickHouseMessageRow | null;
+  /** Override fetch for testing. */
+  fetchImpl?: ClickHouseFetch;
+}
+
+export class ClickHouseLlmRequestLogSource implements LlmRequestLogSource {
+  private cachedUrl: string | null = null;
+  private cachedPassword: string | null = null;
+  private cachedAssistantId: string | null = null;
+
+  private readonly resolveUrl: () => Promise<string | null>;
+  private readonly resolvePassword: () => Promise<string | null>;
+  private readonly resolveAssistantId: () => Promise<string | null>;
+  private readonly resolveTurnMessageIds: (messageId: string) => string[];
+  private readonly resolveMessage: (
+    messageId: string,
+  ) => ClickHouseMessageRow | null;
+  private readonly fetchImpl: ClickHouseFetch;
+
+  constructor(
+    private readonly config: LlmRequestLogsClickHouseConfig,
+    deps: ClickHouseLlmRequestLogSourceDeps = {},
+  ) {
+    this.resolveUrl =
+      deps.resolveUrl ?? (() => readCredentialOrNull("clickhouse", "url"));
+    this.resolvePassword =
+      deps.resolvePassword ??
+      (() => readCredentialOrNull("clickhouse", "password"));
+    this.resolveAssistantId =
+      deps.resolveAssistantId ??
+      (() => readCredentialOrNull("vellum", "platform_assistant_id"));
+    this.resolveTurnMessageIds =
+      deps.resolveTurnMessageIds ?? getAssistantMessageIdsInTurn;
+    this.resolveMessage = deps.resolveMessage ?? getMessageById;
+    this.fetchImpl = deps.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  }
+
+  async getRequestLogById(logId: string): Promise<LogRow | null> {
+    const aid = await this.assistantId();
+    const sql = `SELECT
+        id,
+        conversation_id,
+        message_id,
+        provider,
+        request_payload,
+        response_payload,
+        toUnixTimestamp64Milli(created_at) AS created_at
+      FROM ${this.tableRef()}
+      WHERE assistant_id = {assistant_id:String}
+        AND id = {log_id:String}
+      ORDER BY created_at DESC
+      LIMIT 1
+      FORMAT JSONEachRow`;
+    const rows = await this.exec(sql, { assistant_id: aid, log_id: logId });
+    return rows[0] ? this.toLogRow(rows[0]) : null;
+  }
+
+  async getRequestLogsByMessageId(messageId: string): Promise<LogRow[]> {
+    const turnIds = this.resolveTurnMessageIds(messageId);
+    let rows = await this.selectByMessageIds(turnIds);
+
+    if (rows.length === 0) {
+      // Fork-source fallback. Mirror behavior of the local source: when no
+      // logs match the queried message's turn, see if it was forked from
+      // another and resolve that source's turn. The fork relationship lives
+      // in local SQLite (message.metadata.forkSourceMessageId), not CH.
+      const message = this.resolveMessage(messageId);
+      if (message?.metadata) {
+        try {
+          const parsed = messageMetadataSchema.safeParse(
+            JSON.parse(message.metadata),
+          );
+          const sourceMessageId =
+            parsed.success &&
+            typeof parsed.data.forkSourceMessageId === "string"
+              ? parsed.data.forkSourceMessageId
+              : null;
+          if (sourceMessageId && sourceMessageId !== messageId) {
+            const sourceTurnIds = this.resolveTurnMessageIds(sourceMessageId);
+            rows = await this.selectByMessageIds(sourceTurnIds);
+          }
+        } catch {
+          // metadata not JSON / schema mismatch — no fork fallback, return []
+        }
+      }
+    }
+
+    return rows.sort(
+      (a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id),
+    );
+  }
+
+  private async selectByMessageIds(ids: string[]): Promise<LogRow[]> {
+    if (ids.length === 0) return [];
+    const aid = await this.assistantId();
+    // ClickHouse Array(String) URL encoding is fiddly; the message IDs are
+    // server-generated UUIDs (or safe internal strings), so inline the
+    // literal after escaping single quotes. No SQL-injection surface — the
+    // values originate from our own SQLite messages table.
+    const idLiteral =
+      "[" +
+      ids.map((id) => `'${id.replace(/'/g, "''")}'`).join(",") +
+      "]";
+    const sql = `SELECT
+        id,
+        conversation_id,
+        message_id,
+        provider,
+        request_payload,
+        response_payload,
+        toUnixTimestamp64Milli(created_at) AS created_at
+      FROM ${this.tableRef()}
+      WHERE assistant_id = {assistant_id:String}
+        AND message_id IN ${idLiteral}
+      ORDER BY created_at ASC, id ASC
+      LIMIT 1 BY id
+      FORMAT JSONEachRow`;
+    const rows = await this.exec(sql, { assistant_id: aid });
+    return rows.map((r) => this.toLogRow(r));
+  }
+
+  private tableRef(): string {
+    // Database is set via the `database=` URL param in `exec`, so we only
+    // need to quote the table identifier here. Backtick-quote both to
+    // tolerate non-default names with special characters.
+    return `\`${this.config.table.replace(/`/g, "``")}\``;
+  }
+
+  private async exec(
+    sql: string,
+    params: Record<string, string>,
+  ): Promise<ClickHouseRow[]> {
+    const baseUrl = await this.url();
+    const password = await this.password();
+
+    let target: URL;
+    try {
+      target = new URL(baseUrl);
+    } catch (err) {
+      throw new Error(
+        `clickhouse:url is not a valid URL: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    target.searchParams.set("database", this.config.database);
+    for (const [k, v] of Object.entries(params)) {
+      target.searchParams.set(`param_${k}`, v);
+    }
+
+    const auth =
+      "Basic " +
+      Buffer.from(`${this.config.user}:${password}`, "utf8").toString("base64");
+
+    const res = await this.fetchImpl(target.toString(), {
+      method: "POST",
+      headers: { Authorization: auth, "Content-Type": "text/plain" },
+      body: sql,
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      log.error(
+        { status: res.status, table: this.config.table, bodySnippet: body.slice(0, 200) },
+        "ClickHouse query failed",
+      );
+      throw new Error(
+        `ClickHouse query failed (HTTP ${res.status}): ${body.slice(0, 500)}`,
+      );
+    }
+
+    const text = await res.text();
+    if (text.trim().length === 0) return [];
+
+    const rows: ClickHouseRow[] = [];
+    for (const line of text.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      try {
+        rows.push(JSON.parse(trimmed) as ClickHouseRow);
+      } catch (err) {
+        throw new Error(
+          `Failed to parse ClickHouse JSONEachRow line: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+    return rows;
+  }
+
+  private toLogRow(row: ClickHouseRow): LogRow {
+    return {
+      id: row.id,
+      conversationId: row.conversation_id,
+      // The mirror writes empty-string for missing message_id/provider
+      // because the CH table columns have `DEFAULT ''` (Nullable adds
+      // overhead). Map empty back to null to match the local LogRow shape.
+      messageId: row.message_id === "" ? null : row.message_id,
+      provider: row.provider === "" ? null : row.provider,
+      requestPayload: row.request_payload,
+      responsePayload: row.response_payload,
+      createdAt: Number(row.created_at),
+    };
+  }
+
+  private async assistantId(): Promise<string> {
+    if (this.cachedAssistantId) return this.cachedAssistantId;
+    const val = await this.resolveAssistantId();
+    if (!val) {
+      throw new Error(
+        "vellum:platform_assistant_id credential is required when readSource=clickhouse",
+      );
+    }
+    this.cachedAssistantId = val;
+    return val;
+  }
+
+  private async url(): Promise<string> {
+    if (this.cachedUrl) return this.cachedUrl;
+    const val = await this.resolveUrl();
+    if (!val) {
+      throw new Error(
+        "clickhouse:url credential is required when readSource=clickhouse",
+      );
+    }
+    this.cachedUrl = val;
+    return val;
+  }
+
+  private async password(): Promise<string> {
+    if (this.cachedPassword) return this.cachedPassword;
+    const val = await this.resolvePassword();
+    if (!val) {
+      throw new Error(
+        "clickhouse:password credential is required when readSource=clickhouse",
+      );
+    }
+    this.cachedPassword = val;
+    return val;
+  }
+}