@vellumai/assistant 0.6.4 → 0.6.6

package/src/workspace/migrations/045-release-notes-meet-avatar.ts

@@ -0,0 +1,130 @@
+import {
+  appendFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../../util/logger.js";
+import type { WorkspaceMigration } from "./types.js";
+
+const log = getLogger("workspace-migration-045-release-notes-meet-avatar");
+
+const MIGRATION_ID = "045-release-notes-meet-avatar";
+const MARKER = `<!-- release-note-id:${MIGRATION_ID} -->`;
+
+const RELEASE_NOTE = `${MARKER}
+## Meet video avatar with lip-sync (v1)
+
+I can now appear as a video avatar during Google Meet calls, with lip-sync
+driven by my TTS output. v1 uses the TalkingHead.js renderer running inside
+the meet-bot container; hosted renderers (Simli, HeyGen) and GPU sidecars
+(SadTalker, MuseTalk) are additive follow-ups and are not yet available.
+
+### One-time setup (required before enabling)
+
+The repo currently ships a placeholder \`default-avatar.glb\` at
+\`skills/meet-join/meet-controller-ext/avatar/default-avatar.glb\` that is
+**0 bytes** — the avatar will fail fast at enable time until you replace
+it with a real Ready Player Me model. Export a \`.glb\` from Ready Player Me
+and drop it at that path before turning the feature on.
+
+### Host setup (Linux only)
+
+The avatar publishes frames to a virtual camera via \`v4l2loopback\`. On
+the Linux host that runs the assistant:
+
+\`\`\`bash
+sudo apt-get install v4l2loopback-dkms
+sudo modprobe v4l2loopback video_nr=10 card_label="VellumAvatar" exclusive_caps=1
+\`\`\`
+
+macOS bare-metal is **not supported** for the avatar in v1 — the virtual
+camera stack is Linux-specific.
+
+### Enabling the avatar
+
+In your Meet service config, set:
+
+\`\`\`json
+{
+  "services": {
+    "meet": {
+      "avatar": { "enabled": true, "renderer": "talking-head" }
+    }
+  }
+}
+\`\`\`
+
+**Docker mode:** additionally export \`VELLUM_MEET_AVATAR=1\` in the CLI
+environment **before** spawning the instance, so the CLI bind-mounts
+\`/dev/video10\` into the assistant container. Without this, the inner
+\`dockerd\` has no device to pass through to the meet-bot.
+
+### New tools
+
+Two new assistant tools are available (feature-flag gated on \`meet\`):
+
+- \`meet_enable_avatar\` — turn the avatar on for a meeting.
+- \`meet_disable_avatar\` — turn the avatar off for a meeting.
+
+Ask me to enable or disable my avatar in a Meet and I'll call these for you.
+`;
+
+/**
+ * Release-notes migration for the Meet video avatar feature (Phase 4).
+ *
+ * Per AGENTS.md § Release Update Hygiene, user-facing changes ship notes via a
+ * workspace migration that appends to `<workspace>/UPDATES.md`. The in-file
+ * HTML marker guards against duplicate appends if the runner re-executes this
+ * migration after a mid-run crash (between `appendFileSync` and the runner's
+ * checkpoint promotion to `applied`), which the runner's own checkpoint state
+ * does not cover on its own.
+ */
+export const releaseNotesMeetAvatarMigration: WorkspaceMigration = {
+  id: MIGRATION_ID,
+  description:
+    "Append release notes for Meet video avatar with lip-sync to UPDATES.md",
+
+  run(workspaceDir: string): void {
+    const updatesPath = join(workspaceDir, "UPDATES.md");
+
+    try {
+      if (existsSync(updatesPath)) {
+        const existing = readFileSync(updatesPath, "utf-8");
+        if (existing.includes(MARKER)) {
+          // Marker already present — a prior run of this migration appended
+          // the note. Short-circuit to keep the migration idempotent across
+          // the narrow crash window between append and runner checkpoint.
+          return;
+        }
+        // Ensure separation from prior content.
+        const needsLeadingNewline = !existing.endsWith("\n\n");
+        const prefix = existing.endsWith("\n") ? "\n" : "\n\n";
+        appendFileSync(
+          updatesPath,
+          needsLeadingNewline ? `${prefix}${RELEASE_NOTE}` : RELEASE_NOTE,
+          "utf-8",
+        );
+      } else {
+        writeFileSync(updatesPath, RELEASE_NOTE, "utf-8");
+      }
+      log.info(
+        { path: updatesPath },
+        "Appended Meet video avatar release note",
+      );
+    } catch (err) {
+      log.warn(
+        { err, path: updatesPath },
+        "Failed to append Meet video avatar release note to UPDATES.md",
+      );
+    }
+  },
+
+  down(_workspaceDir: string): void {
+    // Forward-only: UPDATES.md is a user-facing bulletin the assistant
+    // processes and deletes on its own. Attempting to reverse a note that may
+    // have already been read/deleted would risk surprising user-visible state.
+  },
+};

package/src/workspace/migrations/046-seed-conversation-starters-callsite.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+/**
+ * Seed a latency-optimized default for the `conversationStarters` LLM
+ * call site.
+ *
+ * `conversationStarters` drives the reply-suggestion chip rendered in the
+ * macOS client after every assistant turn. Migration 040 seeded most
+ * trivial copy-generation call sites to haiku-4.5 but missed this one, so
+ * it falls through to `llm.default` — on workspaces where the default is
+ * a high-effort / extended-thinking configured model (e.g. Opus 4.x at
+ * `effort: "xhigh"`), every turn completion kicks off an expensive
+ * reasoning call that, to add insult to injury, rejects the assistant
+ * message prefill the suggestion generator previously relied on with an
+ * HTTP 400.
+ *
+ * Follows the same contract as `040-seed-latency-callsite-defaults`:
+ *   - Skip entirely when `VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH` is set
+ *     (platform overlay owns call-site seeds).
+ *   - Skip when the resolved provider is not Anthropic (the seeded
+ *     model IDs are Anthropic-shaped, so mixing with another provider
+ *     would guarantee invalid-model errors).
+ *   - No-op when `llm.callSites.conversationStarters` is already set.
+ *
+ * Idempotent, append-only — existing 040 entries are untouched.
+ */
+export const seedConversationStartersCallsiteMigration: WorkspaceMigration = {
+  id: "046-seed-conversation-starters-callsite",
+  description:
+    "Seed latency-optimized default for conversationStarters LLM call site",
+  run(workspaceDir: string): void {
+    if (process.env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH) return;
+
+    const configPath = join(workspaceDir, "config.json");
+    const configExisted = existsSync(configPath);
+
+    let config: Record<string, unknown> = {};
+    if (configExisted) {
+      try {
+        const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+        config = raw as Record<string, unknown>;
+      } catch {
+        return;
+      }
+    }
+
+    const llm = readObject(config.llm) ?? {};
+    const defaultBlock = readObject(llm.default);
+
+    const explicitProvider = readString(defaultBlock?.provider);
+    if (
+      explicitProvider !== undefined &&
+      explicitProvider !== "anthropic" &&
+      explicitProvider !== "openrouter"
+    ) {
+      return;
+    }
+    const provider = explicitProvider ?? "anthropic";
+    const fastModel = resolveLatencyModel(provider);
+    if (fastModel === undefined) return;
+
+    const callSites = readObject(llm.callSites) ?? {};
+    if (readObject(callSites.conversationStarters) !== null) return;
+
+    callSites.conversationStarters = {
+      model: fastModel,
+      effort: "low",
+      thinking: { enabled: false },
+    };
+
+    llm.callSites = callSites;
+    config.llm = llm;
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  },
+  down(_workspaceDir: string): void {
+    // Forward-only: removing the seeded default would reintroduce the
+    // cost/latency regression and the assistant-prefill 400 that this
+    // migration fixes.
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers — self-contained per workspace migrations AGENTS.md
+// ---------------------------------------------------------------------------
+
+const PROVIDER_LATENCY_MODELS: Record<string, string> = {
+  anthropic: "claude-haiku-4-5-20251001",
+  openrouter: "anthropic/claude-haiku-4.5",
+};
+
+function resolveLatencyModel(provider: string): string | undefined {
+  return PROVIDER_LATENCY_MODELS[provider];
+}
+
+function readObject(value: unknown): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/workspace/migrations/047-remove-watch-callsites.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+/**
+ * Remove `watchCommentary` and `watchSummary` entries from
+ * `llm.callSites` in existing config files. These call-sites were seeded
+ * by migration 040 but the screen-watch feature has been removed, so the
+ * keys are no longer valid members of the `LLMCallSiteEnum` and would
+ * trigger repeated validation warnings if left on disk.
+ */
+export const removeWatchCallsitesMigration: WorkspaceMigration = {
+  id: "047-remove-watch-callsites",
+  description:
+    "Remove watchCommentary and watchSummary from llm.callSites (screen-watch removed)",
+  run(workspaceDir: string): void {
+    const configPath = join(workspaceDir, "config.json");
+    if (!existsSync(configPath)) return;
+
+    let config: Record<string, unknown>;
+    try {
+      const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+      config = raw as Record<string, unknown>;
+    } catch {
+      return;
+    }
+
+    const llm = config.llm;
+    if (!llm || typeof llm !== "object" || Array.isArray(llm)) return;
+
+    const callSites = (llm as Record<string, unknown>).callSites;
+    if (!callSites || typeof callSites !== "object" || Array.isArray(callSites))
+      return;
+
+    const sites = callSites as Record<string, unknown>;
+    let mutated = false;
+
+    for (const key of ["watchCommentary", "watchSummary"]) {
+      if (key in sites) {
+        delete sites[key];
+        mutated = true;
+      }
+    }
+
+    if (!mutated) return;
+
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  },
+  down(_workspaceDir: string): void {
+    // no-op — keys are obsolete
+  },
+};

package/src/workspace/migrations/048-remove-workspace-hooks.ts

@@ -0,0 +1,81 @@
+/**
+ * Workspace migration 046: Remove legacy `workspace/hooks/` directory.
+ *
+ * Migration 022 moved `~/.vellum/hooks/` into `~/.vellum/workspace/hooks/`.
+ * With the hook system entirely removed, that directory is dead state — it is
+ * no longer read or written by the assistant. This migration deletes the
+ * directory (and everything under it) so stale hook manifests, config, and
+ * executables do not linger in user workspaces.
+ *
+ * Idempotent: safe to re-run after interruption. A no-op when the directory
+ * is already absent.
+ */
+
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../../util/logger.js";
+import type { WorkspaceMigration } from "./types.js";
+
+const log = getLogger("workspace-migration-048-remove-workspace-hooks");
+
+/**
+ * Count files under `dir` recursively. Best-effort — returns the count we
+ * could successfully stat, and silently skips entries that fail (e.g. a
+ * symlink whose target is missing, a file removed concurrently). This is
+ * only used for log output, so a slightly stale count is acceptable.
+ */
+function countFilesRecursive(dir: string): number {
+  let count = 0;
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const entryPath = join(dir, entry);
+    try {
+      const s = statSync(entryPath);
+      if (s.isDirectory()) {
+        count += countFilesRecursive(entryPath);
+      } else {
+        count += 1;
+      }
+    } catch {
+      // best-effort
+    }
+  }
+  return count;
+}
+
+export const removeWorkspaceHooksMigration: WorkspaceMigration = {
+  id: "048-remove-workspace-hooks",
+  description:
+    "Remove legacy workspace/hooks/ directory now that the hook system is gone",
+
+  run(workspaceDir: string): void {
+    const hooksDir = join(workspaceDir, "hooks");
+    if (!existsSync(hooksDir)) return;
+
+    const fileCount = countFilesRecursive(hooksDir);
+    try {
+      rmSync(hooksDir, { recursive: true, force: true });
+      log.info(
+        { path: hooksDir, fileCount },
+        "Removed legacy workspace hooks directory",
+      );
+    } catch (err) {
+      log.warn(
+        { err, path: hooksDir },
+        "Failed to remove legacy workspace hooks directory; leaving in place",
+      );
+    }
+  },
+
+  down(_workspaceDir: string): void {
+    // Forward-only: the hook system is gone and the directory contained no
+    // data the assistant still consumes. Restoring an empty directory would
+    // just reintroduce dead state.
+  },
+};

package/src/workspace/migrations/049-release-notes-default-sonnet.ts

@@ -0,0 +1,80 @@
+import {
+  appendFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../../util/logger.js";
+import type { WorkspaceMigration } from "./types.js";
+
+const log = getLogger("workspace-migration-049-release-notes-default-sonnet");
+
+const MIGRATION_ID = "049-release-notes-default-sonnet";
+const MARKER = `<!-- release-note-id:${MIGRATION_ID} -->`;
+
+const RELEASE_NOTE = `${MARKER}
+## Default LLM is now Claude Sonnet 4.6 (main agent stays on Opus)
+
+The schema-level default for \`llm.default.model\` is now
+\`claude-sonnet-4-6\` instead of \`claude-opus-4-7\`, so background call
+sites that fall through to the default now use Sonnet. If you've
+already chosen a model, your persisted config takes precedence.
+
+The main agent conversation loop remains on Opus: a companion
+migration seeds \`llm.callSites.mainAgent = { model: "claude-opus-4-7" }\`
+when it's unset, and the \`quality-optimized\` model intent also still
+resolves to Opus.
+
+To switch the main agent to Sonnet, clear the call-site override:
+
+\`\`\`bash
+assistant config unset llm.callSites.mainAgent
+\`\`\`
+
+To switch the overall default back to Opus, run:
+
+\`\`\`bash
+assistant config set llm.default.model claude-opus-4-7
+\`\`\`
+`;
+
+export const releaseNotesDefaultSonnetMigration: WorkspaceMigration = {
+  id: MIGRATION_ID,
+  description:
+    "Append release notes for default LLM switch to Claude Sonnet 4.6 to UPDATES.md",
+
+  run(workspaceDir: string): void {
+    const updatesPath = join(workspaceDir, "UPDATES.md");
+
+    try {
+      if (existsSync(updatesPath)) {
+        const existing = readFileSync(updatesPath, "utf-8");
+        if (existing.includes(MARKER)) {
+          return;
+        }
+        const needsLeadingNewline = !existing.endsWith("\n\n");
+        const prefix = existing.endsWith("\n") ? "\n" : "\n\n";
+        appendFileSync(
+          updatesPath,
+          needsLeadingNewline ? `${prefix}${RELEASE_NOTE}` : RELEASE_NOTE,
+          "utf-8",
+        );
+      } else {
+        writeFileSync(updatesPath, RELEASE_NOTE, "utf-8");
+      }
+      log.info({ path: updatesPath }, "Appended default-Sonnet release note");
+    } catch (err) {
+      log.warn(
+        { err, path: updatesPath },
+        "Failed to append default-Sonnet release note to UPDATES.md",
+      );
+    }
+  },
+
+  down(_workspaceDir: string): void {
+    // Forward-only: UPDATES.md is a user-facing bulletin the assistant
+    // processes and deletes on its own.
+  },
+};

package/src/workspace/migrations/050-seed-main-agent-opus-callsite.ts

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+/**
+ * Seed `callSites.mainAgent = { model: "claude-opus-4-7" }` so the main
+ * agent conversation loop stays on Opus even though the schema-level
+ * default dropped to Sonnet. Runs in two modes, mirroring migration 040:
+ *
+ *   1. **Existing workspace** (config.json present): merge the seed into
+ *      `llm.callSites` without overwriting a user-defined override.
+ *   2. **Fresh install** (config.json absent): write a minimal starter
+ *      config with just this seed. `loadConfig()` runs after migrations
+ *      and backfills the remaining schema defaults via `deepMergeMissing`.
+ *
+ * Applied only when:
+ *   - the resolved provider is Anthropic (other providers own their
+ *     own mainAgent model choice), **and**
+ *   - `llm.default.model` is either unset or equal to the previous
+ *     schema default `claude-opus-4-7` — a user who explicitly picked
+ *     a different Anthropic model (e.g. Haiku) kept their own choice,
+ *     so forcing Opus onto their mainAgent would be surprising.
+ */
+export const seedMainAgentOpusCallsiteMigration: WorkspaceMigration = {
+  id: "050-seed-main-agent-opus-callsite",
+  description: "Seed callSites.mainAgent to claude-opus-4-7 for Anthropic",
+  run(workspaceDir: string): void {
+    // Defer to platform-provided overlays.
+    if (process.env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH) return;
+
+    const configPath = join(workspaceDir, "config.json");
+    const configExisted = existsSync(configPath);
+
+    let config: Record<string, unknown> = {};
+    if (configExisted) {
+      try {
+        const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+        config = raw as Record<string, unknown>;
+      } catch {
+        return;
+      }
+    }
+
+    const llm = readObject(config.llm) ?? {};
+    const defaultBlock = readObject(llm.default);
+
+    const explicitProvider = readString(defaultBlock?.provider);
+    if (explicitProvider !== undefined && explicitProvider !== "anthropic") {
+      return;
+    }
+
+    const explicitModel = readString(defaultBlock?.model);
+    if (explicitModel !== undefined && explicitModel !== "claude-opus-4-7") {
+      return;
+    }
+
+    const callSites = readObject(llm.callSites) ?? {};
+
+    if (readObject(callSites.mainAgent) !== null) return;
+
+    // maxTokens: 32000 matches Opus's maxOutputTokens (see
+    // model-catalog.ts); without it the site would inherit the
+    // default's 64000 and overshoot the model capability.
+    callSites.mainAgent = { model: "claude-opus-4-7", maxTokens: 32000 };
+    llm.callSites = callSites;
+    config.llm = llm;
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  },
+  down(_workspaceDir: string): void {
+    // Forward-only: removing the seed would silently downgrade the main
+    // agent loop to Sonnet on every re-run.
+  },
+};
+
+function readObject(value: unknown): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/workspace/migrations/051-seed-conversation-summarization-callsite.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+/**
+ * Seed a sensible default for the `conversationSummarization` LLM call site.
+ *
+ * `conversationSummarization` is invoked from `ContextWindowManager.
+ * updateSummary()` during mid-loop compaction. Without a call-site entry it
+ * falls through to `llm.default` (opus + `effort: "max"` + `thinking:
+ * { enabled: true }` + `maxTokens: 64000`), which is far too expensive for
+ * summarizing a ~150k-token transcript inside the agent-loop plugin
+ * pipeline's 30s budget — we were hitting `PluginTimeoutError` and hard-
+ * failing the turn.
+ *
+ * This migration seeds `effort: "low"` and `thinking: { enabled: false }`
+ * (and opus-4.7 as the model when absent) so the summary call runs cheaply
+ * inside budget. Existing user-set fields are preserved — if the user has
+ * explicitly configured `effort` or `thinking` for this call site, we do
+ * not touch those values. Follows the pattern established by migrations
+ * 040 and 046 but merges additively instead of skip-when-present, because
+ * migration 038 may have already seeded a bare `{ model: ... }` entry that
+ * still needs `effort` / `thinking` defaults to avoid the same fallthrough
+ * to the expensive default.
+ *
+ *   - Skip entirely when `VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH` is set
+ *     (platform overlay owns call-site seeds).
+ *   - Skip when the resolved provider is not Anthropic / OpenRouter (the
+ *     seeded model IDs are Anthropic-shaped; mixing with another provider
+ *     would guarantee invalid-model errors).
+ *   - Merge-missing semantics per leaf: never overwrite user-set values.
+ *
+ * Idempotent: re-running after all leaves are populated is a no-op.
+ */
+export const seedConversationSummarizationCallsiteMigration: WorkspaceMigration =
+  {
+    id: "051-seed-conversation-summarization-callsite",
+    description:
+      "Seed conversationSummarization LLM call-site defaults so summary runs stay inside the agent-loop budget",
+    run(workspaceDir: string): void {
+      if (process.env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH) return;
+
+      const configPath = join(workspaceDir, "config.json");
+      const configExisted = existsSync(configPath);
+
+      let config: Record<string, unknown> = {};
+      if (configExisted) {
+        try {
+          const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+          if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+          config = raw as Record<string, unknown>;
+        } catch {
+          return;
+        }
+      }
+
+      const llm = readObject(config.llm) ?? {};
+      const defaultBlock = readObject(llm.default);
+
+      const explicitProvider = readString(defaultBlock?.provider);
+      if (
+        explicitProvider !== undefined &&
+        explicitProvider !== "anthropic" &&
+        explicitProvider !== "openrouter"
+      ) {
+        return;
+      }
+      const provider = explicitProvider ?? "anthropic";
+      const qualityModel = resolveQualityModel(provider);
+      if (qualityModel === undefined) return;
+
+      const callSites = readObject(llm.callSites) ?? {};
+      const existing = readObject(callSites.conversationSummarization) ?? {};
+
+      // Merge-missing per leaf. Presence of the key — even with a value of
+      // `false` — counts as user intent and is preserved.
+      const seeded: Record<string, unknown> = { ...existing };
+      let changed = false;
+      if (!("model" in seeded)) {
+        seeded.model = qualityModel;
+        changed = true;
+      }
+      if (!("effort" in seeded)) {
+        seeded.effort = "low";
+        changed = true;
+      }
+      if (!("thinking" in seeded)) {
+        seeded.thinking = { enabled: false };
+        changed = true;
+      }
+
+      if (!changed) return;
+
+      callSites.conversationSummarization = seeded;
+      llm.callSites = callSites;
+      config.llm = llm;
+      writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+    },
+    down(_workspaceDir: string): void {
+      // Forward-only: removing the seeded defaults would reintroduce the
+      // 30s pipeline-budget timeout this migration fixes.
+    },
+  };
+
+// ---------------------------------------------------------------------------
+// Helpers — self-contained per workspace migrations AGENTS.md
+// ---------------------------------------------------------------------------
+
+const PROVIDER_QUALITY_MODELS: Record<string, string> = {
+  anthropic: "claude-opus-4-7",
+  openrouter: "anthropic/claude-opus-4.7",
+};
+
+function resolveQualityModel(provider: string): string | undefined {
+  return PROVIDER_QUALITY_MODELS[provider];
+}
+
+function readObject(value: unknown): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/workspace/migrations/AGENTS.md

@@ -6,6 +6,6 @@ Each migration file must be **fully self-contained**. All helper functions, cons
 
 - **No external exports.** Migration files must not export anything other than the single `WorkspaceMigration` object. Other code must never import from a migration file.
 - **Duplicate rather than share.** If two migrations need the same helper, duplicate it in both files. Migrations are write-once code — they run once per assistant and are never modified after release. Duplication is preferable to coupling.
-- **Allowed imports:** `./types.js` (for the `WorkspaceMigration` interface) and `../../util/logger.js` (for structured logging). All other dependencies should be inlined.
+- **Allowed imports:** `./types.js` (for the `WorkspaceMigration` interface), `../../util/logger.js` (for structured logging), and Node/Bun runtime built-ins (`node:fs`, `node:path`, `node:crypto`, `bun:sqlite`, etc.). All other dependencies — both project-internal modules and third-party npm packages — must be inlined. Do not import from shared modules like `../../memory/` or `../../config/`, and do not add npm dependencies.
 - **Graceful on all platforms.** Migrations run on macOS, Linux, and in Docker. Platform-specific operations must no-op gracefully on unsupported platforms — never throw.
 - **Idempotent.** Migrations must be safe to re-run if interrupted. The runner checkpoints state as `"started"` before execution and `"completed"` after, so a crash mid-migration triggers a re-run on next startup.