Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

17.6 KB
Raw Blame
/**
 * Agent config kernel versions: the pinned-hash guard (the mechanical definition of "the
 * defaults changed substantively, bump the kernel version"), the record's internal
 * consistency, the pre-#257 generation's reconstruction proof, and the tab-wise merge
 * semantics of applyKernelUpdate (an untouched old default tab advances whole, a tab with any
 * customization is kept whole, identity fields and user data are never touched, YAML comments
 * survive, the config is re-stamped).
 */
import { readFileSync } from "node:fs";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
import {
  DEFAULT_AGENT_ID,
  DEFAULT_PROJECT_ID,
  KERNEL_DEFAULT_TAB_HASHES,
  KERNEL_SUPERSEDED_TAB_HASHES,
  KERNEL_TABS,
  KERNEL_TAB_KEYS,
  KERNEL_VERSION,
  LEGACY_SKILLS_SECTION,
  LEGACY_VAULT_SECTION,
  SCHEDULES_PLACEHOLDER,
  SKILLS_PLACEHOLDER,
  VAULT_PLACEHOLDER,
  applyKernelUpdate,
  computeKernelTabHashes,
  defaultSystemConfig,
  isKernelOutdated,
  kernelTabHash,
  loadAgentState,
  resetSystemConfigToDefaults,
  systemConfigPath,
  type KernelSupersededTabHashes,
  type KernelTab,
  type SystemConfig,
} from "../src/index.js";

/** A mutable plain-object clone of a config, for seeding on-disk scenarios. */
function mutableConfig(config: SystemConfig): Record<string, unknown> {
  return structuredClone(config) as unknown as Record<string, unknown>;
}

/**
 * The `system_prompt` template the toggles generation (`2026-08-11`) shipped, frozen
 * byte-exact — no trailing newline, so the file *is* the template. It is the anchor the
 * reconstruction below needs: the live default goes on evolving, and a recipe reading it
 * would stop reproducing any historical config the moment it did. Never edit it.
 */
const TOGGLES_GENERATION_SYSTEM_PROMPT = readFileSync(
  fileURLToPath(new URL("./fixtures/toggles-generation-system-prompt.txt", import.meta.url)),
  "utf8",
);

/**
 * Reconstructs a pre-#257 (pre-toggles) shaped config: the frozen LEGACY_* sections swapped
 * back into the frozen toggles-generation template in place of the section placeholders, no
 * `{{SCHEDULES}}` line, and no vault/skills/schedules config sections (prompt-sections.test.ts
 * proves the same swap recipe round-trips on the live template). Everything outside the swap —
 * the runtime, tools and memory tabs — carries the *current* defaults, so the merge tests
 * below treat those tabs as already-current; the seeding exercises the old-template migration
 * paths regardless.
 */
function preTogglesDefaultConfig(): SystemConfig {
  const current = defaultSystemConfig();
  const {
    vault: _vault,
    skills: _skills,
    schedules: _schedules,
    kernel_version: _stamp,
    ...rest
  } = current;
  return {
    ...rest,
    system_prompt: TOGGLES_GENERATION_SYSTEM_PROMPT.split(VAULT_PLACEHOLDER)
      .join(LEGACY_VAULT_SECTION)
      .split(SKILLS_PLACEHOLDER)
      .join(LEGACY_SKILLS_SECTION)
      .split(`${SCHEDULES_PLACEHOLDER}\n\n`)
      .join(""),
  };
}

describe("kernel tab hash record (pinned-hash guard)", () => {
  it("KERNEL_VERSION is a date", () => {
    expect(KERNEL_VERSION).toMatch(/^\d{4}-\d{2}-\d{2}$/);
  });

  it("the record covers every tab and lists nothing that could never fire", () => {
    expect(Object.keys(KERNEL_DEFAULT_TAB_HASHES).sort()).toEqual([...KERNEL_TAB_KEYS].sort());
    for (const [tab, hashes] of Object.entries(KERNEL_SUPERSEDED_TAB_HASHES)) {
      expect(KERNEL_TAB_KEYS, `${tab} is not a kernel tab`).toContain(tab);
      expect(hashes.length, tab).toBeGreaterThan(0);
      expect(new Set(hashes).size, `${tab} repeats a superseded hash`).toBe(hashes.length);
      // A kernel update short-circuits on the current default before consulting the record,
      // so the current hash sitting in `superseded` would be dead weight.
      expect(hashes, `${tab} lists its own current default`).not.toContain(
        KERNEL_DEFAULT_TAB_HASHES[tab as KernelTab],
      );
    }
  });

  // THE guard: this failing means the built-in defaults changed substantively without a
  // kernel bump (or vice versa). It is the mechanical definition of "substantive change".
  it("the current defaults hash exactly to KERNEL_DEFAULT_TAB_HASHES — advance the kernel when this fails", () => {
    const recomputed = computeKernelTabHashes(defaultSystemConfig());
    const moved = KERNEL_TAB_KEYS.filter(
      (tab) => recomputed[tab] !== KERNEL_DEFAULT_TAB_HASHES[tab],
    );
    expect(
      moved,
      "The built-in default config changed substantively (the listed settings tabs no longer " +
        "hash to KERNEL_DEFAULT_TAB_HASHES). Advance the kernel in " +
        "core/src/state/kernel-history.ts: set KERNEL_VERSION to today's date (several " +
        "changes on the same day may reuse it), then, for each tab listed, append its OLD " +
        "KERNEL_DEFAULT_TAB_HASHES hash to the end of KERNEL_SUPERSEDED_TAB_HASHES[tab] " +
        "(creating the entry if this is its first change; never edit the hashes already " +
        "there, they are frozen) and write the recomputed hash in — take it from " +
        "computeKernelTabHashes(defaultSystemConfig()). Finally note what moved in the " +
        "generation list above KERNEL_DEFAULT_TAB_HASHES.",
    ).toEqual([]);
  });

  // Keeps the oldest recorded generation honest: its pinned hash is the only record of what a
  // pre-#257 `system_config.yaml` actually contains, and nothing else can catch a typo in it.
  // The recipe runs on the frozen toggles-generation fixture rather than the live default, so
  // the proof keeps standing as `system_prompt` evolves.
  it("the pre-toggles prompt tab equals the LEGACY_* reconstruction", () => {
    const reconstructed = preTogglesDefaultConfig();
    expect(kernelTabHash(reconstructed, "prompt")).toBe(KERNEL_SUPERSEDED_TAB_HASHES.prompt?.[0]);
    // The recipe's other half: an era config carries no vault/skills/schedules sections at all,
    // which is why those tabs have no superseded hash — they are materialized on absence.
    for (const tab of ["vault", "skills", "schedules"] as const) {
      expect(kernelTabHash(reconstructed, tab), tab).toBeNull();
    }
  });

  it("no kernel tab owns identity fields, the State version or MCP servers", () => {
    const owned = KERNEL_TAB_KEYS.flatMap((tab) => [...KERNEL_TABS[tab]]);
    for (const excluded of ["name", "description", "version", "kernel_version", "tools"]) {
      expect(owned).not.toContain(excluded);
    }
    // And writing user data into them moves no tab hash, so none of it can be clobbered.
    const defaults = defaultSystemConfig();
    expect(
      computeKernelTabHashes({
        ...defaults,
        name: "n",
        description: "d",
        version: 7,
        tools: { ...defaults.tools, mcpServers: [{ name: "m", config: {} }] },
      }),
    ).toEqual(computeKernelTabHashes(defaults));
  });
});

describe("isKernelOutdated", () => {
  it("missing stamp = outdated; older date = outdated; current and newer are not", () => {
    expect(isKernelOutdated(null)).toBe(true);
    expect(isKernelOutdated(undefined)).toBe(true);
    expect(isKernelOutdated("2026-01-01")).toBe(true);
    expect(isKernelOutdated(KERNEL_VERSION)).toBe(false);
    expect(isKernelOutdated("2999-12-31")).toBe(false);
  });
});

describe("applyKernelUpdate", () => {
  let root: string;

  beforeEach(async () => {
    root = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-kernel-"));
  });

  afterEach(async () => {
    await fs.rm(root, { recursive: true, force: true });
  });

  const configPath = () => systemConfigPath(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID);

  /** Creates the default agent, then rewrites its config file with the given object. */
  async function seedConfig(config: Record<string, unknown>): Promise<void> {
    await loadAgentState({ init: {}, root });
    await fs.writeFile(configPath(), stringifyYaml(config), "utf8");
  }

  async function readConfig(): Promise<SystemConfig> {
    return parseYaml(await fs.readFile(configPath(), "utf8")) as SystemConfig;
  }

  const update = () => applyKernelUpdate(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID);

  it("throws for a nonexistent agent (never initializes one)", async () => {
    await expect(applyKernelUpdate(root, DEFAULT_PROJECT_ID, "ghost_agent")).rejects.toThrow(
      /not found/,
    );
  });

  it("is a stamped no-op on a freshly created config", async () => {
    await loadAgentState({ init: {}, root });
    const before = await readConfig();
    const result = await update();
    expect(result).toEqual({ advanced: [], kept: [], kernelVersion: KERNEL_VERSION });
    expect(await readConfig()).toEqual(before);
  });

  it("advances an untouched pre-toggles config wholesale: template migrated, sections materialized, stamp written", async () => {
    await seedConfig(mutableConfig(preTogglesDefaultConfig()));
    const result = await update();
    expect(result.kept).toEqual([]);
    expect(result.advanced).toEqual(["prompt", "skills", "vault", "schedules"]);
    const defaults = defaultSystemConfig();
    const written = await readConfig();
    expect(written.system_prompt).toBe(defaults.system_prompt);
    expect(written.vault).toEqual(defaults.vault);
    expect(written.skills).toEqual(defaults.skills);
    expect(written.schedules).toEqual(defaults.schedules);
    expect(written.kernel_version).toBe(KERNEL_VERSION);
    // A second run finds everything current: fully idempotent.
    expect(await update()).toEqual({ advanced: [], kept: [], kernelVersion: KERNEL_VERSION });
  });

  it("keeps a customized tab whole (reported) while its untouched siblings advance", async () => {
    const config = mutableConfig(preTogglesDefaultConfig());
    config.system_prompt = "MY CUSTOM PROMPT";
    (config.memory as Record<string, unknown>).prompt = "my memory prompt";
    await seedConfig(config);
    const result = await update();
    expect(result.kept).toEqual(["prompt", "memory"]);
    expect(result.advanced).toEqual(["skills", "vault", "schedules"]);
    const written = await readConfig();
    expect(written.system_prompt).toBe("MY CUSTOM PROMPT");
    expect(written.memory?.prompt).toBe("my memory prompt");
    // The rest of the kept tab is kept with it — nothing inside it is rewritten.
    expect(written.memory?.workspace_prompt).toBe(
      preTogglesDefaultConfig().memory?.workspace_prompt,
    );
    expect(written.vault).toEqual(defaultSystemConfig().vault);
    expect(written.kernel_version).toBe(KERNEL_VERSION);
  });

  it("keeps a tab from an unrecorded generation conservatively, missing fields included", async () => {
    const config = mutableConfig(defaultSystemConfig());
    delete config.kernel_version;
    // An ancient compaction wording we cannot reconstruct, with the rest of the section gone:
    // the runtime tab matches no recorded hash, so it is kept exactly as written.
    config.compaction = { mode: "summarize", prompt: "Ancient compaction wording." };
    await seedConfig(config);
    const result = await update();
    expect(result.kept).toEqual(["runtime"]);
    expect(result.advanced).toEqual([]);
    const written = await readConfig();
    expect(written.compaction?.prompt).toBe("Ancient compaction wording.");
    // The tab is kept whole: its absent fields stay absent and keep falling back to the
    // built-in defaults at runtime, rather than being materialized field by field.
    expect(written.compaction?.max_context_length).toBeUndefined();
  });

  it("never touches name, description, version or mcpServers", async () => {
    const config = mutableConfig(preTogglesDefaultConfig());
    config.name = "Custom Name";
    config.description = "Custom description";
    config.version = 7;
    (config.tools as Record<string, unknown>).mcpServers = [
      { name: "custom-mcp", config: { command: "custom-server" } },
    ];
    await seedConfig(config);
    await update();
    const written = await readConfig();
    expect(written.name).toBe("Custom Name");
    expect(written.description).toBe("Custom description");
    expect(written.version).toBe(7);
    expect(written.tools?.mcpServers).toEqual([
      { name: "custom-mcp", config: { command: "custom-server" } },
    ]);
  });

  it("keeps the whole tools tab once any tool is edited, added or removed", async () => {
    const config = mutableConfig(defaultSystemConfig());
    delete config.kernel_version;
    const tools = config.tools as { builtin: Array<Record<string, unknown>> };
    const readFile = tools.builtin.find((t) => t.name === "read_file")!;
    readFile.description = "my own description";
    tools.builtin = tools.builtin.filter((t) => t.name !== "edit_file");
    tools.builtin.push({ name: "my_tool", description: "user-added", permission: "r" });
    await seedConfig(config);

    const result = await update();
    expect(result.kept).toEqual(["tools"]);
    expect(result.advanced).toEqual([]);

    const written = await readConfig();
    const names = (written.tools?.builtin ?? []).map((t) => t.name);
    expect(names).not.toContain("edit_file"); // a deliberate removal is preserved
    expect(names).toContain("my_tool"); // user-added entries survive
    expect(written.tools?.builtin?.find((t) => t.name === "read_file")?.description).toBe(
      "my own description",
    );
  });

  it("advances a tools tab that matches a superseded default, bringing tools added since", async () => {
    // The path every existing config takes when the default toolset changes: the stored tab is
    // not the current default, but it hash-matches a superseded one, so it is an untouched old
    // default and the whole tab is rewritten — which is also how a tool added by a later
    // kernel reaches the config. Driven through the seam so the test cannot rot when the real
    // record moves on.
    const config = mutableConfig(defaultSystemConfig());
    delete config.kernel_version;
    const tools = config.tools as { builtin: Array<Record<string, unknown>> };
    tools.builtin = tools.builtin.slice(0, -1); // an old default, missing a tool added since
    const supersededTabs: KernelSupersededTabHashes = { tools: [kernelTabHash(config, "tools")!] };
    await seedConfig(config);

    const result = await applyKernelUpdate(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID, {
      supersededTabs,
    });
    expect(result.advanced).toEqual(["tools"]);
    expect(result.kept).toEqual([]);
    const written = await readConfig();
    expect(written.tools?.builtin).toEqual(defaultSystemConfig().tools?.builtin);
    expect(written.kernel_version).toBe(KERNEL_VERSION);
  });

  it("materializes the whole default toolset when tools.builtin is missing", async () => {
    const config = mutableConfig(defaultSystemConfig());
    delete config.kernel_version;
    delete config.tools;
    await seedConfig(config);
    const result = await update();
    expect(result.advanced).toEqual(["tools"]);
    expect((await readConfig()).tools?.builtin).toEqual(defaultSystemConfig().tools?.builtin);
  });

  it("tolerates dangling/invalid section keys (a hand-edited `tools:` with no value parses as null)", async () => {
    await loadAgentState({ init: {}, root });
    await fs.writeFile(
      configPath(),
      // `tools` is a dangling key: the whole tab reads absent and must be materialized instead
      // of crashing setIn. `model: 3` leaves the runtime tab present but matching nothing, so
      // that tab is kept exactly as the user left it.
      "system_prompt: custom\nmodel: 3\ntools:\n",
      "utf8",
    );
    const result = await update();
    expect(result.kept).toEqual(["prompt", "runtime"]);
    expect(result.advanced).toEqual(["tools", "skills", "memory", "vault", "schedules"]);
    const defaults = defaultSystemConfig();
    const written = await readConfig();
    expect(written.tools?.builtin).toEqual(defaults.tools?.builtin);
    expect(written.memory).toEqual(defaults.memory);
    expect(written.system_prompt).toBe("custom");
    expect(written.model as unknown).toBe(3);
    expect(written.kernel_version).toBe(KERNEL_VERSION);
  });

  it("preserves YAML comments on untouched content", async () => {
    await loadAgentState({ init: {}, root });
    const raw = await fs.readFile(configPath(), "utf8");
    await fs.writeFile(
      configPath(),
      `# my precious comment\n${raw.replace("max_turns: -1", "max_turns: 5")}`,
      "utf8",
    );
    const result = await update();
    // max_turns 5 is a customization (no generation ever defaulted to 5) — its tab is kept.
    expect(result.kept).toEqual(["runtime"]);
    const after = await fs.readFile(configPath(), "utf8");
    expect(after).toContain("# my precious comment");
    expect((await readConfig()).max_turns).toBe(5);
  });
});

describe("kernel stamping on the materialization paths", () => {
  let root: string;

  beforeEach(async () => {
    root = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-kernel-stamp-"));
  });

  afterEach(async () => {
    await fs.rm(root, { recursive: true, force: true });
  });

  it("a newly created agent is stamped with the current kernel version", async () => {
    const state = await loadAgentState({ init: {}, root });
    expect(state.systemConfig.kernel_version).toBe(KERNEL_VERSION);
  });

  it("restore-defaults re-stamps a config that predates the mechanism", async () => {
    await loadAgentState({ init: {}, root });
    const configPath = systemConfigPath(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID);
    await fs.writeFile(configPath, "system_prompt: old\nversion: 3\n", "utf8");
    const written = await resetSystemConfigToDefaults(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID);
    expect(written.kernel_version).toBe(KERNEL_VERSION);
    expect(written.version).toBe(3);
  });
});