@vellumai/assistant 0.6.4 → 0.6.5

package/src/__tests__/config-loader-backfill.test.ts

@@ -65,6 +65,7 @@ afterAll(() => {
 
 import {
   deepMergeMissing,
+  deepMergeOverwrite,
   invalidateConfigCache,
   loadConfig,
 } from "../config/loader.js";
@@ -143,6 +144,179 @@ describe("deepMergeMissing", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Tests: deepMergeOverwrite (unit) — JSON-null-as-deletion semantics
+// ---------------------------------------------------------------------------
+
+describe("deepMergeOverwrite", () => {
+  test("overwrites top-level scalars", () => {
+    const target: Record<string, unknown> = { a: 1, b: "old" };
+    deepMergeOverwrite(target, { a: 2, c: "new" });
+    expect(target).toEqual({ a: 2, b: "old", c: "new" });
+  });
+
+  test("recursively merges nested objects, overwriting leaves", () => {
+    const target: Record<string, unknown> = {
+      nested: { keep: "yes", change: "before" },
+    };
+    deepMergeOverwrite(target, {
+      nested: { change: "after", added: 42 },
+    });
+    expect(target).toEqual({
+      nested: { keep: "yes", change: "after", added: 42 },
+    });
+  });
+
+  test("replaces arrays wholesale rather than merging", () => {
+    const target: Record<string, unknown> = { items: [1, 2, 3] };
+    deepMergeOverwrite(target, { items: [9] });
+    expect(target).toEqual({ items: [9] });
+  });
+
+  test("assigns null to scalar fields (preserves nullable config values)", () => {
+    const target: Record<string, unknown> = { a: 1, b: 2 };
+    deepMergeOverwrite(target, { a: null });
+    expect(target).toEqual({ a: null, b: 2 });
+    expect("a" in target).toBe(true);
+  });
+
+  test("assigns null to nested scalar fields, preserving siblings", () => {
+    const target: Record<string, unknown> = {
+      a: { b: 1, c: 2, d: 3 },
+    };
+    deepMergeOverwrite(target, { a: { b: null } });
+    expect(target).toEqual({ a: { b: null, c: 2, d: 3 } });
+    expect("b" in (target.a as Record<string, unknown>)).toBe(true);
+  });
+
+  test("assigns null to existing null fields (no-op for already-null)", () => {
+    const target: Record<string, unknown> = {
+      heartbeat: { activeHoursStart: null, intervalMs: 6000 },
+    };
+    deepMergeOverwrite(target, {
+      heartbeat: { activeHoursStart: null },
+    });
+    expect(target).toEqual({
+      heartbeat: { activeHoursStart: null, intervalMs: 6000 },
+    });
+  });
+
+  test("deletion of a nested key whose value is itself an object", () => {
+    // Models the macOS clear-call-site-override case:
+    // PATCH { llm: { callSites: { commitMessage: null } } } removes the
+    // commitMessage entry entirely while keeping other call-site entries
+    // and unrelated llm fields intact.
+    const target: Record<string, unknown> = {
+      llm: {
+        provider: "anthropic",
+        callSites: {
+          commitMessage: { provider: "openai", model: "gpt-4" },
+          memoryRetrieval: { profile: "fast" },
+        },
+      },
+    };
+    deepMergeOverwrite(target, {
+      llm: { callSites: { commitMessage: null } },
+    });
+    expect(target).toEqual({
+      llm: {
+        provider: "anthropic",
+        callSites: {
+          memoryRetrieval: { profile: "fast" },
+        },
+      },
+    });
+  });
+
+  test("deletion is a no-op when the key is already absent", () => {
+    const target: Record<string, unknown> = { a: 1 };
+    deepMergeOverwrite(target, { missing: null });
+    expect(target).toEqual({ a: 1 });
+    expect("missing" in target).toBe(false);
+  });
+
+  test("strips null leaves when assigning a whole subtree to a missing key", () => {
+    // Models a PATCH that introduces a new call-site entry while clearing
+    // some of its sub-fields in the same payload — the nulls must not
+    // be persisted.
+    const target: Record<string, unknown> = { llm: { provider: "anthropic" } };
+    deepMergeOverwrite(target, {
+      llm: {
+        callSites: {
+          commitMessage: { provider: null, model: "gpt-4", profile: null },
+        },
+      },
+    });
+    expect(target).toEqual({
+      llm: {
+        provider: "anthropic",
+        callSites: {
+          commitMessage: { model: "gpt-4" },
+        },
+      },
+    });
+  });
+
+  test("strips null leaves when overwriting a scalar with an object subtree", () => {
+    const target: Record<string, unknown> = { a: 1 };
+    deepMergeOverwrite(target, { a: { b: null, c: 5, d: { e: null, f: 6 } } });
+    expect(target).toEqual({ a: { c: 5, d: { f: 6 } } });
+  });
+
+  test("nullable config fields: null replaces scalar default, not deleted", () => {
+    // Models PATCH { heartbeat: { activeHoursStart: null, activeHoursEnd: null } }
+    // on a config where the defaults (8, 22) are in place. The nullable fields
+    // must store null (meaning "disabled") — NOT be deleted (which would
+    // re-apply schema defaults on next load).
+    const target: Record<string, unknown> = {
+      heartbeat: { intervalMs: 6000, activeHoursStart: 8, activeHoursEnd: 22 },
+    };
+    deepMergeOverwrite(target, {
+      heartbeat: { activeHoursStart: null, activeHoursEnd: null },
+    });
+    expect(target).toEqual({
+      heartbeat: { intervalMs: 6000, activeHoursStart: null, activeHoursEnd: null },
+    });
+  });
+
+  test("mixed: deletes object entries, assigns null to scalars in same merge", () => {
+    // Verifies both behaviors coexist in a single merge: object entries are
+    // deleted (call-site clearing) while scalar nulls are assigned (nullable fields).
+    const target: Record<string, unknown> = {
+      llm: {
+        callSites: {
+          commitMessage: { provider: "openai" },
+        },
+      },
+      heartbeat: { activeHoursStart: 8 },
+    };
+    deepMergeOverwrite(target, {
+      llm: { callSites: { commitMessage: null } },
+      heartbeat: { activeHoursStart: null },
+    });
+    expect(target).toEqual({
+      llm: { callSites: {} },
+      heartbeat: { activeHoursStart: null },
+    });
+  });
+
+  test("preserves explicit boolean false and zero (not treated as null)", () => {
+    const target: Record<string, unknown> = { a: true, b: 1 };
+    deepMergeOverwrite(target, { a: false, b: 0 });
+    expect(target).toEqual({ a: false, b: 0 });
+  });
+
+  test("undefined override values are passed through, not treated as deletion", () => {
+    // JSON.parse never produces undefined, but guard the in-process call path:
+    // an explicit undefined assignment should follow the same "scalar overwrite"
+    // path as before, not the null-deletion path.
+    const target: Record<string, unknown> = { a: 1 };
+    deepMergeOverwrite(target, { a: undefined });
+    expect("a" in target).toBe(true);
+    expect(target.a).toBeUndefined();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Tests: startup backfill integration
 // ---------------------------------------------------------------------------

package/src/__tests__/config-loader-corrupt.test.ts

@@ -0,0 +1,183 @@
+/**
+ * A corrupt config.json (truncated during a power-loss mid-write, or
+ * hand-edited to invalid JSON) is quarantined by the loader, which
+ * logs an error with a remediation hint and falls through to the
+ * default-config path so startup proceeds. These tests verify that
+ * loadConfig() / loadRawConfig() never throw on corrupt input, and
+ * that the corrupt file is preserved for debugging.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  invalidateConfigCache,
+  loadConfig,
+  loadRawConfig,
+} from "../config/loader.js";
+import { _setStorePath } from "../security/encrypted-store.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const WORKSPACE_DIR = process.env.VELLUM_WORKSPACE_DIR!;
+const CONFIG_PATH = join(WORKSPACE_DIR, "config.json");
+
+function ensureTestDir(): void {
+  const dirs = [
+    WORKSPACE_DIR,
+    join(WORKSPACE_DIR, "data"),
+    join(WORKSPACE_DIR, "data", "memory"),
+    join(WORKSPACE_DIR, "data", "memory", "knowledge"),
+    join(WORKSPACE_DIR, "data", "logs"),
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+}
+
+function resetWorkspace(): void {
+  for (const name of readdirSync(WORKSPACE_DIR)) {
+    rmSync(join(WORKSPACE_DIR, name), { recursive: true, force: true });
+  }
+  ensureTestDir();
+}
+
+function listQuarantinedFiles(): string[] {
+  return readdirSync(WORKSPACE_DIR).filter((name) =>
+    /^config\.json\.corrupt-.+\.json$/.test(name),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("loadConfig corrupt-file recovery", () => {
+  beforeEach(() => {
+    resetWorkspace();
+    _setStorePath(join(WORKSPACE_DIR, "keys.enc"));
+    invalidateConfigCache();
+  });
+
+  afterEach(() => {
+    _setStorePath(null);
+    invalidateConfigCache();
+  });
+
+  test("quarantines corrupt config.json and returns defaults", () => {
+    // Simulate a truncated mid-write: valid JSON prefix, abrupt end.
+    writeFileSync(CONFIG_PATH, '{"provider": "anthropic", "mo');
+
+    // Must not throw — the daemon must never block startup on corrupt config.
+    const config = loadConfig();
+
+    // Defaults loaded — config is populated through the Zod schema.
+    expect(config).toBeDefined();
+    expect(config.memory).toBeDefined();
+
+    // Corrupt file renamed, not deleted — content preserved for debug.
+    const quarantined = listQuarantinedFiles();
+    expect(quarantined).toHaveLength(1);
+    const quarantinedPath = join(WORKSPACE_DIR, quarantined[0]);
+    expect(readFileSync(quarantinedPath, "utf-8")).toBe(
+      '{"provider": "anthropic", "mo',
+    );
+
+    // After quarantine the daemon wrote a fresh default config.json.
+    expect(existsSync(CONFIG_PATH)).toBe(true);
+  });
+
+  test("loads a valid config without renaming (regression guard)", () => {
+    writeFileSync(
+      CONFIG_PATH,
+      JSON.stringify({ provider: "anthropic", model: "claude-opus-4-7" }),
+    );
+
+    const config = loadConfig();
+    expect(config).toBeDefined();
+
+    // No quarantine file for valid JSON.
+    expect(listQuarantinedFiles()).toHaveLength(0);
+    // The original file is still present.
+    expect(existsSync(CONFIG_PATH)).toBe(true);
+  });
+
+  test("does not re-quarantine existing quarantine files on subsequent startups", () => {
+    // First startup: corrupt config is quarantined.
+    writeFileSync(CONFIG_PATH, "}{not json");
+    loadConfig();
+
+    const firstBatch = listQuarantinedFiles();
+    expect(firstBatch).toHaveLength(1);
+
+    // Daemon restart with no new config.json (the loader wrote defaults after
+    // the quarantine on the previous load, so there IS now a valid config.json
+    // on disk — no second quarantine should occur).
+    invalidateConfigCache();
+    loadConfig();
+
+    // Still exactly one quarantined file — the loader did not re-rename a
+    // pristine or already-quarantined file.
+    expect(listQuarantinedFiles()).toHaveLength(1);
+    expect(listQuarantinedFiles()[0]).toBe(firstBatch[0]);
+  });
+
+  test("quarantine filenames are filesystem-safe (no colons)", () => {
+    writeFileSync(CONFIG_PATH, "not-valid-json");
+    loadConfig();
+
+    const quarantined = listQuarantinedFiles();
+    expect(quarantined).toHaveLength(1);
+    // ISO-8601 colons must have been replaced — filenames with `:` are
+    // invalid on Windows and awkward on macOS Finder.
+    expect(quarantined[0]).not.toContain(":");
+    // Should match the documented shape: config.json.corrupt-<ISO>.json
+    expect(quarantined[0]).toMatch(
+      /^config\.json\.corrupt-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}\.\d{3}Z\.json$/,
+    );
+  });
+});
+
+describe("loadRawConfig corrupt-file recovery", () => {
+  beforeEach(() => {
+    resetWorkspace();
+    _setStorePath(join(WORKSPACE_DIR, "keys.enc"));
+    invalidateConfigCache();
+  });
+
+  afterEach(() => {
+    _setStorePath(null);
+    invalidateConfigCache();
+  });
+
+  test("returns {} and quarantines corrupt file instead of throwing", () => {
+    writeFileSync(CONFIG_PATH, "this is not json at all");
+
+    // Must not throw — the /v1/config handler depends on this.
+    const raw = loadRawConfig();
+
+    expect(raw).toEqual({});
+    expect(listQuarantinedFiles()).toHaveLength(1);
+  });
+
+  test("returns parsed object when config is valid", () => {
+    writeFileSync(
+      CONFIG_PATH,
+      JSON.stringify({ foo: "bar", nested: { k: 1 } }),
+    );
+
+    const raw = loadRawConfig();
+    expect(raw).toEqual({ foo: "bar", nested: { k: 1 } });
+    expect(listQuarantinedFiles()).toHaveLength(0);
+  });
+});

package/src/__tests__/config-loader-quarantine-bulletin.test.ts

@@ -0,0 +1,202 @@
+/**
+ * When loadConfig()/loadRawConfig() quarantines a corrupt config.json, it
+ * appends a bulletin to <workspace>/UPDATES.md so the background update-
+ * bulletin job picks up the event inside a background-only conversation.
+ * The agent decides whether to surface the quarantine to the user — it's
+ * agent-visible context, not a push notification.
+ *
+ * The bulletin is keyed on the quarantine filename via an HTML marker so
+ * repeated appends for the same quarantine are idempotent — per the
+ * Release-Update-Hygiene rule in the root AGENTS.md, idempotency at both the
+ * runner level AND an in-file marker is required to close the crash-mid-append
+ * window.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  _appendQuarantineBulletin,
+  invalidateConfigCache,
+  loadConfig,
+} from "../config/loader.js";
+import { _setStorePath } from "../security/encrypted-store.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const WORKSPACE_DIR = process.env.VELLUM_WORKSPACE_DIR!;
+const CONFIG_PATH = join(WORKSPACE_DIR, "config.json");
+const UPDATES_PATH = join(WORKSPACE_DIR, "UPDATES.md");
+
+function ensureTestDir(): void {
+  const dirs = [
+    WORKSPACE_DIR,
+    join(WORKSPACE_DIR, "data"),
+    join(WORKSPACE_DIR, "data", "memory"),
+    join(WORKSPACE_DIR, "data", "memory", "knowledge"),
+    join(WORKSPACE_DIR, "data", "logs"),
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+}
+
+function resetWorkspace(): void {
+  for (const name of readdirSync(WORKSPACE_DIR)) {
+    rmSync(join(WORKSPACE_DIR, name), { recursive: true, force: true });
+  }
+  ensureTestDir();
+}
+
+function listQuarantinedFiles(): string[] {
+  return readdirSync(WORKSPACE_DIR).filter((name) =>
+    /^config\.json\.corrupt-.+\.json$/.test(name),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("config-quarantine UPDATES.md bulletin", () => {
+  beforeEach(() => {
+    resetWorkspace();
+    _setStorePath(join(WORKSPACE_DIR, "keys.enc"));
+    invalidateConfigCache();
+  });
+
+  afterEach(() => {
+    _setStorePath(null);
+    invalidateConfigCache();
+  });
+
+  test("writes a bulletin with the quarantine marker when config.json is corrupt", () => {
+    writeFileSync(CONFIG_PATH, '{"provider": "anthropic", "mo');
+
+    loadConfig();
+
+    const [quarantinedName] = listQuarantinedFiles();
+    expect(quarantinedName).toBeDefined();
+    const quarantinedPath = join(WORKSPACE_DIR, quarantinedName);
+
+    expect(existsSync(UPDATES_PATH)).toBe(true);
+    const body = readFileSync(UPDATES_PATH, "utf-8");
+
+    // Heading must match the wording the background update-bulletin job
+    // relays to the user.
+    expect(body).toContain("## Config was reset to defaults");
+    // Quarantine file path is what the user cats to recover.
+    expect(body).toContain(quarantinedPath);
+    // Idempotency marker is shape-exact, basename-keyed (not full path).
+    expect(body).toContain(`<!-- config-quarantine:${quarantinedName} -->`);
+    expect(body).toMatch(
+      /<!-- config-quarantine:config\.json\.corrupt-.+\.json -->/,
+    );
+  });
+
+  test("two successive quarantines append two distinct bulletins (not overwrite)", () => {
+    // First corruption round.
+    writeFileSync(CONFIG_PATH, '{"partial": ');
+    loadConfig();
+    invalidateConfigCache();
+
+    const firstQuarantined = listQuarantinedFiles();
+    expect(firstQuarantined).toHaveLength(1);
+    const firstBody = readFileSync(UPDATES_PATH, "utf-8");
+    const firstMarker = `<!-- config-quarantine:${firstQuarantined[0]} -->`;
+    expect(firstBody).toContain(firstMarker);
+
+    // Loader wrote a fresh default config.json after quarantine; corrupt it
+    // again. Sleep briefly to guarantee a different ISO-timestamp millisecond
+    // component and therefore a distinct quarantine filename.
+    const untilDifferentMs = Date.now() + 5;
+    while (Date.now() < untilDifferentMs) {
+      /* spin */
+    }
+    writeFileSync(CONFIG_PATH, "still not json");
+    loadConfig();
+
+    const quarantined = listQuarantinedFiles().sort();
+    expect(quarantined).toHaveLength(2);
+
+    const body = readFileSync(UPDATES_PATH, "utf-8");
+    for (const name of quarantined) {
+      expect(body).toContain(`<!-- config-quarantine:${name} -->`);
+    }
+    // Two "Config was reset to defaults" sections — appended, not overwritten.
+    const headingMatches = body.match(/## Config was reset to defaults/g) ?? [];
+    expect(headingMatches).toHaveLength(2);
+    // The earlier marker is still present (append semantics).
+    expect(body).toContain(firstMarker);
+  });
+
+  test("idempotent: pre-existing marker for the same quarantine filename skips the append", () => {
+    // Simulate a crash-mid-append: UPDATES.md already contains a marker for
+    // a specific quarantine filename. A follow-up call referencing the same
+    // filename must leave the file untouched.
+    const quarantineName = "config.json.corrupt-2026-04-20T12-00-00.000Z.json";
+    const quarantinePath = join(WORKSPACE_DIR, quarantineName);
+    const preexisting =
+      `## Config was reset to defaults\n\n` +
+      `Pre-existing bulletin for ${quarantinePath}.\n\n` +
+      `<!-- config-quarantine:${quarantineName} -->\n`;
+    writeFileSync(UPDATES_PATH, preexisting, "utf-8");
+    // Also create the quarantine file on disk so the helper sees an
+    // environment consistent with a prior successful rename.
+    writeFileSync(quarantinePath, "{ not json", "utf-8");
+
+    _appendQuarantineBulletin(CONFIG_PATH, quarantinePath);
+
+    const after = readFileSync(UPDATES_PATH, "utf-8");
+    expect(after).toBe(preexisting);
+    // Exactly one marker present — no duplicate was appended.
+    expect(
+      after.match(
+        new RegExp(`<!-- config-quarantine:${quarantineName} -->`, "g"),
+      )?.length,
+    ).toBe(1);
+    expect(basename(quarantinePath)).toBe(quarantineName);
+  });
+
+  test("valid config.json does not create UPDATES.md (regression guard)", () => {
+    writeFileSync(
+      CONFIG_PATH,
+      JSON.stringify({ provider: "anthropic", model: "claude-opus-4-7" }),
+    );
+
+    loadConfig();
+
+    expect(listQuarantinedFiles()).toHaveLength(0);
+    expect(existsSync(UPDATES_PATH)).toBe(false);
+  });
+
+  test("appends (does not overwrite) when UPDATES.md already has unrelated content", () => {
+    const priorContent =
+      `## Some earlier bulletin\n\n` +
+      `Unrelated prior content from a previous migration.\n\n` +
+      `<!-- release-note-id:unrelated-note -->\n`;
+    writeFileSync(UPDATES_PATH, priorContent, "utf-8");
+
+    writeFileSync(CONFIG_PATH, "{oops");
+    loadConfig();
+
+    const body = readFileSync(UPDATES_PATH, "utf-8");
+    // Prior content preserved verbatim at the start.
+    expect(body.startsWith(priorContent)).toBe(true);
+    // New bulletin appended.
+    expect(body).toContain("## Config was reset to defaults");
+    expect(body).toMatch(
+      /<!-- config-quarantine:config\.json\.corrupt-.+\.json -->/,
+    );
+  });
+});

package/src/__tests__/config-schema-cmd.test.ts

@@ -82,8 +82,11 @@ import { getSchemaAtPath } from "../config/schema-utils.js";
 // ---------------------------------------------------------------------------
 
 describe("getSchemaAtPath", () => {
-  test("returns full schema for a top-level key (maxTokens → number schema)", () => {
-    const result = getSchemaAtPath(AssistantConfigSchema, "maxTokens");
+  test("returns full schema for a leaf key (llm.default.maxTokens → number schema)", () => {
+    const result = getSchemaAtPath(
+      AssistantConfigSchema,
+      "llm.default.maxTokens",
+    );
     expect(result).not.toBeNull();
     // maxTokens has a default, so it should be parseable
     const parsed = (result as z.ZodType).parse(undefined);
@@ -184,7 +187,7 @@ describe("z.toJSONSchema integration", () => {
     expect(properties).toBeDefined();
     // Check that top-level keys are present
     expect(properties.services).toBeDefined();
-    expect(properties.maxTokens).toBeDefined();
+    expect(properties.llm).toBeDefined();
     expect(properties.calls).toBeDefined();
     expect(properties.memory).toBeDefined();
     expect(properties.timeouts).toBeDefined();
@@ -222,8 +225,11 @@ describe("z.toJSONSchema integration", () => {
     expect(properties!.safety).toBeDefined();
   });
 
-  test("sub-schema at a leaf like maxTokens produces integer schema", () => {
-    const maxTokensSchema = getSchemaAtPath(AssistantConfigSchema, "maxTokens");
+  test("sub-schema at a leaf like llm.default.maxTokens produces integer schema", () => {
+    const maxTokensSchema = getSchemaAtPath(
+      AssistantConfigSchema,
+      "llm.default.maxTokens",
+    );
     expect(maxTokensSchema).not.toBeNull();
     const jsonSchema = z.toJSONSchema(maxTokensSchema!, {
       unrepresentable: "any",