@vellumai/assistant 0.10.0-dev.202606200318.c052d10 → 0.10.0-dev.202606201453.1417592

package/src/memory/db-init.ts

@@ -10,6 +10,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { getLogger } from "../util/logger.js";
+import { getLogsDbPath } from "../util/logs-db-path.js";
 import { ensureDataDir, getDbPath } from "../util/platform.js";
 import { backfillAppConversationIds } from "./app-store.js";
 import { getDb, getSqlite } from "./db-connection.js";
@@ -154,6 +155,7 @@ import {
   migrateMessagesConversationCreatedAtIndex,
   migrateMessagesFtsBackfill,
   migrateMessagesRoleCreatedAtIndex,
+  migrateMoveLlmRequestLogsToLogsDb,
   migrateNormalizePhoneIdentities,
   migrateNormalizeSlackExternalContent,
   migrateNormalizeUserFileByPrincipal,
@@ -265,12 +267,31 @@ function getTemplateDbPath(): string {
   );
 }
 
+/**
+ * Template path for the attached `logs` database, kept alongside the main
+ * template. Both files must be captured/restored together: the migrated state
+ * now spans two files (llm_request_logs and its indexes live in `logs`), so
+ * restoring only the main DB would leave a fresh, empty logs DB with no
+ * `llm_request_logs` table.
+ */
+function getLogsTemplateDbPath(): string {
+  return `${getTemplateDbPath()}.logs`;
+}
+
 function tryRestoreTemplate(): boolean {
   const templatePath = getTemplateDbPath();
   if (!existsSync(templatePath)) return false;
   // getDb() hasn't run yet, so the data directory may not exist.
   ensureDataDir();
   copyFileSync(templatePath, getDbPath());
+  // Restore the attached logs DB before getDb() opens (and ATTACHes) it, so the
+  // relocated llm_request_logs table is present. Older templates may predate
+  // the split; the hash includes the migration files, so a stale template
+  // without this sibling won't be reused — but guard anyway.
+  const logsTemplate = getLogsTemplateDbPath();
+  if (existsSync(logsTemplate)) {
+    copyFileSync(logsTemplate, getLogsDbPath());
+  }
   // Open the pre-migrated copy — getDb() will set PRAGMAs but skip migrations.
   getDb();
   return true;
@@ -278,12 +299,18 @@ function tryRestoreTemplate(): boolean {
 
 function saveTemplate(): void {
   try {
-    // Flush WAL to main DB file before copying.
+    // Flush each DB's WAL to its main file before copying.
     getSqlite().exec("PRAGMA wal_checkpoint(TRUNCATE)");
-    const tmpFile = `${getTemplateDbPath()}.${process.pid}`;
-    copyFileSync(getDbPath(), tmpFile);
-    // Atomic rename — safe even with parallel test workers.
-    renameSync(tmpFile, getTemplateDbPath());
+    getSqlite().exec("PRAGMA logs.wal_checkpoint(TRUNCATE)");
+
+    const mainTmp = `${getTemplateDbPath()}.${process.pid}`;
+    copyFileSync(getDbPath(), mainTmp);
+    const logsTmp = `${getLogsTemplateDbPath()}.${process.pid}`;
+    copyFileSync(getLogsDbPath(), logsTmp);
+
+    // Atomic renames — safe even with parallel test workers.
+    renameSync(mainTmp, getTemplateDbPath());
+    renameSync(logsTmp, getLogsTemplateDbPath());
   } catch {
     // Best effort — next file will just run migrations normally.
   }
@@ -531,6 +558,7 @@ export function initializeDb(): void {
     migrateDropExternalUserId,
     dropApprovalPromptTsTrackerTable,
     migrateRewriteBalancedEconomyProfilePins,
+    migrateMoveLlmRequestLogsToLogsDb,
   ];
 
   // Run each migration step, catching and logging individual failures so one

package/src/memory/db-maintenance.ts

@@ -58,11 +58,10 @@ async function runDbMaintenance(): Promise<void> {
   );
 
   // Prune finished workflow runs (and their journals) past the retention
-  // window BEFORE VACUUM so the freed pages are reclaimed in the same pass.
-  // This is a fast bounded DELETE on the small workflow tables, so it runs on
-  // the main connection (`rawRun`) — unlike VACUUM/optimize it doesn't need the
-  // async/subprocess path. The maintenance scheduler below already defers this
-  // whole routine to an idle window.
+  // window. This is a fast bounded DELETE on the small workflow tables, so it
+  // runs on the main connection (`rawRun`). SQLite reuses the pages it frees
+  // for later writes — we deliberately do not VACUUM to hand them back to the
+  // OS (see the WAL note below).
   try {
     const deletedRuns = pruneRuns(getConfig().workflows.journalRetentionDays);
     if (deletedRuns > 0) {
@@ -72,18 +71,9 @@ async function runDbMaintenance(): Promise<void> {
     log.warn({ err }, "Workflow run pruning failed (non-fatal)");
   }
 
-  // VACUUM is the long-running one — minutes on a multi-GB DB. PRAGMA
-  // optimize is fast but routed through the same async path for
-  // consistency and to keep both off the main thread when the CLI
-  // backend is available.
-  const vacuumResult = await runAsyncSqlite("VACUUM");
-  if (!vacuumResult.ok) {
-    log.warn(
-      { error: vacuumResult.error, backend: vacuumResult.backend },
-      "VACUUM failed (non-fatal)",
-    );
-  }
-
+  // Refresh the query planner's statistics. PRAGMA optimize is cheap; it is
+  // routed through the async path for consistency and to keep it off the main
+  // thread when the sqlite3 CLI backend is available.
   const optimizeResult = await runAsyncSqlite("PRAGMA optimize");
   if (!optimizeResult.ok) {
     log.warn(
@@ -92,26 +82,42 @@ async function runDbMaintenance(): Promise<void> {
     );
   }
 
-  const after = getDbStats();
-  const reclaimedPages = before.pageCount - after.pageCount;
-  const reclaimedBytes =
-    before.fileSizeBytes != null && after.fileSizeBytes != null
-      ? before.fileSizeBytes - after.fileSizeBytes
-      : null;
+  // Truncate the WAL so it doesn't sit at its high-water mark. We intentionally
+  // do NOT run a full VACUUM: in WAL mode VACUUM rewrites the whole database
+  // through the WAL, inflating it to ~the database size and needing up to 2x the
+  // DB size in free disk to finish. SQLite already reuses freed pages for new
+  // writes, so eager space return isn't worth that cost on a multi-GB database.
+  //
+  // The checkpoint goes through the async path (sqlite3 subprocess when one is
+  // available) for the same reason VACUUM/optimize do: a synchronous
+  // wal_checkpoint(TRUNCATE) on the shared connection blocks the event loop
+  // while it checkpoints frames and waits out readers — the health/IPC stall
+  // runAsyncSqlite exists to avoid. A checkpoint from a separate connection
+  // still truncates the shared WAL; if a reader holds it back it's a
+  // best-effort no-op and the next maintenance pass retries.
+  const checkpointResult = await runAsyncSqlite(
+    "PRAGMA wal_checkpoint(TRUNCATE)",
+  );
+  if (!checkpointResult.ok) {
+    log.warn(
+      { error: checkpointResult.error, backend: checkpointResult.backend },
+      "WAL checkpoint failed (non-fatal)",
+    );
+  }
 
+  const after = getDbStats();
   log.info(
     {
-      backend: vacuumResult.backend,
-      vacuumOk: vacuumResult.ok,
       optimizeOk: optimizeResult.ok,
-      vacuumElapsedMs: vacuumResult.elapsedMs,
+      optimizeBackend: optimizeResult.backend,
       optimizeElapsedMs: optimizeResult.elapsedMs,
-      beforePageCount: before.pageCount,
-      afterPageCount: after.pageCount,
-      reclaimedPages,
-      beforeFileSizeBytes: before.fileSizeBytes,
-      afterFileSizeBytes: after.fileSizeBytes,
-      reclaimedBytes,
+      checkpointOk: checkpointResult.ok,
+      checkpointBackend: checkpointResult.backend,
+      checkpointResult: checkpointResult.stdout?.trim(),
+      checkpointElapsedMs: checkpointResult.elapsedMs,
+      pageCount: after.pageCount,
+      freelistCount: after.freelistCount,
+      fileSizeBytes: after.fileSizeBytes,
     },
     "Database maintenance complete",
   );
@@ -126,12 +132,11 @@ export async function maybeRunDbMaintenance(nowMs = Date.now()): Promise<void> {
   );
   if (nowMs - lastRun < intervalMs) return;
 
-  // VACUUM holds an exclusive lock on the database for its full duration —
-  // minutes on a multi-GB DB — during which every other write fails with
-  // SQLITE_BUSY ("database is locked"). Defer maintenance until the user has
-  // been quiet for `quietPeriodMs` so that lock never lands mid-conversation.
-  // The checkpoint below is only written once maintenance actually runs, so a
-  // deferred run is simply retried on a later (still-idle) worker tick.
+  // Maintenance still takes brief write locks (PRAGMA optimize and the
+  // truncating WAL checkpoint), so defer it until the user has been quiet for
+  // `quietPeriodMs` and those locks never land mid-conversation. The checkpoint
+  // below is only written once maintenance actually runs, so a deferred run is
+  // simply retried on a later (still-idle) worker tick.
   if (quietPeriodMs > 0) {
     const lastUserMessageAt = getLastUserMessageTimestamp();
     if (lastUserMessageAt > 0 && nowMs - lastUserMessageAt < quietPeriodMs) {

package/src/memory/job-handlers/cleanup.ts

@@ -1,5 +1,6 @@
 import type { AssistantConfig } from "../../config/types.js";
 import { getLogger } from "../../util/logger.js";
+import { getLogsDbPath } from "../../util/logs-db-path.js";
 import { runAsyncSqlite } from "../db-async-query.js";
 import { getDb } from "../db-connection.js";
 import { enqueueMemoryJob, type MemoryJob } from "../jobs-store.js";
@@ -49,9 +50,14 @@ export async function pruneOldLlmRequestLogsJob(
   // fallback backend in `db-async-query.ts` synthesizes the same shape
   // by capturing `changes()` atomically after `exec()`. Both backends
   // end up on the parser path below.
+  // llm_request_logs lives in the attached logs database. Point the sqlite3
+  // subprocess at that file directly (it can't see the daemon connection's
+  // ATTACH); the in-process fallback runs on the daemon connection, where the
+  // unqualified name already resolves to the attached table.
   const result = await runAsyncSqlite(
     `DELETE FROM llm_request_logs WHERE rowid IN (SELECT rowid FROM llm_request_logs WHERE created_at < ${cutoffMs} LIMIT ${PRUNE_LOG_BATCH_LIMIT});
 SELECT changes();`,
+    { dbPath: getLogsDbPath() },
   );
   if (!result.ok) {
     log.warn(

package/src/memory/migrations/297-move-llm-request-logs-to-logs-db.ts

@@ -0,0 +1,130 @@
+import {
+  type DrizzleDb,
+  getSqliteFrom,
+  LOGS_DB_SCHEMA,
+} from "../db-connection.js";
+
+/**
+ * Column names of `llm_request_logs`, in a fixed order used for the
+ * cross-database copy. Listed explicitly (rather than `SELECT *`) so the copy
+ * is insensitive to the physical column order of the `main` table, which varies
+ * with the historical sequence of `ALTER TABLE ... ADD COLUMN` migrations.
+ *
+ * The first columns are the original base columns; the rest were added by later
+ * column migrations.
+ */
+const COLUMN_NAMES = [
+  "id",
+  "conversation_id",
+  "message_id",
+  "provider",
+  "request_payload",
+  "response_payload",
+  "created_at",
+  "agent_loop_exit_reason",
+  "call_site",
+];
+const COLUMNS = COLUMN_NAMES.join(", ");
+
+const CREATE_TABLE = (schema: string): string => /*sql*/ `
+  CREATE TABLE IF NOT EXISTS ${schema}.llm_request_logs (
+    id TEXT PRIMARY KEY,
+    conversation_id TEXT NOT NULL,
+    message_id TEXT,
+    provider TEXT,
+    request_payload TEXT NOT NULL,
+    response_payload TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    agent_loop_exit_reason TEXT,
+    call_site TEXT
+  )
+`;
+
+/**
+ * Create the three indexes in `schema`. The index names are schema-qualified;
+ * the table name in `CREATE INDEX` must be unqualified and is resolved within
+ * the index's schema — so the table must already resolve to `schema` (i.e. no
+ * same-named table shadowing it in `main`) when this runs.
+ */
+function createIndexes(raw: ReturnType<typeof getSqliteFrom>, schema: string) {
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS ${schema}.idx_llm_request_logs_message_id ON llm_request_logs(message_id)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS ${schema}.idx_llm_request_logs_created_at ON llm_request_logs(created_at)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS ${schema}.idx_llm_request_logs_conv_created ON llm_request_logs(conversation_id, created_at)`,
+  );
+}
+
+function tableExists(
+  raw: ReturnType<typeof getSqliteFrom>,
+  schema: string,
+): boolean {
+  return (
+    raw
+      .query(
+        `SELECT name FROM ${schema}.sqlite_master WHERE type='table' AND name='llm_request_logs'`,
+      )
+      .get() != null
+  );
+}
+
+/**
+ * Copy every row of `llm_request_logs` from `main` into the `logs` database,
+ * substituting `NULL` for any target column missing in the source. The newer
+ * columns (message_id/provider/agent_loop_exit_reason/call_site) are all
+ * nullable, so NULL is correct for a legacy row that predates them.
+ */
+function copyRowsFromMain(raw: ReturnType<typeof getSqliteFrom>): void {
+  const presentColumns = new Set(
+    (
+      raw
+        .query(`SELECT name FROM pragma_table_info('llm_request_logs', 'main')`)
+        .all() as Array<{ name: string }>
+    ).map((r) => r.name),
+  );
+  const selectList = COLUMN_NAMES.map((c) =>
+    presentColumns.has(c) ? c : "NULL",
+  ).join(", ");
+  raw.exec(/*sql*/ `
+    INSERT OR IGNORE INTO ${LOGS_DB_SCHEMA}.llm_request_logs (${COLUMNS})
+    SELECT ${selectList} FROM main.llm_request_logs
+  `);
+}
+
+/**
+ * Keep `llm_request_logs` housed in the attached append-only `logs` database
+ * (`assistant-logs.db`) rather than the main DB. Keeping this heavy table — and
+ * the request/response payloads it stores — in its own file stops it from
+ * bloating the main DB and its WAL, and lets the two files VACUUM and
+ * checkpoint independently. Once it lives only in `logs`, the unqualified name
+ * used by the Drizzle store resolves to the attached copy, so query code is
+ * unchanged.
+ *
+ * This step is idempotent and runs on every startup (it is not checkpoint-
+ * gated). It must, because the earlier `createWatchersAndLogsTables` migration
+ * recreates an empty `main.llm_request_logs` on every boot via
+ * `CREATE TABLE IF NOT EXISTS`; this step re-relocates and drops that shadow so
+ * the unqualified name keeps resolving to `logs`.
+ *
+ * Ordering within the step matters:
+ *   1. Create the table in `logs` (safe whether or not `main` has it).
+ *   2. If `main` still has the table, copy its rows over (`INSERT OR IGNORE` on
+ *      the id PK, so a re-run is a no-op) and drop it.
+ *   3. Create the indexes — only now is `main` guaranteed not to shadow the
+ *      table, so the unqualified reference resolves to `logs`.
+ */
+export function migrateMoveLlmRequestLogsToLogsDb(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+
+  raw.exec(CREATE_TABLE(LOGS_DB_SCHEMA));
+
+  if (tableExists(raw, "main")) {
+    copyRowsFromMain(raw);
+    raw.exec(`DROP TABLE main.llm_request_logs`);
+  }
+
+  createIndexes(raw, LOGS_DB_SCHEMA);
+}

package/src/memory/migrations/__tests__/297-move-llm-request-logs.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Tests for migration 297 — keeping `llm_request_logs` in the attached
+ * `logs` database.
+ *
+ * Covers:
+ *   1. End state after a full initializeDb(): the table lives in `logs`, not
+ *      `main`, and the Drizzle store round-trips against it.
+ *   2. The relocation itself: rows in a `main.llm_request_logs` are copied into
+ *      `logs` and the main-DB copy is dropped, with indexes built in `logs`.
+ *   3. A legacy base-only `main` table (predating the newer columns) is copied
+ *      without error, NULL-filling the absent columns.
+ *
+ * The step is idempotent and not checkpoint-gated, so each test can drive it
+ * directly without clearing any checkpoint.
+ */
+import { describe, expect, test } from "bun:test";
+
+const { getDb, getSqlite, LOGS_DB_SCHEMA } =
+  await import("../../db-connection.js");
+const { initializeDb } = await import("../../db-init.js");
+const { migrateMoveLlmRequestLogsToLogsDb } =
+  await import("../297-move-llm-request-logs-to-logs-db.js");
+const { recordRequestLog, getRequestLogById } =
+  await import("../../llm-request-log-store.js");
+
+initializeDb();
+
+function tableSchemas(name: string): string[] {
+  return getSqlite()
+    .query<{ schema: string }, []>(
+      `SELECT 'main' AS schema FROM main.sqlite_master WHERE type='table' AND name='${name}'
+       UNION ALL
+       SELECT '${LOGS_DB_SCHEMA}' FROM ${LOGS_DB_SCHEMA}.sqlite_master WHERE type='table' AND name='${name}'`,
+    )
+    .all()
+    .map((r) => r.schema);
+}
+
+describe("migration 297 — llm_request_logs lives in the logs database", () => {
+  test("after init, the table is in logs and not in main", () => {
+    expect(tableSchemas("llm_request_logs")).toEqual([LOGS_DB_SCHEMA]);
+  });
+
+  test("the store round-trips against the relocated table", () => {
+    const id = recordRequestLog(
+      "conv-297",
+      JSON.stringify({ req: 1 }),
+      JSON.stringify({ res: 1 }),
+      "msg-297",
+      "anthropic",
+      "mainAgent",
+    );
+    const row = getRequestLogById(id);
+    expect(row?.conversationId).toBe("conv-297");
+    expect(row?.messageId).toBe("msg-297");
+    expect(row?.provider).toBe("anthropic");
+    expect(row?.callSite).toBe("mainAgent");
+
+    // The written row physically lives in the logs database.
+    const inLogs = getSqlite()
+      .query<
+        { c: number },
+        [string]
+      >(`SELECT COUNT(*) AS c FROM ${LOGS_DB_SCHEMA}.llm_request_logs WHERE id = ?`)
+      .get(id);
+    expect(inLogs?.c).toBe(1);
+  });
+
+  test("relocates rows from a main-DB table and drops it", () => {
+    const sqlite = getSqlite();
+
+    // Simulate the shadow that createWatchersAndLogsTables recreates each boot:
+    // a main-DB table with a row, alongside the logs copy.
+    sqlite.exec(`DROP TABLE IF EXISTS ${LOGS_DB_SCHEMA}.llm_request_logs`);
+    sqlite.exec(`
+      CREATE TABLE main.llm_request_logs (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL,
+        message_id TEXT,
+        provider TEXT,
+        request_payload TEXT NOT NULL,
+        response_payload TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        agent_loop_exit_reason TEXT,
+        call_site TEXT
+      )
+    `);
+    sqlite.exec(
+      `INSERT INTO main.llm_request_logs (id, conversation_id, request_payload, response_payload, created_at, provider) VALUES ('legacy-1', 'conv-legacy', '{}', '{}', 123, 'openai')`,
+    );
+
+    migrateMoveLlmRequestLogsToLogsDb(getDb());
+
+    // Main copy gone, logs copy has the row.
+    expect(tableSchemas("llm_request_logs")).toEqual([LOGS_DB_SCHEMA]);
+    const moved = sqlite
+      .query<
+        { conversation_id: string; provider: string },
+        []
+      >(`SELECT conversation_id, provider FROM ${LOGS_DB_SCHEMA}.llm_request_logs WHERE id = 'legacy-1'`)
+      .get();
+    expect(moved?.conversation_id).toBe("conv-legacy");
+    expect(moved?.provider).toBe("openai");
+
+    // Indexes were created in the logs database.
+    const indexes = sqlite
+      .query<{ name: string }, []>(
+        `SELECT name FROM ${LOGS_DB_SCHEMA}.sqlite_master WHERE type='index' AND tbl_name='llm_request_logs'`,
+      )
+      .all()
+      .map((r) => r.name);
+    expect(indexes).toContain("idx_llm_request_logs_message_id");
+    expect(indexes).toContain("idx_llm_request_logs_created_at");
+    expect(indexes).toContain("idx_llm_request_logs_conv_created");
+  });
+
+  test("copies a legacy base-only table, NULL-filling newer columns", () => {
+    const sqlite = getSqlite();
+
+    // A workspace upgrading from a build that predates the
+    // message_id/provider/agent_loop_exit_reason/call_site columns: the main
+    // table has only the original base columns.
+    sqlite.exec(`DROP TABLE IF EXISTS ${LOGS_DB_SCHEMA}.llm_request_logs`);
+    sqlite.exec(`
+      CREATE TABLE main.llm_request_logs (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL,
+        request_payload TEXT NOT NULL,
+        response_payload TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    sqlite.exec(
+      `INSERT INTO main.llm_request_logs (id, conversation_id, request_payload, response_payload, created_at) VALUES ('base-1', 'conv-base', '{}', '{}', 7)`,
+    );
+
+    // Must not throw on the absent columns.
+    migrateMoveLlmRequestLogsToLogsDb(getDb());
+
+    expect(tableSchemas("llm_request_logs")).toEqual([LOGS_DB_SCHEMA]);
+    const moved = sqlite
+      .query<
+        {
+          conversation_id: string;
+          message_id: string | null;
+          provider: string | null;
+          call_site: string | null;
+        },
+        []
+      >(
+        `SELECT conversation_id, message_id, provider, call_site FROM ${LOGS_DB_SCHEMA}.llm_request_logs WHERE id = 'base-1'`,
+      )
+      .get();
+    expect(moved?.conversation_id).toBe("conv-base");
+    expect(moved?.message_id).toBeNull();
+    expect(moved?.provider).toBeNull();
+    expect(moved?.call_site).toBeNull();
+  });
+});

package/src/memory/migrations/index.ts

@@ -288,6 +288,7 @@ export { migrateWorkflowJournalLeafTokens } from "./293-workflow-journal-leaf-to
 export { migrateDropExternalUserId } from "./294-drop-external-user-id.js";
 export { dropApprovalPromptTsTrackerTable } from "./295-drop-approval-prompt-ts-tracker.js";
 export { migrateRewriteBalancedEconomyProfilePins } from "./296-rewrite-balanced-economy-profile-pins.js";
+export { migrateMoveLlmRequestLogsToLogsDb } from "./297-move-llm-request-logs-to-logs-db.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/plugin-api/index.ts

@@ -132,6 +132,13 @@ export type {
 export { assistantEventHub } from "../runtime/assistant-event-hub.js";
 export { getSecureKeyAsync } from "../security/secure-keys.js";
 export { getModelProfiles } from "./model-profiles.js";
+// Check whether a profile's resolved model can process image input. Resolves
+// the effective (provider, model) by merging over the workspace default and
+// inferring the provider for model-only profiles, then looks up the model
+// catalog's `supportsVision` flag. Handles mix profiles (true if any arm
+// supports vision). Fail-open for unknown models. Pair with
+// `getModelProfiles()` to inspect the active or candidate profiles.
+export { doesSupportVision } from "./vision-support.js";
 // Resolve a provider for a call site (optionally overriding the profile) so a
 // plugin can run inference through the workspace's configured profiles and
 // credentials — managed-proxy or BYOK — without supplying its own API key.

package/src/plugin-api/vision-support.ts

@@ -0,0 +1,75 @@
+/**
+ * Vision-support resolution for plugin consumption.
+ *
+ * A plugin that gates image processing on vision capability (e.g. an
+ * image-to-text fallback for text-only models) calls {@link doesSupportVision}
+ * instead of hardcoding model names. The function resolves the effective
+ * (provider, model) for a profile — merging with `llm.default` to fill gaps,
+ * inferring the provider for model-only profiles via the catalog — and then
+ * looks up `supportsVision` in the model catalog.
+ */
+
+import { getConfig } from "../config/loader.js";
+import {
+  getCatalogProviderForModel,
+  PROVIDER_CATALOG,
+} from "../providers/model-catalog.js";
+import type { ModelProfileInfo } from "./types.js";
+
+/**
+ * Whether a profile's resolved model can process image input.
+ *
+ * Resolution mirrors the host's call-site resolver:
+ * - The profile's `(provider, model)` fields are merged over `llm.default` so
+ *   a profile that only sets `model` (or only `provider`) inherits the other
+ *   from the workspace default.
+ * - When `provider` is still missing but `model` is a known catalog model,
+ *   the provider is inferred via `getCatalogProviderForModel` (same logic as
+ *   the resolver's `withImpliedProviderForKnownModel`).
+ * - For a mix profile, returns `true` if any constituent arm supports vision
+ *   (the mix can route to it) and `false` only if every arm is text-only.
+ * - Unknown `(provider, model)` pairs default to `true` (fail-open), matching
+ *   the config GET route's `enrichProfilesWithVisionFlag`.
+ */
+export function doesSupportVision(profile: ModelProfileInfo): boolean {
+  const { llm } = getConfig();
+  const entry = llm.profiles[profile.key];
+  if (entry == null) return true;
+
+  // Mix: fail-open if any arm supports vision.
+  if (entry.mix != null) {
+    return entry.mix.some((arm) => {
+      const armEntry = llm.profiles[arm.profile];
+      if (armEntry == null) return true;
+      return resolveEntrySupportsVision(armEntry, llm);
+    });
+  }
+
+  return resolveEntrySupportsVision(entry, llm);
+}
+
+/**
+ * Resolve whether a concrete (non-mix) profile entry supports vision by
+ * merging its fields over `llm.default` and inferring the provider when
+ * only the model is set.
+ */
+function resolveEntrySupportsVision(
+  entry: { provider?: string; model?: string },
+  llm: { default?: { provider?: string; model?: string } },
+): boolean {
+  const provider = entry.provider ?? llm.default?.provider;
+  const model = entry.model ?? llm.default?.model;
+
+  // Infer provider from model when missing (mirrors the resolver's
+  // withImpliedProviderForKnownModel).
+  const effectiveProvider =
+    provider ?? (typeof model === "string" ? getCatalogProviderForModel(model) : undefined);
+
+  if (typeof effectiveProvider !== "string" || typeof model !== "string") {
+    return true; // fail-open
+  }
+
+  const catalogProvider = PROVIDER_CATALOG.find((p) => p.id === effectiveProvider);
+  const catalogModel = catalogProvider?.models.find((m) => m.id === model);
+  return catalogModel?.supportsVision ?? true;
+}

package/src/prompts/system-prompt.ts

@@ -274,7 +274,7 @@ export function maybeReseedBootstrap(templateFileName: string): boolean {
  * Marking happens here — at the single point where the bootstrap selection is
  * known — so it lands BEFORE the agent loop resolves tools and BEFORE the model
  * can call the emit tool on the first activation-rail turn. (`resolveTools`
- * runs before `resolveSystemPrompt` in the loop, so the system-prompt build is
+ * runs before the system-prompt build in the loop, so the system-prompt build is
  * too late to be the *only* marking site.) The marker write is best-effort and
  * idempotent (`markActivationSession` swallows errors and dedups on the PK), so
  * calling this from both `setOnboardingContext` and `buildSystemPrompt` is safe.

package/src/runtime/__tests__/agent-wake.test.ts

@@ -52,8 +52,8 @@ interface WakeConversationProbe {
     allowedTools?: string[];
     /**
      * `conversation.wakePersonaOverride` as observed at run start — the
-     * field the conversation's resolveSystemPrompt callback reads when
-     * building the wake's system prompt.
+     * field `buildCurrentSystemPrompt` reads when building the wake's
+     * system prompt before `agentLoop.run()`.
      */
     personaOverride?: unknown;
     order: number;
@@ -503,6 +503,8 @@ function makeWakeConversation(options: {
     getTurnChannelContext: () => null,
     getTurnInterfaceContext: () => null,
     trustContext: undefined,
+    buildCurrentSystemPrompt: () => "mock-system-prompt",
+    modelOverride: undefined,
     ...(drainQueue ? { drainQueue } : {}),
   };
 
@@ -693,8 +695,8 @@ describe("wakeAgentForOpportunity", () => {
     );
 
     expect(result.invoked).toBe(true);
-    // The override was live on the conversation when the loop ran — the
-    // resolveSystemPrompt callback reads this field at prompt-build time.
+    // The override was live on the conversation when the loop ran —
+    // `buildCurrentSystemPrompt` reads this field before `agentLoop.run()`.
     expect(conversation.runCalls[0]!.personaOverride).toEqual(override);
     // Applied exactly once and cleared before the wake released the
     // conversation, so a queued user turn can't build under it.