@vellumai/assistant 0.11.7-dev.202609012016.14eabff → 0.11.7-dev.202609012114.f9ebd01

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.7-dev.202609012016.14eabff",
+  "version": "0.11.7-dev.202609012114.f9ebd01",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/skill-load-tool.test.ts

@@ -127,6 +127,14 @@ describe("skill_load tool", () => {
     );
   });
 
+  test("description routes Claude Code and Codex mentions to acp", () => {
+    // skill_load is always in the tool list. Naming the agents here is what
+    // makes a mention load ACP instead of treating Claude Code as a competitor.
+    expect(skillLoadTool.description).toContain("Claude Code");
+    expect(skillLoadTool.description).toContain("Codex");
+    expect(skillLoadTool.description).toContain('skill: "acp"');
+  });
+
   test("routes recurring monitoring and reminders to the schedule skill", () => {
     const description = skillLoadTool.description;
     expect(description).toContain('skill: "schedule"');
@@ -399,6 +407,19 @@ describe("skill_load tool", () => {
     expect(result.content).toContain('<loaded_skill id="app-builder"');
   });
 
+  test("bundled acp skill offers a one-time connect when the user names an agent", async () => {
+    const result = await executeSkillLoad({ skill: "acp" });
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("Skill: ACP");
+    expect(result.content).toContain(
+      "When the user names Claude Code or Codex",
+    );
+    expect(result.content).toContain("offer once, in one short sentence");
+    expect(result.content).toContain("Do not spawn unless they accept");
+    expect(result.content).toContain('<loaded_skill id="acp"');
+  });
+
   test("bundled phone-calls loads when setup includes are unavailable", async () => {
     const result = await executeSkillLoad({ skill: "phone-calls" });
 

package/src/__tests__/skills.test.ts

@@ -898,12 +898,20 @@ describe("always-candidate frontmatter parsing", () => {
     // A "configure Claude Code" or "let's do the auth" turn only reaches this
     // skill if the card actually says it covers setup and authentication;
     // delegation-only wording routes those turns to a terminal skill instead.
+    // "names" keeps a mention ("claude code will do it") from falling through
+    // as a competitor reference.
     const { buildSkillContent } =
       await import("../plugins/defaults/memory/substrate/skill-content.js");
     const acp = loadSkillCatalog().find((skill) => skill.id === "acp");
     const card = buildSkillContent(acp!).toLowerCase();
 
-    for (const term of ["set up", "install", "authenticate", "connect"]) {
+    for (const term of [
+      "names",
+      "set up",
+      "install",
+      "authenticate",
+      "connect",
+    ]) {
       expect(card).toContain(term);
     }
   });

package/src/cli/commands/db/__tests__/status.test.ts

@@ -169,6 +169,8 @@ describe("assistant db status — happy path", () => {
     // (memory_checkpoints has 3 rows.)
     expect(stdout).toContain("Largest tables");
     expect(stdout.indexOf("messages")).toBeLessThan(stdout.indexOf("small"));
+    expect(stdout).toContain("Schema contract");
+    expect(stdout).toContain("missing");
   });
 
   test("reports the latest 'completed' migration, ignoring 'started'", async () => {
@@ -212,6 +214,26 @@ describe("assistant db status — happy path", () => {
     expect(parsed.db.largest.length).toBeGreaterThan(0);
     // Either 'bytes' (if dbstat is available) or 'rows' fallback.
     expect(["bytes", "rows"]).toContain(parsed.db.sizingMethod);
+    expect(Array.isArray(parsed.schemaContract.missingTables)).toBe(true);
+    expect(Array.isArray(parsed.schemaContract.missingColumns)).toBe(true);
+    // The seed is a 3-table stub, so the drizzle catalog reports misses.
+    expect(parsed.schemaContract.missingTables.length).toBeGreaterThan(0);
+  });
+
+  test("reports conversations.fork_strategy when the table exists without that column", async () => {
+    seedDb();
+    const db = new Database(dbPath);
+    try {
+      db.exec(`CREATE TABLE conversations (id TEXT PRIMARY KEY, title TEXT)`);
+    } finally {
+      db.close();
+    }
+
+    const { stdout, exitCode } = await runStatus(["status"]);
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("Schema contract");
+    expect(stdout).toContain("conversations.fork_strategy");
   });
 });
 

package/src/cli/commands/db/index.help.ts

@@ -12,7 +12,7 @@ export const dbHelp: CliCommandHelp = {
     {
       name: "status",
       description:
-        "Show database path, size, key pragmas, and the 5 largest tables",
+        "Show database path, size, key pragmas, largest tables, and drizzle schema misses",
     },
     {
       name: "repair",

package/src/cli/commands/db/status.ts

@@ -16,6 +16,8 @@
  *     callers will see the row-count path today)
  *   - latest applied workspace migration (proxy for schema version, read
  *     from the `memory_checkpoints` rows the migration runner writes)
+ *   - drizzle-vs-SQLite schema contract (columns the current binary
+ *     selects that no live database file has)
  *   - file mtime + age, for "is this DB live?" triage at a glance
  *
  * If the DB file is missing, exits with code 1 after a loud error. If the file
@@ -28,6 +30,7 @@ import { Database } from "bun:sqlite";
 
 import type { Command } from "commander";
 
+import type { SchemaContractReport } from "../../../persistence/schema-contract.js";
 import { getLogsDbPath } from "../../../util/logs-db-path.js";
 import { getMemoryDbPath } from "../../../util/memory-db-path.js";
 import { getDbPath } from "../../../util/platform.js";
@@ -110,6 +113,12 @@ interface StatusReport {
    */
   telemetryFile?: FileFacts;
   telemetryDb?: DbFacts | null;
+  /**
+   * Drizzle source catalog vs the union of columns in every live SQLite
+   * file (main, logs, memory, telemetry). Extra SQLite-only columns are
+   * ignored. Omitted when the main file could not be opened.
+   */
+  schemaContract?: SchemaContractReport;
 }
 
 interface MigrationSummary {
@@ -260,6 +269,83 @@ function readDbFacts(path: string): DbFacts {
   }
 }
 
+/** Quote a SQLite identifier that came from sqlite_master (never user input). */
+function quoteIdent(name: string): string {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+
+/**
+ * Read table → column names from one SQLite file. Skips `sqlite_*`
+ * internals and tables whose `PRAGMA table_info` fails.
+ */
+function readSqliteColumns(path: string): Map<string, Set<string>> {
+  const db = new Database(path, { readonly: true });
+  try {
+    const tables = db
+      .query<{ name: string }, []>(
+        `SELECT name FROM sqlite_master
+         WHERE type='table' AND name NOT LIKE 'sqlite_%'`,
+      )
+      .all();
+    const out = new Map<string, Set<string>>();
+    for (const table of tables) {
+      try {
+        const columns = db
+          .query<{ name: string }, []>(
+            `PRAGMA table_info(${quoteIdent(table.name)})`,
+          )
+          .all();
+        out.set(table.name, new Set(columns.map((column) => column.name)));
+      } catch {
+        // Virtual or unreadable table. Skip so one failure does not hide
+        // the rest of the contract.
+      }
+    }
+    return out;
+  } finally {
+    db.close();
+  }
+}
+
+/** Union column sets from several files. Same table name keeps every column. */
+function mergeSqliteColumns(
+  files: Array<Map<string, Set<string>>>,
+): Map<string, Set<string>> {
+  const merged = new Map<string, Set<string>>();
+  for (const file of files) {
+    for (const [table, columns] of file) {
+      const existing = merged.get(table);
+      if (!existing) {
+        merged.set(table, new Set(columns));
+        continue;
+      }
+      for (const column of columns) {
+        existing.add(column);
+      }
+    }
+  }
+  return merged;
+}
+
+async function readSchemaContract(
+  paths: string[],
+): Promise<SchemaContractReport> {
+  // Lazy so the drizzle catalog stays out of the CLI's static graph
+  // (cli/no-daemon-internals).
+  const { diffDrizzleSchemaContract } =
+    await import("../../../persistence/schema-contract.js");
+  const live: Array<Map<string, Set<string>>> = [];
+  for (const path of paths) {
+    try {
+      live.push(readSqliteColumns(path));
+    } catch {
+      // File vanished or is unreadable. The main-file open already
+      // succeeded; skip this sidecar rather than fail the report.
+    }
+  }
+  return diffDrizzleSchemaContract(mergeSqliteColumns(live));
+}
+
 // ---------------------------------------------------------------------------
 // Rendering
 // ---------------------------------------------------------------------------
@@ -350,6 +436,7 @@ function renderHuman(report: StatusReport): string {
   // Cross-database migration summary — the checkpoint ledger lives only in
   // the main DB, so this is a single block at the end covering all three.
   out += renderSummary(report.migration);
+  out += renderSchemaContract(report.schemaContract);
 
   return out;
 }
@@ -469,6 +556,72 @@ function renderSummary(migration: MigrationSummary | undefined): string {
   return out;
 }
 
+const HUMAN_COLUMN_MISS_LIMIT = 40;
+const HUMAN_TABLE_MISS_LIMIT = 15;
+
+function schemaContractIsClean(report: SchemaContractReport): boolean {
+  return (
+    report.missingTables.length === 0 && report.missingColumns.length === 0
+  );
+}
+
+function renderMissList(labels: string[], limit: number): string {
+  let out = "";
+  const shown = labels.slice(0, limit);
+  for (const label of shown) {
+    out += `  ${label}\n`;
+  }
+  if (labels.length > limit) {
+    out += `  … and ${formatCount(labels.length - limit)} more\n`;
+  }
+  return out;
+}
+
+function renderSchemaContract(
+  contract: SchemaContractReport | undefined,
+): string {
+  if (!contract) {
+    return "";
+  }
+
+  let out = "\nSchema contract (drizzle vs SQLite)\n";
+  if (schemaContractIsClean(contract)) {
+    out += row("Status", "ok");
+    return out;
+  }
+
+  const parts: string[] = [];
+  if (contract.missingColumns.length > 0) {
+    parts.push(
+      `${formatCount(contract.missingColumns.length)} missing column${
+        contract.missingColumns.length === 1 ? "" : "s"
+      }`,
+    );
+  }
+  if (contract.missingTables.length > 0) {
+    parts.push(
+      `${formatCount(contract.missingTables.length)} missing table${
+        contract.missingTables.length === 1 ? "" : "s"
+      }`,
+    );
+  }
+  out += row("Status", red(parts.join(", ")));
+
+  if (contract.missingColumns.length > 0) {
+    out += "Missing columns\n";
+    out += renderMissList(
+      contract.missingColumns.map((miss) => `${miss.table}.${miss.column}`),
+      HUMAN_COLUMN_MISS_LIMIT,
+    );
+  }
+  if (contract.missingTables.length > 0) {
+    out += "Missing tables\n";
+    out += renderMissList(contract.missingTables, HUMAN_TABLE_MISS_LIMIT);
+  }
+
+  return out;
+}
+
 function renderMissing(path: string): string {
   return (
     `${red("ERROR")}  Database not found at ${path}\n\n` +
@@ -487,7 +640,7 @@ function renderMissing(path: string): string {
 // ---------------------------------------------------------------------------
 
 export function registerDbStatus(parent: Command): void {
-  subcommand(parent, "status").action(function (this: Command) {
+  subcommand(parent, "status").action(async function (this: Command) {
     const file = readFileFacts(getDbPath());
 
     if (!file.exists) {
@@ -561,10 +714,28 @@ export function registerDbStatus(parent: Command): void {
       migration = null;
     }
 
+    const schemaPaths = [file.path];
+    if (logsFile.exists) {
+      schemaPaths.push(logsFile.path);
+    }
+    if (memoryFile.exists) {
+      schemaPaths.push(memoryFile.path);
+    }
+    if (telemetryFile.exists) {
+      schemaPaths.push(telemetryFile.path);
+    }
+    let schemaContract: SchemaContractReport | undefined;
+    try {
+      schemaContract = await readSchemaContract(schemaPaths);
+    } catch {
+      schemaContract = undefined;
+    }
+
     const report: StatusReport = {
       file,
       db,
       migration: migration ?? undefined,
+      schemaContract,
       logsFile,
       logsDb,
       memoryFile,

package/src/config/bundled-skills/acp/SKILL.md

@@ -8,12 +8,11 @@ metadata:
     display-name: "ACP"
     category: "development"
     activation-hints:
-      - "User wants to set up, install, configure, authenticate, or connect Claude Code or Codex"
-      - "User asks to use Claude Code or Codex, or delegate a coding task to an ACP agent"
+      - "User names Claude Code or Codex, or wants to set up, install, configure, authenticate, connect, use, or delegate work to them"
       - "User wants an agent to work autonomously and report back later"
       - "User mentions ACP, claude-agent-acp, or codex-acp"
     avoid-when:
-      - "The task is small enough to do inline"
+      - "The task is small enough to do inline and the user did not name Claude Code or Codex"
 ---
 
 ACP agent orchestration - spawn external coding agents (Claude Code, Codex) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.
@@ -24,6 +23,14 @@ Use `acp_spawn` to delegate a coding task to an external agent. The agent runs a
 
 Users can refer to agents by natural names: "claude code", "codex cli", and "openai codex" all resolve to the canonical `claude` and `codex` ids (unless the user's config defines an agent literally keyed by that name, which always wins).
 
+## When the user names Claude Code or Codex
+
+If they name Claude Code or Codex without asking you to run it here (for example they say that tool will do the work), offer once, in one short sentence, that you can connect and run it in this conversation. Then continue with whatever they were doing.
+
+- Do not spawn unless they accept.
+- Skip if you already offered this conversation, they declined, or they are already connected.
+- This is not the missing-token card path. Do not invent setup steps.
+
 ## First-time setup
 
 ACP is always available - default profiles for `claude` and `codex` ship out-of-box, so no config edit is needed to start. First-time setup is just making the adapter binary available, then spawning:

package/src/persistence/schema-contract.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  diffDrizzleSchemaContract,
+  listDrizzleTables,
+  schemaContractIsClean,
+} from "./schema-contract.js";
+
+describe("listDrizzleTables", () => {
+  test("includes conversations.fork_strategy from the source catalog", () => {
+    const conversations = listDrizzleTables().find(
+      (table) => table.name === "conversations",
+    );
+    expect(conversations).toBeDefined();
+    expect(conversations!.columns).toContain("fork_strategy");
+    expect(conversations!.columns).toContain("id");
+  });
+
+  test("de-duplicates aliased table exports", () => {
+    const names = listDrizzleTables().map((table) => table.name);
+    expect(names.filter((name) => name === "cron_jobs")).toEqual(["cron_jobs"]);
+  });
+});
+
+describe("diffDrizzleSchemaContract", () => {
+  test("reports a missing column on a table that exists", () => {
+    const conversations = listDrizzleTables().find(
+      (table) => table.name === "conversations",
+    );
+    expect(conversations).toBeDefined();
+    const liveColumns = new Set(
+      conversations!.columns.filter((column) => column !== "fork_strategy"),
+    );
+    const live = new Map<string, Set<string>>(
+      listDrizzleTables().map((table) => [
+        table.name,
+        table.name === "conversations" ? liveColumns : new Set(table.columns),
+      ]),
+    );
+
+    const report = diffDrizzleSchemaContract(live);
+    expect(schemaContractIsClean(report)).toBe(false);
+    expect(report.missingTables).toEqual([]);
+    expect(report.missingColumns).toEqual([
+      { table: "conversations", column: "fork_strategy" },
+    ]);
+  });
+
+  test("ignores extra SQLite columns that Drizzle does not own", () => {
+    const live = new Map<string, Set<string>>(
+      listDrizzleTables().map((table) => {
+        const columns = new Set(table.columns);
+        if (table.name === "conversations") {
+          columns.add("group_id");
+        }
+        return [table.name, columns];
+      }),
+    );
+
+    const report = diffDrizzleSchemaContract(live);
+    expect(schemaContractIsClean(report)).toBe(true);
+    expect(report.missingColumns).toEqual([]);
+  });
+
+  test("reports a drizzle table that is absent from every live file", () => {
+    const live = new Map<string, Set<string>>(
+      listDrizzleTables()
+        .filter((table) => table.name !== "conversations")
+        .map((table) => [table.name, new Set(table.columns)]),
+    );
+
+    const report = diffDrizzleSchemaContract(live);
+    expect(report.missingTables).toEqual(["conversations"]);
+    expect(
+      report.missingColumns.some((miss) => miss.table === "conversations"),
+    ).toBe(false);
+  });
+});

package/src/persistence/schema-contract.ts

@@ -0,0 +1,96 @@
+/**
+ * Compare the Drizzle table/column catalog in source to a live SQLite schema.
+ *
+ * Used by `assistant db status` to surface a binary that selects a
+ * column the live database never received. Extra SQLite tables or
+ * columns are ignored. Those are often raw-SQL fields (`group_id`) that
+ * Drizzle does not own.
+ *
+ * The catalog is the union of every `sqliteTable` exported from
+ * `schema/index.ts`. Tables live across the main, logs, memory, and
+ * telemetry files; callers merge those files before calling
+ * {@link diffDrizzleSchemaContract}.
+ */
+
+import { getTableColumns, getTableName, is, Table } from "drizzle-orm";
+
+import * as schema from "./schema/index.js";
+
+export interface SchemaColumnMiss {
+  table: string;
+  column: string;
+}
+
+export interface SchemaContractReport {
+  /** Drizzle tables with no matching SQLite table in the live files. */
+  missingTables: string[];
+  /** Drizzle columns whose table exists in SQLite but the column does not. */
+  missingColumns: SchemaColumnMiss[];
+}
+
+export interface DrizzleTableColumns {
+  name: string;
+  columns: string[];
+}
+
+/** Every Drizzle table name and its SQL column names, de-duplicated. */
+export function listDrizzleTables(): DrizzleTableColumns[] {
+  const byName = new Map<string, string[]>();
+  for (const value of Object.values(schema)) {
+    if (!is(value, Table)) {
+      continue;
+    }
+    const name = getTableName(value);
+    if (!name) {
+      continue;
+    }
+    const columns = Object.values(getTableColumns(value)).map(
+      (column) => column.name,
+    );
+    byName.set(name, columns);
+  }
+  return [...byName.entries()]
+    .map(([name, columns]) => ({ name, columns: [...columns].sort() }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Diff Drizzle's catalog against a merged live schema (table name → columns).
+ * Tables and columns present only in SQLite are not reported.
+ */
+export function diffDrizzleSchemaContract(
+  liveColumnsByTable: Map<string, ReadonlySet<string>>,
+): SchemaContractReport {
+  const missingTables: string[] = [];
+  const missingColumns: SchemaColumnMiss[] = [];
+
+  for (const table of listDrizzleTables()) {
+    const live = liveColumnsByTable.get(table.name);
+    if (!live) {
+      missingTables.push(table.name);
+      continue;
+    }
+    for (const column of table.columns) {
+      if (!live.has(column)) {
+        missingColumns.push({ table: table.name, column });
+      }
+    }
+  }
+
+  missingTables.sort();
+  missingColumns.sort((a, b) => {
+    const tableCmp = a.table.localeCompare(b.table);
+    if (tableCmp !== 0) {
+      return tableCmp;
+    }
+    return a.column.localeCompare(b.column);
+  });
+
+  return { missingTables, missingColumns };
+}
+
+export function schemaContractIsClean(report: SchemaContractReport): boolean {
+  return (
+    report.missingTables.length === 0 && report.missingColumns.length === 0
+  );
+}

package/src/tools/skills/load.ts

@@ -158,7 +158,7 @@ export const skillLoadTool = {
   name: "skill_load",
 
   description:
-    'Load full instructions for a skill. Works for both bundled skills (listed in the catalog) and custom workspace skills. Bundled/first-party skills (like `app-builder`) are already installed: loading only activates their instructions for the current conversation, since skills unload between turns. Treat "load" as activation, not installation, and don\'t tell users a bundled skill needs installing. Loading can still fail (e.g. a feature-gated skill returns "currently unavailable", or the load errors). If it does, relay that specific error rather than claiming the skill is not installed or offering to install it. For app, website, dashboard, game, calculator, tracker, visualization, or interactive tool requests, load `app-builder` with `skill: "app-builder"`. For recurring monitoring of a page, dashboard, or status (check it later and notify), or for reminders and timed checks, load `schedule` with `skill: "schedule"`.',
+    'Load full instructions for a skill. Works for both bundled skills (listed in the catalog) and custom workspace skills. Bundled/first-party skills (like `app-builder`) are already installed: loading only activates their instructions for the current conversation, since skills unload between turns. Treat "load" as activation, not installation, and don\'t tell users a bundled skill needs installing. Loading can still fail (e.g. a feature-gated skill returns "currently unavailable", or the load errors). If it does, relay that specific error rather than claiming the skill is not installed or offering to install it. For app, website, dashboard, game, calculator, tracker, visualization, or interactive tool requests, load `app-builder` with `skill: "app-builder"`. For recurring monitoring of a page, dashboard, or status (check it later and notify), or for reminders and timed checks, load `schedule` with `skill: "schedule"`. When the user names Claude Code or Codex (including as a tool they will use elsewhere), load `acp` with `skill: "acp"`.',
 
   category: "skills",